Table Of Contents

Previous topic

shapely.examples package

Next topic

shapely.speedups package

This Page

shapely.geometry package

Submodules

shapely.geometry.base module

Base geometry class and utilities

class shapely.geometry.base.BaseGeometry

Bases: object

Provides GEOS spatial predicates and topological operations.

almost_equals(other, decimal=6)

Returns True if geometries are equal at all coordinates to a specified decimal place

area

Unitless area of the geometry (float)

array_interface_base
boundary

Returns a lower dimension geometry that bounds the object

The boundary of a polygon is a line, the boundary of a line is a collection of points. The boundary of a point is an empty (null) collection.

bounds

Returns minimum bounding region (minx, miny, maxx, maxy)

buffer(distance, resolution=16, quadsegs=None, cap_style=1, join_style=1, mitre_limit=0)

Returns a geometry with an envelope at a distance from the object’s envelope

A negative distance has a “shrink” effect. A zero distance may be used to “tidy” a polygon. The resolution of the buffer around each vertex of the object increases by increasing the resolution keyword parameter or second positional parameter. Note: the use of a quadsegs parameter is deprecated and will be gone from the next major release.

The styles of caps are: CAP_STYLE.round (1), CAP_STYLE.flat (2), and CAP_STYLE.square (3).

The styles of joins between offset segments are: JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).

The mitre limit ratio is used for very sharp corners. The mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.

Example:

>>> from shapely.wkt import loads
>>> g = loads('POINT (0.0 0.0)')
>>> g.buffer(1.0).area        # 16-gon approx of a unit radius circle
3.1365484905459389
>>> g.buffer(1.0, 128).area   # 128-gon approximation
3.1415138011443009
>>> g.buffer(1.0, 3).area     # triangle approximation
3.0
>>> list(g.buffer(1.0, cap_style='square').exterior.coords)
[(1.0, 1.0), (1.0, -1.0), (-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0)]
>>> g.buffer(1.0, cap_style='square').area
4.0
centroid

Returns the geometric center of the object

contains(other)

Returns True if the geometry contains the other, else False

convex_hull

Imagine an elastic band stretched around the geometry: that’s a convex hull, more or less

The convex hull of a three member multipoint, for example, is a triangular polygon.

coords

Access to geometry’s coordinates (CoordinateSequence)

crosses(other)

Returns True if the geometries cross, else False

ctypes

Return ctypes buffer

difference(other)

Returns the difference of the geometries

disjoint(other)

Returns True if geometries are disjoint, else False

distance(other)

Unitless distance to other geometry (float)

empty()
envelope

A figure that envelopes the geometry

equals(other)

Returns True if geometries are equal, else False

equals_exact(other, tolerance)

Returns True if geometries are equal to within a specified tolerance

geom_type

Name of the geometry’s type, such as ‘Point’

geometryType()
has_z

True if the geometry’s coordinate sequence(s) have z values (are 3-dimensional)

impl = <GEOSImpl object: GEOS C API version (1, 7, 0)>
interpolate(*args, **kwargs)

Return a point at the specified distance along a linear geometry

If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.

intersection(other)

Returns the intersection of the geometries

intersects(other)

Returns True if geometries intersect, else False

is_empty

True if the set of points in this geometry is empty, else False

is_ring

True if the geometry is a closed ring, else False

is_simple

True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False

is_valid

True if the geometry is valid (definition depends on sub-class), else False

length

Unitless length of the geometry (float)

overlaps(other)

Returns True if geometries overlap, else False

project(*args, **kwargs)

Returns the distance along this geometry to a point nearest the specified point

If the normalized arg is True, return the distance normalized to the length of the linear geometry.

relate(other)

Returns the DE-9IM intersection matrix for the two geometries (string)

representative_point(*args, **kwargs)

Returns a point guaranteed to be within the object, cheaply.

simplify(*args, **kwargs)

Returns a simplified geometry produced by the Douglas-Puecker algorithm

Coordinates of the simplified geometry will be no more than the tolerance distance from the original. Unless the topology preserving option is used, the algorithm may produce self-intersecting or otherwise invalid geometries.

symmetric_difference(other)

Returns the symmetric difference of the geometries (Shapely geometry)

to_wkb()
to_wkt()
touches(other)

Returns True if geometries touch, else False

