geo-adjacency 1.0.7__py3-none-any.whl → 1.1.2__py3-none-any.whl

geo_adjacency/adjacency.py

@@ -1,61 +1,86 @@
 """
-The adjacency module is a part of the geo-adjacency package, which provides functionality for
-calculating and analyzing adjacency between geometries. It implements the AdjacencyEngine class,
-which allows users to determine adjacency relationships between a set of source and target
-geometries, taking into account obstacles and a specified radius. The module utilizes the Voronoi
-diagram to generate adjacency linkages and provides methods for plotting the adjacency linkages on
-a map. The module also handles cases where there are gaps between features, ensuring accurate
-adjacency analysis. Overall, the adjacency module enables users to answer questions about spatial
-adjacency, providing valuable insights for geospatial analysis and decision-making processes.
+The `adjacency` module implements the AdjacencyEngine class,
+which allows us to calculate adjacency relationships. Adjacency relationships are between a set of source geometries,
+or between source geometries and a second set of target geometries. Obstacle geometries can be passed in to
+stand between sources or sources and targets, but they are not included in the output.
+
+For example, if we wanted to know what trees in a forest are adjacent to the shore of a lake, we could
+pass in a set of Point geometries to the trees, a Polygon to represent the lake, and a LineString to represent
+a road passing between some of the trees and the shore.
+
+`AdjacencyEngine` utilizes a Voronoi diagram of all the vertices in all the geometries combined to determine
+which geometries are adjacent to each other. See
 """
 
 import math
-import os
-import time
 from collections import defaultdict
-from typing import List, Union, Dict, Tuple
+from typing import List, Union, Dict, Tuple, Generator
+
+try:
+    from typing_extensions import Self  # Python < 3.11
+except ImportError:
+    from typing import Self  # Python >= 3.11
 import logging
 
-from scipy.spatial import distance, voronoi_plot_2d
+import matplotlib.pyplot as plt
+import numpy as np
+import shapely.ops
+from scipy.spatial import distance
 from scipy.spatial import Voronoi
-from shapely import Polygon, MultiPolygon, LineString, Point
+from shapely import LineString, Point, Polygon, MultiPolygon
 from shapely.geometry.base import BaseGeometry
-from shapely.ops import nearest_points
-from shapely.wkt import loads
-from shapely.geometry import mapping
-import numpy as np
-import matplotlib.pyplot as plt
 
 from geo_adjacency.exception import ImmutablePropertyError
-from geo_adjacency.utils import flatten_list, add_geometry_to_plot
-
+from geo_adjacency.utils import (
+    add_geometry_to_plot,
+    coords_from_point,
+    coords_from_ring,
+    coords_from_polygon,
+    coords_from_multipolygon,
+)
+
+# ToDo: Support geometries with Z-coordinates
 # Create a custom logger
-logger = logging.getLogger(__name__)
+log: logging.Logger = logging.getLogger(__name__)
 
 # Create handlers
-c_handler = logging.StreamHandler()
-f_handler = logging.FileHandler("file.log")
+c_handler: logging.StreamHandler = logging.StreamHandler()
 c_handler.setLevel(logging.WARNING)
-f_handler.setLevel(logging.ERROR)
 
 # Create formatters and add it to handlers
