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

"""Methods that operate on the coordinates of geometries."""

import numpy as np

import shapely
from shapely import lib
from shapely.decorators import deprecate_positional

__all__ = ["count_coordinates", "get_coordinates", "set_coordinates", "transform"]


# Note: future plan is to change this signature over a few releases:
# shapely 2.0: only supported XY and XYZ geometries
#   transform(geometry, transformation, include_z=False)
# shapely 2.1: shows deprecation warning about positional 'include_z' arg
#   transform(geometry, transformation, include_z=False, *, interleaved=True)
# shapely 2.2(?): enforce keyword-only arguments after 'transformation'
#   transform(geometry, transformation, *, include_z=False, interleaved=True)


@deprecate_positional(["include_z"], category=DeprecationWarning)
def transform(
    geometry,
    transformation,
    include_z: bool | None = False,
    *,
    interleaved: bool = True,
):
    """Apply a function to the coordinates of a geometry.

    With the default of ``include_z=False``, all returned geometries will be
    two-dimensional; the third dimension will be discarded, if present.
    When specifying ``include_z=True``, the returned geometries preserve
    the dimensionality of the respective input geometries.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to transform.
    transformation : function
        A function that transforms a (N, 2) or (N, 3) ndarray of float64 to
        another (N, 2) or (N, 3) ndarray of float64.
        The function may not change N.
    include_z : bool, optional, default False
        If False, always return 2D geometries.
        If True, the data being passed to the
        transformation function will include the third dimension
        (if a geometry has no third dimension, the z-coordinates
        will be NaN). If None, will infer the dimensionality per
        input geometry using ``has_z``, which may result in 2 calls to
        the transformation function. Note that this inference
        can be unreliable with empty geometries or NaN coordinates: for a
        guaranteed result, it is recommended to specify ``include_z`` explicitly.
    interleaved : bool, default True
        If set to False, the transformation function should accept 2 or 3 separate
        one-dimensional arrays (x, y and optional z) instead of a single
        two-dimensional array.

        .. versionadded:: 2.1.0

    Notes
    -----

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

    See Also
    --------
    has_z

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Point
    >>> shapely.transform(Point(0, 0), lambda x: x + 1)
    <POINT (1 1)>
    >>> shapely.transform(LineString([(2, 2), (4, 4)]), lambda x: x * [2, 3])
    <LINESTRING (4 6, 8 12)>
    >>> shapely.transform(None, lambda x: x) is None
    True
    >>> shapely.transform([Point(0, 0), None], lambda x: x).tolist()
    [<POINT (0 0)>, None]

    The presence of a third dimension can be automatically detected, or
    controlled explicitly:

    >>> shapely.transform(Point(0, 0, 0), lambda x: x + 1)
    <POINT (1 1)>
    >>> shapely.transform(Point(0, 0, 0), lambda x: x + 1, include_z=True)
    <POINT Z (1 1 1)>
    >>> shapely.transform(Point(0, 0, 0), lambda x: x + 1, include_z=None)
    <POINT Z (1 1 1)>

    With interleaved=False, the call signature of the transformation is different:

    >>> shapely.transform(LineString([(1, 2), (3, 4)]), lambda x, y: (x + 1, y), \
interleaved=False)
    <LINESTRING (2 2, 4 4)>

    Or with a z coordinate:

    >>> shapely.transform(Point(0, 0, 0), lambda x, y, z: (x + 1, y, z + 2), \
interleaved=False, include_z=True)
    <POINT Z (1 0 2)>

    Using pyproj >= 2.1, the following example will reproject Shapely geometries
    from EPSG 4326 to EPSG 32618:

    >>> from pyproj import Transformer
    >>> transformer = Transformer.from_crs(4326, 32618, always_xy=True)
    >>> shapely.transform(Point(-75, 50), transformer.transform, interleaved=False)
    <POINT (500000 5538630.703)>

    """
    geometry_arr = np.array(geometry, dtype=np.object_)  # makes a copy
    if include_z is None:
        has_z = shapely.has_z(geometry_arr)
        result = np.empty_like(geometry_arr)
        result[has_z] = transform(
            geometry_arr[has_z], transformation, include_z=True, interleaved=interleaved
        )
        result[~has_z] = transform(
            geometry_arr[~has_z],
            transformation,
            include_z=False,
            interleaved=interleaved,
        )
    else:
        # TODO: expose include_m
        include_m = False
        coordinates = lib.get_coordinates(geometry_arr, include_z, include_m, False)
        if interleaved:
            new_coordinates = transformation(coordinates)
        else:
            new_coordinates = np.asarray(
                transformation(*coordinates.T), dtype=np.float64
            ).T
        # check the array to yield understandable error messages
        if not isinstance(new_coordinates, np.ndarray) or new_coordinates.ndim != 2:
            raise ValueError(
                "The provided transformation did not return a two-dimensional numpy "
                "array"
            )
        if new_coordinates.dtype != np.float64:
            raise ValueError(
                "The provided transformation returned an array with an unexpected "
                f"dtype ({new_coordinates.dtype})"
            )
        if new_coordinates.shape != coordinates.shape:
            # if the shape is too small we will get a segfault
            raise ValueError(
                "The provided transformation returned an array with an unexpected "
                f"shape ({new_coordinates.shape})"
            )
        result = lib.set_coordinates(geometry_arr, new_coordinates)
    if result.ndim == 0 and not isinstance(geometry, np.ndarray):
        return result.item()
    return result


