336 lines
10 KiB
Python
336 lines
10 KiB
Python
import warnings
|
|
|
|
import numpy as np
|
|
|
|
from . import lib
|
|
from .decorators import multithreading_enabled, requires_geos
|
|
|
|
__all__ = [
|
|
"area",
|
|
"distance",
|
|
"bounds",
|
|
"total_bounds",
|
|
"length",
|
|
"hausdorff_distance",
|
|
"frechet_distance",
|
|
"minimum_clearance",
|
|
"minimum_bounding_radius",
|
|
]
|
|
|
|
|
|
@multithreading_enabled
|
|
def area(geometry, **kwargs):
|
|
"""Computes the area of a (multi)polygon.
|
|
|
|
Parameters
|
|
----------
|
|
geometry : Geometry or array_like
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
`NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
|
|
|
|
Examples
|
|
--------
|
|
>>> from shapely import MultiPolygon, Polygon
|
|
>>> polygon = Polygon([(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)])
|
|
>>> area(polygon)
|
|
100.0
|
|
>>> area(MultiPolygon([polygon, Polygon([(10, 10), (10, 20), (20, 20), (20, 10), (10, 10)])]))
|
|
200.0
|
|
>>> area(Polygon())
|
|
0.0
|
|
>>> area(None)
|
|
nan
|
|
"""
|
|
return lib.area(geometry, **kwargs)
|
|
|
|
|
|
@multithreading_enabled
|
|
def distance(a, b, **kwargs):
|
|
"""Computes the Cartesian distance between two geometries.
|
|
|
|
Parameters
|
|
----------
|
|
a, b : Geometry or array_like
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
`NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
|
|
|
|
Examples
|
|
--------
|
|
>>> from shapely import LineString, Point, Polygon
|
|
>>> point = Point(0, 0)
|
|
>>> distance(Point(10, 0), point)
|
|
10.0
|
|
>>> distance(LineString([(1, 1), (1, -1)]), point)
|
|
1.0
|
|
>>> distance(Polygon([(3, 0), (5, 0), (5, 5), (3, 5), (3, 0)]), point)
|
|
3.0
|
|
>>> distance(Point(), point)
|
|
nan
|
|
>>> distance(None, point)
|
|
nan
|
|
"""
|
|
return lib.distance(a, b, **kwargs)
|
|
|
|
|
|
@multithreading_enabled
|
|
def bounds(geometry, **kwargs):
|
|
"""Computes 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
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
`NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
|
|
|
|
Examples
|
|
--------
|
|
>>> from shapely import LineString, Point, Polygon
|
|
>>> bounds(Point(2, 3)).tolist()
|
|
[2.0, 3.0, 2.0, 3.0]
|
|
>>> bounds(LineString([(0, 0), (0, 2), (3, 2)])).tolist()
|
|
[0.0, 0.0, 3.0, 2.0]
|
|
>>> bounds(Polygon()).tolist()
|
|
[nan, nan, nan, nan]
|
|
>>> bounds(None).tolist()
|
|
[nan, nan, nan, nan]
|
|
"""
|
|
# We need to provide the `out` argument here for compatibility with
|
|
# numpy < 1.16. See https://github.com/numpy/numpy/issues/14949
|
|
geometry_arr = np.asarray(geometry, dtype=np.object_)
|
|
out = np.empty(geometry_arr.shape + (4,), dtype="float64")
|
|
return lib.bounds(geometry_arr, out=out, **kwargs)
|
|
|
|
|
|
def total_bounds(geometry, **kwargs):
|
|
"""Computes the total bounds (extent) of the geometry.
|
|
|
|
Parameters
|
|
----------
|
|
geometry : Geometry or array_like
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
`NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
|
|
|
|
Returns
|
|
-------
|
|
numpy ndarray of [xmin, ymin, xmax, ymax]
|
|
|
|
Examples
|
|
--------
|
|
>>> from shapely import LineString, Point, Polygon
|
|
>>> total_bounds(Point(2, 3)).tolist()
|
|
[2.0, 3.0, 2.0, 3.0]
|
|
>>> total_bounds([Point(2, 3), Point(4, 5)]).tolist()
|
|
[2.0, 3.0, 4.0, 5.0]
|
|
>>> 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]
|
|
>>> total_bounds(Polygon()).tolist()
|
|
[nan, nan, nan, nan]
|
|
>>> total_bounds([Polygon(), Point(2, 3)]).tolist()
|
|
[2.0, 3.0, 2.0, 3.0]
|
|
>>> 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):
|
|
"""Computes the length of a (multi)linestring or polygon perimeter.
|
|
|
|
Parameters
|
|
----------
|
|
geometry : Geometry or array_like
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
`NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
|
|
|
|
Examples
|
|
--------
|
|
>>> from shapely import LineString, MultiLineString, Polygon
|
|
>>> length(LineString([(0, 0), (0, 2), (3, 2)]))
|
|
5.0
|
|
>>> length(MultiLineString([
|
|
... LineString([(0, 0), (1, 0)]),
|
|
... LineString([(1, 0), (2, 0)])
|
|
... ]))
|
|
2.0
|
|
>>> length(Polygon([(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)]))
|
|
40.0
|
|
>>> length(LineString())
|
|
0.0
|
|
>>> 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
|
|
densify : float or array_like, optional
|
|
The value of densify is required to be between 0 and 1.
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
`NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
|
|
|
|
Examples
|
|
--------
|
|
>>> from shapely import LineString
|
|
>>> line1 = LineString([(130, 0), (0, 0), (0, 150)])
|
|
>>> line2 = LineString([(10, 10), (10, 150), (130, 10)])
|
|
>>> hausdorff_distance(line1, line2) # doctest: +ELLIPSIS
|
|
14.14...
|
|
>>> hausdorff_distance(line1, line2, densify=0.5)
|
|
70.0
|
|
>>> hausdorff_distance(line1, LineString())
|
|
nan
|
|
>>> 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)
|
|
|
|
|
|
@requires_geos("3.7.0")
|
|
@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
|
|
densify : float or array_like, optional
|
|
The value of densify is required to be between 0 and 1.
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
`NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
|
|
|
|
Examples
|
|
--------
|
|
>>> from shapely import LineString
|
|
>>> line1 = LineString([(0, 0), (100, 0)])
|
|
>>> line2 = LineString([(0, 0), (50, 50), (100, 0)])
|
|
>>> frechet_distance(line1, line2) # doctest: +ELLIPSIS
|
|
70.71...
|
|
>>> frechet_distance(line1, line2, densify=0.5)
|
|
50.0
|
|
>>> frechet_distance(line1, LineString())
|
|
nan
|
|
>>> 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)
|
|
|
|
|
|
@requires_geos("3.6.0")
|
|
@multithreading_enabled
|
|
def minimum_clearance(geometry, **kwargs):
|
|
"""Computes 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
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
`NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
|
|
|
|
Examples
|
|
--------
|
|
>>> from shapely import Polygon
|
|
>>> polygon = Polygon([(0, 0), (0, 10), (5, 6), (10, 10), (10, 0), (5, 4), (0, 0)])
|
|
>>> minimum_clearance(polygon)
|
|
2.0
|
|
>>> minimum_clearance(Polygon())
|
|
inf
|
|
>>> minimum_clearance(None)
|
|
nan
|
|
"""
|
|
return lib.minimum_clearance(geometry, **kwargs)
|
|
|
|
|
|
@requires_geos("3.8.0")
|
|
@multithreading_enabled
|
|
def minimum_bounding_radius(geometry, **kwargs):
|
|
"""Computes the radius of the minimum bounding circle that encloses an input geometry.
|
|
|
|
Parameters
|
|
----------
|
|
geometry : Geometry or array_like
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
`NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
|
|
|
|
|
|
Examples
|
|
--------
|
|
>>> from shapely import GeometryCollection, LineString, MultiPoint, Point, Polygon
|
|
>>> minimum_bounding_radius(Polygon([(0, 5), (5, 10), (10, 5), (5, 0), (0, 5)]))
|
|
5.0
|
|
>>> minimum_bounding_radius(LineString([(1, 1), (1, 10)]))
|
|
4.5
|
|
>>> minimum_bounding_radius(MultiPoint([(2, 2), (4, 2)]))
|
|
1.0
|
|
>>> minimum_bounding_radius(Point(0, 1))
|
|
0.0
|
|
>>> minimum_bounding_radius(GeometryCollection())
|
|
0.0
|
|
|
|
See also
|
|
--------
|
|
minimum_bounding_circle
|
|
"""
|
|
return lib.minimum_bounding_radius(geometry, **kwargs)
|