-c_format = logging.Formatter("%(name)s - %(levelname)s - %(message)s")
-f_format = logging.Formatter(
-    "%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+c_format: logging.Formatter = logging.Formatter("%(name)s - %(levelname)s - %(message)s")
+f_format: logging.Formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
 c_handler.setFormatter(c_format)
-f_handler.setFormatter(f_format)
 
 # Add handlers to the logger
-logger.addHandler(c_handler)
-logger.addHandler(f_handler)
+log.addHandler(c_handler)
 
 
 class _Feature:
+    """
+    A _Feature is a wrapper around a Shapely geometry that allows us to easily determine if two
+    geometries are adjacent.
+    """
     __slots__ = ("_geometry", "_coords", "voronoi_points")
 
     def __init__(self, geometry: BaseGeometry):
+        """
+        Create a _Feature from a Shapely geometry.
+
+        Args:
+            geometry (BaseGeometry): A valid Shapely Geometry, either a Point, LineString, Polygon, or
+        MultiPolygon.
+        """
+
+        if not isinstance(geometry, (Point, Polygon, MultiPolygon, LineString)):
+            raise TypeError(
+                "Cannot create _Feature for geometry type '%s'." % type(geometry)
+            )
+
+        assert geometry.is_valid, "Could not process invalid geometry: %s" % geometry.wkt
+
         self._geometry: BaseGeometry = geometry
-        self._coords = None
+        self._coords: Union[List[Tuple[float, float]], None] = None
         self.voronoi_points: set = set()
 
     def __str__(self):
@@ -64,11 +89,43 @@ class _Feature:
     def __repr__(self):
         return f"<_Feature: {str(self.geometry)}>"
 
+    def _is_adjacent(
+        self, other: Self, min_overlapping_voronoi_vertices: int = 2
+    ) -> bool:
+        """
+        Determine if two features are adjacent based on how many Voronoi vertices they share. Note:
+        the Voronoi analysis must have been run, or this will always return False.
+        Args:
+            other (_Feature): Another _Feature to compare to.
+            min_overlapping_voronoi_vertices (int): The minimum number of Voronoi vertices that
+                must be shared to be considered adjacent.
+
+        Returns:
+            bool: True if the two features are adjacent.
+
+        """
+        assert isinstance(other, type(self)), "Cannot compare '%s' with '%s'." % (
+            type(self),
+            type(other),
+        )
+        if len(self.voronoi_points) == 0 and len(other.voronoi_points) == 0:
+            log.warning(
+                "No Voronoi vertices found for either feature. Did you run the analysis yet?"
+            )
+            return False
+        return (
+            len(self.voronoi_points & other.voronoi_points)
+            >= min_overlapping_voronoi_vertices
+        )
+
     @property
     def geometry(self):
         """
         Access the Shapely geometry of the feature.
-        :return: BaseGeometry
+
+        Returns:
+            BaseGeometry: The Shapely geometry of the feature.
+
         """
         return self._geometry
 
@@ -82,23 +139,28 @@ class _Feature:
         """
         Convenience property for accessing the coordinates of the geometry as a list of 2-tuples.
 
-        :return: List[Tuple[float, float]]: A list of coordinate tuples.
+        Returns:
+            List[Tuple[float, float]]: A list of coordinate tuples.
+
         """
+
         if not self._coords:
             if isinstance(self.geometry, Point):
-                self._coords = tuple([(self.geometry.x, self.geometry.y)])
+                self._coords = coords_from_point(self.geometry)
+            elif isinstance(self.geometry, LineString):
+                self._coords = coords_from_ring(self.geometry)
             elif isinstance(self.geometry, Polygon):
-                self._coords = tuple(mapping(self.geometry)["coordinates"][0])
+                self._coords = coords_from_polygon(self.geometry)
             elif isinstance(self.geometry, MultiPolygon):
-                self._coords = tuple(flatten_list(
-                    mapping(self.geometry)["coordinates"][0]))
-            elif isinstance(self.geometry, LineString):
-                self._coords = tuple((x, y) for x, y in self.geometry.coords)
+                self._coords = coords_from_multipolygon(self.geometry)
             else:
-                raise TypeError(
-                    f"Unknown geometry type '{type(self.geometry)}'")
+                raise TypeError(f"Unknown geometry type '{type(self.geometry)}'")
         return self._coords
 
+    @coords.setter
+    def coords(self, coords):
+        raise ImmutablePropertyError("Property coords is immutable.")
+
 
 class AdjacencyEngine:
     """
@@ -110,36 +172,43 @@ class AdjacencyEngine:
     adjacent.
     """
 
-    __slots__ = ("_source_features", "_target_features", "_obstacle_features", "_adjacency_dict",
-                 "_feature_indices", "_vor", "all_features", "all_coordinates")
+    __slots__ = (
+        "_source_features",
+        "_target_features",
+        "_obstacle_features",
+        "_adjacency_dict",
+        "_feature_indices",
+        "_vor",
+        "_all_features",
+        "_all_coordinates",
+    )
 
     def __init__(
-            self,
-            source_geoms: List[BaseGeometry],
-            target_geoms: List[BaseGeometry],
-            obstacle_geoms: Union[List[BaseGeometry], None] = None,
-            densify_features: bool = False,
-            max_segment_length: Union[float, None] = None,
+        self,
+        source_geoms: List[BaseGeometry],
+        target_geoms: Union[List[BaseGeometry], None] = None,
+        obstacle_geoms: Union[List[BaseGeometry], None] = None,
+        densify_features: bool = False,
+        max_segment_length: Union[float, None] = None,
     ):
         """
-        Note: only Multipolygons, Polygons, and LineStrings are supported. It is assumed all
+         Note: only Multipolygons, Polygons, LineStrings and Points are supported. It is assumed all
         features are in the same projection.
 
-        :param source_geoms: List of Shapely geometries. We will test if these features are
-        adjacent to the target features.
-        :param target_geoms: List of Shapley geometries. We will
+        Args:
+            source_geoms (List[BaseGeometry]): List of Shapely geometries. We will which ones are adjacent to
+        which others, unless target_geoms is specified.
+            target_geoms (Union[List[BaseGeometry], None]), optional): list of Shapley geometries. if not None, We will
         test if these features are adjacent to the source features.
-        :param obstacle_geoms: List
+            obstacle_geoms (Union[List[BaseGeometry], None]), optional): List
         of Shapely geometries. These features will not be tested for adjacency, but they can
         prevent a source and target feature from being adjacent.
-        :param densify_features: If
+            densify_features (bool, optional):  If
         True, we will add additional points to the features to improve accuracy of the voronoi
-        diagram.
-        :param max_segment_length: The maximum distance between vertices that we want.
-        In projection units. densify_features must be True, or an error will be thrown. If
-        densify_features is True and max_segment_length is false, then the max_segment_length
+        diagram. If densify_features is True and max_segment_length is false, then the max_segment_length
         will be calculated based on the average segment length of all features, divided by 5.
-        This often works well.
+            max_segment_length (Union[float, None], optional): The maximum distance between vertices that we want.
+        In projection units. densify_features must be True, or an error will be thrown.
         """
 
         if max_segment_length and not densify_features:
@@ -147,38 +216,80 @@ class AdjacencyEngine:
                 "interpolate_points must be True if interpolation_distance is not None"
             )
 
