Geometry creation¶

box(xmin, ymin, xmax, ymax, ccw=True, **kwargs)¶

Create box polygons.

Parameters

xminarray_like
yminarray_like
xmaxarray_like
ymaxarray_like
ccwbool, 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: For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> box(0, 0, 1, 1)
<pygeos.Geometry POLYGON ((1 0, 1 1, 0 1, 0 0, 1 0))>
>>> box(0, 0, 1, 1, ccw=False)
<pygeos.Geometry POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>

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

geometryGeometry or array_like: Geometries are changed inplace
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs.

See also

prepare

empty(shape, geom_type=None, order='C')¶

Create a geometry array prefilled with None or with empty geometries.

Parameters

shapeint or tuple of int: Shape of the empty array, e.g., (2, 3) or 2.
geom_typepygeos.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

>>> empty((2, 3)).tolist()
[[None, None, None], [None, None, None]]
>>> empty(2, geom_type=GeometryType.POINT).tolist()
[<pygeos.Geometry POINT EMPTY>, <pygeos.Geometry POINT EMPTY>]

geometrycollections(geometries, indices=None, out=None, **kwargs)¶

Create geometrycollections from arrays of geometries

Parameters

geometriesarray_like: An array of geometries
indicesarray_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.
outndarray, optional: An array (with dtype object) to output the geometries into.
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs. Ignored if indices is provided.

See also

multipoints

