Bellingcat logo: Discover Bellingcat Discord logo: Join our community Colab icon: Try it on Colab
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:
No installation necessary, just try it out using the Google Colab notebook here!
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 so can be installed via pip with:
pip install shadowfinder
If you want to use ShadowFinder directly from Python, the usage is as follows.
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()
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)
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):
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:
shadowfinder find --help shadowfinder find_sun --help
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.
# Clone the repository git clone https://github.com/bellingcat/ShadowFinder.git # Change directory to the project folder cd ShadowFinder
This project uses Poetry for dependency management and packaging.
# 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