-        self._source_features: Tuple[_Feature] = tuple([
-            _Feature(geom) for geom in source_geoms
-        ])
-        self._target_features: Tuple[_Feature] = tuple([
-            _Feature(geom) for geom in target_geoms
-        ])
-        self._obstacle_features: Union[Tuple[_Feature], None] = tuple([
-            _Feature(geom) for geom in obstacle_geoms
-        ])
-        self._adjacency_dict = None
-        self._feature_indices = None
+        self._source_features: Tuple[_Feature] = tuple(
+            [_Feature(geom) for geom in source_geoms]
+        )
+        self._target_features: Tuple[_Feature] = (
+            tuple([_Feature(geom) for geom in target_geoms])
+            if target_geoms
+            else tuple()
+        )
+        self._obstacle_features: Union[Tuple[_Feature], None] = (
+            tuple([_Feature(geom) for geom in obstacle_geoms])
+            if obstacle_geoms
+            else tuple()
+        )
+        self._adjacency_dict: Union[Dict[int, List[int]], None] = None
+        self._feature_indices: Union[Dict[int, int], None] = None
         self._vor = None
+        self._all_coordinates = None
 
         """All source, target, and obstacle features in a single list. The order of this list must
         not be changed."""
-        self.all_features: Tuple[_Feature, ...] = tuple([*self.source_features, *self.target_features,
-                                                         *self.obstacle_features])
+        self._all_features: Tuple[_Feature, ...] = tuple(
+            [*self.source_features, *self.target_features, *self.obstacle_features]
+        )
 
         if densify_features:
             if max_segment_length is None:
-                max_segment_length = self.calc_segmentation_dist()
-                logger.info("Calculated max_segment_length of %s" % max_segment_length)
+                max_segment_length = self._calc_segmentation_dist()
+                log.info("Calculated max_segment_length of %s" % max_segment_length)
 
             for feature in self.all_features:
