Tuning Simplification with the Detail Flag

--detail sets the integer coordinate grid inside every tile — extent equals 2^detail, so the default 12 gives the familiar 4096-unit grid — while --simplification scales how aggressively Douglas-Peucker removes vertices at zooms below the maximum; lowering either one yields smaller tiles and coarser geometry, and the craft is choosing values that shed bytes without letting shared polygon borders drift apart.

When to Use This

Detail and simplification are per-build resolution knobs, not per-zoom ones, so tune them against the character of the layer:

• Size-constrained low-zoom base layers (z0–z8). Coarse geometry is invisible at these scales. A higher --simplification (say 10) and, for extreme cases, a reduced --low-detail shrink tiles hard with no perceptible fidelity loss.
• Full-detail high-zoom layers (z12–z15). Keep --detail=12 and a gentle --simplification (default 1) so streets, parcel corners, and building footprints stay sharp where users zoom in to read them.
• Adjacent-polygon coverages (land-cover, admin units, cadastre). Any simplification must be topology-aware; enable --detect-shared-borders so neighbouring rings collapse the same vertices and no slivers open along the seam.
• Pre-simplified input. If you already reduced vertices in Shapely upstream, disable Tippecanoe’s pass with --no-simplification (or -S0-equivalent behaviour) rather than double-simplifying.

Specification Detail

The core relationship is extent = 2^detail. At --detail=12 a tile is a 4096×4096 integer grid, which quantizes to roughly a quarter-pixel at 256-pixel display tiles — fine enough that further precision is wasted bytes. Drop to --detail=11 and the grid halves to 2048, cutting coordinate storage and often 10–20% of tile bytes, at the cost of visibly coarser geometry at high zoom. --minimum-detail is the safety floor: when even the size-shedding passes cannot fit a tile, Tippecanoe lowers detail toward this value as a last resort before dropping features.

Production Command

A build that keeps full detail at the maximum zoom, simplifies harder at intermediate zooms, and protects polygon adjacency:

tippecanoe \
  --output=admin.pmtiles \
  --layer=admin \
  --minimum-zoom=3 \
  --maximum-zoom=12 \
  --detail=12 \
  --low-detail=11 \
  --simplification=4 \
  --detect-shared-borders \
  --no-simplification-of-shared-nodes \
  --coalesce-smallest-as-needed \
  --force \
  admin_4326.geojson

Here --detail=12 preserves the full grid at z12 (the maximum, which is never internally simplified), while --low-detail=11 and --simplification=4 thin the z3–z11 tiles that carry the bulk of the archive. Verify that fidelity and size landed where intended:

# Byte size of a representative low-zoom tile
tippecanoe-decode admin.pmtiles 5 16 11 | wc -c

# Vertex count of one feature at the max zoom (should stay high)
tippecanoe-decode admin.pmtiles 12 2048 1361 \
  | python3 -c "import sys,json; d=json.load(sys.stdin); \
    print(sum(len(f['geometry']['coordinates'][0]) for f in d['admin']['features'][:1]))"

Interaction Effects

With drop and coalesce. Detail and simplification reduce vertices per feature; the drop and coalesce passes reduce the number of features. They are the two levers for the same 500 KB budget, and they fire in a defined order — Tippecanoe simplifies first, then sheds features, then as a final resort lowers detail toward --minimum-detail. If a vertex-heavy coastline layer overflows, raise --simplification before touching the flags in controlling tile size with drop and coalesce flags; dropping whole coastline segments looks far worse than smoothing them.

With the MVT extent. --detail is the tile extent that the protobuf structure encodes — the extent field written into every layer header. Understanding how those quantized integer coordinates are stored and later reprojected to screen space is covered in MVT encoding internals; a lower --detail writes a smaller extent and therefore fewer bytes per coordinate delta in the encoded geometry.

With per-zoom bounds. Because only zooms below --maximum-zoom are simplified, the -z you choose determines how much of the pyramid --simplification even touches. The choice of algorithm underneath that simplification — perpendicular-distance versus effective-area removal — is the subject of Visvalingam versus Douglas-Peucker in tile generation; --simplification scales whichever pass is active.

Performance Impact

Directionally, --simplification is the highest-leverage byte lever on winding line and polygon data, and --detail is the blunt fallback that trades geometric precision uniformly. On a national hydrography layer, raising --simplification from 1 to 5 typically cuts low-zoom tile bytes by a third while high-zoom tiles are untouched; --no-line-simplification on the same data can nearly double archive size and is almost never the right default.

Common Mistakes

1. Over-simplifying until polygons detach at shared borders

A high --simplification without --detect-shared-borders lets two adjacent polygons collapse different vertices along the edge they share, tearing a thin gap between them that renders as a hairline of background colour.

Symptom: slivers or seams appear between neighbouring fills at low and mid zooms; decoding shows the shared edge has different coordinates in each feature.

Fix: keep the simplification but make the edge treatment topology-aware.

tippecanoe --simplification=5 --detect-shared-borders \
  --no-simplification-of-shared-nodes \
  --output=admin.pmtiles --force admin_4326.geojson

2. Detail too low, causing coordinate snapping and gaps

Dropping --detail to 9 or 10 on a high-zoom layer snaps every coordinate to a coarse 512- or 1024-unit grid; nearby vertices collapse onto the same integer point and small features degenerate or vanish.

Symptom: buildings and parcels look jagged or lose corners at z13+; distinct vertices land on identical tile coordinates when decoded.

Fix: restore the full grid at the maximum zoom and push size savings to the lower zooms with --low-detail instead.

tippecanoe --detail=12 --low-detail=11 --simplification=3 \
  --maximum-zoom=14 --output=parcels.pmtiles --force parcels_4326.geojson

3. --no-line-simplification bloating tiles

Reaching for --no-line-simplification to “keep every detail” retains every source vertex at every zoom, so low-zoom tiles carry millions of coordinates that no display pixel can resolve.

Symptom: low-zoom tiles balloon past 500 KB and trigger dropping warnings; build time climbs sharply; the map is no crisper for it.

Fix: remove the flag and let scaled simplification thin the lower zooms while the maximum zoom stays full-fidelity.

tippecanoe --simplification=2 --maximum-zoom=14 \
  --output=roads.pmtiles --force roads_4326.geojson

Parent: Geometry Simplification Algorithms

Related

• Controlling Tile Size with Drop and Coalesce Flags — the feature-count lever that fires after simplification when a tile still overflows the budget.
• Visvalingam vs Douglas-Peucker in Tile Generation — the algorithm choice that --simplification scales, with fidelity benchmarks per feature class.
• MVT Encoding Internals — how the --detail extent becomes the quantized integer coordinate grid written into the protobuf tile.