Repairing Unclosed Ways and Broken Multipolygons Jump to heading#

Take the member ways of an OSM multipolygon relation — some open, some fragmented across several ways, some digitised a nanodegree short of closing — and assemble them into valid, correctly nested Polygon geometry with the right outer/inner roles and winding.

Prerequisites Jump to heading#

• shapely ≥ 2.0 (pip install "shapely>=2.0") for make_valid, polygonize, and orient.
• Python 3.10+ for the union types and structural code below.
• Member ways already resolved to coordinate sequences, with each member’s role (outer/inner/empty) available — the reconstruction covered in Understanding OSM Multipolygon Relations for GIS.
• A closing tolerance in degrees appropriate to your data (a few 1e-7 for near-miss snapping).
• The parent Geometry Validation & Repair guide’s validity checks available for the post-repair gate.

Conceptual minimum Jump to heading#

An OSM multipolygon relation does not store rings — it stores member ways, and a ring often spans several of them. A large lake boundary might be split into four ways that only form a closed loop when chained end-to-end; a building might be a single closed way used directly as an outer ring. Three things routinely go wrong. A way meant to close on itself ends a hair short, because the editor never snapped the final node to the first — the endpoints differ by a nanodegree, so a Polygon constructor rejects it. Fragmented members fail to chain because their shared endpoints do not match exactly, or because a member is reversed relative to its neighbour. And the outer/inner role tags may be missing or wrong, so a ring that should punch a hole is treated as a second outer, or vice versa.

Repair is therefore a pipeline: chain members into rings by matching endpoints, close each ring by snapping near-miss endpoints, classify rings as outer or inner by containment rather than trusting the role tags blindly, and orient each ring to the right-hand-rule winding that the OGC Simple Features model and GIS engines expect — exterior counter-clockwise, holes clockwise. Only then does make_valid get the last word, resolving any residual self-touch. This sits under Geometry Validation & Repair, which frames when to attempt this repair versus quarantine a relation whose members simply do not form coherent rings.

Runnable solution Jump to heading#

The module chains member ways into rings, closes near-miss rings by snapping, classifies rings as outer or inner by containment, orients them, and validates the assembled polygon. It uses Shapely 2.x, Python 3.10+ type hints, and the project logger convention.

from __future__ import annotations

import logging
from dataclasses import dataclass

from shapely import make_valid
from shapely.geometry import LinearRing, MultiPolygon, Point, Polygon
from shapely.geometry.polygon import orient

logger = logging.getLogger("osm.geometry.repair_multipolygon")

Coord = tuple[float, float]


@dataclass
class Member:
    role: str                 # "outer", "inner", or ""
    coords: list[Coord]       # resolved node coordinates in way order


def _endpoints_match(a: Coord, b: Coord, tol: float) -> bool:
    return abs(a[0] - b[0]) <= tol and abs(a[1] - b[1]) <= tol


def chain_members(members: list[Member], tol: float) -> list[list[Coord]]:
    """Chain member ways into ordered rings by matching shared endpoints."""
    pending = [list(m.coords) for m in members if len(m.coords) >= 2]
    rings: list[list[Coord]] = []
    while pending:
        ring = pending.pop(0)
        extended = True
        while extended and not _endpoints_match(ring[0], ring[-1], tol):
            extended = False
            for i, seg in enumerate(pending):
                if _endpoints_match(ring[-1], seg[0], tol):
                    ring.extend(seg[1:]); pending.pop(i); extended = True; break
                if _endpoints_match(ring[-1], seg[-1], tol):
                    ring.extend(reversed(seg[:-1])); pending.pop(i); extended = True; break
        rings.append(ring)
    return rings


def close_ring(ring: list[Coord], tol: float) -> list[Coord] | None:
    """Snap a near-miss ring closed; return None if the gap exceeds tolerance."""
    if len(ring) < 4:
        return None
    if ring[0] == ring[-1]:
        return ring
    if _endpoints_match(ring[0], ring[-1], tol):
        return [*ring[:-1], ring[0]]      # snap last onto first
    logger.warning("ring gap %.9f exceeds tolerance; cannot close", _gap(ring))
    return None


def _gap(ring: list[Coord]) -> float:
    return Point(ring[0]).distance(Point(ring[-1]))


