Geometry

The pygeos.Geometry class is the central datatype in PyGEOS. An instance of Geometry is a container of the actual GEOSGeometry object. The Geometry object keeps track of the underlying GEOSGeometry and lets the python garbage collector free its memory when it is not used anymore.

Geometry objects are immutable. This means that after constructed, they cannot be changed in place. Every PyGEOS operation will result in a new object being returned.

Construction

For convenience, the Geometry class can be constructed with a WKT (Well-Known Text) or WKB (Well-Known Binary) representation of a geometry:

>>> from pygeos import Geometry
>>> point_1 = Geometry("POINT (5.2 52.1)")
>>> point_2 = Geometry(b"\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\xf0?\x00\x00\x00\x00\x00\x00\xf0?")

A more efficient way of constructing geometries is by making use of the (vectorized) functions described in pygeos.creation.

Pickling

Geometries can be serialized using pickle:

>>> import pickle
>>> pickled = pickle.dumps(point_1)
>>> pickle.loads(point_1)
<pygeos.Geometry POINT (5.2 52.1)>

Warning

Pickling will convert linearrings to linestrings. See pygeos.io.to_wkb() for a complete list of limitations.

Hashing

Geometries can be used as elements in sets or as keys in dictionaries. Python uses a technique called hashing for lookups in these datastructures. PyGEOS generates this hash from the WKB representation. Therefore, geometries are equal if and only if their WKB representations are equal.

>>> point_3 = Geometry("POINT (5.2 52.1)")
>>> {point_1, point_2, point_3}
{<pygeos.Geometry POINT (5.2 52.1)>, <pygeos.Geometry POINT (1 1)>}

Warning

Due to limitations of WKB, linearrings will equal linestrings if they contain the exact same points. See pygeos.io.to_wkb().

Comparing two geometries directly is also supported. This is the same as using pygeos.predicates.equals_exact() with a tolerance value of zero.

>>> point_1 == point_2
False
>>> point_1 != point_2
True

Properties

Geometry objects have neither properties nor methods. Instead, use the functions listed below to obtain information about geometry objects.

force_2d(geometry, **kwargs)

Forces the dimensionality of a geometry to 2D.

Parameters
geometryGeometry or array_like
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> force_2d(Geometry("POINT Z (0 0 0)"))
<pygeos.Geometry POINT (0 0)>
>>> force_2d(Geometry("POINT (0 0)"))
<pygeos.Geometry POINT (0 0)>
>>> force_2d(Geometry("LINESTRING (0 0 0, 0 1 1, 1 1 2)"))
<pygeos.Geometry LINESTRING (0 0, 0 1, 1 1)>
>>> force_2d(Geometry("POLYGON Z EMPTY"))
<pygeos.Geometry POLYGON EMPTY>
>>> force_2d(None) is None
True
force_3d(geometry, z=0.0, **kwargs)

Forces the dimensionality of a geometry to 3D.

2D geometries will get the provided Z coordinate; Z coordinates of 3D geometries are unchanged (unless they are nan).

Note that for empty geometries, 3D is only supported since GEOS 3.9 and then still only for simple geometries (non-collections).

Parameters
geometryGeometry or array_like
zfloat or array_like, default 0.0
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> force_3d(Geometry("POINT (0 0)"), z=3)
<pygeos.Geometry POINT Z (0 0 3)>
>>> force_3d(Geometry("POINT Z (0 0 0)"), z=3)
<pygeos.Geometry POINT Z (0 0 0)>
>>> force_3d(Geometry("LINESTRING (0 0, 0 1, 1 1)"))
<pygeos.Geometry LINESTRING Z (0 0 0, 0 1 0, 1 1 0)>
>>> force_3d(None) is None
True
get_coordinate_dimension(geometry, **kwargs)

Returns the dimensionality of the coordinates in a geometry (2 or 3).

Returns -1 for missing geometries (None values). Note that if the first Z coordinate equals nan, this function will return 2.

Parameters
geometryGeometry or array_like
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> get_coordinate_dimension(Geometry("POINT (0 0)"))
2
>>> get_coordinate_dimension(Geometry("POINT Z (0 0 0)"))
3
>>> get_coordinate_dimension(None)
-1
>>> get_coordinate_dimension(Geometry("POINT Z (0 0 nan)"))
2
get_dimensions(geometry, **kwargs)

Returns the inherent dimensionality of a geometry.

The inherent dimension is 0 for points, 1 for linestrings and linearrings, and 2 for polygons. For geometrycollections it is the max of the containing elements. Empty collections and None values return -1.

Parameters
geometryGeometry or array_like
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> get_dimensions(Geometry("POINT (0 0)"))
0
>>> get_dimensions(Geometry("POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))"))
2
>>> get_dimensions(Geometry("GEOMETRYCOLLECTION (POINT(0 0), LINESTRING(0 0, 1 1))"))
1
>>> get_dimensions(Geometry("GEOMETRYCOLLECTION EMPTY"))
-1
>>> get_dimensions(None)
-1
get_exterior_ring(geometry, **kwargs)

