shapely.to_ragged_array

shapely.to_ragged_array#

to_ragged_array(geometries, include_z=None, include_m=None)#

Convert geometries to a ragged array representation.

This function converts an array of geometries to a ragged array (i.e. irregular array of arrays) of coordinates, represented in memory using a single contiguous array of the coordinates, and up to 3 offset arrays that keep track where each sub-array starts and ends.

This follows the in-memory layout of the variable size list arrays defined by Apache Arrow, as specified for geometries by the GeoArrow project: geoarrow/geoarrow.

Parameters:
geometriesarray_like

Array of geometries (1-dimensional).

include_z, include_mbool, default None

If both are False, return XY (2D) geometries. If both are True, return XYZM (4D) geometries. If either is True, return either XYZ or XYM (3D) geometries. If a geometry has no Z or M dimension, extra coordinate data will be NaN. By default, will infer the dimensionality from the input geometries. Note that this inference can be unreliable with empty geometries (for a guaranteed result, it is recommended to specify the keyword).

Added in version 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.

Returns:
tuple of (geometry_type, coords, offsets)
geometry_typeGeometryType

The type of the input geometries (required information for roundtrip).

coordsnp.ndarray

Contiguous array of shape (n, 2), (n, 3), or (n, 4) of all coordinates of all input geometries.

offsets: tuple of np.ndarray

Offset arrays that make it possible to reconstruct the geometries from the flat coordinates array. The number of offset arrays depends on the geometry type. See geoarrow/geoarrow for details. Uses int32 dtype offsets if possible, otherwise int64 for large inputs (coordinates > 32GB).

See also

from_ragged_array

Notes

Mixed singular and multi geometry types of the same basic type are allowed (e.g., Point and MultiPoint) and all singular types will be treated as multi types. GeometryCollections and other mixed geometry types are not supported.

Examples

Consider a Polygon with one hole (interior ring):

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

This polygon can be thought of as a list of rings (first ring is the exterior ring, subsequent rings are the interior rings), and each ring as a list of coordinate pairs. This is very similar to how GeoJSON represents the coordinates:

>>> import json
>>> json.loads(shapely.to_geojson(polygon))["coordinates"]
[[[0.0, 0.0], [10.0, 0.0], [10.0, 10.0], [0.0, 10.0], [0.0, 0.0]],
 [[2.0, 2.0], [3.0, 2.0], [2.0, 3.0], [2.0, 2.0]]]

This function will return a similar list of lists of lists, but using a single contiguous array of coordinates, and multiple arrays of offsets:

>>> geometry_type, coords, offsets = shapely.to_ragged_array([polygon])
>>> geometry_type
<GeometryType.POLYGON: 3>
>>> coords
array([[ 0.,  0.],
       [10.,  0.],
       [10., 10.],
       [ 0., 10.],
       [ 0.,  0.],
       [ 2.,  2.],
       [ 3.,  2.],
       [ 2.,  3.],
       [ 2.,  2.]])

>>> offsets
(array([0, 5, 9], dtype=int32), array([0, 2], dtype=int32))

As an example how to interpret the offsets: the i-th ring in the coordinates is represented by offsets[0][i] to offsets[0][i+1]:

>>> exterior_ring_start, exterior_ring_end = offsets[0][0], offsets[0][1]
>>> coords[exterior_ring_start:exterior_ring_end]
array([[ 0.,  0.],
       [10.,  0.],
       [10., 10.],
       [ 0., 10.],
       [ 0.,  0.]])
Contents