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

"""Methods that yield new objects not derived from set-theoretic analysis."""

import numpy as np

from shapely import lib
from shapely._enum import ParamEnum
from shapely.algorithms._oriented_envelope import _oriented_envelope_min_area_vectorized
from shapely.algorithms.cga import _orient_polygons_vectorized
from shapely.decorators import (
    deprecate_positional,
    multithreading_enabled,
    requires_geos,
)
from shapely.errors import UnsupportedGEOSVersionError

__all__ = [
    "BufferCapStyle",
    "BufferJoinStyle",
    "boundary",
    "buffer",
    "build_area",
    "centroid",
    "clip_by_rect",
    "concave_hull",
    "constrained_delaunay_triangles",
    "convex_hull",
    "delaunay_triangles",
    "envelope",
    "extract_unique_points",
    "make_valid",
    "maximum_inscribed_circle",
    "minimum_bounding_circle",
    "minimum_clearance_line",
    "minimum_rotated_rectangle",
    "node",
    "normalize",
    "offset_curve",
    "orient_polygons",
    "oriented_envelope",
    "point_on_surface",
    "polygonize",
    "polygonize_full",
    "remove_repeated_points",
    "reverse",
    "segmentize",
    "simplify",
    "snap",
    "voronoi_polygons",
]


class BufferCapStyle(ParamEnum):
    """Enumeration of buffer cap styles.

    Attributes
    ----------
    round : int
        Represents a round cap style.
    flat : int
        Represents a flat cap style.
    square : int
        Represents a square cap style.

    """

    round = 1
    flat = 2
    square = 3


class BufferJoinStyle(ParamEnum):
    """Enumeration of buffer join styles.

    Attributes
    ----------
    round : int
        Specifies a round join style.
    mitre : int
        Specifies a mitre join style.
    bevel : int
        Specifies a bevel join style.

    """

    round = 1
    mitre = 2
    bevel = 3


@multithreading_enabled
def boundary(geometry, **kwargs):
    """Return the topological boundary of a geometry.

    This function will return None for geometrycollections.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry for which to return the boundary.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import GeometryCollection, LinearRing, LineString, \
MultiLineString, MultiPoint, Point, Polygon
    >>> shapely.boundary(Point(0, 0))
    <GEOMETRYCOLLECTION EMPTY>
    >>> shapely.boundary(LineString([(0, 0), (1, 1), (1, 2)]))
    <MULTIPOINT ((0 0), (1 2))>
    >>> shapely.boundary(LinearRing([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]))
    <MULTIPOINT EMPTY>
    >>> shapely.boundary(Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]))
    <LINESTRING (0 0, 1 0, 1 1, 0 1, 0 0)>
    >>> shapely.boundary(MultiPoint([(0, 0), (1, 2)]))
    <GEOMETRYCOLLECTION EMPTY>
    >>> shapely.boundary(MultiLineString([[(0, 0), (1, 1)], [(0, 1), (1, 0)]]))
    <MULTIPOINT ((0 0), (0 1), (1 0), (1 1))>
    >>> shapely.boundary(GeometryCollection([Point(0, 0)])) is None
    True

    """
    return lib.boundary(geometry, **kwargs)


# Note: future plan is to change this signature over a few releases:
# shapely 2.0:
#   buffer(geometry, distance, quad_segs=8, ...)
# shapely 2.1: shows deprecation warning about positional 'quad_segs', etc.
#   same signature as 2.0
# shapely 2.2(?): enforce keyword-only arguments after 'distance'
#   buffer(geometry, distance, *, quad_segs=8, ...)


@deprecate_positional(
    ["quad_segs", "cap_style", "join_style", "mitre_limit", "single_sided"],
    category=DeprecationWarning,
)
@multithreading_enabled
def buffer(
    geometry,
    distance,
    quad_segs=8,
    cap_style="round",
    join_style="round",
    mitre_limit=5.0,
    single_sided=False,
    **kwargs,
):
    """Compute the buffer of a geometry for positive and negative buffer distance.

    The buffer of a geometry is defined as the Minkowski sum (or difference,
    for negative distance) of the geometry with a circle with radius equal
    to the absolute value of the buffer distance.

    The buffer operation always returns a polygonal result. The negative
    or zero-distance buffer of lines and points is always empty.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the buffer.
    distance : float or array_like
        Specifies the circle radius in the Minkowski sum (or difference).
    quad_segs : int, default 8
        Specifies the number of linear segments in a quarter circle in the
        approximation of circular arcs.
    cap_style : shapely.BufferCapStyle or {'round', 'square', 'flat'}, default 'round'
        Specifies the shape of buffered line endings. BufferCapStyle.round ('round')
        results in circular line endings (see ``quad_segs``). Both BufferCapStyle.square
        ('square') and BufferCapStyle.flat ('flat') result in rectangular line endings,
        only BufferCapStyle.flat ('flat') will end at the original vertex,
        while BufferCapStyle.square ('square') involves adding the buffer width.
    join_style : shapely.BufferJoinStyle or {'round', 'mitre', 'bevel'}, default 'round'
        Specifies the shape of buffered line midpoints. BufferJoinStyle.round ('round')
        results in rounded shapes. BufferJoinStyle.bevel ('bevel') results in a beveled
        edge that touches the original vertex. BufferJoinStyle.mitre ('mitre') results
        in a single vertex that is beveled depending on the ``mitre_limit`` parameter.
    mitre_limit : float, default 5.0
        Crops of 'mitre'-style joins if the point is displaced from the
        buffered vertex by more than this limit.
    single_sided : bool, default False
        Only buffer at one side of the geometry.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Notes
    -----

    .. deprecated:: 2.1.0
        A deprecation warning is shown if ``quad_segs``,  ``cap_style``,
        ``join_style``, ``mitre_limit`` or ``single_sided`` are
        specified as positional arguments. In a future release, these will
        need to be specified as keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Point, Polygon, BufferCapStyle, BufferJoinStyle
    >>> shapely.buffer(Point(10, 10), 2, quad_segs=1)
    <POLYGON ((12 10, 10 8, 8 10, 10 12, 12 10))>
    >>> shapely.buffer(Point(10, 10), 2, quad_segs=2)
    <POLYGON ((12 10, 11.414 8.586, 10 8, 8.586 8.586, 8 10, 8.5...>
    >>> shapely.buffer(Point(10, 10), -2, quad_segs=1)
    <POLYGON EMPTY>
    >>> line = LineString([(10, 10), (20, 10)])
    >>> shapely.buffer(line, 2, cap_style="square")
    <POLYGON ((20 12, 22 12, 22 8, 10 8, 8 8, 8 12, 20 12))>
    >>> shapely.buffer(line, 2, cap_style="flat")
    <POLYGON ((20 12, 20 8, 10 8, 10 12, 20 12))>
    >>> shapely.buffer(line, 2, single_sided=True, cap_style="flat")
    <POLYGON ((20 10, 10 10, 10 12, 20 12, 20 10))>
    >>> line2 = LineString([(10, 10), (20, 10), (20, 20)])
    >>> shapely.buffer(line2, 2, cap_style="flat", join_style="bevel")
    <POLYGON ((18 12, 18 20, 22 20, 22 10, 20 8, 10 8, 10 12, 18 12))>
    >>> shapely.buffer(line2, 2, cap_style="flat", join_style="mitre")
    <POLYGON ((18 12, 18 20, 22 20, 22 8, 10 8, 10 12, 18 12))>
    >>> shapely.buffer(line2, 2, cap_style="flat", join_style="mitre", mitre_limit=1)
    <POLYGON ((18 12, 18 20, 22 20, 22 9.172, 20.828 8, 10 8, 10 12, 18 12))>
    >>> square = Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)])
    >>> shapely.buffer(square, 2, join_style="mitre")
    <POLYGON ((-2 -2, -2 12, 12 12, 12 -2, -2 -2))>
    >>> shapely.buffer(square, -2, join_style="mitre")
    <POLYGON ((2 2, 2 8, 8 8, 8 2, 2 2))>
    >>> shapely.buffer(square, -5, join_style="mitre")
    <POLYGON EMPTY>
    >>> shapely.buffer(line, float("nan")) is None
    True

    """
    if isinstance(cap_style, str):
        cap_style = BufferCapStyle.get_value(cap_style)
    if isinstance(join_style, str):
        join_style = BufferJoinStyle.get_value(join_style)
    if not np.isscalar(quad_segs):
        raise TypeError("quad_segs only accepts scalar values")
    if not np.isscalar(cap_style):
        raise TypeError("cap_style only accepts scalar values")
    if not np.isscalar(join_style):
        raise TypeError("join_style only accepts scalar values")
    if not np.isscalar(mitre_limit):
        raise TypeError("mitre_limit only accepts scalar values")
    if not np.isscalar(single_sided):
        raise TypeError("single_sided only accepts scalar values")
    return lib.buffer(
        geometry,
        distance,
        np.intc(quad_segs),
        np.intc(cap_style),
        np.intc(join_style),
        mitre_limit,
        np.bool_(single_sided),
        **kwargs,
    )


