336 lines
12 KiB
Python
336 lines
12 KiB
Python
"""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
|