AndroidRemoteController/python/py/Lib/site-packages/shapely/measurement.py

"""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)