Back to Shapely

Shapely Manual

Shapely is a package for manipulation and analysis of 2D geospatial geometries.

It can be used to

• Obtain the unions, intersections, or differences of 2D shapes

• Determine whether 2D shapes intersect, touch, or contain one another

and more.

Example geometries

The manual refers to the geometries defined and illustrated below:

>>> from shapely.geometry import Point, LineString, Polygon
>>> polygon = Polygon(((-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0), (1.0, -1.0)))
>>> point_r = Point(-1.5, 1.2)
>>> point_g = Point(-1.0, 1.0)
>>> point_b = Point(-0.5, 0.5)
>>> line_r = LineString(((-0.5, 0.5), (0.5, 0.5)))
>>> line_g = LineString(((1.0, -1.0), (1.8, 0.5)))
>>> line_b = LineString(((-1.8, -1.2), (1.8, 0.5)))

The polygon is shown in cyan, other geometries are shown in the color corresponding to their name. Red for point_r, green for line_g, etc. See also Shapely/trunk/examples/geoms.py.

Scalar Properties

area : float

Area of the geometry, unitless. Non-zero only for surfaces (polygons, multipolygons).

length : float

Length of the geometry, unitless. Non-zero only for linear geometries (linestrings, linearrings, polygon boundaries)

>>> polygon.area
4.0
>>> polygon.length
8.0
>>> line_r.length
1.0
>>> line_b.length
3.9812058474788765

Operations

It is important to note that these are topological and not point-wise operations, and therefore may produce results that are not what one might expect from operations on Python sets.

These methods allocate and return new geometries.

Constructive Operations

buffer(distance, quadsegs=16) : geometry

Buffers the geometry by a unitless distance. The quadsegs parameter is the number of segments per quadrant in resulting geometries. The default result of buffering a point is a 66-gon:

>>> buffered = point_r.buffer(1.0)
>>> buffered
<shapely.geometry.polygon.Polygon object at ...>
>>> buffered.length
6.2806623139097271
>>> buffered.area
3.1365484905463727
>>> len(buffered.exterior.coords)
66

boundary : geometry

Returns a lower dimension geometry. 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.

>>> polygon.boundary
<shapely.geometry.linestring.LineString object at ...>
>>> line_b.boundary
<shapely.geometry.multipoint.MultiPoint object at ...>
>>> point_r.boundary.is_empty
True

centroid : geometry

Returns the centroid, or geometric center of the polygon.

convex_hull : geometry

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

Set-theoretic operations

(Illustration from JTS Technical Specification: http://www.vividsolutions.com/jts/jtshome.htm)

difference

envelope

intersection

symmetric_difference

union

Unary Predicates

These are implemented as Python attributes.

is_empty : bool

True if the set of points in this geometry is empty, else False. For more details, see http://geos.refractions.net/ro/doxygen_docs/html/classgeos_1_1geom_1_1Geometry.html#a17.

is_valid : bool

True if the geometry is valid (definition depends on sub-class), else False. For more details, see http://geos.refractions.net/ro/doxygen_docs/html/classgeos_1_1geom_1_1Geometry.html#a16.

is_ring : bool

True if the geometry is a closed ring, else False.

has_z : bool

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

>>> polygon.is_empty
False
>>> polygon.is_valid
True
>>> polygon.is_ring
False
>>> polygon.boundary.is_ring
True
>>> polygon.has_z
True

(Note: that last return value exposes a bug in GEOS 2.2.3. Should be False.)

Binary Predicates

All of these methods take a single positional argument, a geometry g. It is important to note that these are topological and not point-wise operations, and therefore may produce results that are not what one might expect from operations on Python sets.

contains(g) : bool

True if the geometry is spatially within, without touching. Applies to all types of geometries.

>>> polygon.contains(point_b)
True

crosses(g) : bool

Only linear geometries (lines, rings, polygon boundaries) may ever cross. No geometry may ever cross a point.

>>> line_b.crosses(polygon)
True

disjoint(g) : bool

True if geometries do not spatially relate in any way, else False. See the complementary intersects.

>>> polygon.disjoint(point_r)
True

equals(g) : bool

Two geometries are topologically equal if their interiors intersect and no part of the interior or boundary of one geometry intersects the exterior of the other [1]. Not to be confused with Python's __equals__.

intersects(g) : bool

This predicate is the complement of disjoint: geometries that do not intersect are disjoint. Intersects is the most inclusive predicate.

>>> polygon.intersects(point_b)
True

touches(g) : bool

True if geometries only touch. The least inclusive predicate.

>>> polygon.touches(line_g)
True
>>> polygon.touches(line_b)
False

within(g): bool

The inverse of contains.