mapgen

Overview ¶

Command mapgen converts the vendored world-atlas TopoJSON into Go source.

This is the generate-time half of D63. The fetched TopoJSON is a *vendored* file — pinned, checksummed, verified by `make verify-assets`. What this command writes is *generated output*, committed the way sqlc's dbgen is committed, and re-running it on an unchanged tree must produce no diff. That is the property `make sqlc` is held to and this is held to the same one.

Conversion happens here and never at request time. The server renders inline SVG from Go data it already holds, so `ui` stays stdlib-only, nothing parses TopoJSON on a dashboard request, and the CSP is untouched.

The projection ¶

**Equirectangular (plate carrée)**, named rather than left implicit, because a choropleth's shapes are an argument about the world and an unnamed projection is an argument nobody can check. Longitude maps linearly to x and latitude linearly to y, at one uniform scale in both axes.

It is the honest choice for this particular chart. The map is read as a lookup table — "which countries clicked this link" — rather than for area or distance, and equirectangular is the only projection where a reader can point at a pixel and name its coordinates. Web Mercator would have made Greenland argue with Africa about a number neither of them is displaying.

Latitude is clipped to [-58, 84] and Antarctica is dropped. 84°N is where the northernmost land ends (Greenland reaches 83.6°N); -58° is south of Cape Horn at -55.9°. The band below that is Antarctica and empty ocean, and in an equirectangular frame it is a third of the height for a landmass that has never produced a click. Clipping is a clamp, not a cut: no shape outside the dropped continent reaches either bound, so nothing is truncated.

Winding order and the antimeridian ¶

TopoJSON follows the shapefile convention — exterior rings clockwise, holes counter-clockwise — and SVG's default `nonzero` fill rule would need that to be right in the emitted path or Lesotho would fill in solid inside South Africa. Rather than depend on upstream winding surviving arc reversal, every country is emitted as one path rendered with **fill-rule="evenodd"**, under which a ring inside another ring is a hole whichever way round it is wound. The template carries the attribute; geo.FillRule is where it comes from.

The antimeridian needs no special handling *and that is checked rather than assumed*: Natural Earth cuts its geometry at ±180 already, so no ring wraps. The generator fails if any decoded coordinate lands outside the sphere, which is what a wrapped ring would look like — a country stretched across the whole frame is the failure this catches before it is committed. Russia and Fiji do touch both frame edges, in separate rings, which is the cut working rather than a wrap.

Why the paths are relative ¶

One absolute M per subpath and relative l steps after it. At 110m resolution almost every step is under one unit, so "l.4,-.3" replaces "L643.8,165.9" and both the generated file and the markup on the wire shrink by about a third: measured, 120,457 to 81,312 bytes in the file, and a rendered link page from 213,940 to 174,792 bytes. The map is still ~86 KB of inline SVG on every view of a link that has geography, and nothing compresses it on the way out — that cost is stated in docs/usage.md rather than hidden. Deltas are computed between coordinates already quantized to the emitted precision, so the encoding is exact rather than merely close: there is no accumulating error to drift.