Shapely

Shapely is a Python package for the manipulation and analysis of two-dimensional geospatial geometries. It is based on the GEOS library, which implements a wide range of geospatial data manipulations in C++. GEOS is itself based on a library called the Java Topology Suite, which provides the same functionality for Java programmers. Shapely provides a Pythonic interface to GEOS, which makes it easy to use these manipulations directly from your Python programs.

Installing Shapely

Shapely will run on all major operating systems, including MS Windows, Mac OS X, and Linux. Shapely's main web site can be found at https://github.com/Toblerity/Shapely. The Python Package Index page for Shapely also includes lots of useful information, and can be found at https://pypi.python.org/pypi/Shapely.

How you install Shapely depends on which operating system your computer is using:

Once you have installed Shapely, start up your Python interpreter and try typing the following:

import shapely
import shapely.speedups
print(shapely.__version__)
print(shapely.speedups.available)

This will print the version of Shapely you have installed and whether or not the shapely.speedups module is available. If speedups are available, then Shapely will use the underlying GEOS library to do all the hard work; without speedups, Shapely will still mostly work but will be very slow.

Understanding Shapely

The Shapely library is split up into a number of separate modules, which you import as required. The most commonly used Shapely modules include:

While you will almost always import the shapely.geometry module into your program, you would normally import the other modules only if you need them.

Let's take a closer look at the various geometry objects defined in the shapely.geometry module. There are eight fundamental geometry types supported by Shapely:

Each of these geometry types is implemented as a class within the shapely.geometry module:

As well as being able to represent these various types of geometries, Shapely provides a number of methods and attributes for manipulating and analyzing them. For example, the LineString class provides a length attribute that equals the length of all the line segments that make up the LineString, and a crosses() method that returns True if two LineStrings cross. Other methods allow you to calculate the intersection of two polygons, dilate or erode geometries, simplify a geometry, calculate the distance between two geometries, and build a polygon that encloses all the points within a given list of geometries (called a convex hull).

Note that Shapely is a spatial manipulation library rather than a geospatial manipulation library. It has no concept of geographical coordinates. Instead, it assumes that the geospatial data has been projected onto a two-dimensional Cartesian plane before it is manipulated, and the results can then be converted back into geographic coordinates if desired.

Shapely example code

The following program creates two Shapely geometry objects, a circle and a square, and calculates their intersection. The intersection will be a polygon in the shape of a semicircle, as shown in the following diagram:

Here is the source code for our program:

import shapely.geometry
import shapely.wkt

pt = shapely.geometry.Point(0, 0)
circle = pt.buffer(1.0)

square = shapely.geometry.Polygon([(0, 0), (1, 0),
                                   (1, 1), (0, 1),
                                   (0, 0)])

intersect = circle.intersection(square)
for x,y in intersect.exterior.coords:
    print(x,y)
print(shapely.wkt.dumps(intersect))

Notice how the circle is constructed by taking a Point geometry and using the buffer() method to create a Polygon representing the outline of a circle.

Shapely documentation

Complete and comprehensive documentation for the Shapely library can be found at http://toblerity.org/shapely/manual.html. It is well worth reading this manual, and if you are unsure about anything to do with Shapely, this web page should be your first port of call.