---
title: "Body Map Viewer — Prep Grounding"
description: "Pre-read for the T-1176 prep session (Jeroen + lead + Tyre) and later the workshop: current mechanism, error-class evidence, delivered ladder design, binding constraints, candidate directions"
type: workshop
status: active
workshop: body-map-viewer
created: 2026-07-25
decision_refs: [D-166, D-226, D-227, D-243]
---

# Body Map Viewer — Prep Grounding

Prepared by the lead for the three-way prep session (Jeroen, lead, Tyre) that writes
the workshop brief. Working name `body-map-viewer` (Jeroen's phrase) — rename with the
brief if a better one emerges. Everything here is *input*, not position: Jeroen's
outline of his own design opens the session and nothing below pre-empts it.

## 1. Why this exists

Jeroen, 2026-07-23 (T-1176): *"I want to discuss and maybe revise the pixel
scan/output mechanism for drawing the map. I feel we can be smarter about this and
bypass an entire class of errors we are seeing as well as probably improve
performance."* Follow-up 2026-07-25: he, the lead, and Tyre write a plan to start a
wider-team workshop on the new map handler; Jeroen will outline how he would build
**the body map viewer with zoom to ground level** and **how the deterministic
generation cascade connects into it**.

## 2. The error-class evidence (PRs #195–#197, recorded in D-226 implementation notes)

All rendering-layer bugs of the river arc descend from one architectural choice:
**immediate-mode `draw_*` calls issued by children of a zoom-scaled canvas**
(`_canvas.scale = _view_zoom`), which makes every on-screen size a canvas-local value
divided by zoom:

- **Per-call-site compensation fragility** — every radius/stroke needs `_zs`/`_zs_stroke`/
  `_zs_ring_radius` wrapping (atlas_window_geometry_nature.gd); a missed site degrades
  silently. Happened twice (PR #195 attractor strokes, PR #197 course widths).
- **Godot line-rasterizer stroke floor** — widths below ~1.0 canvas units collapse to a
  1 px hairline (bracketed live: 0.6 → hairline, 1.1 → visible). Consequence on record:
  per-class course *width* grading is inert at every shipping fit zoom; classes
  distinguish by opacity alone until T-1175.
- **`draw_arc` blob regime** — ring radius below stroke width renders a filled blob
  (bracketed: 1×stroke = blob, 1.5× = recovers, 2× = clean; floored at 2×).
- **Wrap-image resolution family** — seam tiles must mirror the painter's
  `nearest_wrap_image(tile_center, held_center, cols)` exactly (T-1172 round 2 inverted
  it); shared index math now lives in `cell_index_for_local_offset`.
- **Auditability** — the mechanism defeated visual verification three times in one
  batch (lead capture misreads corrected only by wire data). A mechanism whose
  correctness can't be eyeballed is itself a finding.

## 3. The current mechanism (the thing being revised)

**Client** (`client/ui/implant/apps/atlas/`): `AtlasWindowViewer` (~1017 ln) owns a
`_canvas` Node2D; pan/zoom = `_canvas.position/_canvas.scale` (`_apply_transform`).
Terrain: `atlas_window_overlay.gd` builds one Image texel per derived cell →
ImageTexture → `draw_texture_rect` (COMPOSITE_SMOOTH pipeline axis; rebuilt only on
window change — pan/zoom is free), per-rung sampling filter `_filter_for_granularity_v2`
(Region/orbital-mosaic → NEAREST, District/Quarter → LINEAR; T-1161 two-axes outcome).
Nature features (`atlas_window_nature_overlay.gd`): `draw_polyline`/`draw_circle`/
`draw_arc` inside the scaled canvas with the §2 compensation family. Orbital rest
state: whole-body mosaic of capped Region tiles (per-tile ImageTextures,
`AtlasWindowTileSet`). Rung selection: coverage-ceiling walk (`select_rung()`,
MAX_COVERAGE_M — Quarter ≈ 32.8 km, District ≈ 131 km, Region ≈ 13,107 km, beyond →
tile mode). CELL_PIXEL_SIZE = 16 px at zoom 1.0. Redraws on pan/zoom/rung-cross/
arrival, not per-frame.

**Server** (`server/src/atlas/`): windowed derives on the Rayon background queue,
never inline (D-226 T-1124 §1 [HARD]); one windowed payload (`DistrictWindowLayer`:
per-cell u8 arrays + `courses: Vec<RiverCourse>`), echo/cache keyed on
`(body, center, n, granularity)`; wire clamp `window_n² × granularity² ≤
WIRE_CAP_CELLS (4096)`; whole-body Layer1 family (512×256: heightmap analysis, D8
drainage/rivers) rung-independent. Measured (zoom_ladder_bench, release, 16 cores):
District derive 3.0 µs/cell uncut, 1.785 µs @2048 m cutoff; Quarter 1.823 µs @512 m;
orbital 1.454 µs; served Region window (4096 cells) **0.617 ms/call**.

## 4. The delivered ladder design and what it already settles

`docs/architecture/atlas-zoom-ladder-t1143.md` (9-agent pass, 2026-07-21) + Jeroen's
three rulings (recorded as D-226 amendment):

1. **Floor OPENED** — *"we set a new BHAG so old restrictions are up for debate."*
   The D-226(d) ceiling is opened for the Atlas ladder; "down to tile scale" reads
   literally. Below-quarter rungs (block/tile) are **implementation-gated on T-1154**
   (below-quarter measurement pass — backlog, now unblocked: the octave-cutoff
   plumbing it was blocked on has existed since T-1162). Chunk/tile output still never
   appears as a *whole-body planetary layer* — windowed viewport only.
2. **Planetary carrier** — progressive capped-density tiling on the generalized
   `district_window` carrier (shipped as the orbital mosaic).
3. **Entry seam** — continuous cursor-anchored zoom, full-zoom-out resets to the
   canonical planetary frame (shipped, T-1153).

Standing risks from that doc that touch this workshop: **R1** planetary/canvas-fill
cost story (full-canvas sample still extrapolated, ~524 ms @2 px/cell parallel-
estimated); **R2** temperature steps at district boundaries by construction at every
rung (never continuous); **R3** average-back unverified for categorical morphology
gates; **R6** border-fade referent must repoint when the heightmap-texture path
retires.

## 5. Binding governance (verified verbatim)

- **D-166 amendment + corollary (2026-07-21):** continuous zoom ladder planetary→tile,
  every level *"deterministically calculated information at that level's native
  granularity … never magnified interpolation of a coarser composite"*; display
  *"samples the derivation at canvas resolution (the ladder is a continuous field, not
  a stack of fixed display rasters)"*; heightmap PNGs are invisible derivation input.
  Hard Phase-4 exit bar (T-750).
- **D-226(d)** as amended by ruling 1 above: the old hard ceiling is opened for the
  windowed viewport; the whole-body-planetary-layer prohibition stands.
- **D-227:** derive-don't-store — `subtile(x,y,z) = derive(seed, atlas, position)`,
  transient evictable caches only; coast crinkle + river courses are rung-indexed
  invention.
- **D-243:** the containment ladder (voxel 1 m … region 204.8 km, one elastic
  planetary seam); climate edge-fuzzed (*"climate does not change on a line"*),
  morphology seams sharp-but-organic.
- **Carrier three-way rule** (docs/architecture/river-courses-t1170.md, binding):
  (i) rung-independent discrete features → whole-body family, filtered client-side;
  (ii) continuous per-metre fields → windowed per-cell arrays; (iii) rung-indexed
  invented detail → windowed payload regardless of geometric kind.
- **Windowed-family ceiling** (D-226 T-1124 §2 [HARD]): exactly one windowed-query
  field on `AtlasLayerResponse`; a second forces the tagged-envelope migration.

## 6. T-1176 candidate directions (sparring material, not positions)

- **(a) Unscaled screen-space sibling layer** — annotation/feature drawing moves to an
  unscaled sibling of the canvas; positions transformed to screen space, sizes literal
  px. Kills the whole §2 compensation class for vector features. (Tyre's earlier note,
  T-1156 wave 2 / T-1158-adjacent.)
- **(b) Render-to-texture per window/tile** — features rendered at native resolution
  into textures; zoom becomes pure texture transform; sizes texel-exact. Must be
  argued against D-166's "canvas resolution / continuous field, not fixed display
  rasters" sentence. Prior art in-tree (Tyre): the orbital tile-mode mosaic already
  composites per-tile ImageTextures (`_tile_texture_cache`, `compute_tile_grid()` —
  Lendel 3×2, verified this session) — the terrain path is halfway to this model.
- **(c) Shader-side composition** — morphology/courses as data textures, coloring +
  feature rendering in fragment shader; per-vertex width/tapering (T-1175) comes free;
  likely the performance route for canvas-resolution sampling at planetary scale (R1).
- **(d) Hybrid** — e.g. terrain via (c), vector annotations via (a).

## 7. Adjacent work that intersects

| Item | Status | Intersection |
|---|---|---|
| T-1154 below-quarter measurement pass | backlog, unblocked | the gate for "zoom to groundlevel"; block/tile rung costs + wire |
| T-1158 viewer decomposition | backlog | any new mechanism restructures the same file |
| T-1175 polish collector | backlog | tapering/width grammar wants Polygon2D strips or shaders — mechanism-dependent |
| T-1157 capture harness redesign | backlog | §2's auditability finding — verification story for whatever ships |
| T-1174 batch/window sampling divergence | backlog | pre-existing sampling debt |
| D-239 tile-derivation contract | **verified in-session**: confirmed/active, "coarse→fine refinement chain (resolves Q-101)", 2026-06-07 | the derivation side of "connect the cascade" is settled governance |
| Phase-5 boundary (D-166 generation-before-player) | standing | ground-level *rendering* is Phase 5; the Atlas ladder maps derived layers — where Jeroen's viewer sits relative to this line is his to outline |

Prior workshop art: `atlas-derivation-model.md` (brief-only, data side),
`generation-cascade/` (atlas UI coords vs sim coords), `world-generation/` (atlas as
annotated information layer), `map-authoring-pipeline/` (brief-only, predates the
no-hand-made-test-map rule — historical only).

## 8. What the prep session must produce

1. Jeroen's design outline, captured faithfully (the session's round 1).
2. Every point sorted: **settled by the three of us** vs **genuinely open → workshop
   question** vs **already ruled** (cite the record).
3. The workshop brief (`body-map-viewer-workshop-brief.md`): question, locked/open
   context, roster, per-agent questions, format, input docs, expected outputs
   (D-record(s), ticket plan).