# Note: future plan is to change this signature over a few releases:
# shapely 2.0:
#   offset_curve(geometry, distance, quad_segs=8, ...)
# shapely 2.1: shows deprecation warning about positional 'quad_segs', etc.
#   same signature as 2.0
# shapely 2.2(?): enforce keyword-only arguments after 'distance'
#   offset_curve(geometry, distance, *, quad_segs=8, ...)


@deprecate_positional(
    ["quad_segs", "join_style", "mitre_limit"], category=DeprecationWarning
)
@multithreading_enabled
def offset_curve(
    geometry, distance, quad_segs=8, join_style="round", mitre_limit=5.0, **kwargs
):
    """Return a (Multi)LineString at a distance from the object.

    For positive distance the offset will be at the left side of the input
    line. For a negative distance it will be at the right side. In general,
    this function tries to preserve the direction of the input.

    Note: the behaviour regarding orientation of the resulting line depends
    on the GEOS version. With GEOS < 3.11, the line retains the same
    direction for a left offset (positive distance) or has opposite direction
    for a right offset (negative distance), and this behaviour was documented
    as such in previous Shapely versions. Starting with GEOS 3.11, the
    function tries to preserve the orientation of the original line.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the offset.
    distance : float or array_like
        Specifies the offset distance from the input geometry. Negative
        for right side offset, positive for left side offset.
    quad_segs : int, default 8
        Specifies the number of linear segments in a quarter circle in the
        approximation of circular arcs.
    join_style : {'round', 'bevel', 'mitre'}, default 'round'
        Specifies the shape of outside corners. 'round' results in
        rounded shapes. 'bevel' results in a beveled edge that touches the
        original vertex. 'mitre' results in a single vertex that is beveled
        depending on the ``mitre_limit`` parameter.
    mitre_limit : float, default 5.0
        Crops of 'mitre'-style joins if the point is displaced from the
        buffered vertex by more than this limit.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Notes
    -----

    .. deprecated:: 2.1.0
        A deprecation warning is shown if ``quad_segs``, ``join_style`` or
        ``mitre_limit`` are specified as positional arguments. In a future
        release, these will need to be specified as keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString
    >>> line = LineString([(0, 0), (0, 2)])
    >>> shapely.offset_curve(line, 2)
    <LINESTRING (-2 0, -2 2)>
    >>> shapely.offset_curve(line, -2)
    <LINESTRING (2 0, 2 2)>

    """
    if isinstance(join_style, str):
        join_style = BufferJoinStyle.get_value(join_style)
    if not np.isscalar(quad_segs):
        raise TypeError("quad_segs only accepts scalar values")
    if not np.isscalar(join_style):
        raise TypeError("join_style only accepts scalar values")
    if not np.isscalar(mitre_limit):
        raise TypeError("mitre_limit only accepts scalar values")
    return lib.offset_curve(
        geometry,
        distance,
        np.intc(quad_segs),
        np.intc(join_style),
        np.double(mitre_limit),
        **kwargs,
    )


@multithreading_enabled
def centroid(geometry, **kwargs):
    """Compute the geometric center (center-of-mass) of a geometry.

    For multipoints this is computed as the mean of the input coordinates.
    For multilinestrings the centroid is weighted by the length of each
    line segment. For multipolygons the centroid is weighted by the area of
    each polygon.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the centroid.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, MultiPoint, Polygon
    >>> shapely.centroid(Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]))
    <POINT (5 5)>
    >>> shapely.centroid(LineString([(0, 0), (2, 2), (10, 10)]))
    <POINT (5 5)>
    >>> shapely.centroid(MultiPoint([(0, 0), (10, 10)]))
    <POINT (5 5)>
    >>> shapely.centroid(Polygon())
    <POINT EMPTY>

    """
    return lib.centroid(geometry, **kwargs)


