https://github.com/bellingcat/shadowfinder
Find possible locations of shadows around the world
https://github.com/bellingcat/shadowfinder
command-line geolocation notebook open-source-research python
Last synced: 7 months ago
JSON representation
Find possible locations of shadows around the world
- Host: GitHub
- URL: https://github.com/bellingcat/shadowfinder
- Owner: bellingcat
- License: mit
- Created: 2024-05-01T18:14:57.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-12T16:47:11.000Z (7 months ago)
- Last Synced: 2025-06-12T17:34:34.696Z (7 months ago)
- Topics: command-line, geolocation, notebook, open-source-research, python
- Language: Python
- Homepage: https://colab.research.google.com/github/Bellingcat/ShadowFinder/blob/main/ShadowFinderColab.ipynb
- Size: 1.02 MB
- Stars: 479
- Watchers: 4
- Forks: 39
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ShadowFinder
A lightweight tool and Google Colab notebook for estimating the points on the Earth's surface where a shadow of a particular length could occur, for geolocation purposes.
Using an object's height, the length of its shadow, the date and the time, ShadowFinder estimates the possible locations where that shadow could occur. These possible locations are shown as a bright band on a map of the Earth:
## Usage - Google Colab Notebook 🚀
No installation necessary, just try it out using the [Google Colab notebook here](https://colab.research.google.com/github/Bellingcat/ShadowFinder/blob/main/ShadowFinderColab.ipynb)!
## Installation :magic_wand:
[](https://pypi.org/project/ShadowFinder/)
ShadowFinder is built with the interactive notebook in mind, which can be downloaded and used in a local Jupyter environment, the package also provides a Python API and a command-line interface.
ShadowFinder is published on [PyPi](https://pypi.org/project/ShadowFinder/) so can be installed via `pip` with:
```shell
pip install shadowfinder
```
## Usage - Python Library 🐍
If you want to use ShadowFinder directly from Python, the usage is as follows.
```python
from shadowfinder import ShadowFinder
finder = ShadowFinder()
# Use a pre-generated timezone grid to save time
# Attempt to load a timezone grid and on a failure generate the grid and save to file
try:
finder.load_timezone_grid()
except FileNotFoundError:
finder.generate_timezone_grid()
finder.save_timezone_grid() # timezone_grid.json
# Set up the scenario
# Provide either object_height and shadow_length OR sun_altitude_angle
finder.set_details(
date_time=date_time, # datetime object with no timezone awareness
object_height=object_height, # object height in arbitrary units
shadow_length=shadow_length, # shadow length in arbitrary units
time_format=time_type, # string, either 'local' or 'utc'
sun_altitude_angle=sun_altitude_angle, # altitude angle of the sun, in degrees above the horizon
)
# Run the finder
finder.find_shadows()
# Access the resulting figure
fig = finder.plot_shadows()
```
## Usage - Command Line Interface 🐌
>[!IMPORTANT]
> Using the CLI is not the recommended way of using ShadowFinder as it is quite slow (there is currently not a caching strategy for the timezone_grid, so this is generated every run which is resource intesive)
```shell
shadowfinder find 10 5 2024-02-29 13:59:59 --time_format=utc
```
Where the arguments are `OBJECT_HEIGHT`, `SHADOW_LENGTH`, `DATE`, and `TIME` respectively.
You can also use the angle to the sun directly (above the horizon, in degrees):
```shell
shadowfinder find_sun 50 2024-02-29 13:59:59 --time_format=utc
```
Where the arguments are `SUN_ALTITUDE_ANGLE`, `DATE`, and `TIME` respectively.
More complete help information can be found by running:
```shell
shadowfinder find --help
shadowfinder find_sun --help
```
## Development :octocat:
Expand to view information for developers
This section describes how to install the project to run it from source, for example if you want to build new features.
```bash
# Clone the repository
git clone https://github.com/bellingcat/ShadowFinder.git
# Change directory to the project folder
cd ShadowFinder
```
This project uses [Poetry](https://python-poetry.org/docs) for dependency management and packaging.
```bash
# Install poetry if you haven't already
pip install poetry
# Install dependencies
poetry install
# Setup pre-commit hooks
poetry run pre-commit install
# Run the tool
poetry run shadowfinder --help
# Run tests against your current Python interpreter
poetry run pytest
# Or, run pytest against all shadowfinder supported Python versions
poetry run tox p # p=run in parallel
```