Table Of Contents

Previous topic


Next topic

shapely.algorithms package

This Page

shapely package



shapely.affinity module

Affine transforms, both in general and specific, named transforms.

shapely.affinity.affine_transform(geom, matrix)

Returns a transformed geometry using an affine transformation matrix.

The coefficient matrix is provided as a list or tuple with 6 or 12 items for 2D or 3D transformations, respectively.

For 2D affine transformations, the 6 parameter matrix is:

[a, b, d, e, xoff, yoff]

which represents the augmented matrix:

/ a b xoff
[x’ y’ 1] = [x y 1] | d e yoff |
0 0 1 /

or the equations for the transformed coordinates:

x’ = a * x + b * y + xoff y’ = d * x + e * y + yoff

For 3D affine transformations, the 12 parameter matrix is:

[a, b, c, d, e, f, g, h, i, xoff, yoff, zoff]

which represents the augmented matrix:

/ a b c xoff
[x’ y’ z’ 1] = [x y z 1] | d e f yoff |
g h i zoff |

0 0 0 1 /

or the equations for the transformed coordinates:

x’ = a * x + b * y + c * z + xoff y’ = d * x + e * y + f * z + yoff z’ = g * x + h * y + i * z + zoff
shapely.affinity.rotate(geom, angle, origin='center', use_radians=False)

Returns a rotated geometry on a 2D plane.

The angle of rotation can be specified in either degrees (default) or radians by setting use_radians=True. Positive angles are counter-clockwise and negative are clockwise rotations.

The point of origin can be a keyword ‘center’ for the bounding box center (default), ‘centroid’ for the geometry’s centroid, a Point object or a coordinate tuple (x0, y0).

The affine transformation matrix for 2D rotation is:

/ cos(r) -sin(r) xoff | sin(r) cos(r) yoff | 0 0 1 /

where the offsets are calculated from the origin Point(x0, y0):

xoff = x0 - x0 * cos(r) + y0 * sin(r) yoff = y0 - x0 * sin(r) - y0 * cos(r)
shapely.affinity.scale(geom, xfact=1.0, yfact=1.0, zfact=1.0, origin='center')

Returns a scaled geometry, scaled by factors along each dimension.

The point of origin can be a keyword ‘center’ for the 2D bounding box center (default), ‘centroid’ for the geometry’s 2D centroid, a Point object or a coordinate tuple (x0, y0, z0).

Negative scale factors will mirror or reflect coordinates.

The general 3D affine transformation matrix for scaling is:

/ xfact 0 0 xoff | 0 yfact 0 yoff | | 0 0 zfact zoff | 0 0 0 1 /

where the offsets are calculated from the origin Point(x0, y0, z0):

xoff = x0 - x0 * xfact yoff = y0 - y0 * yfact zoff = z0 - z0 * zfact
shapely.affinity.skew(geom, xs=0.0, ys=0.0, origin='center', use_radians=False)

Returns a skewed geometry, sheared by angles along x and y dimensions.

The shear angle can be specified in either degrees (default) or radians by setting use_radians=True.

The point of origin can be a keyword ‘center’ for the bounding box center (default), ‘centroid’ for the geometry’s centroid, a Point object or a coordinate tuple (x0, y0).

The general 2D affine transformation matrix for skewing is:

/ 1 tan(xs) xoff | tan(ys) 1 yoff | 0 0 1 /

where the offsets are calculated from the origin Point(x0, y0):

xoff = -y0 * tan(xs) yoff = -x0 * tan(ys)
shapely.affinity.translate(geom, xoff=0.0, yoff=0.0, zoff=0.0)

Returns a translated geometry shifted by offsets along each dimension.

The general 3D affine transformation matrix for translation is:

/ 1 0 0 xoff | 0 1 0 yoff | | 0 0 1 zoff | 0 0 0 1 /

shapely.coords module

Coordinate sequence utilities