type
union(other)

Returns the union of the geometries (Shapely geometry)

within(other)

Returns True if geometry is within the other, else False

wkb

WKB representation of the geometry

wkb_hex

WKB hex representation of the geometry

wkt

WKT representation of the geometry

xy

Separate arrays of X and Y coordinate values

class shapely.geometry.base.BaseMultipartGeometry

Bases: shapely.geometry.base.BaseGeometry

coords
ctypes
geoms
shape_factory(*args)
class shapely.geometry.base.CAP_STYLE

Bases: object

flat = 2
round = 1
square = 3
class shapely.geometry.base.GeometrySequence(parent, type)

Bases: object

Iterative access to members of a homogeneous multipart geometry.

shape_factory = None
class shapely.geometry.base.HeterogeneousGeometrySequence(parent)

Bases: shapely.geometry.base.GeometrySequence

Iterative access to a heterogeneous sequence of geometries.

class shapely.geometry.base.JOIN_STYLE

Bases: object

bevel = 3
mitre = 2
round = 1
shapely.geometry.base.deserialize_wkb(data)
shapely.geometry.base.dump_coords(geom)

Dump coordinates of a geometry in the same order as data packing

shapely.geometry.base.exceptNull(func)

Decorator which helps avoid GEOS operations on null pointers.

shapely.geometry.base.geom_factory(g, parent=None)
shapely.geometry.base.geom_from_wkb(data)
shapely.geometry.base.geom_from_wkt(data)
shapely.geometry.base.geom_to_wkb(ob)
shapely.geometry.base.geom_to_wkt(ob)
shapely.geometry.base.geometry_type_name(g)

shapely.geometry.collection module

Multi-part collections of geometries

class shapely.geometry.collection.GeometryCollection

Bases: shapely.geometry.base.BaseMultipartGeometry

A heterogenous collection of geometries

geoms : sequence
A sequence of Shapely geometry instances
geoms

shapely.geometry.geo module

Geometry factories based on the geo interface

shapely.geometry.geo.asShape(context)

Adapts the context to a geometry interface. The coordinates remain stored in the context.

shapely.geometry.geo.box(minx, miny, maxx, maxy, ccw=True)

Returns a rectangular polygon with configurable normal vector

shapely.geometry.geo.mapping(ob)

Returns a GeoJSON-like mapping

shapely.geometry.geo.shape(context)

Returns a new, independent geometry with coordinates copied from the context.

shapely.geometry.linestring module

Line strings and related utilities

class shapely.geometry.linestring.LineString(coordinates=None)

Bases: shapely.geometry.base.BaseGeometry

A one-dimensional figure comprising one or more line segments

A LineString has non-zero length and zero area. It may approximate a curve and need not be straight. Unlike a LinearRing, a LineString is not closed.

array_interface()

Provide the Numpy array protocol.

coords

Access to geometry’s coordinates (CoordinateSequence)

ctypes
parallel_offset(distance, side, resolution=16, join_style=1, mitre_limit=1.0)

Returns a LineString or MultiLineString geometry at a distance from the object on its right or its left side.

Distance must be a positive float value. The side parameter may be ‘left’ or ‘right’. The resolution of the buffer around each vertex of the object increases by increasing the resolution keyword parameter or third positional parameter.

The join style is for outside corners between line segments. Accepted values are JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).

The mitre ratio limit is used for very sharp corners. It is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend far beyond the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.

xy

Separate arrays of X and Y coordinate values

Example:

>>> x, y = LineString(((0, 0), (1, 1))).xy
>>> list(x)
[0.0, 1.0]
>>> list(y)
[0.0, 1.0]
shapely.geometry.linestring.asLineString(context)

Adapt an object the LineString interface

shapely.geometry.multilinestring module

Collections of linestrings and related utilities

class shapely.geometry.multilinestring.MultiLineString(lines=None)

Bases: shapely.geometry.base.BaseMultipartGeometry

A collection of one or more line strings

A MultiLineString has non-zero length and zero area.

geoms : sequence
A sequence of LineStrings
shape_factory(*args)
shapely.geometry.multilinestring.asMultiLineString(context)

Adapts a sequence of objects to the MultiLineString interface

shapely.geometry.multipoint module

Collections of points and related utilities

class shapely.geometry.multipoint.MultiPoint(points=None)

