nordisk/facett

facett-map — crate card

Reverse-engineered (from source — verify, don't trust the name)

• One-line pitch: A geo viewer — a (lon,lat) point layer plus a Web-Mercator vector basemap (line ways / filled silhouettes), CPU-painted with an optional wgpu GPU kernel ported from katana-osm's osm-viewer.

• Does: MapView plots points + Ways (roads/coastlines/water/rings, WayKind/WayStyle/Lod/classify) with mercator() projection. Two render paths behind one ui(): a default CPU painter (always available, headless-testable, never panics) and, behind feature wgpu, a GpuMapRenderer/MapPaintCallback upload-once compute-cull + draw_indirect pipeline (cull.wgsl/draw.wgsl) plus an L0 SDF points lane (l0_points) routed through facett-core's shared GpuSdfRenderer. Also index, project, style, tessellate modules. Graceful: no ways → just points; a host with no wgpu still gets a real basemap.

• Palette (style): MapPalette carries one colour per feature class (land/water/green/building/coast + road tiers + casing). Two sources: from_theme (re-themeable) and cartographic(day) — a fixed concrete-hex preset (light paper / dark skade basemap). classify is a thin wrapper over the palette-driven classify_with(tags,&pal) (one tag-branch path, no twinning); PaletteMode {Theme, CartographicDay, CartographicNight} is the shared selector, MapIndex::recolor / MapPalette::recolor_way reskin a built way set at runtime keyed on kind+width (geometry untouched, ≤1px). Way::from_lonlat_with builds a set directly in a preset.

• Line width (style) — ONE formula, both lanes (studied from deck.gl): line_width_scale(zoom) + line_width_px(style_width, zoom) resolve a way's on-screen width as deck.gl's PathLayer does — clamp(width × widthScale, widthMinPixels, widthMaxPixels) (LINE_WIDTH_MIN_PX 1.0, LINE_WIDTH_MAX_PX 24.0, scale ramp clamped [0.5, 3.0] around LINE_WIDTH_ZOOM_REF 50 000). The GPU line lane applies it in the vertex shader every frame from a width_scale uniform (the vertex bake carries the RAW themed width and is zoom-independent), and the CPU basemap painter calls the same functions — so the two can never draw the same road at different widths. Guarded by line_width_is_pixel_clamped_and_shared_by_both_lanes (facett-demo).

• Dashes (style) — ONE law, both lanes (HO-T3): a WayKind::Rail core is cut along the way's arc length at dash_period_px(w_px) = DASH_PERIOD_RATIO (4) × w_px, DASH_DUTY (0.5) lit, the gaps showing the casing under it — the Garmin rail. WayStyle::dashed() is the gate (roads: off). The GPU lane bakes the arc length ONCE per vertex (never per frame) into LineVertex::col.a under a dash flag in half_px's sign — the vertex stays 48 B — and line.wgsl's fill pass discards the gaps; the CPU painter walks the same arc length (layer::dash_polyline) and strokes one Shape::line per lit run over the same whole casing — not epaint's dashed_line_many, whose per-segment line_segments are pixel-rounded to nothing on a dense polyline at a wide camera. Guarded on real pixels by tests/rail_dash_pixels.rs (horizontal and 45° rails carry the same dash count; a pan does not crawl; a road stays solid; the WGSL constants equal the Rust ones).

• What deck.gl (Uber's WebGL map lib) does that we did not — read from the bundled PathLayer/ScatterplotLayer shader source, and what we adopted:

  1. Pixel-clamped width, resolved per frame. deck.gl: vec2 widthPixels = vec2(clamp(project_size_to_pixel(instanceStrokeWidths * path.widthScale, path.widthUnits), path.widthMinPixels, path.widthMaxPixels) / 2.0); — a road never vanishes when zoomed out nor bloats when zoomed in, and every renderer of the same data agrees. Ours disagreed: the CPU painter scaled style.width by a zoom factor in [0.5, 3.0] while the GPU baked style.width × 1.0 once into the vertex buffer (a constant that could never respond to zoom) — the same road drawn 2–3× apart depending on zoom, which reads as "the land and the lines are at two different scales". ADOPTED (see above).
  2. Half-pixel smoothstep AA. deck.gl's shared primitive is const float SMOOTH_EDGE_RADIUS = 0.5; float smoothedge(float edge, float x) { return smoothstep(edge - SMOOTH_EDGE_RADIUS, edge + SMOOTH_EDGE_RADIUS, x); }. Ours feathered with a linear ramp over a whole pixel, which is why our roads read softer. ADOPTED in line.wgsl (smoothstep(-r, r, edge_px - r), LINE_FEATHER_PX 0.5-style radius).
  3. Miter limit. deck.gl's default miterLimit is 4 — ours already matched (MITER_LIMIT = 4.0). deck.gl additionally limits the inner corner by segment length (miterSize = min(miterSize, max(lenA, lenB) / cosHalfA) when cornerPosition < 0), which we do not yet do; the remaining artefact is inner-corner overshoot on switchbacks with segments shorter than the line width. NOT adopted (bounded by our 24 px ceiling; noted as the next gap).
  4. Rounded joins/caps (jointRounded/capRounded, both default false in deck.gl) — we are miter/bevel only, matching deck.gl's defaults. Not a gap at default settings.
  5. PathLayer AA is MSAA + discard, not analytic — its fragment shader only discards outside the joint (if (vJointType > 0.5 && length(vCornerOffset) > 1.0) discard;). Our SDF-feathered edge is arguably better than deck.gl's path AA; keep it.
  6. High-zoom precision: deck.gl uses fp64/offset-origin (project_uCoordinateOrigin, …64Low attributes). We already solve this with the origin-local rebase against MapIndex::origin — no gap (guarded by gpu_line_lane_and_cpu_basemap_share_one_scale_at_high_zoom in facett-geomap).
  7. Label collision/declutter (CollisionFilterExtension, getCollisionPriority): the biggest remaining visible gap was ours labelling every named OSM Way, so one street lettered its name 5–7× per view ("Feldkircher Strasse" ×7) and burned the label budget on repeats. ADOPTED a repeat-distance filter in facett-geomap's osm2d label pass (MIN_REPEAT_PX 380 + padded collision boxes), so the budget goes to distinct streets.

• Key deps: facett-core (Facet, Theme; shared L0 GPU plumbing via facett-core/wgpu), egui, serde_json; optional egui-wgpu/wgpu/bytemuck (GPU kernel).

• Shape: lib; medium (gpu/index/l0_points/project/style/tessellate).

• Observed role in the workspace: Re-exported by umbrella facett as facett::map; base layer reused by facett-geomap; fed OSM geometry by facett-osm; the demo installs its GPU renderer into eframe's RenderState. The umbrella map-wgpu feature turns on its wgpu lane.

Fill in (one line each — only the human knows these)

• Primary consumer(s):
• Why it exists (vs the obvious alternative):
• Hard constraint (airgap / no-C-deps / no-FFI / pure-Rust / etc.):
• Release cadence & independence (rides a parent? own repo someday?):
• Status (production / prototype / experimental / stubbed):
• Must-NOT-change invariant:
• Biggest known gap or TODO:
• Anything a newcomer would get wrong about it: