Source: https://gometry.monicz.dev/api/toplevel/coverage-polygonal/

# Coverage (polygonal)

Validate, clean, simplify, and union edge-sharing polygon coverages.

**Related:** [Validation & repair](https://gometry.monicz.dev/guide/validation/)

## coverage\_clean

Accepted call forms

```python
coverage_clean(values: Polygon | MultiPolygon | GeometryArray[Polygon | MultiPolygon] | Iterable[Polygon | MultiPolygon | Buffer | Mapping[str, Any] | SupportsGeoInterface], *, grid_size: float = 0.0, gap_width: float = 0.0, overlap_rule: Literal['longest_border', 'max_area', 'min_area', 'min_index'] = 'longest_border') -> GeometryArray[Polygon | MultiPolygon]
```

```python
coverage_clean(values: GeometryArray[Polygon | MultiPolygon | None] | Iterable[Polygon | MultiPolygon | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, grid_size: float = 0.0, gap_width: float = 0.0, overlap_rule: Literal['longest_border', 'max_area', 'min_area', 'min_index'] = 'longest_border') -> GeometryArray[Polygon | MultiPolygon | None]
```

Clean a near-coverage into an exact polygonal coverage.

Optionally snaps vertices, nodes every boundary, then assigns each face
of the arrangement to exactly one row: overlaps go to the row chosen by
`overlap_rule`, and enclosed gaps narrower than `gap_width` merge into
the neighbor with the longest shared border. Both sides of every
interface come from the same noded linework, so the result is an exact
coverage by construction.
Geographic cleaning handles full-turn boundaries around a pole even when
the inner cap row precedes its surrounding cap. Overlap assignment continues
to follow `overlap_rule`.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `values` | `Geometry, GeometryArray, or iterable of Geometry` | One coverage row or multiple rows (`Polygon` or `MultiPolygon` each). | *required* |
| `grid_size` | `float` | Finite non-negative vertex snapping grid in coordinate space: geographic CRSs use native angular units, projected CRSs use native linear units, and CRS-free inputs use raw coordinate units. `0` preserves input coordinates and disables snapping. Unlike `snap_to_grid(grid_size=...)`, this operation accepts zero. | `0.0` |
| `gap_width` | `float` | Finite non-negative coordinate-space width of gaps to merge (0 keeps gaps). Geographic CRSs use native angular units without conversion to physical units; projected CRSs use native linear units, and CRS-free inputs use raw coordinate units. | `0.0` |
| `overlap_rule` | `str` | Which row keeps a region covered more than once: `'longest_border'`, `'max_area'`, `'min_area'`, or `'min_index'`. Geographic inputs rank rows by ellipsoidal area in square metres and rank shared borders by ellipsoidal arclength in metres along retained chart-straight edges. Projected and CRS-free inputs retain coordinate-space rankings. Cleaning rebuilds faces from one exact partition. Source Z/M ordinates are retained for rows whose emitted nodes have one consistent source value; an unavailable or conflicting axis is dropped for that row. | `'longest_border'` |

Returns:

| Type | Description |
| --- | --- |
| `GeometryArray` | One cleaned `Polygon`/`MultiPolygon` per input row. |

Raises:

| Type | Description |
| --- | --- |
| `GeometryTypeError` | If a row is not a `Polygon` or `MultiPolygon`. |
| `GeometryError` | If `grid_size` or `gap_width` is negative or non-finite. |
| `OverflowError` | If no adjacent binary64 assignment preserves the exact cleaned coverage. |
| `ResourceLimitError` | If the bounded embedding search is exhausted. |
| `InvalidGeometryError` | If `grid_size > 0` and snap-repair cannot converge on a valid grid-aligned result. |
| `CRSMismatchError` | If the rows' CRS or coordinate-epoch metadata differ. |

See Also

[coverage\_is\_valid](https://gometry.monicz.dev/api/toplevel/coverage-polygonal/#gometry.coverage_is_valid "coverage_is_valid") : Test whether a polygonal coverage is already valid.

Examples:

```pycon
>>> import gometry as gm
>>> rows = [gm.box(0, 0, 1.2, 1), gm.box(1, 0, 2, 1)]
>>> gm.coverage_is_valid(rows)
False
>>> cleaned = gm.coverage_clean(rows)
>>> gm.coverage_is_valid(cleaned)
True
```

## coverage\_invalid\_edges

Accepted call forms

```python
coverage_invalid_edges(values: Polygon | MultiPolygon | GeometryArray[Polygon | MultiPolygon] | Iterable[Polygon | MultiPolygon | Buffer | Mapping[str, Any] | SupportsGeoInterface], *, gap_width: float = 0.0) -> GeometryArray[LineString | MultiLineString]
```

```python
coverage_invalid_edges(values: GeometryArray[Polygon | MultiPolygon | None] | Iterable[Polygon | MultiPolygon | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, gap_width: float = 0.0) -> GeometryArray[LineString | MultiLineString | None]
```

Per-row invalid coverage boundary linework.

Each output row merges the row's boundary segments that violate the
coverage contract (overlaps, T-joins, slivers, and — with `gap_width`
— narrow gaps); rows that are clean come back as `LINESTRING EMPTY`.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `values` | `Geometry, GeometryArray, or iterable of Geometry` | One coverage row or multiple rows (`Polygon` or `MultiPolygon` each). | *required* |
| `gap_width` | `float` | Finite non-negative coordinate-space gap width; 0 disables gap detection. Geographic CRSs use native angular units, projected CRSs use native linear units, and CRS-free inputs use raw coordinate units. | `0.0` |

Returns:

| Type | Description |
| --- | --- |
| `GeometryArray` | One `LineString`/`MultiLineString` per input row. |

Raises:

| Type | Description |
| --- | --- |
| `GeometryTypeError` | If a row is not a `Polygon` or `MultiPolygon`. |
| `GeometryError` | If `gap_width` is negative or non-finite. |
| `CRSMismatchError` | If the rows' CRS or coordinate-epoch metadata differ. |

See Also

[coverage\_is\_valid](https://gometry.monicz.dev/api/toplevel/coverage-polygonal/#gometry.coverage_is_valid "coverage_is_valid") : The boolean verdict.

Examples:

```pycon
>>> import gometry as gm
>>> len(gm.coverage_invalid_edges(
...     [gm.box(0, 0, 1, 1), gm.box(0.5, 0, 1.5, 1)]))
2
```

## coverage\_is\_valid

```python
coverage_is_valid(values: Polygon | MultiPolygon | GeometryArray[Polygon | MultiPolygon] | Iterable[Polygon | MultiPolygon | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, gap_width: float = 0.0) -> bool
```

Test whether geometries form a valid polygonal coverage.

A polygonal coverage (parcels, admin boundaries) is a set of polygons
with no interior overlaps whose shared
boundaries use vector-identical linework. Distinct from the DGGS cell
`Coverage` classes.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `values` | `Geometry, GeometryArray, or iterable of Geometry` | One coverage row or multiple rows (`Polygon` or `MultiPolygon` each). | *required* |
| `gap_width` | `float` | Finite non-negative coordinate-space gap width; 0 disables gap detection. Geographic CRSs use native angular units, projected CRSs use native linear units, and CRS-free inputs use raw coordinate units. | `0.0` |

Returns:

| Type | Description |
| --- | --- |
| `bool` | `True` when no row has invalid coverage edges. |

Raises:

| Type | Description |
| --- | --- |
| `GeometryTypeError` | If a row is not a `Polygon` or `MultiPolygon`. |
| `GeometryError` | If `gap_width` is negative or non-finite. |
| `CRSMismatchError` | If the rows' CRS or coordinate-epoch metadata differ. |

See Also

[coverage\_invalid\_edges](https://gometry.monicz.dev/api/toplevel/coverage-polygonal/#gometry.coverage_invalid_edges "coverage_invalid_edges") : The offending linework itself.
[coverage\_clean](https://gometry.monicz.dev/api/toplevel/coverage-polygonal/#gometry.coverage_clean "coverage_clean") : Rebuild an exact coverage from a near-coverage.

Examples:

```pycon
>>> import gometry as gm
>>> grid = gm.GeometryArray([
...     gm.Polygon([(0, 0), (1, 0), (1, 1), (0, 1)]),
...     gm.Polygon([(1, 0), (2, 0), (2, 1), (1, 1)]),
... ])
>>> gm.coverage_is_valid(grid)
True
>>> gm.coverage_is_valid(gm.GeometryArray([
...     gm.Polygon([(0, 0), (1.1, 0), (1.1, 1), (0, 1)]),
...     gm.Polygon([(1, 0), (2, 0), (2, 1), (1, 1)]),
... ]))
False
```

## coverage\_simplify

Accepted call forms

```python
coverage_simplify(values: Polygon | MultiPolygon | GeometryArray[Polygon | MultiPolygon] | Iterable[Polygon | MultiPolygon | Buffer | Mapping[str, Any] | SupportsGeoInterface], tolerance: float, *, method: Literal['vw', 'dp'] = 'vw', simplify_boundary: bool = True) -> GeometryArray[Polygon | MultiPolygon]
```

```python
coverage_simplify(values: GeometryArray[Polygon | MultiPolygon | None] | Iterable[Polygon | MultiPolygon | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], tolerance: float, *, method: Literal['vw', 'dp'] = 'vw', simplify_boundary: bool = True) -> GeometryArray[Polygon | MultiPolygon | None]
```

Simplify a VALID polygonal coverage's boundaries, preserving its
topology.

Shared boundaries are simplified once and spliced into both neighbors,
so the result stays an exact coverage (vector-identical interfaces, no
new crossings — a conservative topology guard rejects any vertex removal
that would intersect other linework or swallow a neighbor). Input must
be a valid coverage; invalid rows raise with repair guidance. For a
near-coverage that needs overlap or gap repair, use `coverage_clean` first.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `values` | `Geometry, GeometryArray, or iterable of Geometry` | One coverage row or multiple rows (`Polygon` or `MultiPolygon` each). | *required* |
| `tolerance` | `float` | Finite non-negative coordinate-space distance-scale tolerance: geographic CRSs use native angular units, projected CRSs use native linear units, and CRS-free inputs use raw coordinate units. Read on the same scale by both methods (the Visvalingam-Whyatt effective area is `tolerance**2 / 2`). | *required* |
| `method` | `('vw', 'dp')` | Importance criterion: `'vw'` is area-based (Visvalingam-Whyatt), `'dp'` is distance-based (Douglas-Peucker). Both run under the same topology guard. For coverage simplification, `'dp'` is a local importance criterion; it does not provide scalar Douglas-Peucker's original-span error contract. | `'vw'` |
| `simplify_boundary` | `bool` | Also simplify exterior (unshared) boundaries; `False` pins them and simplifies only the shared interfaces. | `True` |

Returns:

| Type | Description |
| --- | --- |
| `GeometryArray` | One simplified `Polygon`/`MultiPolygon` per input row. |

Raises:

| Type | Description |
| --- | --- |
| `GeometryTypeError` | If a row is not a `Polygon` or `MultiPolygon`. |
| `GeometryError` | If `tolerance` is negative or non-finite. |
| `CRSMismatchError` | If the rows' CRS or coordinate-epoch metadata differ. |
| `InvalidGeometryError` | If the rows are not a valid polygonal coverage. |

See Also

[Geometry.simplify](https://gometry.monicz.dev/api/geometry/geometry/#gometry.Geometry.simplify "simplify") : Per-geometry simplify (not coverage-topology-preserving).
[coverage\_is\_valid](https://gometry.monicz.dev/api/toplevel/coverage-polygonal/#gometry.coverage_is_valid "coverage_is_valid") : Whether the rows form a valid polygonal coverage.
[coverage\_clean](https://gometry.monicz.dev/api/toplevel/coverage-polygonal/#gometry.coverage_clean "coverage_clean") : Rebuild a near-coverage before simplification.

Examples:

```pycon
>>> import gometry as gm
>>> left = gm.Polygon([(0, 0), (1, 0), (1.05, 0.5), (1, 1), (0, 1)])
>>> right = gm.Polygon([(1, 0), (2, 0), (2, 1), (1, 1), (1.05, 0.5)])
>>> out = gm.coverage_simplify([left, right], 0.5)
>>> out.to_wkt()[0]
'POLYGON ((1 0, 1 1, 0 1, 0 0, 1 0))'
```

## coverage\_union\_all

```python
coverage_union_all(values: Polygon | MultiPolygon | GeometryArray[Polygon | MultiPolygon | None] | Iterable[Polygon | MultiPolygon | Buffer | Mapping[str, Any] | SupportsGeoInterface | None]) -> Polygon | MultiPolygon
```

Union a polygonal *coverage* into one geometry by dissolving shared edges.

A fast specialization of `union_all` for a **valid
coverage** — polygons that tile a region edge-to-edge with no overlaps and
no T-junctions (see `coverage_is_valid`). It
cancels the interior edges shared between adjacent polygons rather than
general noding and classification. On overlapping or badly-noded input it
raises before the specialized dissolve runs; use
`union_all` there.

In a geographic CRS, rows whose raw bounds are unsound at the periodic seam,
a pole, or a non-canonical longitude are dissolved in the exact geographic
topology and drawn as admitted chart-safe pieces. Canonical seam-free and
pole-free rows retain the direct path. The result preserves the shared CRS
and coordinate epoch; polygon order and cyclic ring starts are unspecified.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `values` | `Geometry, GeometryArray, or iterable of Geometry` | One polygonal row or multiple rows of a valid coverage. Missing array rows are skipped. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `Geometry` | A single `Polygon`/`MultiPolygon` covering the merged area. |

Raises:

| Type | Description |
| --- | --- |
| `CRSMismatchError` | If the operands' CRS or coordinate-epoch metadata differ. |
| `InvalidGeometryError` | If `values` is empty, the rows are not a valid coverage, or coordinates are outside their geographic CRS domain. |

See Also

[union\_all](https://gometry.monicz.dev/api/toplevel/overlay-dissolve/#gometry.union_all "union_all") : General multi-geometry union (handles overlaps).
[coverage\_is\_valid](https://gometry.monicz.dev/api/toplevel/coverage-polygonal/#gometry.coverage_is_valid "coverage_is_valid") : Whether the rows form a valid polygonal coverage.

Examples:

```pycon
>>> import gometry as gm
>>> tiles = gm.GeometryArray([gm.box(0, 0, 1, 1), gm.box(1, 0, 2, 1)])
>>> merged = gm.coverage_union_all(tiles)
>>> (merged.geometry_type, round(merged.area, 6))
('Polygon', 2.0)
```