Bases: shapely.geometry.base.BaseMultipartGeometry

A collection of one or more points

A MultiPoint has zero area and zero length.

geoms : sequence
A sequence of Points
array_interface(*args, **kwargs)

Provide the Numpy array protocol.

ctypes
shape_factory(*args)
shapely.geometry.multipoint.asMultiPoint(context)

Adapt a sequence of objects to the MultiPoint interface

shapely.geometry.multipolygon module

Collections of polygons and related utilities

class shapely.geometry.multipolygon.MultiPolygon(polygons=None, context_type='polygons')

Bases: shapely.geometry.base.BaseMultipartGeometry

A collection of one or more polygons

If component polygons overlap the collection is invalid and some operations on it may fail.

geoms : sequence
A sequence of Polygon instances
shape_factory(*args)
shapely.geometry.multipolygon.asMultiPolygon(context)

Adapts a sequence of objects to the MultiPolygon interface

shapely.geometry.point module

Points and related utilities

class shapely.geometry.point.Point(*args)

Bases: shapely.geometry.base.BaseGeometry

A zero dimensional feature

A point has zero length and zero area.

x, y, z : float
Coordinate values
>>> p = Point(1.0, -1.0)
>>> print(p)
POINT (1.0000000000000000 -1.0000000000000000)
>>> p.y
-1.0
>>> p.x
1.0
array_interface()

Provide the Numpy array protocol.

bounds
coords

Access to geometry’s coordinates (CoordinateSequence)

ctypes
x

Return x coordinate.

xy

Separate arrays of X and Y coordinate values

Example:
>>> x, y = Point(0, 0).xy
>>> list(x)
[0.0]
>>> list(y)
[0.0]
y

Return y coordinate.

z

Return z coordinate.

shapely.geometry.point.asPoint(context)

Adapt an object to the Point interface

shapely.geometry.polygon module

Polygons and their linear ring components

class shapely.geometry.polygon.Polygon(shell=None, holes=None)

Bases: shapely.geometry.base.BaseGeometry

A two-dimensional figure bounded by a linear ring

A polygon has a non-zero area. It may have one or more negative-space “holes” which are also bounded by linear rings. If any rings cross each other, the feature is invalid and operations on it may fail.

exterior : LinearRing
The ring which bounds the positive space of the polygon.
interiors : sequence
A sequence of rings which bound all existing holes.
coords
ctypes
exterior
interiors
shapely.geometry.polygon.asPolygon(shell, holes=None)

Adapt objects to the Polygon interface

class shapely.geometry.polygon.LinearRing(coordinates=None)

Bases: shapely.geometry.linestring.LineString

A closed one-dimensional feature comprising one or more line segments

A LinearRing that crosses itself or touches itself at a single point is invalid and operations on it may fail.

coords

Access to geometry’s coordinates (CoordinateSequence)

is_ccw

True is the ring is oriented counter clock-wise

is_simple

True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False

shapely.geometry.polygon.asLinearRing(context)

Adapt an object to the LinearRing interface

shapely.geometry.proxy module

Proxy for coordinates stored outside Shapely geometries

class shapely.geometry.proxy.CachingGeometryProxy(context)

Bases: object

context = None
empty()
factory = None
gtag()
class shapely.geometry.proxy.PolygonProxy(context)

Bases: shapely.geometry.proxy.CachingGeometryProxy

Module contents

Geometry classes and factories

shapely.geometry.box(minx, miny, maxx, maxy, ccw=True)

Returns a rectangular polygon with configurable normal vector

shapely.geometry.shape(context)

Returns a new, independent geometry with coordinates copied from the context.

shapely.geometry.asShape(context)

Adapts the context to a geometry interface. The coordinates remain stored in the context.

class shapely.geometry.Point(*args)

Bases: shapely.geometry.base.BaseGeometry

A zero dimensional feature

A point has zero length and zero area.

x, y, z : float
Coordinate values
>>> p = Point(1.0, -1.0)
>>> print(p)
POINT (1.0000000000000000 -1.0000000000000000)
>>> p.y
-1.0
>>> p.x
1.0
array_interface()

Provide the Numpy array protocol.

bounds
coords

Access to geometry’s coordinates (CoordinateSequence)

ctypes
x

Return x coordinate.

xy

Separate arrays of X and Y coordinate values

