0
# Constructive Operations
1

2
Operations that create new geometries through geometric analysis, transformation, and construction. These functions generate derived geometries from input geometries while preserving topological relationships.
3

4
## Capabilities
5

6
### Buffer Operations
7

8
Create buffer zones around geometries.
9

10
```python { .api }
11
def buffer(geometry, distance, quad_segs=8, cap_style='round', join_style='round', mitre_limit=5.0, single_sided=False, **kwargs):
12
    """
13
    Create buffer around geometry.
14
    
15
    Parameters:
16
    - geometry: input geometry or array of geometries
17
    - distance: buffer distance (positive for outward, negative for inward)
18
    - quad_segs: number of segments for quarter-circle approximation
19
    - cap_style: end cap style ('round', 'flat', 'square')
20
    - join_style: join style ('round', 'mitre', 'bevel')
21
    - mitre_limit: mitre ratio limit for mitre joins
22
    - single_sided: create single-sided buffer
23
    
24
    Returns:
25
    Buffered geometry or array of geometries
26
    """
27
```
28

29
**Usage Example:**
30

31
```python
32
import shapely
33
from shapely.geometry import Point, LineString
34

35
# Buffer a point (creates circle)
36
point = Point(0, 0)
37
circle = shapely.buffer(point, 1.0)
38
print(f"Circle area: {circle.area:.2f}")  # ~3.14
39

40
# Buffer a line with different cap styles
41
line = LineString([(0, 0), (2, 0)])
42
rounded_buffer = shapely.buffer(line, 0.5, cap_style='round')
43
flat_buffer = shapely.buffer(line, 0.5, cap_style='flat')
44
square_buffer = shapely.buffer(line, 0.5, cap_style='square')
45

46
# Negative buffer (shrink)
47
polygon = shapely.box(0, 0, 4, 4)
48
smaller = shapely.buffer(polygon, -0.5)
49
```
50

51
### Hull Operations
52

53
Compute convex and concave hulls.
54

55
```python { .api }
56
def convex_hull(geometry, **kwargs):
57
    """
58
    Compute convex hull of geometry.
59
    
60
    Parameters:
61
    - geometry: input geometry or array of geometries
62
    
63
    Returns:
64
    Convex hull geometry
65
    """
66

67
def concave_hull(geometry, ratio, allow_holes=False, **kwargs):
68
    """
69
    Compute concave hull (alpha shape) of geometry.
70
    Requires GEOS 3.11+.
71
    
72
    Parameters:
73
    - geometry: input geometry or array of geometries
74
    - ratio: length ratio for concaveness (0=convex hull, 1=very concave)
75
    - allow_holes: whether to allow holes in result
76
    
77
    Returns:
78
    Concave hull geometry
79
    """
80
```
81

82
**Usage Example:**
83

84
```python
85
import shapely
86
import numpy as np
87

88
# Create scattered points
89
np.random.seed(42)
90
coords = np.random.rand(20, 2) * 10
91
points = shapely.multipoints([coords])
92

93
# Compute hulls
94
convex = shapely.convex_hull(points)
95
concave = shapely.concave_hull(points, ratio=0.3, allow_holes=False)
96

97
print(f"Convex hull area: {convex.area:.2f}")
98
print(f"Concave hull area: {concave.area:.2f}")
99
```
100

101
### Geometric Centers and Representatives
102

103
Find representative points and centers.
104

105
```python { .api }
106
def centroid(geometry, **kwargs):
107
    """
108
    Compute geometric centroid of geometry.
109
    
110
    Parameters:
111
    - geometry: input geometry or array of geometries
112
    
113
    Returns:
114
    Point geometry representing centroid
115
    """
116

117
def point_on_surface(geometry, **kwargs):
118
    """
119
    Get a point guaranteed to be on the geometry surface.
120
    
121
    Parameters:
122
    - geometry: input geometry or array of geometries
123
    
124
    Returns:
125
    Point geometry on the surface
126
    """
127
```
128

129
**Usage Example:**
130

