structure saas with tools

.venv/lib/python3.10/site-packages/shapely/measurement.py

@@ -0,0 +1,355 @@
+"""Methods for measuring (between) geometries."""
+
+import warnings
+
+import numpy as np
+
+from shapely import lib
+from shapely.decorators import multithreading_enabled
+
+__all__ = [
+    "area",
+    "bounds",
+    "distance",
+    "frechet_distance",
+    "hausdorff_distance",
+    "length",
+    "minimum_bounding_radius",
+    "minimum_clearance",
+    "total_bounds",
+]
+
+
+@multithreading_enabled
+def area(geometry, **kwargs):
+    """Compute the area of a (multi)polygon.
+
+    Parameters
+    ----------
+    geometry : Geometry or array_like
+        Geometry or geometries for which to compute the area.
+    **kwargs
+        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
+
+    Examples
+    --------
+    >>> import shapely
+    >>> from shapely import MultiPolygon, Polygon
+    >>> polygon = Polygon([(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)])
+    >>> shapely.area(polygon)
+    100.0
+    >>> polygon2 = Polygon([(10, 10), (10, 20), (20, 20), (20, 10), (10, 10)])
+    >>> shapely.area(MultiPolygon([polygon, polygon2]))
+    200.0
+    >>> shapely.area(Polygon())
+    0.0
+    >>> shapely.area(None)
+    nan
+
+    """
+    return lib.area(geometry, **kwargs)
+
+
+@multithreading_enabled
+def distance(a, b, **kwargs):
+    """Compute the Cartesian distance between two geometries.
+
+    Parameters
+    ----------
+    a, b : Geometry or array_like
+        Geometry or geometries to compute the distance between.
+    **kwargs
+        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
+
+    Examples
+    --------
+    >>> import shapely
+    >>> from shapely import LineString, Point, Polygon
+    >>> point = Point(0, 0)
+    >>> shapely.distance(Point(10, 0), point)
+    10.0
+    >>> shapely.distance(LineString([(1, 1), (1, -1)]), point)
+    1.0
+    >>> shapely.distance(Polygon([(3, 0), (5, 0), (5, 5), (3, 5), (3, 0)]), point)
+    3.0
+    >>> shapely.distance(Point(), point)
+    nan
+    >>> shapely.distance(None, point)
+    nan
+
+    """
+    return lib.distance(a, b, **kwargs)
+
+
+@multithreading_enabled
+def bounds(geometry, **kwargs):
+    """Compute the bounds (extent) of a geometry.
+
+    For each geometry these 4 numbers are returned: min x, min y, max x, max y.
+
+    Parameters
+    ----------
+    geometry : Geometry or array_like
+        Geometry or geometries for which to compute the bounds.
+    **kwargs
+        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
+
+    Examples
+    --------
+    >>> import shapely
+    >>> from shapely import LineString, Point, Polygon
+    >>> shapely.bounds(Point(2, 3)).tolist()
+    [2.0, 3.0, 2.0, 3.0]
+    >>> shapely.bounds(LineString([(0, 0), (0, 2), (3, 2)])).tolist()
+    [0.0, 0.0, 3.0, 2.0]
+    >>> shapely.bounds(Polygon()).tolist()
+    [nan, nan, nan, nan]
+    >>> shapely.bounds(None).tolist()
+    [nan, nan, nan, nan]
+
+    """
+    return lib.bounds(geometry, **kwargs)
+
+
+def total_bounds(geometry, **kwargs):
+    """Compute the total bounds (extent) of the geometry.
+
+    Parameters
+    ----------
+    geometry : Geometry or array_like
+        Geometry or geometries for which to compute the total bounds.
+    **kwargs
+        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
+
+    Returns
+    -------
+    numpy ndarray of [xmin, ymin, xmax, ymax]
+
+    Examples
+    --------
+    >>> import shapely
+    >>> from shapely import LineString, Point, Polygon
+    >>> shapely.total_bounds(Point(2, 3)).tolist()
+    [2.0, 3.0, 2.0, 3.0]
+    >>> shapely.total_bounds([Point(2, 3), Point(4, 5)]).tolist()
+    [2.0, 3.0, 4.0, 5.0]
+    >>> shapely.total_bounds([
+    ...     LineString([(0, 1), (0, 2), (3, 2)]),
+    ...     LineString([(4, 4), (4, 6), (6, 7)])
+    ... ]).tolist()
+    [0.0, 1.0, 6.0, 7.0]
+    >>> shapely.total_bounds(Polygon()).tolist()
+    [nan, nan, nan, nan]
+    >>> shapely.total_bounds([Polygon(), Point(2, 3)]).tolist()
+    [2.0, 3.0, 2.0, 3.0]
+    >>> shapely.total_bounds(None).tolist()
+    [nan, nan, nan, nan]
+
+    """
+    b = bounds(geometry, **kwargs)
+    if b.ndim == 1:
+        return b
+
+    with warnings.catch_warnings():
+        # ignore 'All-NaN slice encountered' warnings
+        warnings.simplefilter("ignore", RuntimeWarning)
+        return np.array(
+            [
+                np.nanmin(b[..., 0]),
+                np.nanmin(b[..., 1]),
+                np.nanmax(b[..., 2]),
+                np.nanmax(b[..., 3]),
+            ]
+        )
+
+
+@multithreading_enabled
+def length(geometry, **kwargs):
+    """Compute the length of a (multi)linestring or polygon perimeter.
+
+    Parameters
+    ----------
+    geometry : Geometry or array_like
+        Geometry or geometries for which to compute the length.
+    **kwargs
+        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
+
+    Examples
+    --------
+    >>> import shapely
+    >>> from shapely import LineString, MultiLineString, Polygon
+    >>> shapely.length(LineString([(0, 0), (0, 2), (3, 2)]))
+    5.0
+    >>> shapely.length(MultiLineString([
+    ...     LineString([(0, 0), (1, 0)]),
+    ...     LineString([(1, 0), (2, 0)])
+    ... ]))
+    2.0
+    >>> shapely.length(Polygon([(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)]))
+    40.0
+    >>> shapely.length(LineString())
+    0.0
+    >>> shapely.length(None)
+    nan
+
+    """
+    return lib.length(geometry, **kwargs)
+
+
+@multithreading_enabled
+def hausdorff_distance(a, b, densify=None, **kwargs):
+    """Compute the discrete Hausdorff distance between two geometries.
+
+    The Hausdorff distance is a measure of similarity: it is the greatest
+    distance between any point in A and the closest point in B. The discrete
+    distance is an approximation of this metric: only vertices are considered.
+    The parameter 'densify' makes this approximation less coarse by splitting
+    the line segments between vertices before computing the distance.
+
+    Parameters
+    ----------
+    a, b : Geometry or array_like
+        Geometry or geometries to compute the distance between.
+    densify : float or array_like, optional
+        The value of densify is required to be between 0 and 1.
+    **kwargs
+        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
+
+    Examples
+    --------
+    >>> import shapely
+    >>> from shapely import LineString
+    >>> line1 = LineString([(130, 0), (0, 0), (0, 150)])
+    >>> line2 = LineString([(10, 10), (10, 150), (130, 10)])
+    >>> shapely.hausdorff_distance(line1, line2)
+    14.142135623730951
+    >>> shapely.hausdorff_distance(line1, line2, densify=0.5)
+    70.0
+    >>> shapely.hausdorff_distance(line1, LineString())
+    nan
+    >>> shapely.hausdorff_distance(line1, None)
+    nan
+
+    """
+    if densify is None:
+        return lib.hausdorff_distance(a, b, **kwargs)
+    else:
+        return lib.hausdorff_distance_densify(a, b, densify, **kwargs)
+
+
+@multithreading_enabled
+def frechet_distance(a, b, densify=None, **kwargs):
+    """Compute the discrete Fréchet distance between two geometries.
+
+    The Fréchet distance is a measure of similarity: it is the greatest
+    distance between any point in A and the closest point in B. The discrete
+    distance is an approximation of this metric: only vertices are considered.
+    The parameter 'densify' makes this approximation less coarse by splitting
+    the line segments between vertices before computing the distance.
+
+    Fréchet distance sweep continuously along their respective curves
+    and the direction of curves is significant. This makes it a better measure
+    of similarity than Hausdorff distance for curve or surface matching.
+
+    Parameters
+    ----------
+    a, b : Geometry or array_like
+        Geometry or geometries to compute the distance between.
+    densify : float or array_like, optional
+        The value of densify is required to be between 0 and 1.
+    **kwargs
+        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
+
+    Examples
+    --------
+    >>> import shapely
+    >>> from shapely import LineString
+    >>> line1 = LineString([(0, 0), (100, 0)])
+    >>> line2 = LineString([(0, 0), (50, 50), (100, 0)])
+    >>> shapely.frechet_distance(line1, line2)
+    70.71067811865476
+    >>> shapely.frechet_distance(line1, line2, densify=0.5)
+    50.0
+    >>> shapely.frechet_distance(line1, LineString())
+    nan
+    >>> shapely.frechet_distance(line1, None)
+    nan
+
+    """
+    if densify is None:
+        return lib.frechet_distance(a, b, **kwargs)
+    return lib.frechet_distance_densify(a, b, densify, **kwargs)
+
+
+@multithreading_enabled
+def minimum_clearance(geometry, **kwargs):
+    """Compute the Minimum Clearance distance.
+
+    A geometry's "minimum clearance" is the smallest distance by which
+    a vertex of the geometry could be moved to produce an invalid geometry.
+
+    If no minimum clearance exists for a geometry (for example, a single
+    point, or an empty geometry), infinity is returned.
+
+    Parameters
+    ----------
+    geometry : Geometry or array_like
+        Geometry or geometries for which to compute the minimum clearance.
+    **kwargs
+        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
+
+    Examples
+    --------
+    >>> import shapely
+    >>> from shapely import Polygon
+    >>> polygon = Polygon([(0, 0), (0, 10), (5, 6), (10, 10), (10, 0), (5, 4), (0, 0)])
+    >>> shapely.minimum_clearance(polygon)
+    2.0
+    >>> shapely.minimum_clearance(Polygon())
+    inf
+    >>> shapely.minimum_clearance(None)
+    nan
+
+    See Also
+    --------
+    minimum_clearance_line
+
+    """
+    return lib.minimum_clearance(geometry, **kwargs)
+
+
+@multithreading_enabled
+def minimum_bounding_radius(geometry, **kwargs):
+    """Compute the radius of the minimum bounding circle of an input geometry.
+
+    Parameters
+    ----------
+    geometry : Geometry or array_like
+        Geometry or geometries for which to compute the minimum bounding radius.
+    **kwargs
+        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
+
+
+    Examples
+    --------
+    >>> import shapely
+    >>> from shapely import GeometryCollection, LineString, MultiPoint, Point, Polygon
+    >>> shapely.minimum_bounding_radius(
+    ...     Polygon([(0, 5), (5, 10), (10, 5), (5, 0), (0, 5)])
+    ... )
+    5.0
+    >>> shapely.minimum_bounding_radius(LineString([(1, 1), (1, 10)]))
+    4.5
+    >>> shapely.minimum_bounding_radius(MultiPoint([(2, 2), (4, 2)]))
+    1.0
+    >>> shapely.minimum_bounding_radius(Point(0, 1))
+    0.0
+    >>> shapely.minimum_bounding_radius(GeometryCollection())
+    0.0
+
+    See Also
+    --------
+    minimum_bounding_circle
+
+    """
+    return lib.minimum_bounding_radius(geometry, **kwargs)