Example:
>>> x, y = Point(0, 0).xy
>>> list(x)
[0.0]
>>> list(y)
[0.0]
y

Return y coordinate.

z

Return z coordinate.

shapely.geometry.asPoint(context)

Adapt an object to the Point interface

class shapely.geometry.LineString(coordinates=None)

Bases: shapely.geometry.base.BaseGeometry

A one-dimensional figure comprising one or more line segments

A LineString has non-zero length and zero area. It may approximate a curve and need not be straight. Unlike a LinearRing, a LineString is not closed.

array_interface()

Provide the Numpy array protocol.

coords

Access to geometry’s coordinates (CoordinateSequence)

ctypes
parallel_offset(distance, side, resolution=16, join_style=1, mitre_limit=1.0)

Returns a LineString or MultiLineString geometry at a distance from the object on its right or its left side.

Distance must be a positive float value. The side parameter may be ‘left’ or ‘right’. The resolution of the buffer around each vertex of the object increases by increasing the resolution keyword parameter or third positional parameter.

The join style is for outside corners between line segments. Accepted values are JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).

The mitre ratio limit is used for very sharp corners. It is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend far beyond the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.

xy

Separate arrays of X and Y coordinate values

Example:

>>> x, y = LineString(((0, 0), (1, 1))).xy
>>> list(x)
[0.0, 1.0]
>>> list(y)
[0.0, 1.0]
shapely.geometry.asLineString(context)

Adapt an object the LineString interface

class shapely.geometry.Polygon(shell=None, holes=None)

Bases: shapely.geometry.base.BaseGeometry

A two-dimensional figure bounded by a linear ring

A polygon has a non-zero area. It may have one or more negative-space “holes” which are also bounded by linear rings. If any rings cross each other, the feature is invalid and operations on it may fail.

exterior : LinearRing
The ring which bounds the positive space of the polygon.
interiors : sequence
A sequence of rings which bound all existing holes.
coords
ctypes
exterior
interiors
shapely.geometry.asPolygon(shell, holes=None)

Adapt objects to the Polygon interface

class shapely.geometry.MultiPoint(points=None)

Bases: shapely.geometry.base.BaseMultipartGeometry

A collection of one or more points

A MultiPoint has zero area and zero length.

geoms : sequence
A sequence of Points
array_interface(*args, **kwargs)

Provide the Numpy array protocol.

ctypes
shape_factory(*args)
shapely.geometry.asMultiPoint(context)

Adapt a sequence of objects to the MultiPoint interface

class shapely.geometry.MultiLineString(lines=None)

Bases: shapely.geometry.base.BaseMultipartGeometry

A collection of one or more line strings

A MultiLineString has non-zero length and zero area.

geoms : sequence
A sequence of LineStrings
shape_factory(*args)
shapely.geometry.asMultiLineString(context)

Adapts a sequence of objects to the MultiLineString interface

class shapely.geometry.MultiPolygon(polygons=None, context_type='polygons')

Bases: shapely.geometry.base.BaseMultipartGeometry

A collection of one or more polygons

If component polygons overlap the collection is invalid and some operations on it may fail.

geoms : sequence
A sequence of Polygon instances
shape_factory(*args)
shapely.geometry.asMultiPolygon(context)

Adapts a sequence of objects to the MultiPolygon interface

class shapely.geometry.GeometryCollection

Bases: shapely.geometry.base.BaseMultipartGeometry

A heterogenous collection of geometries

geoms : sequence
A sequence of Shapely geometry instances
geoms
shapely.geometry.mapping(ob)

Returns a GeoJSON-like mapping

class shapely.geometry.LinearRing(coordinates=None)

Bases: shapely.geometry.linestring.LineString

A closed one-dimensional feature comprising one or more line segments

A LinearRing that crosses itself or touches itself at a single point is invalid and operations on it may fail.

coords

Access to geometry’s coordinates (CoordinateSequence)

is_ccw

True is the ring is oriented counter clock-wise

is_simple

True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False

shapely.geometry.asLinearRing(context)

Adapt an object to the LinearRing interface

class shapely.geometry.CAP_STYLE

Bases: object

flat = 2
round = 1
square = 3
class shapely.geometry.JOIN_STYLE

Bases: object

bevel = 3
mitre = 2
round = 1