131
```python
132
import shapely
133

134
# Centroid might be outside complex polygons
135
c_shape = shapely.Polygon([(0, 0), (0, 2), (1, 2), (1, 1), (2, 1), (2, 0)])
136
centroid = shapely.centroid(c_shape)
137
surface_point = shapely.point_on_surface(c_shape)
138

139
print(f"Centroid inside shape: {c_shape.contains(centroid)}")
140
print(f"Surface point inside shape: {c_shape.contains(surface_point)}")
141
```
142

143
### Bounding Shapes
144

145
Create various bounding shapes around geometries.
146

147
```python { .api }
148
def envelope(geometry, **kwargs):
149
    """
150
    Compute axis-aligned bounding box.
151
    
152
    Parameters:
153
    - geometry: input geometry or array of geometries
154
    
155
    Returns:
156
    Rectangular polygon bounding box
157
    """
158

159
def minimum_rotated_rectangle(geometry, **kwargs):
160
    """
161
    Compute minimum area oriented bounding rectangle.
162
    
163
    Parameters:
164
    - geometry: input geometry or array of geometries
165
    
166
    Returns:
167
    Rotated rectangular polygon
168
    """
169

170
def minimum_bounding_circle(geometry, **kwargs):
171
    """
172
    Compute minimum bounding circle.
173
    
174
    Parameters:
175
    - geometry: input geometry or array of geometries
176
    
177
    Returns:
178
    Circular polygon approximation
179
    """
180

181
def maximum_inscribed_circle(geometry, tolerance=0.01, **kwargs):
182
    """
183
    Find maximum inscribed circle (pole of inaccessibility).
184
    
185
    Parameters:
186
    - geometry: input polygon geometry
187
    - tolerance: precision tolerance
188
    
189
    Returns:
190
    Point at circle center with radius as additional coordinate
191
    """
192
```
193

194
**Usage Example:**
195

196
```python
197
import shapely
198

199
# Create irregular polygon
200
polygon = shapely.Polygon([(0, 0), (3, 1), (2, 3), (0, 2)])
201

202
# Various bounding shapes
203
bbox = shapely.envelope(polygon)
204
min_rect = shapely.minimum_rotated_rectangle(polygon)
205
min_circle = shapely.minimum_bounding_circle(polygon)
206
max_inscribed = shapely.maximum_inscribed_circle(polygon)
207

208
print(f"Original area: {polygon.area:.2f}")
209
print(f"Bounding box area: {bbox.area:.2f}")
210
print(f"Min rectangle area: {min_rect.area:.2f}")
211
```
212

213
### Simplification
214

215
Reduce geometry complexity while preserving essential shape.
216

217
```python { .api }
218
def simplify(geometry, tolerance, preserve_topology=True, **kwargs):
219
    """
220
    Simplify geometry by removing vertices.
221
    
222
    Parameters:
223
    - geometry: input geometry or array of geometries
224
    - tolerance: simplification tolerance
225
    - preserve_topology: maintain topological relationships
226
    
227
    Returns:
228
    Simplified geometry
229
    """
230

231
def remove_repeated_points(geometry, tolerance=0.0, **kwargs):
232
    """
233
    Remove repeated/duplicate points from geometry.
234
    Requires GEOS 3.11+.
235
    
236
    Parameters:
237
    - geometry: input geometry or array of geometries
238
    - tolerance: coordinate tolerance for duplicate detection
239
    
240
    Returns:
241
    Geometry with repeated points removed
242
    """
243
```
244

245
**Usage Example:**
246

247
```python
248
import shapely
249

250
# Create complex polygon
251
detailed_coords = [(0, 0), (0.1, 0.01), (0.2, 0.02), (1, 0), (1, 1), (0, 1)]
252
detailed_polygon = shapely.Polygon(detailed_coords)
253

254
# Simplify with different tolerances
255
simplified = shapely.simplify(detailed_polygon, tolerance=0.05)
256
aggressive = shapely.simplify(detailed_polygon, tolerance=0.2)
257

258
print(f"Original vertices: {len(detailed_polygon.exterior.coords)}")
259
print(f"Simplified vertices: {len(simplified.exterior.coords)}")
260
print(f"Aggressive vertices: {len(aggressive.exterior.coords)}")
261
```
262

263
### Geometry Repair and Validation
264

