makepad/map2.md

map2 — why the map falls apart when you zoom in, and what's missing to fix it

Analysis of makepad-example-map render quality at high zoom (Amsterdam, z16–17), compared against the osm.org (openstreetmap-carto / Mapnik) reference render of the same area. Screenshot symptoms: roads that change width mid-street, butt-capped stubs ending in the middle of the screen, a canal that breaks and shifts sideways, wobbly/lumpy road edges, dark casing bars crossing junctions and tile seams.

TL;DR: the dataset is not the main problem. The renderer magnifies z14 geometry that was tessellated once, in absolute-Mercator f32 coordinates, with widths, AA, tolerance and layer-ordering all baked in at tile-build time. Almost every visible artifact traces back to one of five root causes below. Two of them are genuinely missing bits in the vector API (round joins, GPU-side stroke width); the other three are map-widget architecture and need no API change at all.

---

1. What the pipeline does today

• Data source: noord-holland-shortbread-1.0.mbtiles — Geofabrik Shortbread 1.0 vector tiles, maxzoom 14 (verified from the metadata table). streets and buildings layers only exist at z14. View zoom goes to 17 (view.rs max_zoom: 17.0), but request_zoom_level() clamps tile requests to z14 (view.rs:1648). So everything past z14 is a 4–8× magnification of z14 tiles.
• Tile build (tile.rs build_tile_buffers_from_body): MVT → fake Overpass JSON → re-projected to absolute web-Mercator world pixels at the tile zoom as f32 (lon_lat_to_world, geometry.rs:817). Strokes are merged per style (merge_stroke_polylines), clipped to tile+8px (ROAD_CLIP_PADDING, tile.rs:27), then tessellated on the CPU (libs/svg/src/tessellate.rs) into two cached GPU buffers per tile: one fill geometry, one stroke geometry. Stroke widths, the 1px AA fringe, the 0.25px flatten tolerance and the dash period are all in tile-zoom world units, fixed forever.
• Draw (view.rs draw_walk): two loops — all tiles' fills, then all tiles' strokes — each tile as one draw call with map_scale = 2^(view_zoom − tile_z) and a shared map_offset, transformed in the vertex shader (DrawMapVector, view.rs:21).

---

2. Why the osm.org reference looks so much better with "the same" data

It's the same OSM source, but not the same render-time inputs:

1. osm-carto re-renders every zoom level from the full database. At z16 it has z16-selected geometry, z16-tuned widths, z16 label sizes. Our z16 is a scaled photograph of a z14 rendering. This is the single biggest difference.
2. Global layer compositing. Mapnik draws all road casings in the map, then all road fills, per style layer, across the whole image. We interleave casing/center per tile (see §3.3), so tiles stamp over each other at seams.
3. Screen-space-constant styling. Carto widths/dashes/halos are defined in output pixels per zoom. Ours are frozen world units that scale with magnification.
4. Full-detail data past z14. Shortbread z14 is already simplified and quantized to a 4096 extent. However: 4096 quanta over a 256-world-px tile is 1/16 world px = 0.5 screen px at z17. The data would support a crisp z17 render — the artifacts we see (2–8 px scale) are renderer-made, not data-made.

So "the dataset is supposedly the same" is true enough that it's not the excuse: the ceiling imposed by shortbread-z14 at z17 is ~0.5px; we're leaving ~10× that on the floor.

---

3. Root causes, ranked by visual damage

3.1 f32 absolute-Mercator coordinates (precision) — the lumpy edges & offset seams

Geometry is stored as world pixels at tile zoom. Amsterdam at z14: x_world ≈ 0.5136 × 4,194,304 ≈ 2,154,000, which sits in [2^21, 2^22) → f32 ULP = 0.25 world px. Every projected vertex is snapped to a 0.25px grid before tessellation; at z17 (×8) that's a 2 screen px quantization on every vertex. All the join/normal math in the tessellator then runs on these coarse inputs (short segments get visibly wrong normals — extra wobble in extrusions).

It gets worse in the shader (view.rs:28): pos * map_scale + map_offset in f32. At z17, pos * scale ≈ 1.7e7 ∈ [2^24, 2^25) → ULP = 2 screen px on both terms of a catastrophic cancellation. Net: final vertex positions carry up to ~2–4 px of position-dependent error, and map_offset (same magnitude) rounds while panning → pan jitter and per-vertex "shimmer" of edges.

