Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Toblerity/Shapely

Manipulation and analysis of geometric objects
https://github.com/Toblerity/Shapely

Last synced: 3 months ago
JSON representation

Manipulation and analysis of geometric objects

Awesome Lists containing this project

README 

        
=======

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



.. Travis CI status -- https://travis-ci.com



.. image:: https://travis-ci.com/shapely/shapely.svg?branch=main

   :alt: Travis CI status

   :target: https://travis-ci.com/github/shapely/shapely



.. 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 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:



.. code-block:: pycon



    >>> from shapely import Point

    >>> patch = Point(0.0, 0.0).buffer(10.0)

    >>> patch

    

    >>> patch.area

    313.6548490545941



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.1 requires



* Python >=3.8

* GEOS >=3.7

* NumPy >=1.16



Installing Shapely

==================



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

    

    >>> 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.