@multithreading_enabled
def clip_by_rect(geometry, xmin, ymin, xmax, ymax, **kwargs):
    """Return the portion of a geometry within a rectangle.

    The geometry is clipped in a fast but possibly dirty way. The output is
    not guaranteed to be valid. No exceptions will be raised for topological
    errors.

    Note: empty geometries or geometries that do not overlap with the
    specified bounds will result in GEOMETRYCOLLECTION EMPTY.

    Parameters
    ----------
    geometry : Geometry or array_like
        The geometry to be clipped.
    xmin : float
        Minimum x value of the rectangle.
    ymin : float
        Minimum y value of the rectangle.
    xmax : float
        Maximum x value of the rectangle.
    ymax : float
        Maximum y value of the rectangle.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Polygon
    >>> line = LineString([(0, 0), (10, 10)])
    >>> shapely.clip_by_rect(line, 0., 0., 1., 1.)
    <LINESTRING (0 0, 1 1)>
    >>> polygon = Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)])
    >>> shapely.clip_by_rect(polygon, 0., 0., 1., 1.)
    <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>

    """
    if not all(np.isscalar(val) for val in [xmin, ymin, xmax, ymax]):
        raise TypeError("xmin/ymin/xmax/ymax only accepts scalar values")
    return lib.clip_by_rect(
        geometry,
        np.double(xmin),
        np.double(ymin),
        np.double(xmax),
        np.double(ymax),
        **kwargs,
    )


@requires_geos("3.11.0")
@multithreading_enabled
def concave_hull(geometry, ratio=0.0, allow_holes=False, **kwargs):
    """Compute a concave geometry that encloses an input geometry.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the concave hull.
    ratio : float, default 0.0
        Number in the range [0, 1]. Higher numbers will include fewer vertices
        in the hull.
    allow_holes : bool, default False
        If set to True, the concave hull may have holes.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import MultiPoint, Polygon
    >>> multi_point = MultiPoint([(0, 0), (0, 3), (1, 1), (3, 0), (3, 3)])
    >>> shapely.concave_hull(multi_point, ratio=0.1)
    <POLYGON ((0 0, 0 3, 1 1, 3 3, 3 0, 0 0))>
    >>> shapely.concave_hull(multi_point, ratio=1.0)
    <POLYGON ((0 0, 0 3, 3 3, 3 0, 0 0))>
    >>> shapely.concave_hull(Polygon())
    <POLYGON EMPTY>

    """
    if not np.isscalar(ratio):
        raise TypeError("ratio must be scalar")
    if not np.isscalar(allow_holes):
        raise TypeError("allow_holes must be scalar")
    return lib.concave_hull(geometry, np.double(ratio), np.bool_(allow_holes), **kwargs)


@multithreading_enabled
def convex_hull(geometry, **kwargs):
    """Compute the minimum convex geometry that encloses an input geometry.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the convex hull.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import MultiPoint, Polygon
    >>> shapely.convex_hull(MultiPoint([(0, 0), (10, 0), (10, 10)]))
    <POLYGON ((0 0, 10 10, 10 0, 0 0))>
    >>> shapely.convex_hull(Polygon())
    <GEOMETRYCOLLECTION EMPTY>

    """
    return lib.convex_hull(geometry, **kwargs)


@multithreading_enabled
def delaunay_triangles(geometry, tolerance=0.0, only_edges=False, **kwargs):
    """Compute a Delaunay triangulation around the vertices of an input geometry.

    The output is a geometrycollection containing polygons (default)
    or linestrings (see ``only_edges``). Returns an empty geometry for input
    geometries that contain less than 3 vertices.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the Delaunay triangulation.
    tolerance : float or array_like, default 0.0
        Snap input vertices together if their distance is less than this value.
    only_edges : bool or array_like, default False
        If set to True, the triangulation will return a collection of
        linestrings instead of polygons.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Returns
    -------
    GeometryCollection or array of GeometryCollections

    See Also
    --------
    constrained_delaunay_triangles

    Examples
    --------
    >>> import shapely
    >>> from shapely import GeometryCollection, LineString, MultiPoint, Polygon
    >>> points = MultiPoint([(50, 30), (60, 30), (100, 100)])
    >>> shapely.delaunay_triangles(points).normalize()
    <GEOMETRYCOLLECTION (POLYGON ((50 30, 100 100, 60 30, 50 30)))>
    >>> shapely.delaunay_triangles(points, only_edges=True)
    <MULTILINESTRING ((50 30, 100 100), (50 30, 60 30), ...>
    >>> shapely.delaunay_triangles(
    ...     MultiPoint([(50, 30), (51, 30), (60, 30), (100, 100)]),
    ...     tolerance=2
    ... ).normalize()
    <GEOMETRYCOLLECTION (POLYGON ((50 30, 100 100, 60 30, 50 30)))>
    >>> shapely.delaunay_triangles(Polygon([(50, 30), (60, 30), (100, 100), (50, 30)]))\
.normalize()
    <GEOMETRYCOLLECTION (POLYGON ((50 30, 100 100, 60 30, 50 30)))>
    >>> shapely.delaunay_triangles(LineString([(50, 30), (60, 30), (100, 100)]))\
.normalize()
    <GEOMETRYCOLLECTION (POLYGON ((50 30, 100 100, 60 30, 50 30)))>
    >>> shapely.delaunay_triangles(GeometryCollection([]))
    <GEOMETRYCOLLECTION EMPTY>

    """
    return lib.delaunay_triangles(geometry, tolerance, only_edges, **kwargs)