This alone explains the wobbly Nassaukade edges and most of the "doesn't fit together" impression. It is the classic web-mercator-in-float problem; every GPU map renderer (MapLibre etc.) solves it with tile-local coordinates (0..256 — exact in f32) plus a per-tile translation computed in f64 on the CPU. Our shader already takes per-draw-call map_scale/map_offset uniforms — the fix is purely to make geometry tile-local and compute offset + tile_origin × scale in f64 per tile. No vector-API change needed.

3.2 Overzoom: everything styled in baked tile-zoom units

Because tiles stop at z14 and buffers are cached per tile only (never per view zoom), at z17 all of these are magnified ×8:

• Stroke widths (view.rs:139 style table, applied at tile.rs build time): residential casing 2.0 world px → 16 screen px. Roads look bloated and toy-like.
• AA fringes: strokes are expanded by aa/2 = 0.5 world px per side (tessellate.rs stroke, hw = w/2 + aa/2) → roads are drawn 8 screen px wider than styled at z17 (the fragment AA itself stays crisp thanks to fwidth-based coverage in draw_vector.rs:251 — the edge position is what's wrong, not the sharpness).
• Fill fringe bloat: fills push their AA fringe outward by woff = 0.5 world px (tessellate.rs fill, non-GPU-expand path) → every polygon (water, buildings, landuse) grows ~4 screen px at z17. Small courtyards close up; unrelated fills touch.
• Flatten tolerance DEFAULT_FLATTEN_TOLERANCE = 0.25 world px (geometry.rs:12) → 2px chords on curves.
• Vertex thinning: project_way_points_with_nodes drops any point closer than 0.5 world px to the previous one (tile.rs:580, < 0.25 squared) → up to 4 screen px of curve detail discarded at z17.
• Dash periods (rail shape_id 10, tunnels 11): v_stroke_dist is baked in world units, so dashes stretch ×8 (view.rs get_stroke_mask / draw_vector.rs dash() — the shader never sees map_scale for distances).
• Clip padding: ROAD_CLIP_PADDING = 8 world px becomes a 64-screen-px overlap strip along every tile edge at z17, which supersizes the seam problem below.

3.3 Per-tile painter's order breaks casing/center layering at seams

Within a tile, tile.rs draws correctly: pass 1 all casings, pass 2 all centers (tile.rs:474–548). But both passes live in one geometry buffer per tile, and tiles are drawn one draw call after another (view.rs:517). In the ±8 world px overlap strip that both neighbors tessellate, the later tile's casing paints on top of the earlier tile's road center — a casing-colored plug across every road at every tile boundary, 64 screen px long at z17. The same mechanism produces the dark bars across the canal (waterway casing) in the screenshot. The ROAD_CENTER_OVERLAY_* constants (tile.rs:29–32) are an existing partial hack around the intra-tile version of this; they can't help across tiles.

Related: merged stroke chains end with butt caps at junctions where degree ≠ 2 or the style changes (merge_stroke_polylines only chains degree-2 endpoints), so T-junctions get notches and overlapping wedges, magnified ×8.

3.4 Mixed-zoom fallback tiles drawn side by side

fill_draw_tile_keys (view.rs:1100) substitutes any ready ancestor/descendant for a missing tile and draws it in the same frame with a different map_scale. A z13 parent next to a z14 tile has different simplification, ×2 widths, and different f32 rounding → the visibly offset canal segment (Bloemgracht) and the Rozengracht width jump, with duplicate labels at two sizes. There is no fade, no "children fully cover parent → skip parent" logic, and stale parents can persist because eviction is soft (tiles.len() > 640).

3.5 Water drawn twice, cased

Shortbread ships Amsterdam canals as water_polygons and water_lines. We fill the polygon, then stroke the centerline on top with a dark casing (MapWaterwayRule canal: casing #4a8fc3 1.5 → 12 screen px at z17). Carto keeps waterway centerlines invisible where a water polygon exists (or same-color, no casing). The tube-on-polygon look plus its butt caps at tile seams is a large part of the "canals look broken" impression.

---

4. Actual missing bits in the vector API

The user hypothesis ("missing bits in the vector API") is partially right. In libs/svg/src/tessellate.rs / draw/src/vector / DrawVector:

1. LineJoin::Round is not implemented. calculate_joins flags Round the same as Bevel (tessellate.rs:333–338) and stroke() only ever emits emit_bevel_join (tessellate.rs:419). The NanoVG roundJoin arc emission was never ported. Every bend on a road/canal is a bevel; magnified, that reads as faceted/lumpy.
2. No inner-bevel correction (NanoVG chooseBevel for PT_INNERBEVEL). emit_bevel_join extrudes the inner side with raw segment normals (tessellate.rs:704–754), so sharp angles fold geometry over itself. Invisible with opaque strokes at 1×, visible as edge lumps under magnification.
3. No GPU-side stroke width ("gpu_expand_stroke"). Fills have a gpu_expand_fill mode that anchors vertices on the edge and encodes the outward normal for shader-side expansion (tessellate.rs:875–955, fill_gpu() in draw_vector.rs). Strokes have no equivalent: width and AA fringe are baked into vertex positions. This is the API bit that would make zoom-independent road widths possible without re-tessellating — emit centerline-anchored vertices + normal + side, resolve width_px and fringe in the vertex shader from a uniform. (v_stroke_dist/u-side encoding already exists, so the vertex layout barely changes.)
4. Single cap style per path. Map rendering needs butt at tile-clip cuts and round at true dead ends, ideally per polyline end. The API takes one LineCap for everything.
5. No draw-layer separation in accumulated geometry. append_tessellated_geometry flattens everything into one interleaved buffer; there's no way to draw "index range of pass 1 across N geometries, then pass 2". (Workaround without API change: build separate casing/center Geometry objects per tile — doubles buffer count but works today. Nicer API: per-layer index ranges within one buffer, drawable as sub-range draw calls.)
6. Dash/dot distances are geometry-space. dash()/dots() use v_stroke_dist raw (draw_vector.rs:124–139); a scaled consumer like DrawMapVector needs v_stroke_dist × map_scale so patterns are stable in screen px. One-line fix in the map shader, but worth a note in the API docs.
7. Not missing, but unused by the map: cur_tolerance / cur_fill_aa / cur_stroke_aa hooks on DrawVector exist precisely to bake fringes/tolerance for a known display scale — the tile builder ignores them and uses fixed world-unit constants.

Explicitly not API problems: the f32 precision issue (§3.1 — fixable with tile-local coords + existing per-draw uniforms), the per-tile layer ordering (§3.3 — fixable with two buffers), and overzoom styling (§3.2 — fixable with re-tessellation per zoom bucket even without item 3).

---

5. Recommended plan (ordered by impact ÷ effort)

1. Tile-local coordinates. Tessellate everything relative to the tile origin (subtract tile_key.{x,y} × 256 before building paths; also do the projection math in f64 until that subtraction). In draw_walk, compute each tile's map_offset in f64 as global_offset + tile_origin × scale, cast at the end. Fixes §3.1 completely — both CPU-side tessellation precision and shader cancellation — with zero API changes. Biggest single win at high zoom.
2. Split stroke buffers into casing + center geometries per tile; draw three loops (fills → all casings → all centers). Kills the seam plugs and junction wedges of §3.3, and makes the ROAD_CENTER_OVERLAY_* hack removable.
3. Re-tessellate per view-zoom bucket (key tile cache by (tile, render_zoom), build in the existing worker pool): widths from a per-zoom ramp (carto-style ~×1.6/zoom), aa/tolerance/thinning thresholds divided by the render scale so they stay ~1 device px. Alternatively (more work, better): implement gpu_expand_stroke (§4.3) and drive width per frame from a uniform — then one tessellation serves all zooms and continuous zoom is perfectly crisp.
4. Overzoom tile subdivision: synthesize z15–17 tiles by clipping the z14 data (the MVT decode already yields per-feature geometry), so clip padding, world-unit constants and per-tile precision keep their intended meaning at every rendered zoom. Combines naturally with (3).
5. Tessellator quality: port NanoVG round joins + chooseBevel inner-bevel; use Round caps for true dead ends, Butt only at clip cuts (needs §4.4 or a per-part cap flag in append_stroke_pass).
6. Water: suppress water_lines casing (or the whole stroke) where water_polygons cover the same area at z12+; at minimum draw waterway strokes under polygon fills or in the polygon color.
7. Mixed-zoom fallback hygiene (§3.4): skip a parent when all four children are ready, evict replaced parents immediately, optional 100ms fade.
8. Style/label polish toward the reference: per-zoom style curves (min-zoom per road class, width ramps), label font size scaling with zoom + halo (currently fixed font_scale 0.92, no halo — view.rs:1444), building fill contrast + outline, dashed footpath/cycleway styling.

Verification

Use the headless render harness (MAKEPAD=headless render-to-png) with a fixture at a fixed center/zoom over cached tiles: render z14 (native) and z17 (overzoom) crops and eyeball/golden-diff them per step above. Step 1 should visibly remove edge wobble; step 2 removes seam bars; step 3 brings road weights in line with the osm-carto reference.