Returns the exterior ring of a polygon.

Parameters
geometryGeometry or array_like
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> get_exterior_ring(Geometry("POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))"))
<pygeos.Geometry LINEARRING (0 0, 0 10, 10 10, 10 0, 0 0)>
>>> get_exterior_ring(Geometry("POINT (1 1)")) is None
True
get_geometry(geometry, index, **kwargs)

Returns the nth geometry from a collection of geometries.

Parameters
geometryGeometry or array_like
indexint or array_like

Negative values count from the end of the collection backwards.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Notes

  • simple geometries act as length-1 collections

  • out-of-range values return None

Examples

>>> multipoint = Geometry("MULTIPOINT (0 0, 1 1, 2 2, 3 3)")
>>> get_geometry(multipoint, 1)
<pygeos.Geometry POINT (1 1)>
>>> get_geometry(multipoint, -1)
<pygeos.Geometry POINT (3 3)>
>>> get_geometry(multipoint, 5) is None
True
>>> get_geometry(Geometry("POINT (1 1)"), 0)
<pygeos.Geometry POINT (1 1)>
>>> get_geometry(Geometry("POINT (1 1)"), 1) is None
True
get_interior_ring(geometry, index, **kwargs)

Returns the nth interior ring of a polygon.

Parameters
geometryGeometry or array_like
indexint or array_like

Negative values count from the end of the interior rings backwards.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> polygon_with_hole = Geometry("POLYGON((0 0, 0 10, 10 10, 10 0, 0 0), (2 2, 2 4, 4 4, 4 2, 2 2))")
>>> get_interior_ring(polygon_with_hole, 0)
<pygeos.Geometry LINEARRING (2 2, 2 4, 4 4, 4 2, 2 2)>
>>> get_interior_ring(Geometry("POINT (1 1)"), 0) is None
True
get_num_coordinates(geometry, **kwargs)

Returns the total number of coordinates in a geometry.

Returns 0 for not-a-geometry values.

Parameters
geometryGeometry or array_like
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> get_num_coordinates(Geometry("POINT (0 0)"))
1
>>> get_num_coordinates(Geometry("POINT Z (0 0 0)"))
1
>>> get_num_coordinates(Geometry("GEOMETRYCOLLECTION (POINT(0 0), LINESTRING(0 0, 1 1))"))
3
>>> get_num_coordinates(None)
0
get_num_geometries(geometry, **kwargs)

Returns number of geometries in a collection.

Returns 0 for not-a-geometry values.

Parameters
geometryGeometry or array_like

The number of geometries in points, linestrings, linearrings and polygons equals one.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> get_num_geometries(Geometry("MULTIPOINT (0 0, 1 1, 2 2, 3 3)"))
4
>>> get_num_geometries(Geometry("POINT (1 1)"))
1
>>> get_num_geometries(None)
0
get_num_interior_rings(geometry, **kwargs)

Returns number of internal rings in a polygon

Returns 0 for not-a-geometry values.

Parameters
geometryGeometry or array_like

The number of interior rings in non-polygons equals zero.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> polygon = Geometry("POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))")
>>> get_num_interior_rings(polygon)
0
>>> polygon_with_hole = Geometry("POLYGON((0 0, 0 10, 10 10, 10 0, 0 0), (2 2, 2 4, 4 4, 4 2, 2 2))")
>>> get_num_interior_rings(polygon_with_hole)
1
>>> get_num_interior_rings(Geometry("POINT (1 1)"))
0
>>> get_num_interior_rings(None)
0
get_num_points(geometry, **kwargs)

Returns number of points in a linestring or linearring.

Returns 0 for not-a-geometry values.

Parameters
geometryGeometry or array_like

The number of points in geometries other than linestring or linearring equals zero.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> line = Geometry("LINESTRING (0 0, 1 1, 2 2, 3 3)")
>>> get_num_points(line)
4
>>> get_num_points(Geometry("MULTIPOINT (0 0, 1 1, 2 2, 3 3)"))
0
>>> get_num_points(None)
0
get_parts(geometry, return_index=False)

Gets parts of each GeometryCollection or Multi* geometry object; returns a copy of each geometry in the GeometryCollection or Multi* geometry object.

Note: This does not return the individual parts of Multi* geometry objects in a GeometryCollection. You may need to call this function multiple times to return individual parts of Multi* geometry objects in a GeometryCollection.

Parameters
geometryGeometry or array_like
return_indexbool, default False

If True, will return a tuple of ndarrays of (parts, indexes), where indexes are the indexes of the original geometries in the source array.