@requires_geos("3.10.0")
@multithreading_enabled
def constrained_delaunay_triangles(geometry, **kwargs):
    """Compute the constrained Delaunay triangulation of polygons.

    A constrained Delaunay triangulation requires the edges of the input
    polygon(s) to be in the set of resulting triangle edges. An unconstrained
    delaunay triangulation only triangulates based on the vertices, hence
    triangle edges could cross polygon boundaries.

    .. versionadded:: 2.1.0

    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
    -------
    GeometryCollection or array of GeometryCollections
        * GeometryCollection of polygons, given polygonal input
        * Empty GeometryCollection, given non-polygonal input

    See Also
    --------
    delaunay_triangles

    Examples
    --------
    >>> import shapely
    >>> from shapely import MultiPoint, MultiPolygon, Polygon
    >>> shapely.constrained_delaunay_triangles(Polygon([(10, 10), (20, 40), (90, 90), (90, 10), (10, 10)]))
    <GEOMETRYCOLLECTION (POLYGON ((90 10, 20 40, 90 90, 90 10)), POLYGON ((20 40...>
    >>> shapely.constrained_delaunay_triangles(Polygon())
    <GEOMETRYCOLLECTION EMPTY>
    >>> shapely.constrained_delaunay_triangles(MultiPolygon([Polygon(((50, 30), (60, 30), (100, 100), (50, 30))), Polygon(((10, 10), (20, 40), (90, 90), (90, 10), (10, 10)))]))
    <GEOMETRYCOLLECTION (POLYGON ((50 30, 100 100, 60 30, 50 30)), POLYGON ((90 ...>
    >>> shapely.constrained_delaunay_triangles(MultiPolygon())
    <GEOMETRYCOLLECTION EMPTY>
    >>> shapely.constrained_delaunay_triangles(MultiPoint([(50, 30), (51, 30), (60, 30), (100, 100)]))
    <GEOMETRYCOLLECTION EMPTY>

    """  # noqa: E501
    return lib.constrained_delaunay_triangles(geometry, **kwargs)


@multithreading_enabled
def envelope(geometry, **kwargs):
    """Compute the minimum bounding box that encloses an input geometry.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the envelope.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import GeometryCollection, LineString, MultiPoint, Point
    >>> shapely.envelope(LineString([(0, 0), (10, 10)]))
    <POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))>
    >>> shapely.envelope(MultiPoint([(0, 0), (10, 10)]))
    <POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))>
    >>> shapely.envelope(Point(0, 0))
    <POINT (0 0)>
    >>> shapely.envelope(GeometryCollection([]))
    <POINT EMPTY>

    """
    return lib.envelope(geometry, **kwargs)


@multithreading_enabled
def extract_unique_points(geometry, **kwargs):
    """Return all distinct vertices of an input geometry as a multipoint.

    Note that only 2 dimensions of the vertices are considered when testing
    for equality.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to extract unique points.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, MultiPoint, Point, Polygon
    >>> shapely.extract_unique_points(Point(0, 0))
    <MULTIPOINT ((0 0))>
    >>> shapely.extract_unique_points(LineString([(0, 0), (1, 1), (1, 1)]))
    <MULTIPOINT ((0 0), (1 1))>
    >>> shapely.extract_unique_points(Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]))
    <MULTIPOINT ((0 0), (1 0), (1 1), (0 1))>
    >>> shapely.extract_unique_points(MultiPoint([(0, 0), (1, 1), (0, 0)]))
    <MULTIPOINT ((0 0), (1 1))>
    >>> shapely.extract_unique_points(LineString())
    <MULTIPOINT EMPTY>

    """
    return lib.extract_unique_points(geometry, **kwargs)


@multithreading_enabled
def build_area(geometry, **kwargs):
    """Create an areal geometry formed by the constituent linework of given geometry.

    Equivalent of the PostGIS ST_BuildArea() function.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to build an area.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import GeometryCollection, Polygon
    >>> polygon1 = Polygon([(0, 0), (3, 0), (3, 3), (0, 3), (0, 0)])
    >>> polygon2 = Polygon([(1, 1), (1, 2), (2, 2), (1, 1)])
    >>> shapely.build_area(GeometryCollection([polygon1, polygon2]))
    <POLYGON ((0 0, 0 3, 3 3, 3 0, 0 0), (1 1, 2 2, 1 2, 1 1))>

    """
    return lib.build_area(geometry, **kwargs)


@multithreading_enabled
def make_valid(geometry, *, method="linework", keep_collapsed=True, **kwargs):
    """Repair invalid geometries.

    Two ``methods`` are available:

    * the 'linework' algorithm tries to preserve every edge and vertex in the input. It
      combines all rings into a set of noded lines and then extracts valid polygons from
      that linework. An alternating even-odd strategy is used to assign areas as
      interior or exterior. A disadvantage is that for some relatively simple invalid
      geometries this produces rather complex results.
    * the 'structure' algorithm tries to reason from the structure of the input to find
      the 'correct' repair: exterior rings bound area, interior holes exclude area.
      It first makes all rings valid, then shells are merged and holes are subtracted
      from the shells to generate valid result. It assumes that holes and shells are
      correctly categorized in the input geometry.

    Example:

    .. plot:: code/make_valid_methods.py

    When using ``make_valid`` on a Polygon, the result can be a GeometryCollection. For
    this example this is the case when the 'linework' ``method`` is used. LineStrings in
    the result are drawn in red.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to repair.
    method : {'linework', 'structure'}, default 'linework'
        Algorithm to use when repairing geometry. 'structure'
        requires GEOS >= 3.10.

        .. versionadded:: 2.1.0
    keep_collapsed : bool, default True
        For the 'structure' method, True will keep components that have collapsed into a
        lower dimensionality. For example, a ring collapsing to a line, or a line
        collapsing to a point. Must be True for the 'linework' method.

        .. versionadded:: 2.1.0
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import Polygon
    >>> polygon = Polygon([(0, 0), (1, 1), (1, 2), (1, 1), (0, 0)])
    >>> shapely.is_valid(polygon)
    False
    >>> shapely.make_valid(polygon)
    <MULTILINESTRING ((0 0, 1 1), (1 1, 1 2))>
    >>> shapely.make_valid(polygon, method="structure", keep_collapsed=True)
    <LINESTRING (0 0, 1 1, 1 2, 1 1, 0 0)>
    >>> shapely.make_valid(polygon, method="structure", keep_collapsed=False)
    <POLYGON EMPTY>

    """
    if not np.isscalar(method):
        raise TypeError("method only accepts scalar values")
    if not np.isscalar(keep_collapsed):
        raise TypeError("keep_collapsed only accepts scalar values")

    if method == "linework":
        if keep_collapsed is False:
            raise ValueError(
                "The 'linework' method does not support 'keep_collapsed=False'"
            )

        # The make_valid code can be removed once support for GEOS < 3.10 is dropped.
        # In GEOS >= 3.10, make_valid just calls make_valid_with_params with
        # method="linework" and keep_collapsed=True, so there is no advantage to keep
        # both code paths in shapely on long term.
        return lib.make_valid(geometry, **kwargs)

    elif method == "structure":
        if lib.geos_version < (3, 10, 0):
            raise ValueError(
                "The 'structure' method is only available in GEOS >= 3.10.0"
            )

        return lib.make_valid_with_params(
            geometry, np.intc(1), np.bool_(keep_collapsed), **kwargs
        )

    else:
        raise ValueError(f"Unknown method: {method}")