-                feature.geometry = feature.geometry.segmentize(
-                    max_segment_length)
+                if not isinstance(feature.geometry, Point):
+                    feature.geometry = feature.geometry.segmentize(max_segment_length)
+            # Reset all coordinates
+            self._all_coordinates = None
+
+    @property
+    def all_features(self):
+        """
+        All source, target, and obstacle features in a single list. The order of this list must
+        not be changed. This property cannot be set manually.
 
-        self.all_coordinates: Tuple[Tuple[float, float]] = tuple(flatten_list(
-            [feature.coords for feature in self.all_features]
-        ))
+        Returns:
+            List[_Feature]: A list of _Features.
 
-    def calc_segmentation_dist(self, divisor=5):
+        """
+        return self._all_features
+
+    @all_features.setter
+    def all_features(self, value):
+        raise ImmutablePropertyError("Property all_features is immutable.")
+
+    @property
+    def all_coordinates(self):
+        """
+        All source, target, and obstacle coordinates in a single list. The order of this list must
+        not be changed. This property cannot be set manually.
+
+        Returns:
+            List[tuple[float, float]]: A list of coordinate tuples.
+        """
+
+        if not self._all_coordinates:
+            self._all_coordinates = []
+            for feature in self.all_features:
+                self._all_coordinates.extend(feature.coords)
+
+            self._all_coordinates = tuple(self._all_coordinates)
+        return self._all_coordinates
+
+    @all_coordinates.setter
+    def all_coordinates(self, value):
+        raise ImmutablePropertyError("Property all_coordinates is immutable.")
+
+    def _calc_segmentation_dist(self, divisor=5):
         """
         Try to create a well-fitting maximum length for all line segments in all features. Take
         the average distance between all coordinate pairs and divide by 5. This means that the
@@ -188,19 +299,18 @@ class AdjacencyEngine:
         average segment lengths. In that case, it is advisable to prepare the data appropriately
         beforehand.
 
-        :param divisor: Divide the average segment length by this number to get the new desired
+        Args:
+            divisor (int, optional): Divide the average segment length by this number to get the new desired
         segment length.
 
-        :return:
+        Returns:
+            float: Average segment length divided by divisor.
         """
 
-        all_coordinates = flatten_list(
-            [feature.coords for feature in self.all_features]
-        )
         return float(
             (
-                    sum(distance.pdist(all_coordinates, "euclidean"))
-                    / math.pow(len(all_coordinates), 2)
+                sum(distance.pdist(self.all_coordinates, "euclidean"))
+                / math.pow(len(self.all_coordinates), 2)
             )
             / divisor
         )
@@ -209,7 +319,10 @@ class AdjacencyEngine:
     def source_features(self) -> Tuple[_Feature]:
         """
         Features which will be the keys in the adjacency_dict.
-        :return: List of source features.
+
+        Returns:
+            List[_Feature]: A list of _Features.
+
         """
         return self._source_features
 
@@ -221,7 +334,8 @@ class AdjacencyEngine:
     def target_features(self) -> Tuple[_Feature]:
         """
         Features which will be the values in the adjacency_dict.
-        :return: List of target features.
+        Returns:
+            List[_Feature]: A list of _Features.
         """
         return self._target_features
 
@@ -234,14 +348,15 @@ class AdjacencyEngine:
         """
         Features which can prevent source and target features from being adjacent. They
         Do not participate in the adjacency_dict.
-        :return: List of obstacle features.
+
+        Returns:
+            List[_Feature]: A list of _Features.
         """
         return self._obstacle_features
 
     @obstacle_features.setter
     def obstacle_features(self, _):
-        raise ImmutablePropertyError(
-            "Property obstacle_features is immutable.")
+        raise ImmutablePropertyError("Property obstacle_features is immutable.")
 
     def get_feature_from_coord_index(self, coord_index: int) -> _Feature:
         """
@@ -250,8 +365,11 @@ class AdjacencyEngine:
         determine which coordinate belongs to which feature after we calculate the voronoi
         diagram.
 
-        :return: A _Feature.
+        Args:
+            coord_index (int): The index of the coordinate in self._all_coordinates
 
+        Returns:
+            _Feature: A _Feature at the given index.
         """
         if not self._feature_indices:
             self._feature_indices = {}
@@ -268,7 +386,9 @@ class AdjacencyEngine:
         """
         The Voronoi diagram object returned by Scipy. Useful primarily for debugging an
         adjacency analysis.
-        :return: Voronoi object.
+
+        Returns:
+            scipy.spatial.Voronoi: The Scipy Voronoi object.
         """
         if not self._vor:
             self._vor = Voronoi(np.array(self.all_coordinates))
