# ShadowFinder
<a href="https://www.bellingcat.com"><img alt="Bellingcat logo: Discover Bellingcat" src="https://img.shields.io/badge/Discover%20Bellingcat-%20?style=for-the-badge&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAA4AAAAYCAYAAADKx8xXAAABhGlDQ1BJQ0MgcHJvZmlsZQAAKJF9kT1Iw0AcxV9TS0UqDnZQEcxQneyiIo6likWwUNoKrTqYXPoFTRqSFBdHwbXg4Mdi1cHFWVcHV0EQ%2FABxdnBSdJES%2F5cUWsR4cNyPd%2Fced%2B8AoVllqtkTA1TNMtKJuJjLr4rBVwQwhhBEDEvM1JOZxSw8x9c9fHy9i%2FIs73N%2Fjn6lYDLAJxLHmG5YxBvEs5uWznmfOMzKkkJ8Tjxp0AWJH7kuu%2FzGueSwwDPDRjY9TxwmFktdLHcxKxsq8QxxRFE1yhdyLiuctzir1Tpr35O%2FMFTQVjJcpzmKBJaQRIo6klFHBVVYiNKqkWIiTftxD%2F%2BI40%2BRSyZXBYwcC6hBheT4wf%2Fgd7dmcXrKTQrFgcCLbX%2BMA8FdoNWw7e9j226dAP5n4Err%2BGtNYO6T9EZHixwBA9vAxXVHk%2FeAyx1g6EmXDMmR%2FDSFYhF4P6NvygODt0Dfmttbex%2BnD0CWulq%2BAQ4OgYkSZa97vLu3u7d%2Fz7T7%2BwHEU3LHAa%2FQ6gAAAAZiS0dEAAAAAAAA%2BUO7fwAAAAlwSFlzAAAuIwAALiMBeKU%2FdgAAAAd0SU1FB%2BgFHwwiMH4odB4AAAAZdEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIEdJTVBXgQ4XAAAA50lEQVQ4y82SvWpCQRCFz25ERSJiCNqlUiS1b5AuEEiZIq1NOsGXCKms0wXSp9T6dskDiFikyiPc%2FrMZyf3FXSGQ0%2BzuzPl2ZoeVKgQ0gQ2wBVpVHlcDkjM5V%2FJ5nag6sJ%2FZX%2Bh%2FC7gEhqeAFKf7p1M9aB3b5oN1OomB7g1axUBPBr3GQHODHmOgqUF3MZAzKI2d4LWBV4H%2BMXDuJd1a7Cew1k7SwksaHC4LqNaw7aeX9GWHXkC1G1sTAS17Y3Kk2lnp4wNLiz0DrgLq8qt2MfmSSabAO%2FBBXp26dtrADPjOmN%2BAUdG7B3cE61l5hOZiAAAAAElFTkSuQmCC&logoColor=%23fff&color=%23000"></a><!--
--><a href="https://discord.gg/bellingcat"><img alt="Discord logo: Join our community" src="https://img.shields.io/badge/Join%20our%20community-%20?style=for-the-badge&logo=discord&logoColor=%23fff&color=%235865F2"></a><!--
--><a href="https://colab.research.google.com/github/Bellingcat/ShadowFinder/blob/main/ShadowFinderColab.ipynb"><img alt="Colab icon: Try it on Colab" src="https://img.shields.io/badge/Try%20it%20on%20Colab-%20?style=for-the-badge&logo=googlecolab&logoColor=fff&logoSize=auto&color=e8710a"></a>
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:
<details>
<summary>Expand to view information for developers</summary>
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
```
</details>
Raw data
{
"_id": null,
"home_page": "https://github.com/bellingcat/ShadowFinder",
"name": "ShadowFinder",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "shadow, finder, locator, map",
"author": "Bellingcat",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e7/60/4261d6ecb50b7611042ade93a14e2700e581504f0fd41fbc36cc4d485f70/shadowfinder-0.5.0.tar.gz",
"platform": null,
"description": "# ShadowFinder\n\n<a href=\"https://www.bellingcat.com\"><img alt=\"Bellingcat logo: Discover Bellingcat\" src=\"https://img.shields.io/badge/Discover%20Bellingcat-%20?style=for-the-badge&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAA4AAAAYCAYAAADKx8xXAAABhGlDQ1BJQ0MgcHJvZmlsZQAAKJF9kT1Iw0AcxV9TS0UqDnZQEcxQneyiIo6likWwUNoKrTqYXPoFTRqSFBdHwbXg4Mdi1cHFWVcHV0EQ%2FABxdnBSdJES%2F5cUWsR4cNyPd%2Fced%2B8AoVllqtkTA1TNMtKJuJjLr4rBVwQwhhBEDEvM1JOZxSw8x9c9fHy9i%2FIs73N%2Fjn6lYDLAJxLHmG5YxBvEs5uWznmfOMzKkkJ8Tjxp0AWJH7kuu%2FzGueSwwDPDRjY9TxwmFktdLHcxKxsq8QxxRFE1yhdyLiuctzir1Tpr35O%2FMFTQVjJcpzmKBJaQRIo6klFHBVVYiNKqkWIiTftxD%2F%2BI40%2BRSyZXBYwcC6hBheT4wf%2Fgd7dmcXrKTQrFgcCLbX%2BMA8FdoNWw7e9j226dAP5n4Err%2BGtNYO6T9EZHixwBA9vAxXVHk%2FeAyx1g6EmXDMmR%2FDSFYhF4P6NvygODt0Dfmttbex%2BnD0CWulq%2BAQ4OgYkSZa97vLu3u7d%2Fz7T7%2BwHEU3LHAa%2FQ6gAAAAZiS0dEAAAAAAAA%2BUO7fwAAAAlwSFlzAAAuIwAALiMBeKU%2FdgAAAAd0SU1FB%2BgFHwwiMH4odB4AAAAZdEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIEdJTVBXgQ4XAAAA50lEQVQ4y82SvWpCQRCFz25ERSJiCNqlUiS1b5AuEEiZIq1NOsGXCKms0wXSp9T6dskDiFikyiPc%2FrMZyf3FXSGQ0%2BzuzPl2ZoeVKgQ0gQ2wBVpVHlcDkjM5V%2FJ5nag6sJ%2FZX%2Bh%2FC7gEhqeAFKf7p1M9aB3b5oN1OomB7g1axUBPBr3GQHODHmOgqUF3MZAzKI2d4LWBV4H%2BMXDuJd1a7Cew1k7SwksaHC4LqNaw7aeX9GWHXkC1G1sTAS17Y3Kk2lnp4wNLiz0DrgLq8qt2MfmSSabAO%2FBBXp26dtrADPjOmN%2BAUdG7B3cE61l5hOZiAAAAAElFTkSuQmCC&logoColor=%23fff&color=%23000\"></a><!--\n--><a href=\"https://discord.gg/bellingcat\"><img alt=\"Discord logo: Join our community\" src=\"https://img.shields.io/badge/Join%20our%20community-%20?style=for-the-badge&logo=discord&logoColor=%23fff&color=%235865F2\"></a><!--\n--><a href=\"https://colab.research.google.com/github/Bellingcat/ShadowFinder/blob/main/ShadowFinderColab.ipynb\"><img alt=\"Colab icon: Try it on Colab\" src=\"https://img.shields.io/badge/Try%20it%20on%20Colab-%20?style=for-the-badge&logo=googlecolab&logoColor=fff&logoSize=auto&color=e8710a\"></a>\n\nA 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.\n\nUsing 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:\n\n\n\n\n## Usage - Google Colab Notebook \ud83d\ude80\nNo installation necessary, just try it out using the [Google Colab notebook here](https://colab.research.google.com/github/Bellingcat/ShadowFinder/blob/main/ShadowFinderColab.ipynb)!\n\n## Installation :magic_wand:\n[](https://pypi.org/project/ShadowFinder/)\n\nShadowFinder 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.\n\nShadowFinder is published on [PyPi](https://pypi.org/project/ShadowFinder/) so can be installed via `pip` with:\n\n```shell\npip install shadowfinder\n```\n## Usage - Python Library \ud83d\udc0d\n\nIf you want to use ShadowFinder directly from Python, the usage is as follows.\n\n```python\nfrom shadowfinder import ShadowFinder\n\nfinder = ShadowFinder()\n\n# Use a pre-generated timezone grid to save time\n# Attempt to load a timezone grid and on a failure generate the grid and save to file\ntry:\n finder.load_timezone_grid()\nexcept FileNotFoundError:\n finder.generate_timezone_grid()\n finder.save_timezone_grid() # timezone_grid.json\n\n# Set up the scenario\n# Provide either object_height and shadow_length OR sun_altitude_angle\nfinder.set_details(\n date_time=date_time, # datetime object with no timezone awareness\n object_height=object_height, # object height in arbitrary units\n shadow_length=shadow_length, # shadow length in arbitrary units\n time_format=time_type, # string, either 'local' or 'utc'\n sun_altitude_angle=sun_altitude_angle, # altitude angle of the sun, in degrees above the horizon\n)\n\n# Run the finder\nfinder.find_shadows()\n\n# Access the resulting figure\nfig = finder.plot_shadows()\n```\n\n## Usage - Command Line Interface \ud83d\udc0c\n>[!IMPORTANT]\n> 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)\n\n```shell\nshadowfinder find 10 5 2024-02-29 13:59:59 --time_format=utc\n```\nWhere the arguments are `OBJECT_HEIGHT`, `SHADOW_LENGTH`, `DATE`, and `TIME` respectively.\n\nYou can also use the angle to the sun directly (above the horizon, in degrees):\n\n```shell\nshadowfinder find_sun 50 2024-02-29 13:59:59 --time_format=utc\n```\nWhere the arguments are `SUN_ALTITUDE_ANGLE`, `DATE`, and `TIME` respectively.\n\nMore complete help information can be found by running:\n\n```shell\nshadowfinder find --help\nshadowfinder find_sun --help\n```\n\n## Development :octocat:\n\n<details>\n<summary>Expand to view information for developers</summary>\n\nThis section describes how to install the project to run it from source, for example if you want to build new features.\n\n```bash\n# Clone the repository\ngit clone https://github.com/bellingcat/ShadowFinder.git\n\n# Change directory to the project folder\ncd ShadowFinder\n```\n\nThis project uses [Poetry](https://python-poetry.org/docs) for dependency management and packaging.\n\n```bash\n# Install poetry if you haven't already\npip install poetry\n\n# Install dependencies\npoetry install\n\n# Setup pre-commit hooks\npoetry run pre-commit install\n\n# Run the tool\npoetry run shadowfinder --help\n\n# Run tests against your current Python interpreter\npoetry run pytest\n\n# Or, run pytest against all shadowfinder supported Python versions\npoetry run tox p # p=run in parallel\n```\n</details>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Find possible locations of shadows.",
"version": "0.5.0",
"project_urls": {
"Bug Tracker": "https://github.com/bellingcat/ShadowFinder/issues",
"Homepage": "https://github.com/bellingcat/ShadowFinder",
"Repository": "https://github.com/bellingcat/ShadowFinder"
},
"split_keywords": [
"shadow",
" finder",
" locator",
" map"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1c9f47d6362b717ddbdaff5708672bf5268b97840ef47394085f4b3d6f2b4d54",
"md5": "e2d8f8e1153ac24fc2e6e7616ccede5b",
"sha256": "2a5a06880613e0654957a36dea25e6ebf45937f5d4631035064ca9b95a515421"
},
"downloads": -1,
"filename": "shadowfinder-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2d8f8e1153ac24fc2e6e7616ccede5b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 9472,
"upload_time": "2024-08-28T10:29:46",
"upload_time_iso_8601": "2024-08-28T10:29:46.212445Z",
"url": "https://files.pythonhosted.org/packages/1c/9f/47d6362b717ddbdaff5708672bf5268b97840ef47394085f4b3d6f2b4d54/shadowfinder-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e7604261d6ecb50b7611042ade93a14e2700e581504f0fd41fbc36cc4d485f70",
"md5": "7193e0cf88c298f1ed812e3e5f57ded2",
"sha256": "40dd61c11ad614b121954d94032cfa2417cc4548fc8179284bc34963d7707127"
},
"downloads": -1,
"filename": "shadowfinder-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "7193e0cf88c298f1ed812e3e5f57ded2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 8234,
"upload_time": "2024-08-28T10:29:47",
"upload_time_iso_8601": "2024-08-28T10:29:47.664793Z",
"url": "https://files.pythonhosted.org/packages/e7/60/4261d6ecb50b7611042ade93a14e2700e581504f0fd41fbc36cc4d485f70/shadowfinder-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-28 10:29:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bellingcat",
"github_project": "ShadowFinder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "shadowfinder"
}
JSON