@multithreading_enabled
def minimum_clearance_line(geometry, **kwargs):
    """Return a LineString whose endpoints define the minimum clearance.

    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 the geometry has no minimum clearance, an empty LineString will be
    returned.

    .. versionadded:: 2.1.0

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to determine the minimum clearance line for.
    **kwargs
        For other keyword-only arguments, see the
        `NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.

    Examples
    --------
    >>> import shapely
    >>> from shapely import Polygon
    >>> poly = Polygon([(0, 0), (10, 0), (10, 10), (5, 5), (0, 10), (0, 0)])
    >>> shapely.minimum_clearance_line(poly)
    <LINESTRING (5 5, 5 0)>

    See Also
    --------
    minimum_clearance

    """
    return lib.minimum_clearance_line(geometry, **kwargs)


@multithreading_enabled
def normalize(geometry, **kwargs):
    """Convert Geometry to strict normal form (or canonical form).

    In :ref:`strict canonical form <canonical-form>`, the coordinates, rings of
    a polygon and parts of multi geometries are ordered consistently. Typically
    useful for testing purposes (for example in combination with
    ``equals_exact``).

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to normalize.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import MultiLineString
    >>> line = MultiLineString([[(0, 0), (1, 1)], [(2, 2), (3, 3)]])
    >>> shapely.normalize(line)
    <MULTILINESTRING ((2 2, 3 3), (0 0, 1 1))>

    """
    return lib.normalize(geometry, **kwargs)


@multithreading_enabled
def point_on_surface(geometry, **kwargs):
    """Return a point that intersects an input geometry.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute a point on the surface.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, MultiPoint, Polygon
    >>> shapely.point_on_surface(Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]))
    <POINT (5 5)>
    >>> shapely.point_on_surface(LineString([(0, 0), (2, 2), (10, 10)]))
    <POINT (2 2)>
    >>> shapely.point_on_surface(MultiPoint([(0, 0), (10, 10)]))
    <POINT (0 0)>
    >>> shapely.point_on_surface(Polygon())
    <POINT EMPTY>

    """
    return lib.point_on_surface(geometry, **kwargs)


@multithreading_enabled
def node(geometry, **kwargs):
    """Return the fully noded version of the linear input as MultiLineString.

    Given a linear input geometry, this function returns a new MultiLineString
    in which no lines cross each other but only touch at and points. To
    obtain this, all intersections between segments are computed and added
    to the segments, and duplicate segments are removed.

    Non-linear input (points) will result in an empty MultiLineString.

    This function can for example be used to create a fully-noded linework
    suitable to passed as input to ``polygonize``.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the noded version.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Point
    >>> line = LineString([(0, 0), (1,1), (0, 1), (1, 0)])
    >>> shapely.node(line)
    <MULTILINESTRING ((0 0, 0.5 0.5), (0.5 0.5, 1 1, 0 1, 0.5 0.5), (0.5 0.5, 1 0))>
    >>> shapely.node(Point(1, 1))
    <MULTILINESTRING EMPTY>

    """
    return lib.node(geometry, **kwargs)


def polygonize(geometries, **kwargs):
    """Create polygons formed from the linework of a set of Geometries.

    Polygonizes an array of Geometries that contain linework which
    represents the edges of a planar graph. Any type of Geometry may be
    provided as input; only the constituent lines and rings will be used to
    create the output polygons.

    Lines or rings that when combined do not completely close a polygon
    will result in an empty GeometryCollection.  Duplicate segments are
    ignored.

    This function returns the polygons within a GeometryCollection.
    Individual Polygons can be obtained using ``get_geometry`` to get
    a single polygon or ``get_parts`` to get an array of polygons.
    MultiPolygons can be constructed from the output using
    ``shapely.multipolygons(shapely.get_parts(shapely.polygonize(geometries)))``.

    Parameters
    ----------
    geometries : array_like
        An array of geometries.
    axis : int
        Axis along which the geometries are polygonized.
        The default is to perform a reduction over the last dimension
        of the input array. A 1D array results in a scalar geometry.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Returns
    -------
    GeometryCollection or array of GeometryCollections

    See Also
    --------
    get_parts, get_geometry
    polygonize_full
    node

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString
    >>> lines = [
    ...     LineString([(0, 0), (1, 1)]),
    ...     LineString([(0, 0), (0, 1)]),
    ...     LineString([(0, 1), (1, 1)])
    ... ]
    >>> shapely.polygonize(lines)
    <GEOMETRYCOLLECTION (POLYGON ((1 1, 0 0, 0 1, 1 1)))>

    """
    return lib.polygonize(geometries, **kwargs)


def polygonize_full(geometries, **kwargs):
    """Create polygons formed from the linework of a set of Geometries.

    All extra outputs are returned as well.

    Polygonizes an array of Geometries that contain linework which
    represents the edges of a planar graph. Any type of Geometry may be
    provided as input; only the constituent lines and rings will be used to
    create the output polygons.

    This function performs the same polygonization as ``polygonize`` but does
    not only return the polygonal result but all extra outputs as well. The
    return value consists of 4 elements:

    * The polygonal valid output
    * **Cut edges**: edges connected on both ends but not part of polygonal output
    * **dangles**: edges connected on one end but not part of polygonal output
    * **invalid rings**: polygons formed but which are not valid

    This function returns the geometries within GeometryCollections.
    Individual geometries can be obtained using ``get_geometry`` to get
    a single geometry or ``get_parts`` to get an array of geometries.

    Parameters
    ----------
    geometries : array_like
        An array of geometries.
    axis : int
        Axis along which the geometries are polygonized.
        The default is to perform a reduction over the last dimension
        of the input array. A 1D array results in a scalar geometry.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Returns
    -------
    (polygons, cuts, dangles, invalid)
        tuple of 4 GeometryCollections or arrays of GeometryCollections

    See Also
    --------
    polygonize

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString
    >>> lines = [
    ...     LineString([(0, 0), (1, 1)]),
    ...     LineString([(0, 0), (0, 1), (1, 1)]),
    ...     LineString([(0, 1), (1, 1)])
    ... ]
    >>> shapely.polygonize_full(lines)
    (<GEOMETRYCOLLECTION (POLYGON ((1 1, 0 0, 0 1, 1 1)))>,
     <GEOMETRYCOLLECTION EMPTY>,
     <GEOMETRYCOLLECTION (LINESTRING (0 1, 1 1))>,
     <GEOMETRYCOLLECTION EMPTY>)

    """
    return lib.polygonize_full(geometries, **kwargs)