def count_coordinates(geometry):
    """Count the number of coordinate pairs in a geometry array.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to count the coordinates of.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Point
    >>> shapely.count_coordinates(Point(0, 0))
    1
    >>> shapely.count_coordinates(LineString([(2, 2), (4, 2)]))
    2
    >>> shapely.count_coordinates(None)
    0
    >>> shapely.count_coordinates([Point(0, 0), None])
    1

    """
    return lib.count_coordinates(np.asarray(geometry, dtype=np.object_))


# Note: future plan is to change this signature over a few releases:
# shapely 2.0: only supported XY and XYZ geometries
#   get_coordinates(geometry, include_z=False, return_index=False)
# shapely 2.1: shows deprecation warning about positional 'include_z' and 'return_index'
#   get_coordinates(geometry, include_z=False, return_index=False, *, include_m=False)
# shapely 2.2(?): enforce keyword-only arguments after 'geometry'
#   get_coordinates(geometry, *, include_z=False, include_m=False, return_index=False)


@deprecate_positional(["include_z", "return_index"], category=DeprecationWarning)
def get_coordinates(geometry, include_z=False, return_index=False, *, include_m=False):
    """Get coordinates from a geometry array as an array of floats.

    The shape of the returned array is (N, 2), with N being the number of
    coordinate pairs. The shape of the data may also be (N, 3) or (N, 4),
    depending on ``include_z`` and ``include_m`` options.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to get the coordinates of.
    include_z, include_m : bool, default False
        If both are False, return XY (2D) geometries.
        If both are True, return XYZM (4D) geometries.
        If either are True, return XYZ or XYM (3D) geometries.
        If a geometry has no Z or M dimension, extra coordinate data will be NaN.

        .. versionadded:: 2.1.0
            The ``include_m`` parameter was added to support XYM (3D) and
            XYZM (4D) geometries available with GEOS 3.12.0 or later.
            With older GEOS versions, M dimension coordinates will be NaN.

    return_index : bool, default False
        If True, also return the index of each returned geometry as a separate
        ndarray of integers. For multidimensional arrays, this indexes into the
        flattened array (in C contiguous order).

    Notes
    -----

    .. deprecated:: 2.1.0
        A deprecation warning is shown if ``include_z`` or ``return_index`` 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
    >>> shapely.get_coordinates(Point(1, 2)).tolist()
    [[1.0, 2.0]]
    >>> shapely.get_coordinates(LineString([(2, 2), (4, 4)])).tolist()
    [[2.0, 2.0], [4.0, 4.0]]
    >>> shapely.get_coordinates(None)
    array([], shape=(0, 2), dtype=float64)

    By default the third dimension is ignored:

    >>> shapely.get_coordinates(Point(1, 2, 3)).tolist()
    [[1.0, 2.0]]
    >>> shapely.get_coordinates(Point(1, 2, 3), include_z=True).tolist()
    [[1.0, 2.0, 3.0]]

    If geometries don't have Z or M dimension, these values will be NaN:

    >>> pt = Point(1, 2)
    >>> shapely.get_coordinates(pt, include_z=True).tolist()
    [[1.0, 2.0, nan]]
    >>> shapely.get_coordinates(pt, include_z=True, include_m=True).tolist()
    [[1.0, 2.0, nan, nan]]

    When ``return_index=True``, indexes are returned also:

    >>> geometries = [LineString([(2, 2), (4, 4)]), Point(0, 0)]
    >>> coordinates, index = shapely.get_coordinates(geometries, return_index=True)
    >>> coordinates.tolist(), index.tolist()
    ([[2.0, 2.0], [4.0, 4.0], [0.0, 0.0]], [0, 0, 1])

    """
    return lib.get_coordinates(
        np.asarray(geometry, dtype=np.object_), include_z, include_m, return_index
    )