class shapely.coords.BoundsOp(*args)

Bases: shapely.topology.Validating

class shapely.coords.CoordinateSequence(parent)

Bases: object

Iterative access to coordinate tuples from the parent geometry’s coordinate sequence.


>>> from shapely.wkt import loads
>>> g = loads('POINT (0.0 0.0)')
>>> list(g.coords)
[(0.0, 0.0)]

Provide the Numpy array protocol.


X and Y arrays


Return an object that meets Shapely requirements for self-owned C-continguous data, copying if necessary, or just return the original object.

shapely.ctypes_declarations module

Prototyping of the GEOS C API

See header file: geos-x.y.z/capi/geos_c.h

class shapely.ctypes_declarations.allocated_c_char_p

Bases: ctypes.c_char_p

char pointer return type


alias of LP_c_ulong

shapely.ctypes_declarations.prototype(lgeos, geos_version)

Protype functions in geos_c.h for different version of GEOS

Use the GEOS version, not the C API version.

shapely.ftools module

shapely.geos module

Proxies for the libgeos_c shared lib, GEOS-specific exceptions, and utilities

exception shapely.geos.DimensionError

Bases: exceptions.Exception


alias of LGEOS330

class shapely.geos.LGEOS300(dll)

Bases: shapely.geos.LGEOSBase

Proxy for GEOS 3.0.0-CAPI-1.4.1

geos_capi_version = (1, 4, 0)
geos_version = (3, 0, 0)
class shapely.geos.LGEOS310(dll)

Bases: shapely.geos.LGEOSBase

Proxy for GEOS 3.1.0-CAPI-1.5.0

geos_capi_version = (1, 5, 0)
geos_version = (3, 1, 0)
class shapely.geos.LGEOS311(dll)

Bases: shapely.geos.LGEOS310

Proxy for GEOS 3.1.1-CAPI-1.6.0

geos_capi_version = (1, 6, 0)
geos_version = (3, 1, 1)
class shapely.geos.LGEOS320(dll)

Bases: shapely.geos.LGEOS311

Proxy for GEOS 3.2.0-CAPI-1.6.0

geos_capi_version = (1, 6, 0)
geos_version = (3, 2, 0)
class shapely.geos.LGEOS330(dll)

Bases: shapely.geos.LGEOS320

Proxy for GEOS 3.3.0-CAPI-1.7.0

geos_capi_version = (1, 7, 0)
geos_version = (3, 3, 0)
class shapely.geos.LGEOSBase(dll)

Bases: thread._local

Proxy for GEOS C API

This is a base class. Do not instantiate.

methods = {'topology_preserve_simplify': <functools.partial object at 0x106619680>, 'intersects': <functools.partial object at 0x10661d940>, 'relate': <functools.partial object at 0x10661f260>, 'within': <functools.partial object at 0x106619d08>, 'is_simple': <functools.partial object at 0x10661f1b0>, 'buffer_with_style': <functools.partial object at 0x1066199f0>, 'disjoint': <functools.partial object at 0x10661f208>, 'cascaded_union': <functools.partial object at 0x10661f0a8>, 'convex_hull': <functools.partial object at 0x10661f730>, 'touches': <functools.partial object at 0x10661dcb0>, 'intersection': <functools.partial object at 0x10661de10>, 'area': <functools.partial object at 0x10661fcb0>, 'union': <functools.partial object at 0x10661f8e8>, 'contains': <functools.partial object at 0x10661dd08>, 'representative_point': <functools.partial object at 0x10661dba8>, 'prepared_covers': <functools.partial object at 0x10661d310>, 'is_valid': <functools.partial object at 0x10661f158>, 'centroid': <functools.partial object at 0x10661d730>, 'symmetric_difference': <functools.partial object at 0x106619940>, 'interpolate_normalized': <functools.partial object at 0x10661db50>, 'boundary': <functools.partial object at 0x10661d2b8>, 'prepared_contains_properly': <functools.partial object at 0x10661f2b8>, 'parallel_offset': <functools.partial object at 0x10661d7e0>, 'overlaps': <functools.partial object at 0x106619ec0>, 'unary_union': <functools.partial object at 0x10661f0a8>, 'buffer': <functools.partial object at 0x10661d628>, 'envelope': <functools.partial object at 0x10661d578>, 'equals': <functools.partial object at 0x106619998>, 'is_ring': <functools.partial object at 0x10661d838>, 'simplify': <functools.partial object at 0x10661dc58>, 'is_empty': <functools.partial object at 0x10661d890>, 'equals_exact': <functools.partial object at 0x1066196d8>, 'interpolate': <functools.partial object at 0x10661d368>, 'prepared_contains': <functools.partial object at 0x1066197e0>, 'has_z': <functools.partial object at 0x106619f70>, 'difference': <functools.partial object at 0x10661f520>, 'distance': <functools.partial object at 0x10661d9f0>, 'crosses': <functools.partial object at 0x10661d5d0>, 'prepared_intersects': <functools.partial object at 0x10661de68>, 'project': <functools.partial object at 0x10661df18>, 'length': <functools.partial object at 0x10661df70>, 'project_normalized': <functools.partial object at 0x106619fc8>}
class shapely.geos.NullHandler(level=0)