@requires_geos("3.11.0")
@multithreading_enabled
def remove_repeated_points(geometry, tolerance=0.0, **kwargs):
    """Return a copy of a Geometry with repeated points removed.

    From the start of the coordinate sequence, each next point within the
    tolerance is removed.

    Removing repeated points with a non-zero tolerance may result in an invalid
    geometry being returned.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to remove repeated points from.
    tolerance : float or array_like, default=0.0
        Use 0.0 to remove only exactly repeated points.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Polygon
    >>> shapely.remove_repeated_points(LineString([(0,0), (0,0), (1,0)]), tolerance=0)
    <LINESTRING (0 0, 1 0)>
    >>> shapely.remove_repeated_points(Polygon([(0, 0), (0, .5), (0, 1), (.5, 1), (0,0)]), tolerance=.5)
    <POLYGON ((0 0, 0 1, 0 0))>

    """  # noqa: E501
    return lib.remove_repeated_points(geometry, tolerance, **kwargs)


@multithreading_enabled
def reverse(geometry, **kwargs):
    """Return a copy of a Geometry with the order of coordinates reversed.

    If a Geometry is a polygon with interior rings, the interior rings are also
    reversed.

    Points are unchanged. None is returned where Geometry is None.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to reverse the coordinates of.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    See Also
    --------
    is_ccw : Checks if a Geometry is clockwise.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Polygon
    >>> shapely.reverse(LineString([(0, 0), (1, 2)]))
    <LINESTRING (1 2, 0 0)>
    >>> shapely.reverse(Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]))
    <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
    >>> shapely.reverse(None) is None
    True

    """
    return lib.reverse(geometry, **kwargs)


@requires_geos("3.10.0")
@multithreading_enabled
def segmentize(geometry, max_segment_length, **kwargs):
    """Add vertices to line segments based on maximum segment length.

    Additional vertices will be added to every line segment in an input geometry
    so that segments are no longer than the provided maximum segment length. New
    vertices will evenly subdivide each segment.

    Only linear components of input geometries are densified; other geometries
    are returned unmodified.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to segmentize.
    max_segment_length : float or array_like
        Additional vertices will be added so that all line segments are no
        longer than this value.  Must be greater than 0.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Polygon
    >>> line = LineString([(0, 0), (0, 10)])
    >>> shapely.segmentize(line, max_segment_length=5)
    <LINESTRING (0 0, 0 5, 0 10)>
    >>> polygon = Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)])
    >>> shapely.segmentize(polygon, max_segment_length=5)
    <POLYGON ((0 0, 5 0, 10 0, 10 5, 10 10, 5 10, 0 10, 0 5, 0 0))>
    >>> shapely.segmentize(None, max_segment_length=5) is None
    True

    """
    return lib.segmentize(geometry, max_segment_length, **kwargs)


# Note: future plan is to change this signature over a few releases:
# shapely 2.0:
#   simplify(geometry, tolerance, preserve_topology=True, **kwargs)
# shapely 2.1: shows deprecation warning about positional 'preserve_topology'
#   same signature as 2.0
# shapely 2.2(?): enforce keyword-only arguments after 'tolerance'
#   simplify(geometry, tolerance, *, preserve_topology=True, **kwargs)


@deprecate_positional(["preserve_topology"], category=DeprecationWarning)
@multithreading_enabled
def simplify(geometry, tolerance, preserve_topology=True, **kwargs):
    """Return a simplified version of an input geometry.

    The Douglas-Peucker algorithm is used to simplify the geometry.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to simplify.
    tolerance : float or array_like
        The maximum allowed geometry displacement. The higher this value, the
        smaller the number of vertices in the resulting geometry.
    preserve_topology : bool, default True
        By default (True), the operation will avoid creating invalid
        geometries (checking for collapses, ring-intersections, etc), but
        this is computationally more expensive.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Notes
    -----

    .. deprecated:: 2.1.0
        A deprecation warning is shown if ``preserve_topology`` is specified as
        a positional argument. This will need to be specified as a keyword
        argument in a future release.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Polygon
    >>> line = LineString([(0, 0), (1, 10), (0, 20)])
    >>> shapely.simplify(line, tolerance=0.9)
    <LINESTRING (0 0, 1 10, 0 20)>
    >>> shapely.simplify(line, tolerance=1)
    <LINESTRING (0 0, 0 20)>
    >>> polygon_with_hole = Polygon(
    ...     [(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)],
    ...     holes=[[(2, 2), (2, 4), (4, 4), (4, 2), (2, 2)]]
    ... )
    >>> shapely.simplify(polygon_with_hole, tolerance=4, preserve_topology=True)
    <POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0), (4 2, 2 4, 4 4, 4 2))>
    >>> shapely.simplify(polygon_with_hole, tolerance=4, preserve_topology=False)
    <POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>

    """
    if preserve_topology:
        return lib.simplify_preserve_topology(geometry, tolerance, **kwargs)
    else:
        return lib.simplify(geometry, tolerance, **kwargs)


