Because geo-spatial data works with geometrical features such as points, lines, and polygons, you often need to perform various calculations using these geometrical features. Fortunately, there are some very powerful tools for doing exactly this. The library of choice for performing this type of computational geometry is named Shapely.
Shapely is a Python package for the manipulation and analysis of two-dimensional geo-spatial geometries. Shapely is based on the GEOS library, which implements a wide range of geo-spatial 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 that makes it easy to use these manipulations directly from your Python programs.
The Shapely library is organized as follows:
All of Shapely's functionality is built on top of GEOS. Indeed, Shapely requires GEOS to be installed before it can run.
Shapely itself consists of eight major classes, representing different types of geometrical shapes:
- The
Pointclass represents a single point in space. Points can be two-dimensional (x,y) or three-dimensional (x,y,z). - The
LineStringclass represents a sequence of points joined together to form a line. LineStrings can be simple (no crossing line segments) or complex (where two line segments within theLineStringcross). - The
LinearRingclass represents a line string that finishes at the starting point. The line segments within a LinearRing cannot cross or touch. - The
Polygonclass represents a filled area, optionally with one or more "holes" inside it. - The
MultiPointclass represents a collection of Points. - The
MultiLineStringclass represents a collection of LineStrings. - The
MultiPolygonclass represents a collection of Polygons. - The
GeometryCollectionclass represents a collection of any combination of Points, Lines, LinearRings, and Polygons.
As well as being able to represent these various types of geometries, Shapely provides a number of methods and attributes for manipulating and analyzing these geometries. 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 the convex_hull attribute).
Note that Shapely is a spatial manipulation library rather than a geo-spatial manipulation library. It has no concept of geographical coordinates. Instead, it assumes that the geo-spatial 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.
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 above.
import shapely.geometry
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
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 version 1.0 includes a fairly straightforward manual that gives a brief description of each class, method, and attribute, along with sample code showing how to use it. However, the manual for Shapely version 1.2 is far more extensive, with detailed descriptions, extended code samples, and many illustrations that clearly show how the various classes, methods, and attributes work. The Shapely 1.2 manual is worth reading even if you are using an earlier version.
The Shapely documentation is entirely self-contained; there is no need to refer to the GEOS documentation, or to the Java Topology Suite it is based on, unless you particularly want to see how things are done in these libraries. The only exception is that you may need to refer to the GEOS documentation if you are compiling GEOS from source, and are having problems getting it to work.
Shapely will run on all major operating systems, including MS Windows, Mac OS X, and Linux. Shapely's main website can be found at:
http://trac.gispython.org/lab/wiki/Shapely
The website has everything you need, including the documentation and downloads for the Shapely library, in both source code form and pre-built binaries for MS Windows.
If you are installing Shapely on a Windows computer, the pre-built binaries include the GEOS library built-in. Otherwise, you will be responsible for installing GEOS before you can use Shapely.
Make sure that you install Shapely version 1.2 or later; you will need this version to work through the examples in this book.
The GEOS library's website is at:
To install GEOS in a Unix-based computer, you can either download the source code from the GEOS website and compile it yourself, or you can install a suitable RPM or APT package that includes GEOS. If you are running Mac OS X, you can either try to download and build GEOS yourself, or you can install the pre-built GEOS framework, which is available from the following website: