832 lines
30 KiB
Python
832 lines
30 KiB
Python
"""Methods to create geometries."""
|
|
|
|
import numpy as np
|
|
|
|
from shapely import Geometry, GeometryType, lib
|
|
from shapely._enum import ParamEnum
|
|
from shapely._geometry_helpers import collections_1d, simple_geometries_1d
|
|
from shapely.decorators import deprecate_positional, multithreading_enabled
|
|
from shapely.io import from_wkt
|
|
|
|
__all__ = [
|
|
"box",
|
|
"destroy_prepared",
|
|
"empty",
|
|
"geometrycollections",
|
|
"linearrings",
|
|
"linestrings",
|
|
"multilinestrings",
|
|
"multipoints",
|
|
"multipolygons",
|
|
"points",
|
|
"polygons",
|
|
"prepare",
|
|
]
|
|
|
|
|
|
class HandleNaN(ParamEnum):
|
|
allow = 0
|
|
skip = 1
|
|
error = 2
|
|
|
|
|
|
def _xyz_to_coords(x, y, z):
|
|
if y is None:
|
|
return x
|
|
if z is None:
|
|
coords = np.broadcast_arrays(x, y)
|
|
else:
|
|
coords = np.broadcast_arrays(x, y, z)
|
|
return np.stack(coords, axis=-1)
|
|
|
|
|
|
# Note: future plan is to change this signature over a few releases:
|
|
# shapely 2.0:
|
|
# points(coords, y=None, z=None, indices=None, out=None, **kwargs)
|
|
# shapely 2.1: shows deprecation warning about positional 'indices' arg
|
|
# points(coords, y=None, z=None, indices=None, *, handle_nan=HandleNaN.allow, out=None, **kwargs) # noqa: E501
|
|
# shapely 2.2(?): enforce keyword-only arguments after 'z'
|
|
# points(coords, y=None, z=None, *, indices=None, handle_nan=HandleNaN.allow, out=None, **kwargs) # noqa: E501
|
|
|
|
|
|
@deprecate_positional(["indices"], category=DeprecationWarning)
|
|
@multithreading_enabled
|
|
def points(
|
|
coords,
|
|
y=None,
|
|
z=None,
|
|
indices=None,
|
|
*,
|
|
handle_nan=HandleNaN.allow,
|
|
out=None,
|
|
**kwargs,
|
|
):
|
|
"""Create an array of points.
|
|
|
|
Parameters
|
|
----------
|
|
coords : array_like
|
|
An array of coordinate tuples (2- or 3-dimensional) or, if ``y`` is
|
|
provided, an array of x coordinates.
|
|
y : array_like, optional
|
|
An array of y coordinates.
|
|
z : array_like, optional
|
|
An array of z coordinates.
|
|
indices : array_like, optional
|
|
Indices into the target array where input coordinates belong. If
|
|
provided, the coords should be 2D with shape (N, 2) or (N, 3) and
|
|
indices should be an array of shape (N,) with integers in increasing
|
|
order. Missing indices result in a ValueError unless ``out`` is
|
|
provided, in which case the original value in ``out`` is kept.
|
|
handle_nan : shapely.HandleNaN or {'allow', 'skip', 'error'}, default 'allow'
|
|
Specifies what to do when a NaN or Inf is encountered in the coordinates:
|
|
|
|
- 'allow': the geometries are created with NaN or Inf coordinates.
|
|
Note that this can result in unexpected behaviour in subsequent
|
|
operations, and generally it is discouraged to have non-finite
|
|
coordinate values. One can use this option if you know all
|
|
coordinates are finite and want to avoid the overhead of checking
|
|
for this.
|
|
- 'skip': if any of x, y or z values are NaN or Inf, an empty point
|
|
will be created.
|
|
- 'error': if any NaN or Inf is detected in the coordinates, a ValueError
|
|
is raised. This option ensures that the created geometries have all
|
|
finite coordinate values.
|
|
|
|
.. versionadded:: 2.1.0
|
|
out : ndarray, optional
|
|
An array (with dtype object) to output the geometries into.
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
Ignored if ``indices`` is provided.
|
|
|
|
Examples
|
|
--------
|
|
>>> import shapely
|
|
>>> shapely.points([[0, 1], [4, 5]]).tolist()
|
|
[<POINT (0 1)>, <POINT (4 5)>]
|
|
>>> shapely.points([0, 1, 2])
|
|
<POINT Z (0 1 2)>
|
|
|
|
Notes
|
|
-----
|
|
- GEOS 3.10, 3.11 and 3.12 automatically converts POINT (nan nan) to POINT EMPTY.
|
|
- GEOS 3.10 and 3.11 will transform a 3D point to 2D if its Z coordinate is NaN.
|
|
- Usage of the ``y`` and ``z`` arguments will prevents lazy evaluation in
|
|
``dask``. Instead provide the coordinates as an array with shape
|
|
``(..., 2)`` or ``(..., 3)`` using only the ``coords`` argument.
|
|
|
|
"""
|
|
coords = _xyz_to_coords(coords, y, z)
|
|
if isinstance(handle_nan, str):
|
|
handle_nan = HandleNaN.get_value(handle_nan)
|
|
if indices is None:
|
|
return lib.points(coords, np.intc(handle_nan), out=out, **kwargs)
|
|
else:
|
|
return simple_geometries_1d(
|
|
coords, indices, GeometryType.POINT, handle_nan=handle_nan, out=out
|
|
)
|
|
|
|
|
|
# Note: future plan is to change this signature over a few releases:
|
|
# shapely 2.0:
|
|
# linestrings(coords, y=None, z=None, indices=None, out=None, **kwargs)
|
|
# shapely 2.1: shows deprecation warning about positional 'indices' arg
|
|
# linestrings(coords, y=None, z=None, indices=None, *, handle_nan=HandleNaN.allow, out=None, **kwargs) # noqa: E501
|
|
# shapely 2.2(?): enforce keyword-only arguments after 'z'
|
|
# linestrings(coords, y=None, z=None, *, indices=None, handle_nan=HandleNaN.allow, out=None, **kwargs) # noqa: E501
|
|
|
|
|
|
@deprecate_positional(["indices"], category=DeprecationWarning)
|
|
@multithreading_enabled
|
|
def linestrings(
|
|
coords,
|
|
y=None,
|
|
z=None,
|
|
indices=None,
|
|
*,
|
|
handle_nan=HandleNaN.allow,
|
|
out=None,
|
|
**kwargs,
|
|
):
|
|
"""Create an array of linestrings.
|
|
|
|
This function will raise an exception if a linestring contains less than
|
|
two points.
|
|
|
|
Parameters
|
|
----------
|
|
coords : array_like
|
|
An array of lists of coordinate tuples (2- or 3-dimensional) or, if ``y``
|
|
is provided, an array of lists of x coordinates.
|
|
y : array_like, optional
|
|
An array of y coordinates.
|
|
z : array_like, optional
|
|
An array of z coordinates.
|
|
indices : array_like, optional
|
|
Indices into the target array where input coordinates belong. If
|
|
provided, the coords should be 2D with shape (N, 2) or (N, 3) and
|
|
indices should be an array of shape (N,) with integers in increasing
|
|
order. Missing indices result in a ValueError unless ``out`` is
|
|
provided, in which case the original value in ``out`` is kept.
|
|
handle_nan : shapely.HandleNaN or {'allow', 'skip', 'error'}, default 'allow'
|
|
Specifies what to do when a NaN or Inf is encountered in the coordinates:
|
|
|
|
- 'allow': the geometries are created with NaN or Inf coordinates.
|
|
Note that this can result in unexpected behaviour in subsequent
|
|
operations, and generally it is discouraged to have non-finite
|
|
coordinate values. One can use this option if you know all
|
|
coordinates are finite and want to avoid the overhead of checking
|
|
for this.
|
|
- 'skip': the coordinate pairs where any of x, y or z values are
|
|
NaN or Inf are ignored. If this results in ignoring all coordinates
|
|
for one geometry, an empty geometry is created.
|
|
- 'error': if any NaN or Inf is detected in the coordinates, a ValueError
|
|
is raised. This option ensures that the created geometries have all
|
|
finite coordinate values.
|
|
|
|
.. versionadded:: 2.1.0
|
|
|
|
out : ndarray, optional
|
|
An array (with dtype object) to output the geometries into.
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
Ignored if ``indices`` is provided.
|
|
|
|
Examples
|
|
--------
|
|
>>> import shapely
|
|
>>> shapely.linestrings([[[0, 1], [4, 5]], [[2, 3], [5, 6]]]).tolist()
|
|
[<LINESTRING (0 1, 4 5)>, <LINESTRING (2 3, 5 6)>]
|
|
>>> shapely.linestrings(
|
|
... [[0, 1], [4, 5], [2, 3], [5, 6], [7, 8]],
|
|
... indices=[0, 0, 1, 1, 1]
|
|
... ).tolist()
|
|
[<LINESTRING (0 1, 4 5)>, <LINESTRING (2 3, 5 6, 7 8)>]
|
|
|
|
Notes
|
|
-----
|
|
- Usage of the ``y`` and ``z`` arguments will prevents lazy evaluation in
|
|
``dask``. Instead provide the coordinates as a ``(..., 2)`` or
|
|
``(..., 3)`` array using only ``coords``.
|
|
|
|
"""
|
|
coords = _xyz_to_coords(coords, y, z)
|
|
if isinstance(handle_nan, str):
|
|
handle_nan = HandleNaN.get_value(handle_nan)
|
|
if indices is None:
|
|
return lib.linestrings(coords, np.intc(handle_nan), out=out, **kwargs)
|
|
else:
|
|
return simple_geometries_1d(
|
|
coords, indices, GeometryType.LINESTRING, handle_nan=handle_nan, out=out
|
|
)
|
|
|
|
|
|
# Note: future plan is to change this signature over a few releases:
|
|
# shapely 2.0:
|
|
# linearrings(coords, y=None, z=None, indices=None, out=None, **kwargs)
|
|
# shapely 2.1: shows deprecation warning about positional 'indices' arg
|
|
# linearrings(coords, y=None, z=None, indices=None, *, handle_nan=HandleNaN.allow, out=None, **kwargs) # noqa: E501
|
|
# shapely 2.2(?): enforce keyword-only arguments after 'z'
|
|
# linearrings(coords, y=None, z=None, *, indices=None, handle_nan=HandleNaN.allow, out=None, **kwargs) # noqa: E501
|
|
|
|
|
|
@deprecate_positional(["indices"], category=DeprecationWarning)
|
|
@multithreading_enabled
|
|
def linearrings(
|
|
coords,
|
|
y=None,
|
|
z=None,
|
|
indices=None,
|
|
*,
|
|
handle_nan=HandleNaN.allow,
|
|
out=None,
|
|
**kwargs,
|
|
):
|
|
"""Create an array of linearrings.
|
|
|
|
If the provided coords do not constitute a closed linestring, or if there
|
|
are only 3 provided coords, the first
|
|
coordinate is duplicated at the end to close the ring. This function will
|
|
raise an exception if a linearring contains less than three points or if
|
|
the terminal coordinates contain NaN (not-a-number).
|
|
|
|
Parameters
|
|
----------
|
|
coords : array_like
|
|
An array of lists of coordinate tuples (2- or 3-dimensional) or, if ``y``
|
|
is provided, an array of lists of x coordinates
|
|
y : array_like, optional
|
|
An array of y coordinates.
|
|
z : array_like, optional
|
|
An array of z coordinates.
|
|
indices : array_like, optional
|
|
Indices into the target array where input coordinates belong. If
|
|
provided, the coords should be 2D with shape (N, 2) or (N, 3) and
|
|
indices should be an array of shape (N,) with integers in increasing
|
|
order. Missing indices result in a ValueError unless ``out`` is
|
|
provided, in which case the original value in ``out`` is kept.
|
|
handle_nan : shapely.HandleNaN or {'allow', 'skip', 'error'}, default 'allow'
|
|
Specifies what to do when a NaN or Inf is encountered in the coordinates:
|
|
|
|
- 'allow': the geometries are created with NaN or Inf coordinates.
|
|
Note that this can result in unexpected behaviour in subsequent
|
|
operations, and generally it is discouraged to have non-finite
|
|
coordinate values. One can use this option if you know all
|
|
coordinates are finite and want to avoid the overhead of checking
|
|
for this.
|
|
- 'skip': the coordinate pairs where any of x, y or z values are
|
|
NaN or Inf are ignored. If this results in ignoring all coordinates
|
|
for one geometry, an empty geometry is created.
|
|
- 'error': if any NaN or Inf is detected in the coordinates, a ValueError
|
|
is raised. This option ensures that the created geometries have all
|
|
finite coordinate values.
|
|
|
|
.. versionadded:: 2.1.0
|
|
|
|
out : ndarray, optional
|
|
An array (with dtype object) to output the geometries into.
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
Ignored if ``indices`` is provided.
|
|
|
|
See Also
|
|
--------
|
|
linestrings
|
|
|
|
Examples
|
|
--------
|
|
>>> import shapely
|
|
>>> shapely.linearrings([[0, 0], [0, 1], [1, 1], [0, 0]])
|
|
<LINEARRING (0 0, 0 1, 1 1, 0 0)>
|
|
>>> shapely.linearrings([[0, 0], [0, 1], [1, 1]])
|
|
<LINEARRING (0 0, 0 1, 1 1, 0 0)>
|
|
|
|
Notes
|
|
-----
|
|
- Usage of the ``y`` and ``z`` arguments will prevents lazy evaluation in
|
|
``dask``. Instead provide the coordinates as a ``(..., 2)`` or
|
|
``(..., 3)`` array using only ``coords``.
|
|
|
|
"""
|
|
coords = _xyz_to_coords(coords, y, z)
|
|
if isinstance(handle_nan, str):
|
|
handle_nan = HandleNaN.get_value(handle_nan)
|
|
if indices is None:
|
|
return lib.linearrings(coords, np.intc(handle_nan), out=out, **kwargs)
|
|
else:
|
|
return simple_geometries_1d(
|
|
coords, indices, GeometryType.LINEARRING, handle_nan=handle_nan, out=out
|
|
)
|
|
|
|
|
|
# Note: future plan is to change this signature over a few releases:
|
|
# shapely 2.0:
|
|
# polygons(geometries, holes=None, indices=None, out=None, **kwargs)
|
|
# shapely 2.1: shows deprecation warning about positional 'indices' arg
|
|
# polygons(geometries, holes=None, indices=None, *, out=None, **kwargs)
|
|
# shapely 2.2(?): enforce keyword-only arguments after 'holes'
|
|
# polygons(geometries, holes=None, *, indices=None, out=None, **kwargs)
|
|
|
|
|
|
@deprecate_positional(["indices"], category=DeprecationWarning)
|
|
@multithreading_enabled
|
|
def polygons(geometries, holes=None, indices=None, *, out=None, **kwargs):
|
|
"""Create an array of polygons.
|
|
|
|
Parameters
|
|
----------
|
|
geometries : array_like
|
|
An array of linearrings or coordinates (see linearrings).
|
|
Unless ``indices`` are given (see description below), this
|
|
include the outer shells only. The ``holes`` argument should be used
|
|
to create polygons with holes.
|
|
holes : array_like, optional
|
|
An array of lists of linearrings that constitute holes for each shell.
|
|
Not to be used in combination with ``indices``.
|
|
indices : array_like, optional
|
|
Indices into the target array where input geometries belong. If
|
|
provided, the holes are expected to be present inside ``geometries``;
|
|
the first geometry for each index is the outer shell
|
|
and all subsequent geometries in that index are the holes.
|
|
Both geometries and indices should be 1D and have matching sizes.
|
|
Indices should be in increasing order. Missing indices result in a
|
|
ValueError unless ``out`` is provided, in which case the original value
|
|
in ``out`` is kept.
|
|
out : ndarray, optional
|
|
An array (with dtype object) to output the geometries into.
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
Ignored if ``indices`` is provided.
|
|
|
|
Notes
|
|
-----
|
|
|
|
.. deprecated:: 2.1.0
|
|
A deprecation warning is shown if ``indices`` is specified as a
|
|
positional argument. This will need to be specified as a keyword
|
|
argument in a future release.
|
|
|
|
Examples
|
|
--------
|
|
>>> import shapely
|
|
|
|
Polygons are constructed from rings:
|
|
|
|
>>> ring_1 = shapely.linearrings([[0, 0], [0, 10], [10, 10], [10, 0]])
|
|
>>> ring_2 = shapely.linearrings([[2, 6], [2, 7], [3, 7], [3, 6]])
|
|
>>> shapely.polygons([ring_1, ring_2])[0]
|
|
<POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>
|
|
>>> shapely.polygons([ring_1, ring_2])[1]
|
|
<POLYGON ((2 6, 2 7, 3 7, 3 6, 2 6))>
|
|
|
|
Or from coordinates directly:
|
|
|
|
>>> shapely.polygons([[0, 0], [0, 10], [10, 10], [10, 0]])
|
|
<POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>
|
|
|
|
Adding holes can be done using the ``holes`` keyword argument:
|
|
|
|
>>> shapely.polygons(ring_1, holes=[ring_2])
|
|
<POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0), (2 6, 2 7, 3 7, 3 6, 2 6))>
|
|
|
|
Or using the ``indices`` argument:
|
|
|
|
>>> shapely.polygons([ring_1, ring_2], indices=[0, 1])[0]
|
|
<POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>
|
|
>>> shapely.polygons([ring_1, ring_2], indices=[0, 1])[1]
|
|
<POLYGON ((2 6, 2 7, 3 7, 3 6, 2 6))>
|
|
>>> shapely.polygons([ring_1, ring_2], indices=[0, 0])[0]
|
|
<POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0), (2 6, 2 7, 3 7, 3 6, 2 6))>
|
|
|
|
Missing input values (``None``) are skipped and may result in an
|
|
empty polygon:
|
|
|
|
>>> shapely.polygons(None)
|
|
<POLYGON EMPTY>
|
|
>>> shapely.polygons(ring_1, holes=[None])
|
|
<POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>
|
|
>>> shapely.polygons([ring_1, None], indices=[0, 0])[0]
|
|
<POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>
|
|
|
|
"""
|
|
geometries = np.asarray(geometries)
|
|
if not isinstance(geometries, Geometry) and np.issubdtype(
|
|
geometries.dtype, np.number
|
|
):
|
|
geometries = linearrings(geometries)
|
|
|
|
if indices is not None:
|
|
if holes is not None:
|
|
raise TypeError("Cannot specify separate holes array when using indices.")
|
|
return collections_1d(geometries, indices, GeometryType.POLYGON, out=out)
|
|
|
|
if holes is None:
|
|
# no holes provided: initialize an empty holes array matching shells
|
|
shape = geometries.shape + (0,) if isinstance(geometries, np.ndarray) else (0,)
|
|
holes = np.empty(shape, dtype=object)
|
|
else:
|
|
holes = np.asarray(holes)
|
|
# convert holes coordinates into linearrings
|
|
if np.issubdtype(holes.dtype, np.number):
|
|
holes = linearrings(holes)
|
|
|
|
return lib.polygons(geometries, holes, out=out, **kwargs)
|
|
|
|
|
|
# Note: future plan is to change this signature over a few releases:
|
|
# shapely 2.0:
|
|
# box(xmin, ymin, xmax, ymax, ccw=True, **kwargs)
|
|
# shapely 2.1: shows deprecation warning about positional 'ccw' arg
|
|
# same signature as 2.0
|
|
# shapely 2.2(?): enforce keyword-only arguments after 'ymax'
|
|
# box(xmin, ymin, xmax, ymax, *, ccw=True, **kwargs)
|
|
|
|
|
|
@deprecate_positional(["ccw"], category=DeprecationWarning)
|
|
@multithreading_enabled
|
|
def box(xmin, ymin, xmax, ymax, ccw=True, **kwargs):
|
|
"""Create box polygons.
|
|
|
|
Parameters
|
|
----------
|
|
xmin : float or array_like
|
|
Float or array of minimum x coordinates.
|
|
ymin : float or array_like
|
|
Float or array of minimum y coordinates.
|
|
xmax : float or array_like
|
|
Float or array of maximum x coordinates.
|
|
ymax : float or array_like
|
|
Float or array of maximum y coordinates.
|
|
ccw : bool, default True
|
|
If True, box will be created in counterclockwise direction starting
|
|
from bottom right coordinate (xmax, ymin).
|
|
If False, box will be created in clockwise direction starting from
|
|
bottom left coordinate (xmin, ymin).
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
|
|
Notes
|
|
-----
|
|
|
|
.. deprecated:: 2.1.0
|
|
A deprecation warning is shown if ``ccw`` is specified as a
|
|
positional argument. This will need to be specified as a keyword
|
|
argument in a future release.
|
|
|
|
Examples
|
|
--------
|
|
>>> import shapely
|
|
>>> shapely.box(0, 0, 1, 1)
|
|
<POLYGON ((1 0, 1 1, 0 1, 0 0, 1 0))>
|
|
>>> shapely.box(0, 0, 1, 1, ccw=False)
|
|
<POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
|
|
|
|
"""
|
|
return lib.box(xmin, ymin, xmax, ymax, ccw, **kwargs)
|
|
|
|
|
|
# Note: future plan is to change this signature over a few releases:
|
|
# shapely 2.0:
|
|
# multipoints(geometries, indices=None, out=None, **kwargs)
|
|
# shapely 2.1: shows deprecation warning about positional 'indices' arg
|
|
# multipoints(geometries, indices=None, *, out=None, **kwargs)
|
|
# shapely 2.2(?): enforce keyword-only arguments after 'indices'
|
|
# multipoints(geometries, *, indices=None, out=None, **kwargs)
|
|
|
|
|
|
@deprecate_positional(["indices"], category=DeprecationWarning)
|
|
@multithreading_enabled
|
|
def multipoints(geometries, indices=None, *, out=None, **kwargs):
|
|
"""Create multipoints from arrays of points.
|
|
|
|
Parameters
|
|
----------
|
|
geometries : array_like
|
|
An array of points or coordinates (see points).
|
|
indices : array_like, optional
|
|
Indices into the target array where input geometries belong. If
|
|
provided, both geometries and indices should be 1D and have matching
|
|
sizes. Indices should be in increasing order. Missing indices result
|
|
in a ValueError unless ``out`` is provided, in which case the original
|
|
value in ``out`` is kept.
|
|
out : ndarray, optional
|
|
An array (with dtype object) to output the geometries into.
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
Ignored if ``indices`` is provided.
|
|
|
|
Notes
|
|
-----
|
|
|
|
.. deprecated:: 2.1.0
|
|
A deprecation warning is shown if ``indices`` is specified as a
|
|
positional argument. This will need to be specified as a keyword
|
|
argument in a future release.
|
|
|
|
Examples
|
|
--------
|
|
>>> import shapely
|
|
|
|
Multipoints are constructed from points:
|
|
|
|
>>> point_1 = shapely.points([1, 1])
|
|
>>> point_2 = shapely.points([2, 2])
|
|
>>> shapely.multipoints([point_1, point_2])
|
|
<MULTIPOINT ((1 1), (2 2))>
|
|
>>> shapely.multipoints([[point_1, point_2], [point_2, None]]).tolist()
|
|
[<MULTIPOINT ((1 1), (2 2))>, <MULTIPOINT ((2 2))>]
|
|
|
|
Or from coordinates directly:
|
|
|
|
>>> shapely.multipoints([[0, 0], [2, 2], [3, 3]])
|
|
<MULTIPOINT ((0 0), (2 2), (3 3))>
|
|
|
|
Multiple multipoints of different sizes can be constructed efficiently using the
|
|
``indices`` keyword argument:
|
|
|
|
>>> shapely.multipoints([point_1, point_2, point_2], indices=[0, 0, 1]).tolist()
|
|
[<MULTIPOINT ((1 1), (2 2))>, <MULTIPOINT ((2 2))>]
|
|
|
|
Missing input values (``None``) are skipped and may result in an
|
|
empty multipoint:
|
|
|
|
>>> shapely.multipoints([None])
|
|
<MULTIPOINT EMPTY>
|
|
>>> shapely.multipoints([point_1, None], indices=[0, 0]).tolist()
|
|
[<MULTIPOINT ((1 1))>]
|
|
>>> shapely.multipoints([point_1, None], indices=[0, 1]).tolist()
|
|
[<MULTIPOINT ((1 1))>, <MULTIPOINT EMPTY>]
|
|
|
|
"""
|
|
typ = GeometryType.MULTIPOINT
|
|
geometries = np.asarray(geometries)
|
|
if not isinstance(geometries, Geometry) and np.issubdtype(
|
|
geometries.dtype, np.number
|
|
):
|
|
geometries = points(geometries)
|
|
if indices is None:
|
|
return lib.create_collection(geometries, np.intc(typ), out=out, **kwargs)
|
|
else:
|
|
return collections_1d(geometries, indices, typ, out=out)
|
|
|
|
|
|
# Note: future plan is to change this signature over a few releases:
|
|
# shapely 2.0:
|
|
# multilinestrings(geometries, indices=None, out=None, **kwargs)
|
|
# shapely 2.1: shows deprecation warning about positional 'indices' arg
|
|
# multilinestrings(geometries, indices=None, *, out=None, **kwargs)
|
|
# shapely 2.2(?): enforce keyword-only arguments after 'indices'
|
|
# multilinestrings(geometries, *, indices=None, out=None, **kwargs)
|
|
|
|
|
|
@deprecate_positional(["indices"], category=DeprecationWarning)
|
|
@multithreading_enabled
|
|
def multilinestrings(geometries, indices=None, *, out=None, **kwargs):
|
|
"""Create multilinestrings from arrays of linestrings.
|
|
|
|
Parameters
|
|
----------
|
|
geometries : array_like
|
|
An array of linestrings or coordinates (see linestrings).
|
|
indices : array_like, optional
|
|
Indices into the target array where input geometries belong. If
|
|
provided, both geometries and indices should be 1D and have matching
|
|
sizes. Indices should be in increasing order. Missing indices result
|
|
in a ValueError unless ``out`` is provided, in which case the original
|
|
value in ``out`` is kept.
|
|
out : ndarray, optional
|
|
An array (with dtype object) to output the geometries into.
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
Ignored if ``indices`` is provided.
|
|
|
|
Notes
|
|
-----
|
|
|
|
.. deprecated:: 2.1.0
|
|
A deprecation warning is shown if ``indices`` is specified as a
|
|
positional argument. This will need to be specified as a keyword
|
|
argument in a future release.
|
|
|
|
See Also
|
|
--------
|
|
multipoints
|
|
|
|
"""
|
|
typ = GeometryType.MULTILINESTRING
|
|
geometries = np.asarray(geometries)
|
|
if not isinstance(geometries, Geometry) and np.issubdtype(
|
|
geometries.dtype, np.number
|
|
):
|
|
geometries = linestrings(geometries)
|
|
|
|
if indices is None:
|
|
return lib.create_collection(geometries, np.intc(typ), out=out, **kwargs)
|
|
else:
|
|
return collections_1d(geometries, indices, typ, out=out)
|
|
|
|
|
|
# Note: future plan is to change this signature over a few releases:
|
|
# shapely 2.0:
|
|
# multipolygons(geometries, indices=None, out=None, **kwargs)
|
|
# shapely 2.1: shows deprecation warning about positional 'indices' arg
|
|
# multipolygons(geometries, indices=None, *, out=None, **kwargs)
|
|
# shapely 2.2(?): enforce keyword-only arguments after 'indices'
|
|
# multipolygons(geometries, *, indices=None, out=None, **kwargs)
|
|
|
|
|
|
@deprecate_positional(["indices"], category=DeprecationWarning)
|
|
@multithreading_enabled
|
|
def multipolygons(geometries, indices=None, *, out=None, **kwargs):
|
|
"""Create multipolygons from arrays of polygons.
|
|
|
|
Parameters
|
|
----------
|
|
geometries : array_like
|
|
An array of polygons or coordinates (see polygons).
|
|
indices : array_like, optional
|
|
Indices into the target array where input geometries belong. If
|
|
provided, both geometries and indices should be 1D and have matching
|
|
sizes. Indices should be in increasing order. Missing indices result
|
|
in a ValueError unless ``out`` is provided, in which case the original
|
|
value in ``out`` is kept.
|
|
out : ndarray, optional
|
|
An array (with dtype object) to output the geometries into.
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
Ignored if ``indices`` is provided.
|
|
|
|
Notes
|
|
-----
|
|
|
|
.. deprecated:: 2.1.0
|
|
A deprecation warning is shown if ``indices`` is specified as a
|
|
positional argument. This will need to be specified as a keyword
|
|
argument in a future release.
|
|
|
|
See Also
|
|
--------
|
|
multipoints
|
|
|
|
"""
|
|
typ = GeometryType.MULTIPOLYGON
|
|
geometries = np.asarray(geometries)
|
|
if not isinstance(geometries, Geometry) and np.issubdtype(
|
|
geometries.dtype, np.number
|
|
):
|
|
geometries = polygons(geometries)
|
|
if indices is None:
|
|
return lib.create_collection(geometries, np.intc(typ), out=out, **kwargs)
|
|
else:
|
|
return collections_1d(geometries, indices, typ, out=out)
|
|
|
|
|
|
# Note: future plan is to change this signature over a few releases:
|
|
# shapely 2.0:
|
|
# geometrycollections(geometries, indices=None, out=None, **kwargs)
|
|
# shapely 2.1: shows deprecation warning about positional 'indices' arg
|
|
# geometrycollections(geometries, indices=None, *, out=None, **kwargs)
|
|
# shapely 2.2(?): enforce keyword-only arguments after 'indices'
|
|
# geometrycollections(geometries, *, indices=None, out=None, **kwargs)
|
|
|
|
|
|
@deprecate_positional(["indices"], category=DeprecationWarning)
|
|
@multithreading_enabled
|
|
def geometrycollections(geometries, indices=None, out=None, **kwargs):
|
|
"""Create geometrycollections from arrays of geometries.
|
|
|
|
Parameters
|
|
----------
|
|
geometries : array_like
|
|
An array of geometries.
|
|
indices : array_like, optional
|
|
Indices into the target array where input geometries belong. If
|
|
provided, both geometries and indices should be 1D and have matching
|
|
sizes. Indices should be in increasing order. Missing indices result
|
|
in a ValueError unless ``out`` is provided, in which case the original
|
|
value in ``out`` is kept.
|
|
out : ndarray, optional
|
|
An array (with dtype object) to output the geometries into.
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
Ignored if ``indices`` is provided.
|
|
|
|
Notes
|
|
-----
|
|
|
|
.. deprecated:: 2.1.0
|
|
A deprecation warning is shown if ``indices`` is specified as a
|
|
positional argument. This will need to be specified as a keyword
|
|
argument in a future release.
|
|
|
|
See Also
|
|
--------
|
|
multipoints
|
|
|
|
"""
|
|
typ = GeometryType.GEOMETRYCOLLECTION
|
|
if indices is None:
|
|
return lib.create_collection(geometries, np.intc(typ), out=out, **kwargs)
|
|
else:
|
|
return collections_1d(geometries, indices, typ, out=out)
|
|
|
|
|
|
def prepare(geometry, **kwargs):
|
|
"""Prepare a geometry, improving performance of other operations.
|
|
|
|
A prepared geometry is a normal geometry with added information such as an
|
|
index on the line segments. This improves the performance of the following
|
|
operations: contains, contains_properly, covered_by, covers, crosses,
|
|
disjoint, intersects, overlaps, touches, and within.
|
|
|
|
Note that if a prepared geometry is modified, the newly created Geometry
|
|
object is not prepared. In that case, ``prepare`` should be called again.
|
|
|
|
This function does not recompute previously prepared geometries;
|
|
it is efficient to call this function on an array that partially contains
|
|
prepared geometries.
|
|
|
|
This function does not return any values; geometries are modified in place.
|
|
|
|
Parameters
|
|
----------
|
|
geometry : Geometry or array_like
|
|
Geometries are changed in place
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
|
|
See Also
|
|
--------
|
|
is_prepared : Identify whether a geometry is prepared already.
|
|
destroy_prepared : Destroy the prepared part of a geometry.
|
|
|
|
Examples
|
|
--------
|
|
>>> import shapely
|
|
>>> from shapely import Point
|
|
>>> poly = shapely.buffer(Point(1.0, 1.0), 1)
|
|
>>> shapely.prepare(poly)
|
|
>>> shapely.contains_properly(poly, [Point(0.0, 0.0), Point(0.5, 0.5)]).tolist()
|
|
[False, True]
|
|
|
|
"""
|
|
lib.prepare(geometry, **kwargs)
|
|
|
|
|
|
def destroy_prepared(geometry, **kwargs):
|
|
"""Destroy the prepared part of a geometry, freeing up memory.
|
|
|
|
Note that the prepared geometry will always be cleaned up if the geometry itself
|
|
is dereferenced. This function needs only be called in very specific circumstances,
|
|
such as freeing up memory without losing the geometries, or benchmarking.
|
|
|
|
Parameters
|
|
----------
|
|
geometry : Geometry or array_like
|
|
Geometries are changed in-place
|
|
**kwargs
|
|
See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.
|
|
|
|
See Also
|
|
--------
|
|
prepare
|
|
|
|
"""
|
|
lib.destroy_prepared(geometry, **kwargs)
|
|
|
|
|
|
def empty(shape, geom_type=None, order="C"):
|
|
"""Create a geometry array prefilled with None or with empty geometries.
|
|
|
|
Parameters
|
|
----------
|
|
shape : int or tuple of int
|
|
Shape of the empty array, e.g., ``(2, 3)`` or ``2``.
|
|
geom_type : shapely.GeometryType, optional
|
|
The desired geometry type in case the array should be prefilled
|
|
with empty geometries. Default ``None``.
|
|
order : {'C', 'F'}, optional, default: 'C'
|
|
Whether to store multi-dimensional data in row-major
|
|
(C-style) or column-major (Fortran-style) order in
|
|
memory.
|
|
|
|
Examples
|
|
--------
|
|
>>> import shapely
|
|
>>> shapely.empty((2, 3)).tolist()
|
|
[[None, None, None], [None, None, None]]
|
|
>>> shapely.empty(2, geom_type=shapely.GeometryType.POINT).tolist()
|
|
[<POINT EMPTY>, <POINT EMPTY>]
|
|
|
|
"""
|
|
if geom_type is None:
|
|
return np.empty(shape, dtype=object, order=order)
|
|
|
|
geom_type = GeometryType(geom_type) # cast int to GeometryType
|
|
if geom_type is GeometryType.MISSING:
|
|
return np.empty(shape, dtype=object, order=order)
|
|
|
|
fill_value = from_wkt(geom_type.name + " EMPTY")
|
|
return np.full(shape, fill_value, dtype=object, order=order)
|