Input/Output#

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

Creates geometries from GeoJSON representations (strings).

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]}')
<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?')
<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)')
<POINT (0 0)>
to_geojson(geometry, indent=None, **kwargs)#

Converts to the GeoJSON representation of a Geometry.

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

>>> from shapely import Point
>>> point = Point(1, 1)
>>> to_geojson(point)
'{"type":"Point","coordinates":[1.0,1.0]}'
>>> print(to_geojson(point, indent=2))
{
  "type": "Point",
  "coordinates": [
      1.0,
      1.0
  ]
}
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

>>> from shapely import Point
>>> point = Point(1, 1)
>>> to_wkb(point, 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(point, 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

>>> from shapely import Point
>>> to_wkt(Point(0, 0))
'POINT (0 0)'
>>> to_wkt(Point(0, 0), rounding_precision=3, trim=False)
'POINT (0.000 0.000)'
>>> to_wkt(Point(0, 0), rounding_precision=-1, trim=False)
'POINT (0.0000000000000000 0.0000000000000000)'
>>> to_wkt(Point(1, 2, 3), trim=True)
'POINT Z (1 2 3)'
>>> to_wkt(Point(1, 2, 3), trim=True, output_dimension=2)
'POINT (1 2)'
>>> to_wkt(Point(1, 2, 3), trim=True, old_3d=True)
'POINT (1 2 3)'