Shapely
Manipulation and analysis of geometric objects in the Cartesian plane.
{width="800px"
height="378px"}
Shapely is a BSD-licensed Python package for manipulation and analysis
of planar geometric objects. It is using the widely deployed open-source
geometry library GEOS (the engine of
PostGIS, and a port of
JTS). Shapely wraps GEOS
geometries and operations to provide both a feature rich
[Geometry]{.title-ref} interface for singular (scalar) geometries and
higher-performance NumPy ufuncs for operations using arrays of
geometries. Shapely is not primarily focused on data serialization
formats or coordinate systems, but can be readily integrated with
packages that are.
What is a ufunc?
A universal function (or ufunc for short) is a function that operates on
n-dimensional arrays on an element-by-element fashion and supports
array broadcasting. The underlying for loops are implemented in C to
reduce the overhead of the Python interpreter.
Multithreading
Shapely functions generally support multithreading by releasing the
Global Interpreter Lock (GIL) during execution. Normally in Python, the
GIL prevents multiple threads from computing at the same time. Shapely
functions internally release this constraint so that the heavy lifting
done by GEOS can be done in parallel, from a single Python process.
Usage
Here is the canonical example of building an approximately circular
patch by buffering a point, using the scalar Geometry interface:
>>> from shapely import Point
>>> patch = Point(0.0, 0.0).buffer(10.0)
>>> patch
<POLYGON ((10 0, 9.952 -0.98, 9.808 -1.951, 9.569 -2.903, 9.239 -3.827, 8.81...>
>>> patch.area
313.6548490545941
Using the vectorized ufunc interface (instead of using a manual for
loop), compare an array of points with a polygon:
>>> import shapely
>>> import numpy as np
>>> geoms = np.array([Point(0, 0), Point(1, 1), Point(2, 2)])
>>> polygon = shapely.box(0, 0, 2, 2)
>>> shapely.contains(polygon, geoms)
array([False, True, False])
See the documentation for more examples and guidance:
https://shapely.readthedocs.io
Requirements
Shapely 2.1 requires
- Python >=3.9
- GEOS >=3.9
- NumPy >=1.20
Installing Shapely
We recommend installing Shapely using one of the available built
distributions, for example using pip or conda:
$ pip install shapely
# or using conda
$ conda install shapely --channel conda-forge
See the installation
documentation
for more details and advanced installation instructions.
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
<POINT (0 0)>
>>> print(json.dumps(mapping(s)))
{"type": "Point", "coordinates": [0.0, 0.0]}
Support
Questions about using Shapely may be asked on the GIS
StackExchange
using the "shapely" tag.
Bugs may be reported at https://github.com/shapely/shapely/issues.
Copyright & License
Shapely is licensed under BSD 3-Clause license. GEOS is available under
the terms of GNU Lesser General Public License (LGPL) 2.1 at
https://libgeos.org.