@@ -278,50 +398,90 @@ class AdjacencyEngine:
     def vor(self, _):
         raise ImmutablePropertyError("Property vor is immutable.")
 
+    def _get_voronoi_vertex_idx_for_coord_idx(self, feature_coord_index: int) -> Generator[int, None, None]:
+        """
+        For a given feature coordinate index, return the indices of the voronoi vertices. Ignore
+        any "-1"s, which indicate vertices at infinity; these provide no adjacency information.
+
+        Args:
+            feature_coord_index (int): The index of the coordinate in self.all_coordinates
+
+        Returns:
+            Generator[int, None, None]: A generator of the indices of the voronoi vertices.
+        """
+        return (i for i in self.vor.regions[self.vor.point_region[feature_coord_index]] if i != -1)
+
+    def _tag_feature_with_voronoi_vertices(self):
+        """
+        Tag each feature with the vertices of the voronoi region it belongs to. Runs the
+        voronoi analysis if it has not been done already. This is broken out mostly for testing.
+        Do not call this function directly.
+
+        Returns:
+            None
+        """
+        # We don't need to tag obstacles with their voronoi vertices
+        obstacle_coord_len = sum(len(feat.coords) for feat in self.obstacle_features)
+
+        # Tag each feature with the vertices of the voronoi region it
+        # belongs to
+        for feature_coord_index in range(
+            len(self.all_coordinates) - obstacle_coord_len
+        ):
+            feature = self.get_feature_from_coord_index(feature_coord_index)
+            for i in self._get_voronoi_vertex_idx_for_coord_idx(feature_coord_index):
+                feature.voronoi_points.add(i)
+
+    def _determine_adjacency(
+        self, source_set: Tuple[_Feature], target_set: Tuple[_Feature]
+    ):
+        """
+        Determines the adjacency relationship between two sets of features.
+        Args:
+            source_set (Tuple[_Feature]): The set of source features.
+            target_set (Tuple[_Feature]): The set of target features.
+
+        Returns:
+            None
+        """
+        min_overlapping_voronoi_vertices = 2
+        for source_index, source_feature in enumerate(source_set):
+            for target_index, target_feature in enumerate(target_set):
+                if source_feature != target_feature and source_feature._is_adjacent(
+                    target_feature, min_overlapping_voronoi_vertices
+                ):
+                    self._adjacency_dict[source_index].append(target_index)
+
     def get_adjacency_dict(self) -> Dict[int, List[int]]:
         """
         Returns a dictionary of indices. They keys are the indices of feature_geoms. The values
         are the indices of any target geometries which are adjacent to the feature_geoms.
 
-        :return: dict A dictionary of indices. The keys are the indices of feature_geoms. The
-        values are the indices of any
+        If no targets were specified, then calculate adjacency between source features and other
+        source features.
+
+        Returns:
+            dict: A dictionary of indices. The keys are the indices of feature_geoms. The
+            values are the indices of any adjacent features.
+
         """
 
-        if self._adjacency_dict is None:
-            # We don't need to tag obstacles with their voronoi vertices
-            obstacle_coord_len = sum(
-                len(feat.coords) for feat in self.obstacle_features
-            )
+        """Note: We want adjacent features to have at least two overlapping vertices, otherwise we 
+        might call the features adjacent when their Voronoi regions don't share any edges."""
 
-            # Tag each feature with the vertices of the voronoi region it
-            # belongs to
-            for coord_index in range(
-                    len(self.all_coordinates) - obstacle_coord_len):
-                feature = self.get_feature_from_coord_index(coord_index)
-                for vor_vertex_index in self.vor.regions[
-                    self.vor.point_region[coord_index]
-                ]:
-                    # "-1" indices indicate the vertex goes to infinity. These don't provide us
-                    # with adjacency information, so we ignore them.
-                    if vor_vertex_index != -1:
-                        feature.voronoi_points.add(vor_vertex_index)
+        if self._adjacency_dict is None:
+            self._tag_feature_with_voronoi_vertices()
 
             # If any two features have any voronoi indices in common, then their voronoi regions
             # must intersect, therefore the input features are adjacent.
             self._adjacency_dict = defaultdict(list)
 
