shapely

Shapely - Planar Geometry

Shapely is the engine behind GeoPandas and many other GIS tools. It focuses on the geometry itself: calculating intersections, unions, distances, and checking spatial relationships (like "is this point inside this polygon?").

When to Use

• Precise manipulation of 2D geometric shapes.
• Performing set-theoretic operations (Intersection, Union, Difference).
• Checking spatial predicates (Contains, Within, Intersects, Touches).
• Cleaning and validating "dirty" geometry (fixing self-intersections).
• Calculating geometric properties (Area, Length, Centroid, Bounds).
• Generating buffers or simplifying complex lines.
• Linear referencing (finding points along a line).

Reference Documentation

Official docs: https://shapely.readthedocs.io/
GEOS (Engine): https://libgeos.org/
Search patterns: shapely.geometry, shapely.ops.unary_union, shapely.validation.make_valid

Core Principles

Geometric Objects

Objects are immutable. Once created, you don't change them; you perform an operation that returns a new object.

• Points: 0-dimensional.
• LineStrings: 1-dimensional curves.
• Polygons: 2-dimensional surfaces with optional holes.

Cartesian Geometry

Shapely operates in a Cartesian plane. It does not know about Earth's curvature, latitudes, or longitudes. Distance is sqrt(dx² + dy²).

Vectorization (Shapely 2.0+)

Modern Shapely supports vectorized operations on NumPy arrays of geometry objects, making it significantly faster than older versions.

Quick Reference

Installation

pip install shapely numpy

Standard Imports

import numpy as np
from shapely import Point, LineString, Polygon, MultiPoint, MultiPolygon
from shapely import ops, wkt, wkb
import shapely

Basic Pattern - Creation and Analysis

from shapely.geometry import Point, Polygon

# 1. Create objects
p = Point(0, 0)
poly = Polygon([(0, 0), (2, 0), (2, 2), (0, 2)])

# 2. Check relationships
is_inside = p.within(poly) # True
is_on_border = p.touches(poly) # False (interior counts as within)

# 3. Calculate
print(f"Area: {poly.area}")
print(f"Distance: {p.distance(Point(10, 10))}")