@multithreading_enabled
def snap(geometry, reference, tolerance, **kwargs):
    """Snap the vertices and segments of the geometry to vertices of the reference.

    Vertices and segments of the input geometry are snapped to vertices of the
    reference geometry, returning a new geometry; the input geometries are not
    modified. The result geometry is the input geometry with the vertices and
    segments snapped. If no snapping occurs then the input geometry is returned
    unchanged. The tolerance is used to control where snapping is performed.

    Where possible, this operation tries to avoid creating invalid geometries;
    however, it does not guarantee that output geometries will be valid. It is
    the responsibility of the caller to check for and handle invalid geometries.

    Because too much snapping can result in invalid geometries being created,
    heuristics are used to determine the number and location of snapped
    vertices that are likely safe to snap. These heuristics may omit
    some potential snaps that are otherwise within the tolerance.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to snap.
    reference : Geometry or array_like
        Geometry or geometries to snap to.
    tolerance : float or array_like
        The maximum distance between the input and reference geometries for
        snapping to occur. A value of 0 will snap only identical points.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Point, Polygon, MultiPoint

    >>> point = Point(0.5, 2.5)
    >>> target_point = Point(0, 2)
    >>> shapely.snap(point, target_point, tolerance=1)
    <POINT (0 2)>
    >>> shapely.snap(point, target_point, tolerance=0.49)
    <POINT (0.5 2.5)>

    >>> polygon = Polygon([(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)])
    >>> shapely.snap(polygon, Point(8, 10), tolerance=5)
    <POLYGON ((0 0, 0 10, 8 10, 10 0, 0 0))>
    >>> shapely.snap(polygon, LineString([(8, 10), (8, 0)]), tolerance=5)
    <POLYGON ((0 0, 0 10, 8 10, 8 0, 0 0))>

    You can snap one line to another, for example to clean imprecise coordinates:

    >>> line1 = LineString([(0.1, 0.1), (0.49, 0.51), (1.01, 0.89)])
    >>> line2 = LineString([(0, 0), (0.5, 0.5), (1.0, 1.0)])
    >>> shapely.snap(line1, line2, 0.25)
    <LINESTRING (0 0, 0.5 0.5, 1 1)>

    Snapping also supports Z coordinates:

    >>> point1 = Point(0.1, 0.1, 0.5)
    >>> multipoint = MultiPoint([(0, 0, 1), (0, 0, 0)])
    >>> shapely.snap(point1, multipoint, 1)
    <POINT Z (0 0 1)>

    Snapping to an empty geometry has no effect:

    >>> shapely.snap(line1, LineString([]), 0.25)
    <LINESTRING (0.1 0.1, 0.49 0.51, 1.01 0.89)>

    Snapping to a non-geometry (None) will always return None:

    >>> shapely.snap(line1, None, 0.25) is None
    True

    Only one vertex of a polygon is snapped to a target point,
    even if all vertices are equidistant to it,
    in order to prevent collapse of the polygon:

    >>> poly = shapely.box(0, 0, 1, 1)
    >>> poly
    <POLYGON ((1 0, 1 1, 0 1, 0 0, 1 0))>
    >>> shapely.snap(poly, Point(0.5, 0.5), 1)
    <POLYGON ((0.5 0.5, 1 1, 0 1, 0 0, 0.5 0.5))>

    """
    return lib.snap(geometry, reference, tolerance, **kwargs)


# Note: future plan is to change this signature over a few releases:
# shapely 2.0:
#   voronoi_polygons(geometry, tolerance=0.0, extend_to=None, ...)
# shapely 2.1: shows deprecation warning about positional 'extend_to'
#   same signature as 2.0
# shapely 2.2(?): enforce keyword-only arguments after 'tolerance'
#   voronoi_polygons(geometry, tolerance=0.0, extend_to=None, ...)


@deprecate_positional(
    ["extend_to", "only_edges", "ordered"], category=DeprecationWarning
)
@multithreading_enabled
def voronoi_polygons(
    geometry, tolerance=0.0, extend_to=None, only_edges=False, ordered=False, **kwargs
):
    """Compute a Voronoi diagram from the vertices of an input geometry.

    The output is a geometrycollection containing polygons (default)
    or linestrings (see only_edges). Returns empty if an input geometry
    contains less than 2 vertices or if the provided extent has zero area.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the Voronoi diagram.
    tolerance : float or array_like, default 0.0
        Snap input vertices together if their distance is less than this value.
    extend_to : Geometry or array_like, optional
        If provided, the diagram will be extended to cover the envelope of this
        geometry (unless this envelope is smaller than the input geometry).
    only_edges : bool or array_like, default False
        If set to True, the triangulation will return a collection of
        linestrings instead of polygons.
    ordered : bool or array_like, default False
        If set to True, polygons within the GeometryCollection will be ordered
        according to the order of the input vertices. Note that this may slow
        down the computation. Requires GEOS >= 3.12.0.

        .. versionadded:: 2.1.0
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Notes
    -----

    .. deprecated:: 2.1.0
        A deprecation warning is shown if ``extend_to``, ``only_edges`` or
        ``ordered`` are specified as positional arguments. In a future
        release, these will need to be specified as keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, MultiPoint, Point
    >>> points = MultiPoint([(2, 2), (4, 2)])
    >>> shapely.voronoi_polygons(points).normalize()
    <GEOMETRYCOLLECTION (POLYGON ((3 0, 3 4, 6 4, 6 0, 3 0)), POLYGON ((0 0, 0 4...>
    >>> shapely.voronoi_polygons(points, only_edges=True)
    <MULTILINESTRING ((3 4, 3 0))>
    >>> shapely.voronoi_polygons(MultiPoint([(2, 2), (4, 2), (4.2, 2)]), 0.5, only_edges=True)
    <MULTILINESTRING ((3 4.2, 3 -0.2))>
    >>> shapely.voronoi_polygons(points, extend_to=LineString([(0, 0), (10, 10)]), only_edges=True)
    <MULTILINESTRING ((3 10, 3 0))>
    >>> shapely.voronoi_polygons(LineString([(2, 2), (4, 2)]), only_edges=True)
    <MULTILINESTRING ((3 4, 3 0))>
    >>> shapely.voronoi_polygons(Point(2, 2))
    <GEOMETRYCOLLECTION EMPTY>
    >>> shapely.voronoi_polygons(points, ordered=True)
    <GEOMETRYCOLLECTION (POLYGON ((0 0, 0 4, 3 4, 3 0, 0 0)), POLYGON ((6 4, 6 0...>

    """  # noqa: E501
    if ordered is not False and lib.geos_version < (3, 12, 0):
        raise UnsupportedGEOSVersionError(
            "Ordered Voronoi polygons require GEOS >= 3.12.0, "
            f"found {lib.geos_version_string}"
        )
    return lib.voronoi_polygons(
        geometry, tolerance, extend_to, only_edges, ordered, **kwargs
    )


@multithreading_enabled
def _oriented_envelope_geos(geometry, **kwargs):
    return lib.oriented_envelope(geometry, **kwargs)