-            for coord_index, source_feature in enumerate(self.source_features):
-                for vor_region_index, target_feature in enumerate(
-                        self.target_features):
-                    if (
-                            len(
-                                source_feature.voronoi_points
-                                & target_feature.voronoi_points
-                            )
-                            > 1
-                    ):
-                        self._adjacency_dict[coord_index].append(
-                            vor_region_index)
+            # Get adjacency between source and target features
+            if len(self.target_features) > 0:
+                self._determine_adjacency(self.source_features, self.target_features)
+            # If no target specified, get adjacency between source and other source features.
+            else:
+                self._determine_adjacency(self.source_features, self.source_features)
 
         return self._adjacency_dict
 
@@ -329,32 +489,54 @@ class AdjacencyEngine:
         """
         Plot the adjacency linkages between the source and target with pyplot. Runs the analysis if
         it has not already been run.
-        :return: None
+
+        Returns:
+            None
         """
         # Plot the adjacency linkages between the source and target
-        for source_i, target_is in self.get_adjacency_dict().items():
-            source_poly = self.source_features[source_i].geometry
-            target_polys = [
-                self.target_features[target_i].geometry for target_i in
-                target_is
-            ]
-
-            # Plot the linestrings between the source and target polygons
-            links = [
-                LineString(
-                    [nearest_points(source_poly, target_poly)
-                     [1], source_poly.centroid]
-                )
-                for target_poly in target_polys
-            ]
-            add_geometry_to_plot(links, "green")
-
-        add_geometry_to_plot(
-            [t.geometry for t in self.target_features], "blue")
-        add_geometry_to_plot(
-            [t.geometry for t in self.source_features], "grey")
-        add_geometry_to_plot(
-            [t.geometry for t in self.obstacle_features], "red")
+        if len(self.target_features) > 0:
+            for source_i, target_is in self.get_adjacency_dict().items():
+                source_poly = self.source_features[source_i].geometry
+                target_polys = [
+                    self.target_features[target_i].geometry for target_i in target_is
+                ]
+
+                # Plot the linestrings between the source and target polygons
+                links = []
+                for target_poly in target_polys:
+                    if target_poly:
+                        try:
+                            links.append(
+                                LineString(
+                                    shapely.ops.nearest_points(target_poly, source_poly)
+                                )
+                            )
+                        except ValueError:
+                            log.error(
+                                f"Error creating link between '{target_poly}' and '{source_poly}'"
+                            )
+                add_geometry_to_plot(links, "green")
+
+        else:
+            for source_i, source_2_is in self.get_adjacency_dict().items():
+                source_poly = self.source_features[source_i].geometry
+                target_polys = [
+                    self.source_features[source_2_i].geometry
+                    for source_2_i in source_2_is
+                    if source_2_i > source_i
+                ]
+
+                # Plot the linestrings between the source and target polygons
+                links = [
+                    LineString([target_poly.centroid, source_poly.centroid])
+                    for target_poly in target_polys
+                    if target_poly is not None
+                ]
+                add_geometry_to_plot(links, "green")
+
+        add_geometry_to_plot([t.geometry for t in self.target_features], "blue")
+        add_geometry_to_plot([t.geometry for t in self.source_features], "grey")
+        add_geometry_to_plot([t.geometry for t in self.obstacle_features], "red")
 
         plt.title("Adjacency linkages between source and target")
         plt.xlabel("Longitude")

geo_adjacency/exception.py

@@ -2,9 +2,11 @@
 Custom exceptions.
 """
 
+
 class ImmutablePropertyError(BaseException):
     """
     Raise when a property is immutable because the setter does nothing.
     """
+
     def __init__(self, message):
         super().__init__(message)

geo_adjacency/utils.py

@@ -1,32 +1,120 @@
 """
