0
# Shapely
1
2
Shapely is a Python package for manipulation and analysis of geometric objects in the Cartesian plane. It provides a comprehensive set of tools for creating, analyzing, and manipulating 2D and 3D geometric shapes, built on top of the industry-standard GEOS library.
3
4
## Package Information
5
6
- **Package Name**: shapely
7
- **Language**: Python
8
- **Installation**: `pip install shapely`
9
10
## Core Imports
11
12
```python
13
import shapely
14
```
15
16
Common patterns for specific functionality:
17
18
```python
19
from shapely.geometry import Point, LineString, Polygon
20
from shapely import affinity
21
import shapely.ops as ops
22
```
23
24
For array-based operations:
25
26
```python
27
import shapely
28
import numpy as np
29
```
30
31
## Basic Usage
32
33
```python
34
import shapely
35
from shapely.geometry import Point, LineString, Polygon
36
37
# Create geometries
38
point = Point(1, 1)
39
line = LineString([(0, 0), (1, 1), (2, 0)])
40
poly = Polygon([(0, 0), (2, 0), (2, 2), (0, 2)])
41
42
# Spatial predicates
43
print(poly.contains(point)) # True
44
print(line.intersects(poly)) # True
45
46
# Measurements
47
print(poly.area) # 4.0
48
print(line.length) # ~2.83
49
50
# Operations
51
buffered = point.buffer(0.5)
52
intersection = line.intersection(poly)
53
54
# Array-based operations for better performance
55
import numpy as np
56
points = shapely.points([(1, 1), (2, 2), (3, 3)])
57
boxes = shapely.box(0, 0, [1, 2, 3], [1, 2, 3])
58
areas = shapely.area(boxes)
59
```
60
61
## Architecture
62
63
Shapely provides two main APIs:
64
65
- **Object-oriented API**: Individual geometry objects with methods (`point.buffer(1.0)`)
66
- **Functional API**: Array-based operations for high performance (`shapely.buffer(geometries, 1.0)`)
67
68
Core geometry types form a hierarchy:
69
- **Base geometries**: Point, LineString, Polygon, LinearRing
70
- **Multi-geometries**: MultiPoint, MultiLineString, MultiPolygon
71
- **Collections**: GeometryCollection for mixed geometry types
72
73
All operations preserve coordinate precision and maintain topological consistency through the underlying GEOS library.
74
75
## Capabilities
76
77
### Core Geometry Classes
78
79
The fundamental geometry types that represent points, lines, polygons, and their multi-geometry collections.
80
81
```python { .api }
82
class Point:
83
def __init__(self, x, y, z=None): ...
84
85
class LineString:
86
def __init__(self, coordinates): ...
87
88
class Polygon:
89
def __init__(self, shell, holes=None): ...
90
91
class MultiPoint:
92
def __init__(self, points): ...
93
94
class MultiLineString:
95
def __init__(self, linestrings): ...
96
97
class MultiPolygon:
98
def __init__(self, polygons): ...
99
100
class GeometryCollection:
101
def __init__(self, geometries): ...
102
```
103
104
[Geometry Classes](./geometry-classes.md)
105
106
### Creation Functions
107
108
High-performance functions for creating arrays of geometries from coordinate data.
109
110
```python { .api }
111
def points(coords, y=None, z=None, indices=None, *, handle_nan='allow', out=None, **kwargs): ...
112
def linestrings(coords, y=None, z=None, indices=None, *, handle_nan='allow', out=None, **kwargs): ...
113
def polygons(geometries, holes=None, indices=None, *, out=None, **kwargs): ...
114
def box(xmin, ymin, xmax, ymax, ccw=True, **kwargs): ...
115
```
116
117
[Creation Functions](./creation.md)
118
119
### Spatial Predicates
120
121
Boolean tests for spatial relationships and geometry properties.
122
123
```python { .api }
124
def contains(a, b, **kwargs) -> bool: ...
125
def intersects(a, b, **kwargs) -> bool: ...
126
def within(a, b, **kwargs) -> bool: ...
127
def touches(a, b, **kwargs) -> bool: ...
128
def is_valid(geometry, **kwargs) -> bool: ...
129
def is_empty(geometry, **kwargs) -> bool: ...
130
```
131
132
[Spatial Predicates](./predicates.md)
133
134
### Measurements
135
136
Compute geometric properties like area, length, distance, and bounds.
137
138
```python { .api }
139
def area(geometry, **kwargs): ...
140
def length(geometry, **kwargs): ...
141
def distance(a, b, **kwargs): ...
142
def bounds(geometry, **kwargs): ...
143
```
144
145
[Measurements](./measurements.md)
146
147
### Constructive Operations
148
149
Operations that create new geometries through transformation and analysis.
150
151
```python { .api }
152
def buffer(geometry, distance, quad_segs=8, cap_style='round', join_style='round', mitre_limit=5.0, single_sided=False, **kwargs): ...
153
def convex_hull(geometry, **kwargs): ...
154
def simplify(geometry, tolerance, preserve_topology=True, **kwargs): ...
155
def centroid(geometry, **kwargs): ...
156
```
157
158
[Constructive Operations](./constructive.md)
159
160
### Set Operations
161
162
Boolean operations combining geometries using union, intersection, and difference.
163
164
```python { .api }
165
def union(a, b, grid_size=None, **kwargs): ...
166
def intersection(a, b, grid_size=None, **kwargs): ...
167
def difference(a, b, grid_size=None, **kwargs): ...
168
def symmetric_difference(a, b, grid_size=None, **kwargs): ...
169
```
170
171
[Set Operations](./set-operations.md)
172
173
### Linear Operations
174
175
Specialized operations for working with linear geometries.
176
177
```python { .api }
178
def line_interpolate_point(line, distance, normalized=False, **kwargs): ...
179
def line_locate_point(line, point, normalized=False, **kwargs): ...
180
def line_merge(geometry, directed=False, **kwargs): ...
181
```
182
183
[Linear Operations](./linear.md)
184
185
### Coordinate Operations
186
187
Direct manipulation of coordinate arrays and coordinate transformations.
188
189
```python { .api }
190
def get_coordinates(geometry, include_z=False, include_m=False, return_index=False, **kwargs): ...
191
def set_coordinates(geometry, coordinates, include_z=None, **kwargs): ...
192
def transform(geometry, transformation, include_z=False, *, interleaved=True): ...
193
```
194
195
[Coordinate Operations](./coordinates.md)
196
197
### Input/Output
198
199
Convert geometries to and from standard formats like WKT, WKB, and GeoJSON.
200
201
```python { .api }
202
def to_wkt(geometry, rounding_precision=None, trim=True, output_dimension=None, old_3d=False, **kwargs): ...
203
def from_wkt(wkt, on_invalid='raise', **kwargs): ...
204
def to_geojson(geometry, indent=None, **kwargs): ...
205
def from_geojson(geojson, on_invalid='raise', **kwargs): ...
206
```
207
208
[Input/Output](./io.md)
209
210
### Affinity Transformations
211
212
Geometric transformations like rotation, scaling, translation, and skewing.
213
214
```python { .api }
215
def rotate(geom, angle, origin='center', use_radians=False): ...
216
def scale(geom, xfact=1.0, yfact=1.0, zfact=1.0, origin='center'): ...
217
def translate(geom, xoff=0.0, yoff=0.0, zoff=0.0): ...
218
```
219
220
[Affinity Transformations](./affinity.md)
221
222
### Spatial Indexing
223
224
R-tree spatial indexing for efficient spatial queries on large geometry collections.
225
226
```python { .api }
227
class STRtree:
228
def __init__(self, geometries, node_capacity=10): ...
229
def query(self, geometry, predicate=None): ...
230
def nearest(self, geometry, max_distance=None, return_distance=False, exclusive=False): ...
231
```
232
233
[Spatial Indexing](./spatial-indexing.md)
234
235
### Geometry Introspection
236
237
Access and examine geometric properties, dimensions, coordinate information, and structure of geometry objects.
238
239
```python { .api }
240
def get_coordinate_dimension(geometry, **kwargs): ...
241
def get_dimensions(geometry, **kwargs): ...
242
def get_num_coordinates(geometry, **kwargs): ...
243
def get_num_geometries(geometry, **kwargs): ...
244
def get_parts(geometry, return_index=False): ...
245
def get_rings(geometry, return_index=False): ...
246
def get_type_id(geometry, **kwargs): ...
247
```
248
249
[Geometry Introspection](./geometry-introspection.md)
250
251
### Coverage Operations
252
253
Advanced operations for working with polygon coverages that share boundaries, requiring GEOS 3.12.0+.
254
255
```python { .api }
256
def coverage_is_valid(geometry, gap_width=0.0, **kwargs): ...
257
def coverage_invalid_edges(geometry, gap_width=0.0, **kwargs): ...
258
def coverage_simplify(geometry, tolerance, *, simplify_boundary=True, **kwargs): ...
259
def coverage_union(a, b, **kwargs): ...
260
def coverage_union_all(geometries, axis=None, **kwargs): ...
261
```
262
263
[Coverage Operations](./coverage-operations.md)
264
265
## Types
266
267
```python { .api }
268
# Base geometry type
269
class Geometry:
270
@property
271
def area(self) -> float: ...
272
@property
273
def bounds(self) -> tuple: ...
274
@property
275
def length(self) -> float: ...
276
def buffer(self, distance: float, **kwargs) -> 'Geometry': ...
277
def contains(self, other: 'Geometry') -> bool: ...
278
def intersects(self, other: 'Geometry') -> bool: ...
279
280
# Enumerations
281
class GeometryType:
282
MISSING = -1
283
POINT = 0
284
LINESTRING = 1
285
LINEARRING = 2
286
POLYGON = 3
287
MULTIPOINT = 4
288
MULTILINESTRING = 5
289
MULTIPOLYGON = 6
290
GEOMETRYCOLLECTION = 7
291
292
class BufferCapStyle:
293
round = 1
294
flat = 2
295
square = 3
296
297
class BufferJoinStyle:
298
round = 1
299
mitre = 2
300
bevel = 3
301
302
# I/O enumerations
303
class DecodingErrorOptions:
304
ignore = 0
305
warn = 1
306
raise = 2
307
fix = 3
308
309
class WKBFlavorOptions:
310
extended = 1
311
iso = 2
312
313
# Spatial indexing enumerations
314
class BinaryPredicate:
315
intersects = 1
316
within = 2
317
contains = 3
318
overlaps = 4
319
crosses = 5
320
touches = 6
321
covers = 7
322
covered_by = 8
323
contains_properly = 9
324
325
# Precision handling enumerations
326
class SetPrecisionMode:
327
valid_output = 0
328
pointwise = 1
329
keep_collapsed = 2
330
331
# Creation handling enumerations
332
class HandleNaN:
333
allow = 0
334
skip = 1
335
error = 2
336
```