Returns
ndarray of parts or tuple of (parts, indexes)

Examples

>>> get_parts(Geometry("MULTIPOINT (0 1, 2 3)")).tolist()
[<pygeos.Geometry POINT (0 1)>, <pygeos.Geometry POINT (2 3)>]
>>> parts, index = get_parts([Geometry("MULTIPOINT (0 1)"), Geometry("MULTIPOINT (4 5, 6 7)")], return_index=True)
>>> parts.tolist()
[<pygeos.Geometry POINT (0 1)>, <pygeos.Geometry POINT (4 5)>, <pygeos.Geometry POINT (6 7)>]
>>> index.tolist()
[0, 1, 1]
get_point(geometry, index, **kwargs)

Returns the nth point of a linestring or linearring.

Parameters
geometryGeometry or array_like
indexint or array_like

Negative values count from the end of the linestring backwards.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

get_num_points

Examples

>>> line = Geometry("LINESTRING (0 0, 1 1, 2 2, 3 3)")
>>> get_point(line, 1)
<pygeos.Geometry POINT (1 1)>
>>> get_point(line, -2)
<pygeos.Geometry POINT (2 2)>
>>> get_point(line, [0, 3]).tolist()
[<pygeos.Geometry POINT (0 0)>, <pygeos.Geometry POINT (3 3)>]
>>> get_point(Geometry("LINEARRING (0 0, 1 1, 2 2, 0 0)"), 1)
<pygeos.Geometry POINT (1 1)>
>>> get_point(Geometry("MULTIPOINT (0 0, 1 1, 2 2, 3 3)"), 1) is None
True
>>> get_point(Geometry("POINT (1 1)"), 0) is None
True
get_precision(geometry, **kwargs)

Get the precision of a geometry.

Note

‘get_precision’ requires at least GEOS 3.6.0.

If a precision has not been previously set, it will be 0 (double precision). Otherwise, it will return the precision grid size that was set on a geometry.

Returns NaN for not-a-geometry values.

Parameters
geometryGeometry or array_like
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

set_precision

Examples

>>> get_precision(Geometry("POINT (1 1)"))
0.0
>>> geometry = set_precision(Geometry("POINT (1 1)"), 1.0)
>>> get_precision(geometry)
1.0
>>> np.isnan(get_precision(None))
True
get_rings(geometry, return_index=False)

Gets rings of Polygon geometry object.

For each Polygon, the first returned ring is always the exterior ring and potential subsequent rings are interior rings.

If the geometry is not a Polygon, nothing is returned (empty array for scalar geometry input or no element in output array for array input).

Parameters
geometryGeometry or array_like
return_indexbool, default False

If True, will return a tuple of ndarrays of (rings, indexes), where indexes are the indexes of the original geometries in the source array.

Returns
ndarray of rings or tuple of (rings, indexes)

Examples

>>> polygon_with_hole = Geometry("POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0), (2 2, 2 4, 4 4, 4 2, 2 2))")
>>> get_rings(polygon_with_hole).tolist()
[<pygeos.Geometry LINEARRING (0 0, 0 10, 10 10, 10 0, 0 0)>,
 <pygeos.Geometry LINEARRING (2 2, 2 4, 4 4, 4 2, 2 2)>]

With return_index=True:

>>> polygon = Geometry("POLYGON ((0 0, 2 0, 2 2, 0 2, 0 0))")
>>> rings, index = get_rings([polygon, polygon_with_hole], return_index=True)
>>> rings.tolist()
[<pygeos.Geometry LINEARRING (0 0, 2 0, 2 2, 0 2, 0 0)>,
 <pygeos.Geometry LINEARRING (0 0, 0 10, 10 10, 10 0, 0 0)>,
 <pygeos.Geometry LINEARRING (2 2, 2 4, 4 4, 4 2, 2 2)>]
>>> index.tolist()
[0, 1, 1]
get_srid(geometry, **kwargs)

Returns the SRID of a geometry.

Returns -1 for not-a-geometry values.

Parameters
geometryGeometry or array_like
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

set_srid

Examples

>>> point = Geometry("POINT (0 0)")
>>> with_srid = set_srid(point, 4326)
>>> get_srid(point)
0
>>> get_srid(with_srid)
4326
get_type_id(geometry, **kwargs)

Returns the type ID of a geometry.

  • None (missing) is -1

  • POINT is 0

  • LINESTRING is 1

  • LINEARRING is 2

  • POLYGON is 3

  • MULTIPOINT is 4

  • MULTILINESTRING is 5

  • MULTIPOLYGON is 6

  • GEOMETRYCOLLECTION is 7

Parameters
geometryGeometry or array_like
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

GeometryType

Examples