def assemble(members: list[Member], tol: float = 5e-7) -> Polygon | MultiPolygon | None:
    """Assemble multipolygon members into a valid, correctly nested polygon."""
    closed: list[LinearRing] = []
    for ring in chain_members(members, tol):
        snapped = close_ring(ring, tol)
        if snapped is None:
            continue                      # send to quarantine upstream
        try:
            closed.append(LinearRing(snapped))
        except ValueError as exc:
            logger.warning("invalid ring discarded: %s", exc)

    if not closed:
        return None

    # Classify by containment: the largest ring not inside another is outer.
    polys = [Polygon(r) for r in closed]
    outers = [p for p in polys if not any(o.contains(p) and o is not p for o in polys)]
    result_parts: list[Polygon] = []
    for outer in outers:
        holes = [p.exterior.coords for p in polys if outer.contains(p) and p is not outer]
        poly = orient(Polygon(outer.exterior.coords, holes), sign=1.0)  # CCW shell
        result_parts.append(poly)

    assembled = result_parts[0] if len(result_parts) == 1 else MultiPolygon(result_parts)
    fixed = make_valid(assembled)
    if not fixed.is_valid or fixed.is_empty:
        logger.error("assembled multipolygon failed final validity gate")
        return None
    return fixed

Step-by-step walkthrough Jump to heading#

1. Members carry their role and coordinates — the Member dataclass keeps the OSM role tag beside the resolved geometry, but note the role is a hint, not the source of truth for nesting.
2. Chaining tolerates reversal — chain_members grows a ring by appending any member whose endpoint matches the ring’s tail, reversing the member when only its far end matches. This handles the common case where members were digitised in inconsistent directions.
3. Endpoint matching uses a tolerance — _endpoints_match compares within tol rather than requiring exact equality, because shared nodes across ways can differ by a floating-point epsilon after coordinate reconstruction.
4. Closing snaps only sub-tolerance gaps — close_ring closes a ring by replacing its last coordinate with its first when the gap is within tolerance, and returns None (a quarantine signal) when the gap is too wide to close honestly.
5. Degenerate rings are rejected early — a ring with fewer than four coordinates cannot bound an area and is dropped before it reaches the LinearRing constructor.
6. Nesting comes from containment, not tags — outers are the rings not contained by any other ring, and each outer’s holes are the rings it contains. This is what fixes a mislabelled inner/outer role: geometry decides.
7. Orientation is set explicitly — orient(..., sign=1.0) forces the exterior counter-clockwise and holes clockwise, the right-hand-rule winding GIS consumers assume, regardless of how the source ways wound.
8. make_valid is the final gate — after assembly, make_valid resolves any residual self-touch between a hole and its shell, and the validity check rejects the result rather than emitting a silently broken polygon.

Verification Jump to heading#

• Closed and valid. assemble(members).is_valid must be True, and is_empty must be False.
• Holes are present. For a relation with inner members, the result’s interiors (or each part’s interiors) must be non-empty; a lost hole means containment classification failed.
• Winding is correct. assembled.exterior.is_ccw must be True and each interior ring’s is_ccw must be False.
• Area is plausible. Compare the assembled area against a rough expected value; a hole treated as a second outer inflates the area, a missing hole also inflates it.
• Quarantine fires on a wide gap. Feed a member set with a deliberately large end-to-end gap and confirm assemble logs the tolerance warning and returns None rather than a torn ring.

Common errors and fixes Jump to heading#

Specification reference Jump to heading#

An OSM multipolygon relation carries member ways with outer and inner roles; the ways must be assembled into closed rings, and a single ring may be split across several member ways that share end nodes. The authoritative rules for ring assembly, role semantics, and the requirement that inner rings lie within outer rings are documented on the OSM Wiki at Relation:multipolygon. Ring closure and validity follow the OGC Simple Features polygon rules that Shapely’s make_valid enforces.

Frequently Asked Questions Jump to heading#

Related Jump to heading#

• Geometry Validation & Repair — the parent guide framing when to repair versus quarantine and the full defect taxonomy.
• Detecting Self-Intersecting OSM Polygons with Shapely — the sibling detection pass that flags the crossings this repair may resolve.
• Understanding OSM Multipolygon Relations for GIS — the relation model and role semantics behind member assembly.
• Error Handling in Large OSM Extracts — where relations that will not assemble are quarantined.
• OSM Data Quality & Validation — the quality section this repair step belongs to.

Up one level: Geometry Validation & Repair.