-Convenience functions.
+Utility functions. These are designed for use in the AdjacencyEngine only, and should not be called
+by end users.
 """
 
+from typing import List, Tuple
+
 from matplotlib import pyplot as plt
 from shapely import Point, LineString, Polygon, MultiPolygon
 
 
-def flatten_list(list_of_lists):
+def coords_from_point(point: Point) -> List[Tuple[float, float]]:
+    """
+    Convert a Point into a tuple of (x, y). We put this inside a list for consistency with other
+    coordinate methods to allow us to seamlessly merge them later.
+
+    Args:
+        point (Point): A Shapely Point.
+
+    Returns:
+        List[Tuple[float, float]]: A list of coordinate tuples.
+
+    """
+    assert isinstance(point, Point), "Geometry must be a Point, not '%s'." % type(point)
+    return [(float(point.x), float(point.y))]
+
+
+def coords_from_ring(ring: LineString) -> List[Tuple[float, float]]:
+    """
+    Convert a LinearRing into a list of (x, y) tuples.
+
+    Args:
+        ring (LineString): A Shapely LinearString.
+
+    Returns:
+        List[Tuple[float, float]]: A list of coordinate tuples.
+    """
+    assert isinstance(
+        ring, LineString
+    ), "Geometry must be a LinearRing, not '%s'." % type(ring)
+    return [(float(coord[0]), float(coord[1])) for coord in ring.coords]
+
+
+def coords_from_polygon(polygon: Polygon) -> List[Tuple[float, float]]:
+    """
+    Convert a Polygon into a list of (x, y) tuples. Does not repeat the first coordinate to close
+    the ring.
+
+    Args:
+        polygon (Polygon): A Shapely Polygon.
+
+    Returns:
+        List[Tuple[float, float]]: A list of coordinate tuples.
+    """
+    assert isinstance(polygon, Polygon), "Geometry must be a Polygon, not '%s'." % type(
+        polygon
+    )
+    coords = []
+    coords.extend(coords_from_ring(polygon.exterior)[:-1])
+    for ring in polygon.interiors:
+        coords.extend(coords_from_ring(ring)[:-1])
+    return coords
+
+
+def coords_from_multipolygon(multipolygon: MultiPolygon) -> List[Tuple[float, float]]:
     """
-    Flattens a list of lists.
-    :param list_of_lists: The list of lists.
-    :return: A flattened list.
+    Convert a MultiPolygon into a list of (x, y) tuples. Does not repeat the first coordinate to
+    close the ring.
+
+    Args:
+        multipolygon (MultiPolygon): A Shapely MultiPolygon.
+
+    Returns:
+        List[Tuple[float, float]]: A list of coordinate tuples.
     """
-    flattened_list = []
+    assert isinstance(
+        multipolygon, MultiPolygon
+    ), "Geometry must be a MultiPolygon, not '%s'." % type(multipolygon)
+    coords = []
+    for polygon in multipolygon.geoms:
+        coords.extend(coords_from_polygon(polygon))
+    return coords
 
-    for sublist in list_of_lists:
-        for item in sublist:
-            flattened_list.append(item)
 
-    return flattened_list
+def flatten_list(nested_list) -> List:
+    """
+    Flatten a list of lists.
+    Args:
+        nested_list (List): A list of lists.
+
+    Returns:
+
+    """
+    # check if list is empty
+    if not bool(nested_list):
+        return nested_list
+
+    # to check instance of list is empty or not
+    if isinstance(nested_list[0], list):
+        # call function with sublist as argument
+        return flatten_list(*nested_list[:1]) + flatten_list(nested_list[1:])
+
+    # Call function with sublist as argument
+    return nested_list[:1] + flatten_list(nested_list[1:])
 
 
 def add_geometry_to_plot(geoms, color="black"):
     """
