wmay / shapely

Manipulation and analysis of geometric objects

Shapely

Manipulation and analysis of geometric objects in the Cartesian plane.

Shapely is a BSD-licensed Python package for manipulation and analysis of planar geometric objects. It is based on the widely deployed GEOS (the engine of PostGIS) and JTS (from which GEOS is ported) libraries. Shapely is not concerned with data formats or coordinate systems, but can be readily integrated with packages that are. For more details, see:

• Shapely on GitHub
• The Shapely manual

Requirements

Shapely 1.6.x requires

• Python >=2.6 (including Python 3.x)
• GEOS >=3.3

Installing Shapely (1.6b2)

Windows users have two good installation options: the wheels at http://www.lfd.uci.edu/~gohlke/pythonlibs/#shapely and the Anaconda platform's conda-forge channel.

OS X users can get Shapely wheels with GEOS included from the Python Package Index with a recent version of pip (8+):

$ pip install shapely==1.6b2

A few extra speedups that require Numpy can be had by running

$ pip install shapely[vectorized]==1.6b2

If you want to build Shapely from source for compatibility with other modules that depend on GEOS (such as cartopy or osgeo.ogr) you may ignore the binary wheels.

$ pip install shapely --no-binary shapely

Binary wheels are also available for Linux. To get them, use pip shapely shapely==1.6b2. To avoid them, use pip install shapely --no-binary shapely==1.6b2.

In other situations, install geos_c libs and headers by any means (for example, brew install geos on OS X or apt-get install libgeos-dev on Debian/Ubuntu) and install Shapely from the Python package index.

$ pip install shapely

If you've installed GEOS to a standard location, the geos-config program will be used to get compiler and linker options. If geos-config is not on your executable, it can be specified with a GEOS_CONFIG environment variable, e.g.:

$ GEOS_CONFIG=/path/to/geos-config pip install shapely

Shapely is also provided by popular Python distributions like Canopy (Enthought) and Anaconda (Continuum Analytics).

Usage

Here is the canonical example of building an approximately circular patch by buffering a point.

>>> from shapely.geometry import Point
>>> patch = Point(0.0, 0.0).buffer(10.0)
>>> patch
<shapely.geometry.polygon.Polygon object at 0x...>
>>> patch.area
313.65484905459385

See the manual for comprehensive usage snippets and the dissolve.py and intersect.py examples.

Integration

Shapely does not read or write data files, but it can serialize and deserialize using several well known formats and protocols. The shapely.wkb and shapely.wkt modules provide dumpers and loaders inspired by Python's pickle module.

>>> from shapely.wkt import dumps, loads
>>> dumps(loads('POINT (0 0)'))
'POINT (0.0000000000000000 0.0000000000000000)'

Shapely can also integrate with other Python GIS packages using GeoJSON-like dicts.

>>> import json
>>> from shapely.geometry import mapping, shape
>>> s = shape(json.loads('{"type": "Point", "coordinates": [0.0, 0.0]}'))
>>> s
<shapely.geometry.point.Point object at 0x...>
>>> print(json.dumps(mapping(s)))
{"type": "Point", "coordinates": [0.0, 0.0]}

Development and Testing

Dependencies for developing Shapely are listed in requirements-dev.txt. Cython and Numpy are not required for production installations, only for development. Use of a virtual environment is strongly recommended.

$ virtualenv .
$ source bin/activate
(env)$ pip install -r requirements-dev.txt
(env)$ pip install -e .

We use py.test to run Shapely's suite of unittests and doctests.

(env)$ python -m pytest

Support

Questions about using Shapely may be asked on the GIS StackExchange using the "shapely" tag.

Bugs may be reported at https://github.com/Toblerity/Shapely/issues.