geokdtree 1.0.0__tar.gz

geokdtree-1.0.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: geokdtree
+Version: 1.0.0
+Summary: Given a coordinate point, find a very close point given a set of coordinate points.
+Author-email: Connor Makowski <conmak@mit.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/connor-makowski/geokdtree
+Project-URL: Bug Tracker, https://github.com/connor-makowski/geokdtree/issues
+Project-URL: Documentation, https://connor-makowski.github.io/geokdtree/geokdtree.html
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# GeoKDTree
+[![PyPI version](https://badge.fury.io/py/geokdtree.svg)](https://badge.fury.io/py/geokdtree)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI Downloads](https://pepy.tech/badge/geokdtree)](https://pypi.org/project/geokdtree/)
+<!-- [![PyPI Downloads](https://img.shields.io/pypi/dm/geokdtree.svg?label=PyPI%20downloads)](https://pypi.org/project/geokdtree/) -->
+
+
+### A Geo KD Tree package for Python
+
+
+![geokdtree](https://raw.githubusercontent.com/connor-makowski/geokdtree/main/static/geokdtree.png)
+
+## Quick Start:
+```py
+from geokdtree import GeoKDTree
+
+example_points = [
+    (34.0522, -118.2437),  # Los Angeles
+    (40.7128, -74.0060),   # New York
+    (37.7749, -122.4194),  # San Francisco
+    (51.5074, -0.1278),    # London
+    (48.8566, 2.3522),     # Paris
+]
+
+geo_kd_tree = GeoKDTree(points = example_points)
+test_point = (47.6062, -122.3321) # Seattle
+
+closest_idx = geo_kd_tree.closest_idx(test_point) # Expect San Francisco to be closest
+print(f"Closest point to {test_point} is {example_points[closest_idx] }")
+```
+
+### Documentation
+
+- Docs: https://connor-makowski.github.io/geokdtree/geokdtree.html
+- Git Repo: https://github.com/connor-makowski/geokdtree
+
+# Development
+## Running Tests, Prettifying Code, and Updating Docs
+
+Make sure Docker is installed and running on a Unix system (Linux, MacOS, WSL2).
+
+- Create a docker container and drop into a shell
+    - `./run.sh`
+- Run all tests (see ./utils/test.sh)
+    - `./run.sh test`
+- Prettify the code (see ./utils/prettify.sh)
+    - `./run.sh prettify`
+- Update the docs (see ./utils/docs.sh)
+    - `./run.sh docs`
+
+- Note: You can and should modify the `Dockerfile` to test different python versions.
+

geokdtree-1.0.0/README.md

@@ -0,0 +1,52 @@
+# GeoKDTree
+[![PyPI version](https://badge.fury.io/py/geokdtree.svg)](https://badge.fury.io/py/geokdtree)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI Downloads](https://pepy.tech/badge/geokdtree)](https://pypi.org/project/geokdtree/)
+<!-- [![PyPI Downloads](https://img.shields.io/pypi/dm/geokdtree.svg?label=PyPI%20downloads)](https://pypi.org/project/geokdtree/) -->
+
+
+### A Geo KD Tree package for Python
+
+
+![geokdtree](https://raw.githubusercontent.com/connor-makowski/geokdtree/main/static/geokdtree.png)
+
+## Quick Start:
+```py
+from geokdtree import GeoKDTree
+
+example_points = [
+    (34.0522, -118.2437),  # Los Angeles
+    (40.7128, -74.0060),   # New York
+    (37.7749, -122.4194),  # San Francisco
+    (51.5074, -0.1278),    # London
+    (48.8566, 2.3522),     # Paris
+]
+
+geo_kd_tree = GeoKDTree(points = example_points)
+test_point = (47.6062, -122.3321) # Seattle
+
+closest_idx = geo_kd_tree.closest_idx(test_point) # Expect San Francisco to be closest
+print(f"Closest point to {test_point} is {example_points[closest_idx] }")
+```
+
+### Documentation
+
+- Docs: https://connor-makowski.github.io/geokdtree/geokdtree.html
+- Git Repo: https://github.com/connor-makowski/geokdtree
+
+# Development
+## Running Tests, Prettifying Code, and Updating Docs
+
+Make sure Docker is installed and running on a Unix system (Linux, MacOS, WSL2).
+
+- Create a docker container and drop into a shell
+    - `./run.sh`
+- Run all tests (see ./utils/test.sh)
+    - `./run.sh test`
+- Prettify the code (see ./utils/prettify.sh)
+    - `./run.sh prettify`
+- Update the docs (see ./utils/docs.sh)
+    - `./run.sh docs`
+
+- Note: You can and should modify the `Dockerfile` to test different python versions.
+

geokdtree-1.0.0/geokdtree/__init__.py

@@ -0,0 +1,56 @@
+"""
+# GeoKDTree
+[![PyPI version](https://badge.fury.io/py/geokdtree.svg)](https://badge.fury.io/py/geokdtree)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI Downloads](https://pepy.tech/badge/geokdtree)](https://pypi.org/project/geokdtree/)
+<!-- [![PyPI Downloads](https://img.shields.io/pypi/dm/geokdtree.svg?label=PyPI%20downloads)](https://pypi.org/project/geokdtree/) -->
+
+
+### A Geo KD Tree package for Python
+
+
+![geokdtree](https://raw.githubusercontent.com/connor-makowski/geokdtree/main/static/geokdtree.png)
+
+## Quick Start:
+```py
+from geokdtree import GeoKDTree
+
+example_points = [
+    (34.0522, -118.2437),  # Los Angeles
+    (40.7128, -74.0060),   # New York
+    (37.7749, -122.4194),  # San Francisco
+    (51.5074, -0.1278),    # London
+    (48.8566, 2.3522),     # Paris
+]
+
+geo_kd_tree = GeoKDTree(points = example_points)
+test_point = (47.6062, -122.3321) # Seattle
+
+closest_idx = geo_kd_tree.closest_idx(test_point) # Expect San Francisco to be closest
+print(f"Closest point to {test_point} is {example_points[closest_idx] }")
+```
+
+### Documentation
+
+- Docs: https://connor-makowski.github.io/geokdtree/geokdtree.html
+- Git Repo: https://github.com/connor-makowski/geokdtree
+
+# Development
+## Running Tests, Prettifying Code, and Updating Docs
+
+Make sure Docker is installed and running on a Unix system (Linux, MacOS, WSL2).
+
+- Create a docker container and drop into a shell
+    - `./run.sh`
+- Run all tests (see ./utils/test.sh)
+    - `./run.sh test`
+- Prettify the code (see ./utils/prettify.sh)
+    - `./run.sh prettify`
+- Update the docs (see ./utils/docs.sh)
+    - `./run.sh docs`
+
+- Note: You can and should modify the `Dockerfile` to test different python versions.
+
+"""
+
+from .core import KDTree, GeoKDTree

geokdtree-1.0.0/geokdtree/core.py

@@ -0,0 +1,345 @@
+from math import pi, cos, sin
+
+
+def kdtree(points, depth=0, axis_count=2):
+    """
+    Function:
+
+    - Build a KDTree from a list of points.
+
+    Required Arguments:
+
+    - `points`
+        - Type: list of tuples
+        - What: A list of points to build the KDTree from
+
+    Optional Arguments:
+
+    - `depth`
+        - Type: int
+        - What: The current depth in the tree (used for axis selection)
+    - `axis_count`
+        - Type: int
+        - What: The number of dimensions in the points (default is 2 for 2D points)
+
+    Returns:
+
+    - The constructed KDTree as a tuple in the format (point, axis, left, right).
+    - Where left and right are subtrees.
+    """
+    if not points:
+        return 0
+    axis = depth % axis_count
+    points.sort(key=lambda p: p[axis])
+    median = len(points) // 2
+    return (
+        points[median],
+        axis,
+        kdtree(points[:median], depth + 1),
+        kdtree(points[median + 1 :], depth + 1),
+    )
+
+
+def squared_distance(p1, p2, axis_count=2):
+    """
+    Function:
+
+    - Calculate the squared distance between two points.
+
+    Required Arguments:
+
+    - `p1`
+        - Type: tuple
+        - What: The first point
+    - `p2`
+        - Type: tuple
+        - What: The second point
+
+    Optional Arguments:
+
+    - `axis_count`
+        - Type: int
+        - What: The number of dimensions in the points
+        - Default: 2 (for 2D points)
+
+    Returns:
+
+    - The squared distance between the two points.
+    """
+    return sum([(p1[i] - p2[i]) ** 2 for i in range(axis_count)])
+
+
+def closest_point(
+    node, point, depth=0, best=None, axis_count=2, best_dist=float("inf")
+):
+    """
+    Function:
+
+    - Find the closest point in the KDTree to a given point.
+
+    Required Arguments:
+
+    - `node`
+        - Type: tuple
+        - What: The node of the KDTree
+    - `point`
+        - Type: tuple
+        - What: The point to find the closest point to
+
+    Optional Arguments:
+
+    - `depth`
+        - Type: int
+        - What: The current depth in the tree (used for axis selection)
+    - `best`
+        - Type: tuple or None
+        - What: The best point found so far (default is None)
+    - `axis_count`
+        - Type: int
+        - What: The number of dimensions in the points (default is 2 for 2D points)
+    - `best_dist`
+        - Type: float
+        - What: The best distance found so far (default is infinity)
+
+    Returns:
+
+    - The closest point found in the KDTree to the given point.
+    """
+    if node == 0:
+        return best, best_dist
+    # Get the median node and its distance
+    median_node = node[0]
+    median_node_dist = squared_distance(
+        point, median_node, axis_count=axis_count
+    )
+    # Update the best point and distance if necessary
+    if best is None or median_node_dist < best_dist:
+        best = median_node
+        best_dist = median_node_dist
+    # Calculate the difference for node selection given the current axis
+    axis = node[1]
+    diff = point[axis] - median_node[axis]
+    # Choose side to search
+    close, away = (node[2], node[3]) if diff < 0 else (node[3], node[2])
+    # Search the close side first
+    best, best_dist = closest_point(
+        close,
+        point,
+        depth + 1,
+        best,
+        axis_count=axis_count,
+        best_dist=best_dist,
+    )
+    # Check the other side if needed
+    if diff**2 < best_dist:
+        best, best_dist = closest_point(
+            away,
+            point,
+            depth + 1,
+            best,
+            axis_count=axis_count,
+            best_dist=best_dist,
+        )
+    return best, best_dist
+
+
+def squared_distance_3d(p1, p2):
+    """
+    Function:
+
+    - Calculate the squared distance between two 3D points.
+
+    Required Arguments:
+
+    - `p1`
+        - Type: tuple
+        - What: The first point in 3D space
+    - `p2`
+        - Type: tuple
+        - What: The second point in 3D space
+
+    Returns:
+
+    - The squared distance between the two 3D points.
+    """
+    return sum(
+        [(p1[0] - p2[0]) ** 2, (p1[1] - p2[1]) ** 2, (p1[2] - p2[2]) ** 2]
+    )
+
+
+def closest_point_3d(node, point, depth=0, best=None, best_dist=float("inf")):
+    """
+    Function:
+
+    - Find the closest point in the KDTree to a given point.
+
+    Required Arguments:
+
+    - `node`
+        - Type: tuple
+        - What: The node of the KDTree
+    - `point`
+        - Type: tuple
+        - What: The point to find the closest point to
+
+    Optional Arguments:
+
+    - `depth`
+        - Type: int
+        - What: The current depth in the tree (used for axis selection)
+    - `best`
+        - Type: tuple or None
+        - What: The best point found so far (default is None)
+    - `best_dist`
+        - Type: float
+        - What: The best distance found so far (default is infinity)
+
+    Returns:
+
+    - The closest point found in the KDTree to the given point.
+    """
+    if node == 0:
+        return best, best_dist
+    # Get the median node and its distance
+    median_node = node[0]
+    median_node_dist = squared_distance_3d(point, median_node)
+    # Update the best point and distance if necessary
+    if best is None or median_node_dist < best_dist:
+        best = median_node
+        best_dist = median_node_dist
+    # Calculate the difference for node selection given the current axis
+    axis = node[1]
+    diff = point[axis] - median_node[axis]
+    # Choose side to search
+    close, away = (node[2], node[3]) if diff < 0 else (node[3], node[2])
+    # Search the close side first
+    best, best_dist = closest_point_3d(close, point, depth + 1, best, best_dist)
+    # Check the other side if needed
+    if diff**2 < best_dist:
+        best, best_dist = closest_point_3d(
+            away, point, depth + 1, best, best_dist
+        )
+    return best, best_dist
+
+
+class KDTree:
+    def __init__(self, points):
+        """
+        Function:
+
+        - Build a KDTree from a list of points.
+
+        Required Arguments:
+
+        - `points`
+            - Type: list of tuples
+            - What: A list of points to build the KDTree from
+
+        Returns:
+
+        - A KDTree object that can be used to find the closest point to a given point.
+        """
+        self.tree = kdtree(points, axis_count=len(points[0]))
+
+    def closest_point(self, point):
+        """
+        Function:
+
+        - Find the closest point in the KDTree to a given point.
+
+        Required Arguments:
+
+        - `point`
+            - Type: tuple
+            - What: The point to find the closest point to
+
+        Returns:
+
+        - The closest point found in the KDTree to the given point.
+        """
+        return closest_point(self.tree, point)[
+            0
+        ]  # Return only the point, not the distance
+
+
+class GeoKDTree:
+    def __init__(self, points: list[tuple]):
+        """
+        Function:
+
+        - Build a GeoKDTree from a list of latitude and longitude points or an existing KDTree.
+
+        Required Arguments:
+
+        - `points`
+            - Type: list of tuples
+            - What: A list of latitude and longitude points to build the GeoKDTree from
+            - The points should be in the format [(lat1, lon1), (lat2, lon2), ...].
+
+        Returns:
+
+        - A GeoKDTree object that can be used to find the closest point to a given latitude and longitude.
+        - The points should be in the format [(lat1, lon1), (lat2, lon2), ...].
+        """
+        self.tree = kdtree(
+            [
+                GeoKDTree.lat_lon_idx_to_xyz_idx(point[0], point[1], idx)
+                for idx, point in enumerate(points)
+            ],
+            axis_count=3,
+        )
+
+    def closest_idx(self, point: tuple):
+        """
+        Function:
+
+        - Find the index of the closest point in the GeoKDTree to a given latitude and longitude point.
+
+        Required Arguments:
+
+        - `point`
+            - Type: tuple
+            - What: The latitude and longitude point to find the closest point to
+
+        Returns:
+
+        - The index of the closest point found in the GeoKDTree to the given latitude and longitude point.
+        """
+        return closest_point_3d(
+            self.tree,
+            GeoKDTree.lat_lon_idx_to_xyz_idx(point[0], point[1]),
+        )[0][
+            3
+        ]  # Return the point [0] and the index of the point [3]
+
+    @staticmethod
+    def lat_lon_idx_to_xyz_idx(
+        lat: int | float, lon: int | float, idx: int = 0
+    ):
+        """
+        Function:
+
+        - Convert latitude and longitude to Cartesian coordinates (x, y, z) and include an index.
+
+        Required Arguments:
+
+        - `lat`
+            - Type: int or float
+            - What: The latitude in degrees
+        - `lon`
+            - Type: int or float
+            - What: The longitude in degrees
+
+        Optional Arguments:
+
+        - `idx`
+            - Type: int
+            - What: An index to include with the coordinates (default is 0)
+        """
+        lat_rad = lat * pi / 180
+        lon_rad = lon * pi / 180
+        cos_lat = cos(lat_rad)
+        x = cos_lat * cos(lon_rad)
+        y = cos_lat * sin(lon_rad)
+        z = sin(lat_rad)
+        return (x, y, z, idx)

geokdtree-1.0.0/geokdtree.egg-info/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: geokdtree
+Version: 1.0.0
+Summary: Given a coordinate point, find a very close point given a set of coordinate points.
+Author-email: Connor Makowski <conmak@mit.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/connor-makowski/geokdtree
+Project-URL: Bug Tracker, https://github.com/connor-makowski/geokdtree/issues
+Project-URL: Documentation, https://connor-makowski.github.io/geokdtree/geokdtree.html
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# GeoKDTree
+[![PyPI version](https://badge.fury.io/py/geokdtree.svg)](https://badge.fury.io/py/geokdtree)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI Downloads](https://pepy.tech/badge/geokdtree)](https://pypi.org/project/geokdtree/)
+<!-- [![PyPI Downloads](https://img.shields.io/pypi/dm/geokdtree.svg?label=PyPI%20downloads)](https://pypi.org/project/geokdtree/) -->
+
+
+### A Geo KD Tree package for Python
+
+
+![geokdtree](https://raw.githubusercontent.com/connor-makowski/geokdtree/main/static/geokdtree.png)
+
+## Quick Start:
+```py
+from geokdtree import GeoKDTree
+
+example_points = [
+    (34.0522, -118.2437),  # Los Angeles
+    (40.7128, -74.0060),   # New York
+    (37.7749, -122.4194),  # San Francisco
+    (51.5074, -0.1278),    # London
+    (48.8566, 2.3522),     # Paris
+]
+
+geo_kd_tree = GeoKDTree(points = example_points)
+test_point = (47.6062, -122.3321) # Seattle
+
+closest_idx = geo_kd_tree.closest_idx(test_point) # Expect San Francisco to be closest
+print(f"Closest point to {test_point} is {example_points[closest_idx] }")
+```
+
+### Documentation
+
+- Docs: https://connor-makowski.github.io/geokdtree/geokdtree.html
+- Git Repo: https://github.com/connor-makowski/geokdtree
+
+# Development
+## Running Tests, Prettifying Code, and Updating Docs
+
+Make sure Docker is installed and running on a Unix system (Linux, MacOS, WSL2).
+
+- Create a docker container and drop into a shell
+    - `./run.sh`
+- Run all tests (see ./utils/test.sh)
+    - `./run.sh test`
+- Prettify the code (see ./utils/prettify.sh)
+    - `./run.sh prettify`
+- Update the docs (see ./utils/docs.sh)
+    - `./run.sh docs`
+
+- Note: You can and should modify the `Dockerfile` to test different python versions.
+

geokdtree-1.0.0/geokdtree.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+setup.cfg
+geokdtree/__init__.py
+geokdtree/core.py
+geokdtree.egg-info/PKG-INFO
+geokdtree.egg-info/SOURCES.txt
+geokdtree.egg-info/dependency_links.txt
+geokdtree.egg-info/top_level.txt
+geokdtree/bin/__init__.py

geokdtree-1.0.0/geokdtree.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

geokdtree-1.0.0/geokdtree.egg-info/top_level.txt

@@ -0,0 +1 @@
+geokdtree

geokdtree-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[tool.black]
+line-length = 80
+target-version = ['py312']
+exclude = '/.*(migrations|__pycache__).*/'
+
+[tool.setuptools]
+py-modules = ["geokdtree"]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "geokdtree"
+version = "1.0.0"
+description = "Given a coordinate point, find a very close point given a set of coordinate points."
+authors = [
+    {name="Connor Makowski", email="conmak@mit.edu"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license="MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C++",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+"Homepage" = "https://github.com/connor-makowski/geokdtree"
+"Bug Tracker" = "https://github.com/connor-makowski/geokdtree/issues"
+"Documentation" = "https://connor-makowski.github.io/geokdtree/geokdtree.html"

geokdtree-1.0.0/setup.cfg

@@ -0,0 +1,12 @@
+[metadata]
+name = geokdtree
+version = 2.15.0
+description_file = README.md
+
+[options]
+packages = find:
+
+[egg_info]
+tag_build = 
+tag_date = 0
+