0
# Coverage Operations
1

2
Advanced operations specifically designed for working with polygon coverages - collections of polygons that share boundaries without gaps or overlaps. These operations are optimized for processing large collections of adjacent polygons such as cadastral maps, administrative boundaries, or ecological zones.
3

4
**Note**: All coverage operations require GEOS 3.12.0 or later.
5

6
## Capabilities
7

8
### Coverage Validation
9

10
Validate the integrity and correctness of polygon coverages.
11

12
```python { .api }
13
def coverage_is_valid(geometry, gap_width=0.0, **kwargs):
14
    """
15
    Check if polygon coverage is valid (no gaps or overlaps).
16
    
17
    Parameters:
18
    - geometry: polygon or multi-polygon coverage to validate
19
    - gap_width: tolerance for small gaps (default 0.0)
20
    
21
    Returns:
22
    bool or ndarray indicating coverage validity
23
    
24
    Note:
25
    Requires GEOS 3.12.0+
26
    """
27
```
28

29
**Usage Example:**
30

31
```python
32
import shapely
33

34
# Create adjacent polygons forming a coverage
35
poly1 = shapely.box(0, 0, 1, 1)
36
poly2 = shapely.box(1, 0, 2, 1)  # Shares edge with poly1
37
poly3 = shapely.box(0, 1, 1, 2)  # Shares edge with poly1
38

39
coverage = shapely.union_all([poly1, poly2, poly3])
40

41
# Validate coverage
42
is_valid = shapely.coverage_is_valid(coverage)
43
print(f"Coverage is valid: {is_valid}")
44

45
# Allow small gaps
46
is_valid_with_tolerance = shapely.coverage_is_valid(coverage, gap_width=0.01)
47
```
48

49
### Coverage Error Detection
50

51
Identify specific edges that cause coverage invalidity.
52

53
```python { .api }
54
def coverage_invalid_edges(geometry, gap_width=0.0, **kwargs):
55
    """
56
    Find edges that make a polygon coverage invalid.
57
    
58
    Parameters:
59
    - geometry: polygon or multi-polygon coverage to analyze
60
    - gap_width: tolerance for small gaps (default 0.0)
61
    
62
    Returns:
63
    LineString or MultiLineString of invalid edges, or empty geometry if valid
64
    
65
    Note:
66
    Requires GEOS 3.12.0+
67
    """
68
```
69

70
**Usage Example:**
71

72
```python
73
import shapely
74

75
# Create coverage with gaps
76
poly1 = shapely.box(0, 0, 1, 1)
77
poly2 = shapely.box(1.1, 0, 2.1, 1)  # Small gap between polygons
78
coverage = shapely.union_all([poly1, poly2])
79

80
# Find invalid edges
81
invalid_edges = shapely.coverage_invalid_edges(coverage)
82
if not shapely.is_empty(invalid_edges):
83
    print(f"Found {shapely.get_num_geometries(invalid_edges)} invalid edges")
84
```
85

86
### Coverage Simplification
87

88
Simplify polygon coverages while maintaining shared boundaries.
89

90
```python { .api }
91
def coverage_simplify(geometry, tolerance, *, simplify_boundary=True, **kwargs):
92
    """
93
    Simplify polygon coverage while preserving topology and shared boundaries.
94
    
95
    Parameters:
96
    - geometry: polygon or multi-polygon coverage to simplify
97
    - tolerance: simplification tolerance
98
    - simplify_boundary: whether to simplify coverage boundary (default True)
99
    
100
    Returns:
101
    Simplified coverage geometry
102
    
103
    Note:
104
    Requires GEOS 3.12.0+
105
    """
106
```
107

108
**Usage Example:**
109

110
```python
111
import shapely
112
import numpy as np
113

114
# Create complex coverage with many vertices
115
def create_detailed_polygon(bounds, num_points=100):
116
    xmin, ymin, xmax, ymax = bounds
117
    # Create polygon with many random vertices
118
    angles = np.linspace(0, 2*np.pi, num_points, endpoint=False)
119
    x = xmin + (xmax - xmin) * (0.5 + 0.3 * np.cos(angles))
120
    y = ymin + (ymax - ymin) * (0.5 + 0.3 * np.sin(angles))
121
    return shapely.Polygon(list(zip(x, y)))
122

123
poly1 = create_detailed_polygon([0, 0, 1, 1])
124
poly2 = create_detailed_polygon([1, 0, 2, 1])
125
coverage = shapely.union_all([poly1, poly2])
126

127
print(f"Original coordinates: {shapely.get_num_coordinates(coverage)}")
128

129
# Simplify coverage
130
simplified = shapely.coverage_simplify(coverage, tolerance=0.1)
131
print(f"Simplified coordinates: {shapely.get_num_coordinates(simplified)}")
132

133
# Simplify without boundary simplification
134
simplified_interior = shapely.coverage_simplify(
135
    coverage, tolerance=0.1, simplify_boundary=False
136
)
137
```
138