linearrings(coords, y=None, z=None, indices=None, 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

coordsarray_like: An array of lists of coordinate tuples (2- or 3-dimensional) or, if y is provided, an array of lists of x coordinates
yarray_like, optional
zarray_like, optional
indicesarray_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.
outndarray, optional: An array (with dtype object) to output the geometries into.
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs. Ignored if indices is provided.

See also

linestrings

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.

Examples

>>> linearrings([[0, 0], [0, 1], [1, 1], [0, 0]])
<pygeos.Geometry LINEARRING (0 0, 0 1, 1 1, 0 0)>
>>> linearrings([[0, 0], [0, 1], [1, 1]])
<pygeos.Geometry LINEARRING (0 0, 0 1, 1 1, 0 0)>

linestrings(coords, y=None, z=None, indices=None, out=None, **kwargs)¶

Create an array of linestrings.

This function will raise an exception if a linestring contains less than two points.

Parameters

coordsarray_like: An array of lists of coordinate tuples (2- or 3-dimensional) or, if y is provided, an array of lists of x coordinates
yarray_like, optional
zarray_like, optional
indicesarray_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.
outndarray, optional: An array (with dtype object) to output the geometries into.
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs. Ignored if indices is provided.

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.

Examples

>>> linestrings([[[0, 1], [4, 5]], [[2, 3], [5, 6]]]).tolist()
[<pygeos.Geometry LINESTRING (0 1, 4 5)>, <pygeos.Geometry LINESTRING (2 3, 5 6)>]
>>> linestrings([[0, 1], [4, 5], [2, 3], [5, 6], [7, 8]], indices=[0, 0, 1, 1, 1]).tolist()
[<pygeos.Geometry LINESTRING (0 1, 4 5)>, <pygeos.Geometry LINESTRING (2 3, 5 6, 7 8)>]

multilinestrings(geometries, indices=None, out=None, **kwargs)¶

Create multilinestrings from arrays of linestrings

Parameters

geometriesarray_like: An array of linestrings or coordinates (see linestrings).
indicesarray_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.
outndarray, optional: An array (with dtype object) to output the geometries into.
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs. Ignored if indices is provided.

See also

multipoints

multipoints(geometries, indices=None, out=None, **kwargs)¶

Create multipoints from arrays of points

Parameters

geometriesarray_like: An array of points or coordinates (see points).
indicesarray_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.
outndarray, optional: An array (with dtype object) to output the geometries into.
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs. Ignored if indices is provided.

Examples

Multipoints are constructed from points:

>>> point_1 = points([1, 1])
>>> point_2 = points([2, 2])
>>> multipoints([point_1, point_2])
<pygeos.Geometry MULTIPOINT (1 1, 2 2)>
>>> multipoints([[point_1, point_2], [point_2, None]]).tolist()
[<pygeos.Geometry MULTIPOINT (1 1, 2 2)>, <pygeos.Geometry MULTIPOINT (2 2)>]

Or from coordinates directly:

>>> multipoints([[0, 0], [2, 2], [3, 3]])
<pygeos.Geometry MULTIPOINT (0 0, 2 2, 3 3)>

Multiple multipoints of different sizes can be constructed efficiently using the indices keyword argument:

>>> multipoints([point_1, point_2, point_2], indices=[0, 0, 1]).tolist()
[<pygeos.Geometry MULTIPOINT (1 1, 2 2)>, <pygeos.Geometry MULTIPOINT (2 2)>]

Missing input values (None) are ignored and may result in an empty multipoint:

>>> multipoints([None])
<pygeos.Geometry MULTIPOINT EMPTY>
>>> multipoints([point_1, None], indices=[0, 0]).tolist()
[<pygeos.Geometry MULTIPOINT (1 1)>]
>>> multipoints([point_1, None], indices=[0, 1]).tolist()
[<pygeos.Geometry MULTIPOINT (1 1)>, <pygeos.Geometry MULTIPOINT EMPTY>]

multipolygons(geometries, indices=None, out=None, **kwargs)¶

Create multipolygons from arrays of polygons

Parameters

geometriesarray_like: An array of polygons or coordinates (see polygons).
indicesarray_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.
outndarray, optional: An array (with dtype object) to output the geometries into.
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs. Ignored if indices is provided.

See also

multipoints

points(coords, y=None, z=None, indices=None, out=None, **kwargs)¶

Create an array of points.

Parameters

coordsarray_like: An array of coordinate tuples (2- or 3-dimensional) or, if y is provided, an array of x coordinates.
yarray_like, optional
zarray_like, optional
indicesarray_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.
outndarray, optional: An array (with dtype object) to output the geometries into.
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs. Ignored if indices is provided.

Notes

GEOS >=3.10 automatically converts POINT (nan nan) to POINT EMPTY.
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.

Examples

>>> points([[0, 1], [4, 5]]).tolist()
[<pygeos.Geometry POINT (0 1)>, <pygeos.Geometry POINT (4 5)>]
>>> points([0, 1, 2])
<pygeos.Geometry POINT Z (0 1 2)>

polygons(geometries, holes=None, indices=None, out=None, **kwargs)¶

Create an array of polygons.

Parameters

geometriesarray_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.
holesarray_like, optional: An array of lists of linearrings that constitute holes for each shell. Not to be used in combination with indices.
indicesarray_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.
outndarray, optional: An array (with dtype object) to output the geometries into.
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs. Ignored if indices is provided.

Examples

Polygons are constructed from rings:

>>> ring_1 = linearrings([[0, 0], [0, 10], [10, 10], [10, 0]])
>>> ring_2 = linearrings([[2, 6], [2, 7], [3, 7], [3, 6]])
>>> polygons([ring_1, ring_2])[0]
<pygeos.Geometry POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>
>>> polygons([ring_1, ring_2])[1]
<pygeos.Geometry POLYGON ((2 6, 2 7, 3 7, 3 6, 2 6))>

Or from coordinates directly:

>>> polygons([[0, 0], [0, 10], [10, 10], [10, 0]])
<pygeos.Geometry POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>

Adding holes can be done using the holes keyword argument:

>>> polygons(ring_1, holes=[ring_2])
<pygeos.Geometry POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0), (2 6, 2 7, 3 7, 3 6...>

Or using the indices argument:

>>> polygons([ring_1, ring_2], indices=[0, 1])[0]
<pygeos.Geometry POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>
>>> polygons([ring_1, ring_2], indices=[0, 1])[1]
<pygeos.Geometry POLYGON ((2 6, 2 7, 3 7, 3 6, 2 6))>
>>> polygons([ring_1, ring_2], indices=[0, 0])[0]
<pygeos.Geometry POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0), (2 6, 2 7, 3 7, 3 6...>

Missing input values (None) are ignored and may result in an empty polygon:

>>> polygons(None)
<pygeos.Geometry POLYGON EMPTY>
>>> polygons(ring_1, holes=[None])
<pygeos.Geometry POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>
>>> polygons([ring_1, None], indices=[0, 0])[0]
<pygeos.Geometry POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0))>

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.

Parameters

geometryGeometry or array_like: Geometries are changed inplace
**kwargs: For other keyword-only arguments, see the NumPy ufunc docs.

See also

is_prepared: Identify whether a geometry is prepared already.
destroy_prepared: Destroy the prepared part of a geometry.