Shapely

Warnings

• breaking Shapely 2.0 introduced a complete internal refactor (merging PyGEOS), making geometries immutable and changing how multi-part geometries behave.
  Fix: Geometries are now immutable and hashable; do not attempt in-place modification. For multi-part geometries (e.g., `MultiPolygon`), they are no longer sequence-like (no `len()`, not iterable, not indexable) – use the `.geoms` attribute to access individual parts.
• breaking Direct conversion of geometry objects to NumPy arrays (`np.asarray(geom)`) is deprecated and removed in 2.0.
  Fix: Use `np.asarray(geom.coords)` to convert geometry coordinates to a NumPy array.
• breaking The `STRtree` API changed significantly in Shapely 2.0. Operations now return indices of input geometries instead of the geometries themselves.
  Fix: Review the `STRtree` documentation for the updated `query()` method, which merges `query()` and `query_bulk()` and directly includes predicate evaluation.
• deprecated Many function parameters, especially boolean flags like `normalized` or `include_z`, are being transitioned to keyword-only arguments. Passing them positionally is deprecated and raises warnings.
  Fix: Always pass such parameters as keyword arguments (e.g., `geom.buffer(distance, quad_segs=16)` instead of `geom.buffer(distance, 16)`).
• gotcha When installing Shapely in a Conda environment, installing via `pip install shapely` can sometimes lead to issues with GEOS library discovery, potentially bundling an outdated GEOS.
  Fix: Always install Shapely via `conda install shapely --channel conda-forge` when using Conda to ensure proper GEOS linking.
• gotcha Shapely is a planar geometry library; Z coordinates are generally ignored in geometric analysis, and geometries differing only in Z are not distinguished. `LineString([(0, 0, 0), (0, 0, 1)])` results in an invalid line with zero length.
  Fix: Be aware that Shapely's core operations are 2D. While geometries can store Z/M values (especially since 2.1.0), most analytical methods primarily use X and Y coordinates. Validate your geometry inputs to avoid unexpected behavior with Z differences.

Install

• pip install shapely Install with pip
• conda install shapely --channel conda-forge Install with Conda (recommended)

Imports

• Point

  from shapely import Point

• Polygon

  from shapely import Polygon

• box

  from shapely import box

• shapely.geometry.Point

  from shapely.geometry import Point

  Geometry subclasses are now available directly in the top-level `shapely` namespace (since 2.0), making `from shapely import Point` the preferred modern import. `from shapely.geometry import Point` still works for individual geometry types.
• shapely.geos

  from shapely import GEOS_VERSION

  The `shapely.geos` module is deprecated in 2.1.x; GEOS-version related attributes are now directly available from the top-level `shapely` namespace (e.g., `shapely.GEOS_VERSION`).
• shapely.vectorized.contains

  from shapely import contains_xy

  The `shapely.vectorized` module is deprecated in 2.1.x. Use top-level vectorized functions like `shapely.contains_xy` and `shapely.intersects_xy` instead.

Quickstart

This quickstart demonstrates creating basic `Point` and `Polygon` geometries and performing a simple spatial intersection. It also includes an example of a vectorized operation using NumPy arrays, a key performance feature introduced in Shapely 2.0.

import shapely
from shapely import Point, Polygon

# Create a point and a polygon
point = Point(0, 0)
polygon = Polygon([(0, 0), (1, 1), (1, 0)])

# Perform a spatial operation
intersection = point.intersection(polygon)

print(f"Point: {point}")
print(f"Polygon: {polygon}")
print(f"Intersection: {intersection}")
print(f"Point within polygon: {polygon.contains(point)}")

# Example of a vectorized operation (Shapely 2.0+)
import numpy as np
geoms = np.array([Point(0.5, 0.5), Point(1.5, 0.5)])
print(f"\nVectorized contains: {shapely.contains(polygon, geoms)}")