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