265
Make invalid geometries valid and repair common issues.
266

267
```python { .api }
268
def make_valid(geometry, **kwargs):
269
    """
270
    Repair invalid geometries to make them valid.
271
    
272
    Parameters:
273
    - geometry: input geometry or array of geometries
274
    
275
    Returns:
276
    Valid geometry (may change geometry type)
277
    """
278

279
def normalize(geometry, **kwargs):
280
    """
281
    Convert geometry to canonical/normalized form.
282
    
283
    Parameters:
284
    - geometry: input geometry or array of geometries
285
    
286
    Returns:
287
    Normalized geometry
288
    """
289

290
def snap(geometry, reference, tolerance, **kwargs):
291
    """
292
    Snap vertices of geometry to reference geometry.
293
    
294
    Parameters:
295
    - geometry: geometry to snap
296
    - reference: reference geometry to snap to
297
    - tolerance: snapping tolerance
298
    
299
    Returns:
300
    Snapped geometry
301
    """
302
```
303

304
**Usage Example:**
305

306
```python
307
import shapely
308
from shapely.geometry import Polygon
309

310
# Create invalid self-intersecting polygon
311
invalid = Polygon([(0, 0), (2, 2), (2, 0), (0, 2)])
312
print(f"Original valid: {shapely.is_valid(invalid)}")
313

314
# Repair it
315
valid = shapely.make_valid(invalid)
316
print(f"Repaired valid: {shapely.is_valid(valid)}")
317
print(f"Result type: {valid.geom_type}")
318
```
319

320
### Triangulation
321

322
Create triangulated representations of geometries.
323

324
```python { .api }
325
def delaunay_triangles(geometry, tolerance=0.0, only_edges=False, **kwargs):
326
    """
327
    Compute Delaunay triangulation.
328
    
329
    Parameters:
330
    - geometry: input geometry or array of geometries
331
    - tolerance: coordinate tolerance
332
    - only_edges: return only triangle edges instead of filled triangles
333
    
334
    Returns:
335
    GeometryCollection of triangles or edges
336
    """
337

338
def constrained_delaunay_triangles(geometry, **kwargs):
339
    """
340
    Compute constrained Delaunay triangulation.
341
    
342
    Parameters:
343
    - geometry: input geometry or array of geometries
344
    
345
    Returns:
346
    GeometryCollection of triangles
347
    """
348
```
349

350
### Advanced Operations
351

352
Specialized geometric constructions.
353

354
```python { .api }
355
def voronoi_polygons(geometry, envelope=None, tolerance=0.0, only_edges=False, **kwargs):
356
    """
357
    Compute Voronoi diagram.
358
    
359
    Parameters:
360
    - geometry: input point geometry
361
    - envelope: clipping envelope for diagram
362
    - tolerance: coordinate tolerance
363
    - only_edges: return only diagram edges
364
    
365
    Returns:
366
    GeometryCollection of Voronoi cells or edges
367
    """
368

369
def build_area(geometry, **kwargs):
370
    """
371
    Build polygonal area from linework.
372
    
373
    Parameters:
374
    - geometry: input linear geometry
375
    
376
    Returns:
377
    Polygon geometry constructed from lines
378
    """
379

380
def node(geometry, **kwargs):
381
    """
382
    Node linear geometry at intersections.
383
    
384
    Parameters:
385
    - geometry: input linear geometry
386
    
387
    Returns:
388
    MultiLineString with all intersections noded
389
    """
390

391
def extract_unique_points(geometry, **kwargs):
392
    """
393
    Extract all unique vertex points from geometry.
394
    
395
    Parameters:
396
    - geometry: input geometry
397
    
398
    Returns:
399
    MultiPoint containing all unique vertices
400
    """
401
```
402

403
**Usage Example:**
404

405
```python
406
import shapely
407

408
# Voronoi diagram from random points
409
import numpy as np
410
np.random.seed(42)
411
points = shapely.points(np.random.rand(10, 2) * 10)
412
envelope = shapely.box(0, 0, 10, 10)
413

414
voronoi = shapely.voronoi_polygons(points, envelope=envelope)
415
print(f"Voronoi cells: {len(voronoi.geoms)}")
416

417
# Extract vertices from polygon
418
polygon = shapely.box(0, 0, 2, 2)
419
vertices = shapely.extract_unique_points(polygon)
420
print(f"Polygon vertices: {len(vertices.geoms)}")
421
```
422