-    When updating the test data, it may be useful to visualize it.
-    :param geoms:
-    :param color:
-    :return:
+    When updating the test data, it may be useful to visualize it. Add a geometry to the global
+    maplotlib plt object. The next time we call plt.show(), this geometry will be plotted.
+
+    Args:
+        geoms (List[BaseGeometry]): A list of Shapely geometries.
+        color (str): The color we want the geometry to be in the plot.
+
+    Returns:
+        None
     """
     for geom in geoms:
         if isinstance(geom, Point):

{geo_adjacency-1.0.7.dist-info → geo_adjacency-1.1.2.dist-info}/METADATA

@@ -1,22 +1,32 @@
 Metadata-Version: 2.1
 Name: geo-adjacency
-Version: 1.0.7
-Summary: 
+Version: 1.1.2
+Summary: A package to determine which geometries are adjacent to each other, accounting for obstacles and gaps between features.
+Home-page: https://asmyth01.github.io/geo-adjacency/
 License: MIT
+Keywords: voronoi,adjacency,geospatial,geometry
 Author: Andrew Smyth
-Author-email: andrews@zillowgroup.com
+Author-email: andrew.j.smyth.89@gmail.com
 Requires-Python: >=3.9,<3.13
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
 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
+Classifier: Topic :: Scientific/Engineering :: GIS
 Requires-Dist: matplotlib (>=3.8.1,<4.0.0)
 Requires-Dist: numpy (>=1.26.2,<2.0.0)
 Requires-Dist: scipy (>=1.11.3,<2.0.0)
 Requires-Dist: setuptools (>=69.0.0,<70.0.0)
 Requires-Dist: shapely (>=2.0.2,<3.0.0)
+Project-URL: Documentation, https://asmyth01.github.io/geo-adjacency/
+Project-URL: Repository, https://github.com/andrewsmyth/geo-adjacency
 Description-Content-Type: text/markdown
 
 # Geo-Adjacency

geo_adjacency-1.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+geo_adjacency/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+geo_adjacency/adjacency.py,sha256=bL6ErCwgtpvNu0XfgpQwCJ6RlK2M-vi-qx_veE1_0Rk,20844
+geo_adjacency/exception.py,sha256=zZNdBOm5LpuiCpNuqH1FNLhiPnQqyCyuhOTMBDnLSTQ,230
+geo_adjacency/utils.py,sha256=57Q-nRZQlW1QetlLoucbDr1jm3CRHYRCVzrarm7xxZw,4188
+geo_adjacency-1.1.2.dist-info/LICENSE,sha256=p0PMGdB2iuOndKPbBCVhTNe9TMIxZRpJ64bQ_CoUIqY,1065
+geo_adjacency-1.1.2.dist-info/METADATA,sha256=fpHyeHH726bndsYxfE_CWAtJLmBN9MlN3lFiraRX8PA,3857
+geo_adjacency-1.1.2.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+geo_adjacency-1.1.2.dist-info/RECORD,,

geo_adjacency/file.log

@@ -1,10 +0,0 @@
-2023-11-20 19:19:58,755 - __main__ - ERROR - This is an error
-2023-11-20 19:21:23,871 - __main__ - ERROR - This is an error
-2023-11-20 19:22:38,493 - __main__ - ERROR - This is an error
-2023-11-20 19:22:48,026 - __main__ - ERROR - This is an error
-2023-11-20 19:23:34,369 - __main__ - ERROR - This is an error
-2023-11-20 19:23:44,297 - __main__ - ERROR - This is an error
-2023-11-20 19:26:28,000 - __main__ - ERROR - This is an error
-2023-11-20 19:26:58,737 - __main__ - ERROR - This is an error
-2023-11-20 19:28:41,686 - __main__ - ERROR - This is an error
-2023-11-20 19:29:03,485 - __main__ - ERROR - This is an error

geo_adjacency-1.0.7.dist-info/RECORD

@@ -1,9 +0,0 @@
-geo_adjacency/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-geo_adjacency/adjacency.py,sha256=vonZw4pZDkuAR_-zWO2zEflsvvepG9njT5APFGnMW2M,14201
-geo_adjacency/exception.py,sha256=-1fdZVR8LayIJmu3Zj2CA-5ItuFH-mOONPCe4g5M6l8,228
-geo_adjacency/file.log,sha256=Zc7rMTU9N_LJKx68zsOwDJcuTnD8Mxll3iHlmZWQUzg,620
-geo_adjacency/utils.py,sha256=gqAV-0tE_P5VIAorJc92u0-jUM-POlcaJnAzFDxcbEk,1333
-geo_adjacency-1.0.7.dist-info/LICENSE,sha256=p0PMGdB2iuOndKPbBCVhTNe9TMIxZRpJ64bQ_CoUIqY,1065
-geo_adjacency-1.0.7.dist-info/METADATA,sha256=PEmj1BtFUJ80Ux5m0V86ayNUzqWR2rLcGJKfsVP7WuI,3215
-geo_adjacency-1.0.7.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
-geo_adjacency-1.0.7.dist-info/RECORD,,