Input/Output

from_geojson(geometry, on_invalid='raise', **kwargs)

Creates geometries from GeoJSON representations (strings).

Note

‘from_geojson’ requires at least GEOS 3.10.1.

If a GeoJSON is a FeatureCollection, it is read as a single geometry (with type GEOMETRYCOLLECTION). This may be unpacked using the pygeos.get_parts. Properties are not read.

The GeoJSON format is defined in RFC 7946.

The following are currently unsupported:

  • Three-dimensional geometries: the third dimension is ignored.

  • Geometries having ‘null’ in the coordinates.

Parameters
geometrystr, bytes or array_like

The GeoJSON string or byte object(s) to convert.

on_invalid{“raise”, “warn”, “ignore”}, default “raise”
  • raise: an exception will be raised if an input GeoJSON is invalid.

  • warn: a warning will be raised and invalid input geometries will be returned as None.

  • ignore: invalid input geometries will be returned as None without a warning.

**kwargs

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

See also

get_parts

Examples

>>> from_geojson('{"type": "Point","coordinates": [1, 2]}')
<pygeos.Geometry POINT (1 2)>
from_shapely(geometry, **kwargs)

Creates geometries from shapely Geometry objects.

Warning

When Shapely and PyGEOS are using the same GEOS version, this function assumes that the libraries are actually the same. In some cases (especially when using pip-installed wheels) this may lead to unexpected behaviour. If you require safe (but slower) behaviour, then we recommend setting pygeos.io.shapely_compatible to False.

Parameters
geometryshapely Geometry object or array_like
**kwargs

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

Notes

If PyGEOS and Shapely do not use the same GEOS version, the conversion happens through the WKB format and will thus be slower.

Examples

>>> from shapely.geometry import Point   
>>> from_shapely(Point(1, 2))   
<pygeos.Geometry POINT (1 2)>
from_wkb(geometry, on_invalid='raise', **kwargs)

Creates geometries from the Well-Known Binary (WKB) representation.

The Well-Known Binary format is defined in the OGC Simple Features Specification for SQL.

Parameters
geometrystr or array_like

The WKB byte object(s) to convert.

on_invalid{“raise”, “warn”, “ignore”}, default “raise”
  • raise: an exception will be raised if a WKB input geometry is invalid.

  • warn: a warning will be raised and invalid WKB geometries will be returned as None.

  • ignore: invalid WKB geometries will be returned as None without a warning.

**kwargs

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

Examples

>>> from_wkb(b'\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\xf0?\x00\x00\x00\x00\x00\x00\xf0?')
<pygeos.Geometry POINT (1 1)>
from_wkt(geometry, on_invalid='raise', **kwargs)

Creates geometries from the Well-Known Text (WKT) representation.

The Well-known Text format is defined in the OGC Simple Features Specification for SQL.

Parameters
geometrystr or array_like

The WKT string(s) to convert.

on_invalid{“raise”, “warn”, “ignore”}, default “raise”
  • raise: an exception will be raised if WKT input geometries are invalid.

  • warn: a warning will be raised and invalid WKT geometries will be returned as None.

  • ignore: invalid WKT geometries will be returned as None without a warning.

**kwargs

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

Examples

>>> from_wkt('POINT (0 0)')
<pygeos.Geometry POINT (0 0)>
to_geojson(geometry, indent=None, **kwargs)

Converts to the GeoJSON representation of a Geometry.

Note

‘to_geojson’ requires at least GEOS 3.10.0.

The GeoJSON format is defined in the RFC 7946. NaN (not-a-number) coordinates will be written as ‘null’.

The following are currently unsupported:

  • Geometries of type LINEARRING: these are output as ‘null’.

  • Three-dimensional geometries: the third dimension is ignored.

Parameters
geometrystr, bytes or array_like
indentint, optional

If indent is a non-negative integer, then GeoJSON will be formatted. An indent level of 0 will only insert newlines. None (the default) selects the most compact representation.

**kwargs

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

Examples

>>> to_geojson(Geometry("POINT (1 1)"))
'{"type":"Point","coordinates":[1.0,1.0]}'
>>> print(to_geojson(Geometry("POINT (1 1)"), indent=2))
{
  "type": "Point",
  "coordinates": [
      1.0,
      1.0
  ]
}
to_shapely(geometry)

Converts PyGEOS geometries to Shapely.

