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 and it may convert empty points. 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. Also, different kind of empty points will be considered equal. 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.

pygeos.geometry.get_coordinate_dimension(geometry)¶

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

Returns -1 for not-a-geometry values.

Parameters

geometryGeometry or array_like

Examples

>>> get_coordinate_dimension(Geometry("POINT (0 0)"))
2
>>> get_coordinate_dimension(Geometry("POINT Z (0 0 0)"))
3
>>> get_coordinate_dimension(None)
-1

pygeos.geometry.get_dimensions(geometry)¶

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 and None geometries return -1.

Parameters

geometryGeometry or array_like

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

pygeos.geometry.get_exterior_ring(geometry)¶

Returns the exterior ring of a polygon.

Parameters

geometryGeometry or array_like

See also

get_interior_ring

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

pygeos.geometry.get_geometry(geometry, index)¶

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.

See also

get_num_geometries

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

pygeos.geometry.get_interior_ring(geometry, index)¶

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.

See also

get_exterior_ring
get_num_interior_rings

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

pygeos.geometry.get_num_coordinates(geometry)¶

Returns the total number of coordinates in a geometry.

Returns 0 for not-a-geometry values.

Parameters

geometryGeometry or array_like

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

pygeos.geometry.get_num_geometries(geometry)¶

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.

See also

get_num_points
get_geometry

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

pygeos.geometry.get_num_interior_rings(geometry)¶

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.

See also

get_exterior_ring
get_interior_ring

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

pygeos.geometry.get_num_points(geometry)¶

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.

See also

get_point
get_num_geometries

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

pygeos.geometry.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, optional (default: False): If True, will return a tuple of ndarrys 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]

pygeos.geometry.get_point(geometry, index)¶

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.

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

pygeos.geometry.get_precision(geometry)¶

Get the precision of a geometry.

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

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

pygeos.geometry.get_srid(geometry)¶

Returns the SRID of a geometry.

Returns -1 for not-a-geometry values.

Parameters

geometryGeometry or array_like

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

pygeos.geometry.get_type_id(geometry)¶

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

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]

pygeos.geometry.get_x(point)¶

Returns the x-coordinate of a point

Parameters

pointGeometry or array_like: Non-point geometries will result in NaN being returned.

See also

get_y, get_z

Examples

>>> get_x(Geometry("POINT (1 2)"))
1.0
>>> get_x(Geometry("MULTIPOINT (1 1, 1 2)"))
nan

pygeos.geometry.get_y(point)¶

Returns the y-coordinate of a point

Parameters

pointGeometry or array_like: Non-point geometries will result in NaN being returned.

See also

get_x, get_z

Examples

>>> get_y(Geometry("POINT (1 2)"))
2.0
>>> get_y(Geometry("MULTIPOINT (1 1, 1 2)"))
nan

pygeos.geometry.get_z(point)¶

Returns the z-coordinate of a point.

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.

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

pygeos.geometry.set_precision(geometry, grid_size, preserve_topology=False)¶

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

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.
preserve_topologybool, optional (default: False): If True, will attempt to preserve the topology of a geometry after rounding coordinates.

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(None, 1.0) is None
True

pygeos.geometry.set_srid(geometry, srid)¶

Returns a geometry with its SRID set.

Parameters

geometryGeometry or array_like
sridint

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