def set_coordinates(geometry, coordinates):
    """Adapts the coordinates of a geometry array in-place.

    If the coordinates array has shape (N, 2), all returned geometries
    will be two-dimensional, and the third dimension will be discarded,
    if present. If the coordinates array has shape (N, 3), the returned
    geometries preserve the dimensionality of the input geometries.

    .. warning::

        The geometry array is modified in-place! If you do not want to
        modify the original array, you can do
        ``set_coordinates(arr.copy(), newcoords)``.

    Parameters
    ----------
    geometry : Geometry or array_like
        Geometry or geometries to set the coordinates of.
    coordinates: array_like
        An array of coordinates to set.

    See Also
    --------
    transform : Returns a copy of a geometry array with a function applied to its
        coordinates.

    Examples
    --------
    >>> import shapely
    >>> from shapely import LineString, Point
    >>> shapely.set_coordinates(Point(0, 0), [[1, 1]])
    <POINT (1 1)>
    >>> shapely.set_coordinates(
    ...     [Point(0, 0), LineString([(0, 0), (0, 0)])],
    ...     [[1, 2], [3, 4], [5, 6]]
    ... ).tolist()
    [<POINT (1 2)>, <LINESTRING (3 4, 5 6)>]
    >>> shapely.set_coordinates([None, Point(0, 0)], [[1, 2]]).tolist()
    [None, <POINT (1 2)>]

    Third dimension of input geometry is discarded if coordinates array does
    not include one:

    >>> shapely.set_coordinates(Point(0, 0, 0), [[1, 1]])
    <POINT (1 1)>
    >>> shapely.set_coordinates(Point(0, 0, 0), [[1, 1, 1]])
    <POINT Z (1 1 1)>

    """
    geometry_arr = np.asarray(geometry, dtype=np.object_)
    coordinates = np.atleast_2d(np.asarray(coordinates)).astype(np.float64)
    if coordinates.ndim != 2:
        raise ValueError(
            f"The coordinate array should have dimension of 2 (has {coordinates.ndim})"
        )
    n_coords = lib.count_coordinates(geometry_arr)
    if (coordinates.shape[0] != n_coords) or (coordinates.shape[1] not in {2, 3}):
        raise ValueError(
            f"The coordinate array has an invalid shape {coordinates.shape}"
        )
    lib.set_coordinates(geometry_arr, coordinates)
    if geometry_arr.ndim == 0 and not isinstance(geometry, np.ndarray):
        return geometry_arr.item()
    return geometry_arr