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 equalsnan
, this function will return2
.- 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.
See also
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.
See also
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.
See also
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.
See also
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.
See also
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.
See also
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)
See also
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
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
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)
See also
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
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.
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.
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.
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:
‘valid_output’ (default): The output is always valid. Collapsed geometry elements (including both polygons and lines) are removed. Duplicate vertices are removed.
‘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.
‘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
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
Examples
>>> point = Geometry("POINT (0 0)") >>> with_srid = set_srid(point, 4326) >>> get_srid(point) 0 >>> get_srid(with_srid) 4326