Topology and cleaning

Shapefile and GeoJSON are non-topological formats — they don't record the spatial relationships between adjacent polygons or intersecting polylines. Each polygon is just a list of coordinates; whether two polygons share an edge has to be detected.

Mapshaper detects topology on import by identifying coordinates that are exactly shared between features. This is what makes operations like simplification, dissolving and clipping work correctly: when two polygons share an edge, the shared path (or "arc") is stored once and edited once.

But coordinates that "should be" identical often aren't. Source datasets routinely contain misalignments (tiny gaps or overlaps between adjacent polygons) that defeat exact-match topology detection. The result is that what looks like a clean boundary turns into duplicated, slightly-offset arcs — and simplification, dissolving and clipping all start to misbehave.

Snapping

The simplest fix is to ask Mapshaper to snap nearby vertices together at import time.

In the command line, pass the snap flag to -i:

mapshaper countries.shp snap -dissolve CONTINENT -o continents.shp

In the web app, tick "snap vertices" in the import dialog (open the import options with the with advanced options checkbox).

By default, snapping uses an automatic threshold of about 0.0025× the average segment length, which is designed to catch misalignments caused by floating-point rounding. To set an explicit snapping distance, use snap-interval=:

mapshaper countries.shp snap-interval=0.0001 -o cleaned.shp

Cleaning

Snapping handles slightly offset pairs of vertices, but doesn't help much when adjacent polygons have small overlapping regions or gaps along their shared boundaries. The -clean command repairs these by recomputing the polygon mosaic and snapping geometry that's nearly identical:

mapshaper countries.shp -clean -o cleaned.shp

-clean accepts a gap-fill-area= option to control how aggressively gaps are filled, and a sliver-control= setting for handling sliver polygons. -dissolve runs an equivalent repair by default, so explicitly running -clean is mainly useful when you want clean output without dissolving anything.

In the web app, -clean runs from the Console the same way as on the CLI — the leading - is optional, e.g. just clean gap-fill-area=100.

Dissolving with topology repair

-dissolve repairs topology automatically. To skip the repair pass (faster, but only safe when you trust the input topology), pass no-repair — Mapshaper will then warn if it detects segment intersections in the input.

mapshaper counties.shp -dissolve STATE_FIPS -o states.shp

Detecting line intersections

The web app can highlight self-intersections in your data: open the Display panel and tick "detect line intersections". Intersections often indicate either a topology error in the source data or self-intersections introduced by simplification — the Repair button at the top-left of the map attempts to fix the latter.

On the command line, -clean and -dissolve both detect and fix intersections.

Notes on common sources of topology errors

A few patterns to watch out for:

• .shp files exported from older GIS tools. Some pipelines round coordinates inconsistently between adjacent features, producing systematic misalignments. Importing with snap is usually enough.
• Older versions of ArcGIS's dissolve tool have been observed to produce topology errors when dissolving a Shapefile that hasn't first been added to a Geodatabase. If you're starting from such output, run it through mapshaper input.shp -clean -o cleaned.shp to repair before further processing.