======= Shapely =======
.. Documentation at RTD — https://readthedocs.org
.. image:: https://readthedocs.org/projects/shapely/badge/?version=stable :alt: Documentation Status :target: https://shapely.readthedocs.io/en/stable/
.. Github Actions status — https://github.com/shapely/shapely/actions
.. |github-actions| image:: https://github.com/shapely/shapely/workflows/Tests/badge.svg?branch=main :alt: Github Actions status :target: https://github.com/shapely/shapely/actions?query=branch%3Amain
.. PyPI
.. image:: https://img.shields.io/pypi/v/shapely.svg :alt: PyPI :target: https://pypi.org/project/shapely/
.. Anaconda
.. image:: https://img.shields.io/conda/vn/conda-forge/shapely :alt: Anaconda :target: https://anaconda.org/conda-forge/shapely
.. Coverage
.. |coveralls| image:: https://coveralls.io/repos/github/shapely/shapely/badge.svg?branch=main :target: https://coveralls.io/github/shapely/shapely?branch=main
.. Zenodo
.. .. image:: https://zenodo.org/badge/191151963.svg .. :alt: Zenodo .. :target: https://zenodo.org/badge/latestdoi/191151963
Manipulation and analysis of geometric objects in the Cartesian plane.
.. image:: https://c2.staticflickr.com/6/5560/31301790086_b3472ea4e9_c.jpg :width: 800 :height: 378
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 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 concurrently from a single Python process.
When sharing NumPy array of geometries between threads, extreme care must be taken to avoid creating thread safety issues when mutating arrays. This holds for any NumPy array, but even more so for arrays of Shapely geometries. When overwriting a geometry in an array, the old geometry is deallocated. If at the same time another thread operates on that geometry, interpreter crashes will occur.
Usage =====
Here is the canonical example of building an approximately circular patch by buffering a point, using the scalar Geometry interface:
.. code-block:: pycon
>>> from shapely import Point
>>> patch = Point(0.0, 0.0).buffer(10.0)
>>> patch
Using the vectorized ufunc interface (instead of using a manual for loop), compare an array of points with a polygon:
.. code:: python
>>> 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.2 requires
- Python >=3.11
- GEOS >=3.10
- NumPy >=1.26
We recommend installing Shapely using one of the available built
distributions, for example using pip or conda:
.. code-block:: console
$ 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.
.. code-block:: pycon
>>> 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.
.. code-block:: pycon
>>> import json
>>> from shapely.geometry import mapping, shape
>>> s = shape(json.loads('{"type": "Point", "coordinates": [0.0, 0.0]}'))
>>> s
Support =======
Questions about using Shapely may be asked on the GIS StackExchange
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.