Warning

When Shapely and PyGEOS are using the same GEOS version, this function assumes that the libraries are actually the same. In some cases (especially when using pip-installed wheels) this may lead to unexpected behaviour. If you require safe (but slower) behaviour, then we recommend setting pygeos.io.shapely_compatible to False.

Parameters
geometryshapely Geometry object or array_like

Notes

If PyGEOS and Shapely do not use the same GEOS version, the conversion happens through the WKB format and will thus be slower.

Examples

>>> to_shapely(Geometry("POINT (1 1)"))   
<shapely.geometry.point.Point at 0x7f0c3d737908>
to_wkb(geometry, hex=False, output_dimension=3, byte_order=- 1, include_srid=False, **kwargs)

Converts to the Well-Known Binary (WKB) representation of a Geometry.

The Well-Known Binary format is defined in the OGC Simple Features Specification for SQL.

The following limitations apply to WKB serialization:

  • linearrings will be converted to linestrings

  • a point with only NaN coordinates is converted to an empty point

  • for GEOS <= 3.7, empty points are always serialized to 3D if output_dimension=3, and to 2D if output_dimension=2

  • for GEOS == 3.8, empty points are always serialized to 2D

Parameters
geometryGeometry or array_like
hexbool, default False

If true, export the WKB as a hexidecimal string. The default is to return a binary bytes object.

output_dimensionint, default 3

The output dimension for the WKB. Supported values are 2 and 3. Specifying 3 means that up to 3 dimensions will be written but 2D geometries will still be represented as 2D in the WKB represenation.

byte_orderint, default -1

Defaults to native machine byte order (-1). Use 0 to force big endian and 1 for little endian.

include_sridbool, default False

If True, the SRID is be included in WKB (this is an extension to the OGC WKB specification).

**kwargs

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

Examples

>>> to_wkb(Geometry("POINT (1 1)"), byte_order=1)
b'\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\xf0?\x00\x00\x00\x00\x00\x00\xf0?'
>>> to_wkb(Geometry("POINT (1 1)"), hex=True, byte_order=1)
'0101000000000000000000F03F000000000000F03F'
to_wkt(geometry, rounding_precision=6, trim=True, output_dimension=3, old_3d=False, **kwargs)

Converts to the Well-Known Text (WKT) representation of a Geometry.

The Well-known Text format is defined in the OGC Simple Features Specification for SQL.

The following limitations apply to WKT serialization:

  • for GEOS <= 3.8 a multipoint with an empty sub-geometry will raise an exception

  • for GEOS <= 3.8 empty geometries are always serialized to 2D

  • for GEOS >= 3.9 only simple empty geometries can be 3D, collections are still always 2D

Parameters
geometryGeometry or array_like
rounding_precisionint, default 6

The rounding precision when writing the WKT string. Set to a value of -1 to indicate the full precision.

trimbool, default True

If True, trim unnecessary decimals (trailing zeros).

output_dimensionint, default 3

The output dimension for the WKT string. Supported values are 2 and 3. Specifying 3 means that up to 3 dimensions will be written but 2D geometries will still be represented as 2D in the WKT string.

old_3dbool, default False

Enable old style 3D/4D WKT generation. By default, new style 3D/4D WKT (ie. “POINT Z (10 20 30)”) is returned, but with old_3d=True the WKT will be formatted in the style “POINT (10 20 30)”.

**kwargs

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

Notes

The defaults differ from the default of the GEOS library. To mimic this, use:

to_wkt(geometry, rounding_precision=-1, trim=False, output_dimension=2)

Examples

>>> to_wkt(Geometry("POINT (0 0)"))
'POINT (0 0)'
>>> to_wkt(Geometry("POINT (0 0)"), rounding_precision=3, trim=False)
'POINT (0.000 0.000)'
>>> to_wkt(Geometry("POINT (0 0)"), rounding_precision=-1, trim=False)
'POINT (0.0000000000000000 0.0000000000000000)'
>>> to_wkt(Geometry("POINT (1 2 3)"), trim=True)
'POINT Z (1 2 3)'
>>> to_wkt(Geometry("POINT (1 2 3)"), trim=True, output_dimension=2)
'POINT (1 2)'
>>> to_wkt(Geometry("POINT (1 2 3)"), trim=True, old_3d=True)
'POINT (1 2 3)'