>>> get_type_id(Geometry("LINESTRING (0 0, 1 1, 2 2, 3 3)"))
1
>>> get_type_id([Geometry("POINT (1 2)"), Geometry("POINT (1 2)")]).tolist()
[0, 0]
get_x(point, **kwargs)

Returns the x-coordinate of a point

Parameters
pointGeometry or array_like

Non-point geometries will result in NaN being returned.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

get_y, get_z

Examples

>>> get_x(Geometry("POINT (1 2)"))
1.0
>>> get_x(Geometry("MULTIPOINT (1 1, 1 2)"))
nan
get_y(point, **kwargs)

Returns the y-coordinate of a point

Parameters
pointGeometry or array_like

Non-point geometries will result in NaN being returned.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

get_x, get_z

Examples

>>> get_y(Geometry("POINT (1 2)"))
2.0
>>> get_y(Geometry("MULTIPOINT (1 1, 1 2)"))
nan
get_z(point, **kwargs)

Returns the z-coordinate of a point.

Note

‘get_z’ requires at least GEOS 3.7.0.

Parameters
pointGeometry or array_like

Non-point geometries or geometries without 3rd dimension will result in NaN being returned.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

get_x, get_y

Examples

>>> get_z(Geometry("POINT Z (1 2 3)"))
3.0
>>> get_z(Geometry("POINT (1 2)"))
nan
>>> get_z(Geometry("MULTIPOINT Z (1 1 1, 2 2 2)"))
nan
set_precision(geometry, grid_size, mode='valid_output', **kwargs)

Returns geometry with the precision set to a precision grid size.

Note

‘set_precision’ requires at least GEOS 3.6.0.

By default, geometries use double precision coordinates (grid_size = 0).

Coordinates will be rounded if a precision grid is less precise than the input geometry. Duplicated vertices will be dropped from lines and polygons for grid sizes greater than 0. Line and polygon geometries may collapse to empty geometries if all vertices are closer together than grid_size. Z values, if present, will not be modified.

Note: subsequent operations will always be performed in the precision of the geometry with higher precision (smaller “grid_size”). That same precision will be attached to the operation outputs.

Also note: input geometries should be geometrically valid; unexpected results may occur if input geometries are not.

Returns None if geometry is None.

Parameters
geometryGeometry or array_like
grid_sizefloat

Precision grid size. If 0, will use double precision (will not modify geometry if precision grid size was not previously set). If this value is more precise than input geometry, the input geometry will not be modified.

mode{‘valid_output’, ‘pointwise’, ‘keep_collapsed’}, default ‘valid_output’

This parameter determines how to handle invalid output geometries. There are three modes:

  1. ‘valid_output’ (default): The output is always valid. Collapsed geometry elements (including both polygons and lines) are removed. Duplicate vertices are removed.

  2. ‘pointwise’: Precision reduction is performed pointwise. Output geometry may be invalid due to collapse or self-intersection. Duplicate vertices are not removed. In GEOS this option is called NO_TOPO.

    Note

    ‘pointwise’ mode requires at least GEOS 3.10. It is accepted in earlier versions, but the results may be unexpected.

  3. ‘keep_collapsed’: Like the default mode, except that collapsed linear geometry elements are preserved. Collapsed polygonal input elements are removed. Duplicate vertices are removed.

preserve_topologybool, optional

Deprecated since version 0.11: This parameter is ignored. Use mode instead.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

get_precision

Examples

>>> set_precision(Geometry("POINT (0.9 0.9)"), 1.0)
<pygeos.Geometry POINT (1 1)>
>>> set_precision(Geometry("POINT (0.9 0.9 0.9)"), 1.0)
<pygeos.Geometry POINT Z (1 1 0.9)>
>>> set_precision(Geometry("LINESTRING (0 0, 0 0.1, 0 1, 1 1)"), 1.0)
<pygeos.Geometry LINESTRING (0 0, 0 1, 1 1)>
>>> set_precision(Geometry("LINESTRING (0 0, 0 0.1, 0.1 0.1)"), 1.0, mode="valid_output")
<pygeos.Geometry LINESTRING Z EMPTY>
>>> set_precision(Geometry("LINESTRING (0 0, 0 0.1, 0.1 0.1)"), 1.0, mode="pointwise")
<pygeos.Geometry LINESTRING (0 0, 0 0, 0 0)>
>>> set_precision(Geometry("LINESTRING (0 0, 0 0.1, 0.1 0.1)"), 1.0, mode="keep_collapsed")
<pygeos.Geometry LINESTRING (0 0, 0 0)>
>>> set_precision(None, 1.0) is None
True
set_srid(geometry, srid, **kwargs)

Returns a geometry with its SRID set.

Parameters
geometryGeometry or array_like
sridint
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

get_srid

Examples

>>> point = Geometry("POINT (0 0)")
>>> with_srid = set_srid(point, 4326)
>>> get_srid(point)
0
>>> get_srid(with_srid)
4326