Coverage (polygonal)¶

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

coverage_clean ¶

Accepted call forms

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]

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 : Test whether a polygonal coverage is already valid.

Examples:

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

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]

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 : The boolean verdict.

Examples:

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

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 : The offending linework itself. coverage_clean : Rebuild an exact coverage from a near-coverage.

Examples:

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

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]

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 : Per-geometry simplify (not coverage-topology-preserving). coverage_is_valid : Whether the rows form a valid polygonal coverage. coverage_clean : Rebuild a near-coverage before simplification.

Examples:

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

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 : General multi-geometry union (handles overlaps). coverage_is_valid : Whether the rows form a valid polygonal coverage.

Examples:

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