139
### Coverage Union Operations
140

141
Union operations optimized for polygon coverages.
142

143
```python { .api }
144
def coverage_union(a, b, **kwargs):
145
    """
146
    Union two polygon coverages efficiently.
147
    
148
    Parameters:
149
    - a: first polygon coverage
150
    - b: second polygon coverage
151
    
152
    Returns:
153
    Union of the two coverages
154
    
155
    Note:
156
    More efficient than regular union for coverages.
157
    Requires GEOS 3.12.0+
158
    """
159

160
def coverage_union_all(geometries, axis=None, **kwargs):
161
    """
162
    Union multiple polygon coverages efficiently.
163
    
164
    Parameters:
165
    - geometries: array of polygon coverages
166
    - axis: axis along which to perform union (optional)
167
    
168
    Returns:
169
    Union of all input coverages
170
    
171
    Note:
172
    More efficient than regular union_all for coverages.
173
    Requires GEOS 3.12.0+
174
    """
175
```
176

177
**Usage Example:**
178

179
```python
180
import shapely
181

182
# Create multiple coverage polygons
183
coverage1 = shapely.union_all([
184
    shapely.box(0, 0, 1, 1),
185
    shapely.box(1, 0, 2, 1)
186
])
187

188
coverage2 = shapely.union_all([
189
    shapely.box(0, 1, 1, 2), 
190
    shapely.box(1, 1, 2, 2)
191
])
192

193
coverage3 = shapely.union_all([
194
    shapely.box(2, 0, 3, 1),
195
    shapely.box(2, 1, 3, 2)
196
])
197

198
# Union two coverages
199
combined = shapely.coverage_union(coverage1, coverage2)
200

201
# Union multiple coverages
202
all_coverages = [coverage1, coverage2, coverage3]
203
full_coverage = shapely.coverage_union_all(all_coverages)
204

205
print(f"Final coverage area: {shapely.area(full_coverage)}")
206
```
207

208
## Coverage Workflow Example
209

210
Here's a complete example of working with polygon coverages:
211

212
```python
213
import shapely
214
import numpy as np
215

216
def validate_and_process_coverage(polygons):
217
    """Process and validate a polygon coverage."""
218
    
219
    # Combine polygons into coverage
220
    coverage = shapely.union_all(polygons)
221
    
222
    # Validate coverage
223
    if shapely.coverage_is_valid(coverage):
224
        print("✓ Coverage is valid")
225
    else:
226
        print("✗ Coverage has issues")
227
        
228
        # Find problematic edges
229
        invalid_edges = shapely.coverage_invalid_edges(coverage)
230
        if not shapely.is_empty(invalid_edges):
231
            print(f"Found {shapely.get_num_geometries(invalid_edges)} invalid edges")
232
            
233
            # You might want to fix the issues here
234
            # For example, by buffering slightly to close small gaps
235
            coverage = shapely.buffer(coverage, 0.001).buffer(-0.001)
236
            
237
            # Re-validate
238
            if shapely.coverage_is_valid(coverage):
239
                print("✓ Coverage fixed")
240
    
241
    # Simplify if needed
242
    original_coords = shapely.get_num_coordinates(coverage)
243
    simplified = shapely.coverage_simplify(coverage, tolerance=0.01)
244
    simplified_coords = shapely.get_num_coordinates(simplified)
245
    
246
    print(f"Simplified from {original_coords} to {simplified_coords} coordinates")
247
    
248
    return simplified
249

250
# Example usage
251
polygons = [
252
    shapely.box(0, 0, 1, 1),
253
    shapely.box(1, 0, 2, 1),
254
    shapely.box(0, 1, 1, 2),
255
    shapely.box(1, 1, 2, 2)
256
]
257

258
processed_coverage = validate_and_process_coverage(polygons)
259
```
260

261
## Performance Benefits
262

263
Coverage operations are specifically optimized for polygon collections that share boundaries:
264

265
1. **coverage_union**: More efficient than regular union for adjacent polygons
266
2. **coverage_simplify**: Maintains shared boundaries while reducing vertex count
267
3. **coverage_is_valid**: Quickly validates coverage topology
268
4. **coverage_invalid_edges**: Precisely identifies problem areas
269

270
These functions are particularly useful for:
271
- **Cadastral mapping**: Land parcel boundaries
272
- **Administrative boundaries**: Political divisions
273
- **Ecological zones**: Habitat or climate regions  
274
- **Urban planning**: Zoning and land use maps
275
- **Geological surveys**: Rock formations and soil types
276

277
## Requirements
278

279
All coverage operations require:
280
- **GEOS 3.12.0 or later**
281
- Input geometries should be **valid polygons**
282
- Best performance with **adjacent, non-overlapping polygons**