Bases: logging.Handler

exception shapely.geos.PredicateError

Bases: exceptions.Exception

exception shapely.geos.ReadingError

Bases: exceptions.Exception

exception shapely.geos.TopologicalError

Bases: exceptions.Exception

class shapely.geos.WKBReader(lgeos)

Bases: object


Returns geometry from WKB


Returns geometry from WKB hex

class shapely.geos.WKBWriter(lgeos, **settings)

Bases: object


Byte order is big endian, True (default) or False

defaults = {'output_dimension': 3}

Include SRID, True or False (default)


Output dimension, either 2 or 3 (default)


Returns WKB byte string for geometry


Returns WKB hex string for geometry

class shapely.geos.WKTReader(lgeos)

Bases: object


Returns geometry from WKT

class shapely.geos.WKTWriter(lgeos, **settings)

Bases: object

defaults = {'trim': True, 'output_dimension': 3}

Show older style for 3D WKT, without ‘Z’ (default: False)


Output dimension, either 2 or 3 (default)


Rounding precision when writing the WKT. A precision of -1 (default) disables it.


Trimming of unnecessary decimals (default: True)


Returns WKT string for geometry

shapely.geos.errcheck_just_free(result, func, argtuple)

Returns string from a C pointer

shapely.geos.errcheck_predicate(result, func, argtuple)

Result is 2 on exception, 1 on True, 0 on False

shapely.geos.errcheck_wkb(result, func, argtuple)

Returns bytes from a C pointer

shapely.geos.error_handler(fmt, *args)
shapely.geos.load_dll(libname, fallbacks=None)
shapely.geos.notice_handler(fmt, args)

shapely.impl module

Implementation of the intermediary layer between Shapely and GEOS

This is layer number 2 from the list below.

  1. geometric objects: the Python OO API.
  2. implementation map: an abstraction that permits different backends.
  3. backend: callable objects that take Shapely geometric objects as arguments and, with GEOS as a backend, translate them to C data structures.
  4. GEOS library: algorithms implemented in C++.

Shapely 1.2 includes a GEOS backend and it is the default.

class shapely.impl.BaseImpl(values)

Bases: object

class shapely.impl.GEOSImpl(values)

Bases: shapely.impl.BaseImpl


A delegated method raises AttributeError in the absence of backend support.


shapely.iterops module

Iterative forms of operations

class shapely.iterops.IterOp(fn)

Bases: object

A generating non-data descriptor.


shapely.linref module

Linear referencing

class shapely.linref.InterpolateOp(name)

Bases: shapely.linref.LinearRefBase

