ShadowFinder 0.1.0__tar.gz

shadowfinder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Stichting Bellingcat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shadowfinder-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.1
+Name: ShadowFinder
+Version: 0.1.0
+Summary: Find possible locations of shadows.
+Home-page: https://github.com/bellingcat/ShadowFinder
+License: MIT
+Keywords: shadow,finder,locator,map
+Author: Bellingcat
+Requires-Python: >=3.9,<3.13
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: basemap (>=1.4,<2.0)
+Requires-Dist: fire (>=0.5,<0.6)
+Requires-Dist: matplotlib (>=3.8,<4.0)
+Requires-Dist: suncalc (>=0.1.3,<0.2.0)
+Project-URL: Bug Tracker, https://github.com/bellingcat/ShadowFinder/issues
+Project-URL: Repository, https://github.com/bellingcat/ShadowFinder
+Description-Content-Type: text/markdown
+
+# 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 lenth of its shadow, the date and the time, ShadowFinder estimates the possible locations where that shadow could occur.
+
+[Try out ShadowFinder on Google Colab now](https://colab.research.google.com/github/Bellingcat/ShadowFinder/blob/main/ShadowFinderColab.ipynb)
+

shadowfinder-0.1.0/README.md

@@ -0,0 +1,7 @@
+# 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 lenth of its shadow, the date and the time, ShadowFinder estimates the possible locations where that shadow could occur.
+
+[Try out ShadowFinder on Google Colab now](https://colab.research.google.com/github/Bellingcat/ShadowFinder/blob/main/ShadowFinderColab.ipynb)

shadowfinder-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[tool.poetry]
+name = "ShadowFinder"
+version = "0.1.0"
+description = "Find possible locations of shadows."
+authors = ["Bellingcat"]
+license = "MIT License"
+readme = "README.md"
+repository = "https://github.com/bellingcat/ShadowFinder"
+classifiers = [
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Visualization",
+]
+keywords=["shadow", "finder", "locator", "map"]
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/bellingcat/ShadowFinder/issues"
+
+[tool.poetry.scripts]
+shadowfinder = "shadowfinder.main:main_entrypoint"
+
+[tool.poetry.dependencies]
+python =  ">=3.9,<3.13"
+matplotlib = "^3.8"
+basemap = "^1.4"
+suncalc = "^0.1.3"
+fire = "^0.5"
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.2.0"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

shadowfinder-0.1.0/shadowfinder/cli.py

@@ -0,0 +1,49 @@
+from datetime import datetime, timezone
+
+from shadowfinder.shadowfinder import ShadowFinder
+
+
+def _validate_args(
+    object_height: float,
+    shadow_length: float,
+    date_time: datetime,
+) -> None:
+    """
+    Validate the text search CLI arguments, raises an error if the arguments are invalid.
+    """
+
+    if not object_height:
+        raise ValueError("Object height cannot be empty")
+    if not shadow_length:
+        raise ValueError("Shadow length cannot be empty")
+    if not date_time:
+        raise ValueError("Date time cannot be empty")
+
+
+class ShadowFinderCli:
+
+    @staticmethod
+    def find(
+        object_height: float,
+        shadow_length: float,
+        date: str,
+        time: str,
+    ) -> None:
+        """
+        Find the shadow length of an object given its height and the date and time.
+        :param object_height: Height of the object in arbitrary units
+        :param shadow_length: Length of the shadow in arbitrary units
+        :param date: Date in the format YYYY-MM-DD
+        :param time: UTC Time in the format HH:MM:SS
+        """
+
+        try:
+            date_time = datetime.strptime(
+                f"{date} {time}", "%Y-%m-%d %H:%M:%S"
+            ).replace(tzinfo=timezone.utc)
+        except Exception as e:
+            raise ValueError(f"Invalid argument type or format: {e}")
+        _validate_args(object_height, shadow_length, date_time)
+
+        shadow_finder = ShadowFinder(object_height, shadow_length, date_time)
+        shadow_finder.quick_find()

shadowfinder-0.1.0/shadowfinder/main.py

@@ -0,0 +1,10 @@
+from shadowfinder.cli import ShadowFinderCli
+import fire
+
+
+def main_entrypoint():
+    fire.Fire(ShadowFinderCli)
+
+
+if __name__ == "__main__":
+    main_entrypoint()

shadowfinder-0.1.0/shadowfinder/shadowfinder.py

@@ -0,0 +1,88 @@
+from types import SimpleNamespace
+from suncalc import get_position
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.colors as colors
+from mpl_toolkits.basemap import Basemap
+
+
+class ShadowFinder:
+    def __init__(self, object_height, shadow_length, date_time):
+        self.object_height = object_height
+        self.shadow_length = shadow_length
+        self.date_time = date_time
+
+        self.grid = None
+        self.shadow_lengths = None
+
+        self.fig = None
+
+    def quick_find(self):
+        self.generate_lat_lon_grid()
+        self.find_shadows()
+        fig = self.plot_shadows()
+        fig.savefig(
+            f"shadow_finder_{self.date_time.strftime('%Y%m%d-%H%M%S-%Z')}_{self.object_height}_{self.shadow_length}.png"
+        )
+
+    def generate_lat_lon_grid(self, angular_resolution=0.25):
+        lats = np.arange(-90, 90, angular_resolution)
+        lons = np.arange(-180, 180, angular_resolution)
+
+        lons, lats = np.meshgrid(lons, lats)
+
+        self.grid = SimpleNamespace(lons=lons, lats=lats)
+
+    def find_shadows(self):
+        # Evaluate the sun's length at a grid of points on the Earth's surface
+
+        if self.grid is None:
+            self.generate_lat_lon_grid()
+
+        pos_obj = get_position(self.date_time, self.grid.lons, self.grid.lats)
+        sun_altitudes = pos_obj["altitude"]  # in radians
+
+        # Calculate the shadow length
+        shadow_lengths = self.object_height / np.apply_along_axis(
+            np.tan, 0, sun_altitudes
+        )
+
+        # Replace points where the sun is below the horizon with nan
+        shadow_lengths[sun_altitudes <= 0] = np.nan
+
+        # Show the relative difference between the calculated shadow length and the observed shadow length
+        shadow_relative_length_difference = (
+            shadow_lengths - self.shadow_length
+        ) / self.shadow_length
+
+        self.shadow_lengths = shadow_relative_length_difference
+
+    def plot_shadows(
+        self,
+        figure_args={"figsize": (12, 6)},
+        basemap_args={"projection": "cyl", "resolution": "c"},
+    ):
+
+        fig = plt.figure(**figure_args)
+
+        # Add a simple map of the Earth
+        m = Basemap(**basemap_args)
+        m.drawcoastlines()
+        m.drawcountries()
+
+        # Deal with the map projection
+        x, y = m(self.grid.lons, self.grid.lats)
+
+        # Set the a color scale and only show the values between 0 and 0.2
+        cmap = plt.cm.get_cmap("inferno_r")
+        norm = colors.BoundaryNorm(np.arange(0, 0.2, 0.02), cmap.N)
+
+        # Plot the data
+        m.pcolormesh(x, y, np.abs(self.shadow_lengths), cmap=cmap, norm=norm, alpha=0.7)
+
+        # plt.colorbar(label='Relative Shadow Length Difference')
+        plt.title(
+            f"Possible Locations at {self.date_time.strftime('%Y-%m-%d %H:%M:%S %Z')}\n(object height: {self.object_height}, shadow length: {self.shadow_length})"
+        )
+        self.fig = fig
+        return fig