def oriented_envelope(geometry, **kwargs):
    """Compute the oriented envelope (minimum rotated rectangle) of the input geometry.

    The oriented envelope encloses an input geometry, such that the resulting
    rectangle has minimum area.

    Unlike envelope this rectangle is not constrained to be parallel to the
    coordinate axes. If the convex hull of the object is a degenerate (line
    or point) this degenerate is returned.

    The starting point of the rectangle is not fixed. You can use
    :func:`~shapely.normalize` to reorganize the rectangle to
    :ref:`strict canonical form <canonical-form>` so the starting point is
    always the lower left point.

    ``minimum_rotated_rectangle`` is an alias for ``oriented_envelope``.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the oriented envelope.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    >>> import shapely
    >>> from shapely import GeometryCollection, LineString, MultiPoint, Point, Polygon
    >>> shapely.oriented_envelope(MultiPoint([(0, 0), (10, 0), (10, 10)])).normalize()
    <POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>
    >>> shapely.oriented_envelope(LineString([(1, 1), (5, 1), (10, 10)])).normalize()
    <POLYGON ((1 1, 10 10, 12 8, 3 -1, 1 1))>
    >>> shapely.oriented_envelope(Polygon([(1, 1), (15, 1), (5, 10), (1, 1)]))\
.normalize()
    <POLYGON ((1 1, 5 10, 16.691 4.804, 12.691 -4.196, 1 1))>
    >>> shapely.oriented_envelope(LineString([(1, 1), (10, 1)])).normalize()
    <LINESTRING (1 1, 10 1)>
    >>> shapely.oriented_envelope(Point(2, 2))
    <POINT (2 2)>
    >>> shapely.oriented_envelope(GeometryCollection([]))
    <POLYGON EMPTY>

    """
    if lib.geos_version < (3, 12, 0):
        f = _oriented_envelope_min_area_vectorized
    else:
        f = _oriented_envelope_geos
    return f(geometry, **kwargs)


minimum_rotated_rectangle = oriented_envelope


@multithreading_enabled
def minimum_bounding_circle(geometry, **kwargs):
    """Compute the minimum bounding circle that encloses an input geometry.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries for which to compute the minimum bounding circle.
    **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_circle(
    ...     Polygon([(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)])
    ... )
    <POLYGON ((12.071 5, 11.935 3.621, 11.533 2.294, 10.879 1.07...>
    >>> shapely.minimum_bounding_circle(LineString([(1, 1), (10, 10)]))
    <POLYGON ((11.864 5.5, 11.742 4.258, 11.38 3.065, 10.791 1.9...>
    >>> shapely.minimum_bounding_circle(MultiPoint([(2, 2), (4, 2)]))
    <POLYGON ((4 2, 3.981 1.805, 3.924 1.617, 3.831 1.444, 3.707...>
    >>> shapely.minimum_bounding_circle(Point(0, 1))
    <POINT (0 1)>
    >>> shapely.minimum_bounding_circle(GeometryCollection([]))
    <POLYGON EMPTY>

    See Also
    --------
    minimum_bounding_radius, maximum_inscribed_circle

    """
    return lib.minimum_bounding_circle(geometry, **kwargs)


@multithreading_enabled
def maximum_inscribed_circle(geometry, tolerance=None, **kwargs):
    """Find the largest circle that is fully contained within the input geometry.

    Constructs the "maximum inscribed circle" (MIC) for a polygonal geometry,
    up to a specified tolerance. The MIC is determined by a point in the
    interior of the area which has the farthest distance from the area
    boundary, along with a boundary point at that distance. In the context of
    geography the center of the MIC is known as the "pole of inaccessibility".
    A cartographic use case is to determine a suitable point to place a map
    label within a polygon.
    The radius length of the MIC is a  measure of how "narrow" a polygon is.
    It is the distance at which the negative buffer becomes empty.

    The function supports polygons with holes and multipolygons.

    Returns a two-point linestring, with the first point at the center of the
    inscribed circle and the second on the boundary of the inscribed circle.

    .. versionadded:: 2.1.0

    Parameters
    ----------
    geometry : Geometry or array_like
    tolerance : float or array_like, optional
        Stop the algorithm when the search area is smaller than this tolerance.
        When not specified, uses `max(width, height) / 1000` per geometry as
        the default.
    **kwargs
        For other keyword-only arguments, see the
        `NumPy ufunc docs <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.

    Examples
    --------
    >>> import shapely
    >>> from shapely import Polygon
    >>> poly = Polygon([(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)])
    >>> shapely.maximum_inscribed_circle(poly)
    <LINESTRING (5 5, 0 5)>

    See Also
    --------
    minimum_bounding_circle
    """
    if tolerance is None:
        tolerance = 0.0
    elif np.isscalar(tolerance) and tolerance < 0:
        raise ValueError("'tolerance' should be positive")
    return lib.maximum_inscribed_circle(geometry, tolerance, **kwargs)


@multithreading_enabled
def _orient_polygons_geos(geometry, exterior_cw=False, **kwargs):
    return lib.orient_polygons(geometry, exterior_cw, **kwargs)


@multithreading_enabled
def orient_polygons(geometry, *, exterior_cw=False, **kwargs):
    """Enforce a ring orientation on all polygonal elements in the input geometry.

    Forces (Multi)Polygons to use a counter-clockwise orientation for their
    exterior ring, and a clockwise orientation for their interior rings (or
    the oppposite if ``exterior_cw=True``).

    Also processes geometries inside a GeometryCollection in the same way.
    Other geometries are returned unchanged.

    .. versionadded:: 2.1.0

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to orient consistently.
    exterior_cw : bool, default False
        If True, exterior rings will be clockwise and interior rings
        will be counter-clockwise.
    **kwargs
        See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.

    Examples
    --------
    A polygon with both shell and hole having clockwise orientation:

    >>> from shapely import Polygon, orient_polygons
    >>> polygon = Polygon(
    ...     [(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)],
    ...     holes=[[(2, 2), (2, 4), (4, 4), (4, 2), (2, 2)]],
    ... )
    >>> polygon
    <POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0), (2 2, 2 4, 4 4, 4 2, 2 2))>

    By default, the exterior ring is oriented counter-clockwise and
    the holes clockwise:

    >>> orient_polygons(polygon)
    <POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0), (2 2, 2 4, 4 4, 4 2, 2 2))>

    Asking for the opposite orientation:

    >>> orient_polygons(polygon, exterior_cw=True)
    <POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0), (2 2, 4 2, 4 4, 2 4, 2 2))>

    """
    if lib.geos_version < (3, 12, 0):
        f = _orient_polygons_vectorized
    else:
        f = _orient_polygons_geos
    return f(geometry, exterior_cw, **kwargs)