class shapely.linref.LinearRefBase(name)

Bases: shapely.topology.Delegating

class shapely.linref.ProjectOp(name)

Bases: shapely.linref.LinearRefBase

shapely.ops module

Support for various GEOS geometry operations

shapely.ops.transform(func, geom)

Applies func to all coordinates of geom and returns a new geometry of the same type from the transformed coordinates.

func maps x, y, and optionally z to output xp, yp, zp. The input parameters may iterable types like lists or arrays or single values. The output shall be of the same type. Scalars in, scalars out. Lists in, lists out.

For example, here is an identity function applicable to both types of input.

def id_func(x, y, z=None):
return tuple(filter(None, [x, y, z]))

g2 = transform(id_func, g1)

A partially applied transform function from pyproj satisfies the requirements for func.

from functools import partial import pyproj

project = partial(
pyproj.transform, pyproj.Proj(init=’espg:4326’), pyproj.Proj(init=’epsg:26913’))

g2 = transform(project, g1)

Lambda expressions such as the one in

g2 = transform(lambda x, y, z=None: (x+1.0, y+1.0), g1)

also satisfy the requirements for func.

shapely.predicates module

Support for GEOS spatial predicates

class shapely.predicates.BinaryPredicate(name)

Bases: shapely.topology.Delegating

class shapely.predicates.RelateOp(name)

Bases: shapely.topology.Delegating

class shapely.predicates.UnaryPredicate(name)

Bases: shapely.topology.Delegating

shapely.prepared module

Support for GEOS prepared geometry operations.

class shapely.prepared.PreparedGeometry(context)

Bases: object

A geometry prepared for efficient comparison to a set of other geometries.


>>> from shapely.geometry import Point, Polygon
>>> triangle = Polygon(((0.0, 0.0), (1.0, 1.0), (1.0, -1.0)))
>>> p = prep(triangle)
>>> p.intersects(Point(0.5, 0.5))
contains(*args, **kwargs)
contains_properly(*args, **kwargs)
covers(*args, **kwargs)
impl = <GEOSImpl object: GEOS C API version (1, 7, 0)>
intersects(*args, **kwargs)

Creates and returns a prepared geometric object.

shapely.topology module

Intermediaries supporting GEOS topological operations

These methods all take Shapely geometries and other Python objects and delegate to GEOS functions via ctypes.

These methods return ctypes objects that should be recast by the caller.

class shapely.topology.BinaryRealProperty(name)

Bases: shapely.topology.Delegating

class shapely.topology.BinaryTopologicalOp(name)

Bases: shapely.topology.Delegating

class shapely.topology.Delegating(name)

Bases: shapely.topology.Validating

class shapely.topology.UnaryRealProperty(name)

Bases: shapely.topology.Delegating

class shapely.topology.UnaryTopologicalOp(name)

Bases: shapely.topology.Delegating

class shapely.topology.Validating

Bases: object

shapely.validation module


shapely.wkb module

Load/dump geometries using the well-known binary (WKB) format

shapely.wkb.dump(ob, fp, hex=False, **kw)

Dump a geometry to an open file.

shapely.wkb.dumps(ob, hex=False, **kw)

Dump a WKB representation of a geometry to a byte string, or a hex-encoded string if hex=True.

See available keyword output settings in shapely.geos.WKBWriter.

shapely.wkb.load(fp, hex=False)

Load a geometry from an open file.

shapely.wkb.loads(data, hex=False)

Load a geometry from a WKB byte string, or hex-encoded string if hex=True.

shapely.wkt module

Load/dump geometries using the well-known text (WKT) format

shapely.wkt.dump(ob, fp, **settings)

Dump a geometry to an open file.

shapely.wkt.dumps(ob, **kw)

Dump a WKT representation of a geometry to a string.

See available keyword output settings in shapely.geos.WKTWriter.


Load a geometry from an open file.


Load a geometry from a WKT string.

Module contents