423
### Additional Constructive Operations
424

425
Other geometric construction and transformation operations.
426

427
```python { .api }
428
def boundary(geometry, **kwargs):
429
    """
430
    Get the topological boundary of geometries.
431
    
432
    Parameters:
433
    - geometry: input geometry or array of geometries
434
    
435
    Returns:
436
    Boundary geometry (points for polygons, endpoints for lines)
437
    """
438

439
def clip_by_rect(geometry, xmin, ymin, xmax, ymax, **kwargs):
440
    """
441
    Clip geometries by rectangular bounds.
442
    
443
    Parameters:
444
    - geometry: input geometry or array of geometries
445
    - xmin, ymin, xmax, ymax: clipping rectangle bounds
446
    
447
    Returns:
448
    Clipped geometry within the rectangle
449
    """
450

451
def minimum_clearance_line(geometry, **kwargs):
452
    """
453
    Get the line representing minimum clearance of geometries.
454
    
455
    Parameters:
456
    - geometry: input geometry or array of geometries
457
    
458
    Returns:
459
    LineString representing minimum clearance
460
    """
461

462
def offset_curve(geometry, distance, quad_segs=8, join_style='round', mitre_limit=5.0, **kwargs):
463
    """
464
    Create offset curves from linestring geometries.
465
    
466
    Parameters:
467
    - geometry: linestring geometry or array
468
    - distance: offset distance (positive for left, negative for right)
469
    - quad_segs: segments for quarter-circle approximation
470
    - join_style: join style ('round', 'mitre', 'bevel')
471
    - mitre_limit: mitre ratio limit
472
    
473
    Returns:
474
    Offset curve geometry
475
    """
476

477
def orient_polygons(geometry, *, exterior_cw=False, **kwargs):
478
    """
479
    Orient polygon rings consistently.
480
    
481
    Parameters:
482
    - geometry: polygon geometry or array of polygons
483
    - exterior_cw: orient exterior rings clockwise if True
484
    
485
    Returns:
486
    Consistently oriented polygons
487
    """
488

489
def oriented_envelope(geometry, **kwargs):
490
    """
491
    Get the minimum rotated rectangle that encloses geometries.
492
    
493
    Parameters:
494
    - geometry: input geometry or array of geometries
495
    
496
    Returns:
497
    Minimum rotated rectangle (oriented envelope)
498
    """
499

500
def polygonize(geometries, **kwargs):
501
    """
502
    Create polygons from a collection of linestrings.
503
    
504
    Parameters:
505
    - geometries: array of linestring geometries
506
    
507
    Returns:
508
    GeometryCollection of polygons formed by input lines
509
    """
510

511
def polygonize_full(geometries, **kwargs):
512
    """
513
    Create polygons and return additional topology information.
514
    
515
    Parameters:
516
    - geometries: array of linestring geometries
517
    
518
    Returns:
519
    Tuple of (polygons, cuts, dangles, invalid_rings)
520
    """
521

522
def reverse(geometry, **kwargs):
523
    """
524
    Reverse the coordinate order of geometries.
525
    
526
    Parameters:
527
    - geometry: input geometry or array of geometries
528
    
529
    Returns:
530
    Geometry with reversed coordinate order
531
    """
532

533
def segmentize(geometry, max_segment_length, **kwargs):
534
    """
535
    Add vertices to geometries to limit segment length.
536
    
537
    Parameters:
538
    - geometry: input geometry or array of geometries
539
    - max_segment_length: maximum allowed segment length
540
    
541
    Returns:
542
    Segmentized geometry with additional vertices
543
    """
544
```
545

546
## Types
547

548
```python { .api }
549
# Buffer style enumerations
550
class BufferCapStyle:
551
    round = 1
552
    flat = 2
553
    square = 3
554

555
class BufferJoinStyle:
556
    round = 1
557
    mitre = 2
558
    bevel = 3
559
```