Skip to content

TrailView ground plan: far cells build only their lines, and the pages of level 17 and 16 are drawn as strokes #3273

Open

Description

@timohueser

Status: approved

State: pull request B1 is merged (PR #3278, head a4c5be4). The owner's check before B2 is done and passed (see
the comment of 2026-11-10). Next are pull request A and B2.

Part of #3096 (it merges into ground-plan). Size: L, in four pull requests (A, B1, B2, B3).
Depends on: pull request #3266 (the request path of a plan worker; B1 uses its cell::build_request and named
tiles) and pull request #3268 (the pull request of #3265; B2 is written against its Pages.fit).
Source: the far-strokes spike (branch spike/far-strokes, 7d36c4b), two adversarial design reviews and a delta
review, the owner's decisions of 2026-11-10 (the far look as strokes is approved; pull requests B2 and B3 start
only after the owner's flight, see "Before B2").

Names below that are not in ground-plan yet say where they come from: (spike), (PR #3266), (PR #3268), (new).
Paths are relative to builder/web/src/lib/trailview/ unless they start with host/ or builder/.

Problem

With ground=plan, every wanted cell (a zoom-16 cell under a wanted terrain page of level 16 or finer, out to
about 2.4 km) builds its full faces and records, and every page of level 16, 17 and 18 looks the road model up per
texel (model_at, height_at). A town view builds about 62 cells; 14 carry a mesh. That costs about 6 s of worker
time, and the 32 MiB records texture does not hold a town view's cells, so far cells have no ways.

A spike drew the pages of level 17 and 16 from the ways' centre-line segments as strokes, and kept the lookup for
the level-18 pages under the meshes. In 30 views and two drives the hand-over (where level 18 morphs into level 17
and the mesh fades, 390 m to 481 m) looks the same as the lookup. A stroke page costs about a third of the GPU time
of a lookup page. A far cell needs about 12 % of the native build. The spike found two faults:

  1. Far trees change under stroke pages. A plant keeps off a way through the page's mask (kept_off). The lookup
    knows a way's edge for sure only within 3 m (a bin lists a candidate's edge within records::MARGIN_M of its
    square) and past that only in some bins; the strokes know it to 12.75 m. So a tree with a clearance over 3 m
    stands under a lookup page in some positions and never under a stroke page.
  2. Near the eye the stroke look is not the lookup's: square junction corners, no fans, a grey track mouth at a
    bridge end, a streak on a deck.

The stroke renderer is a second renderer of the crate's lines, samples, widths and keys. The owner accepts it for
the far field if it looks identical, and near the eye before a mesh arrives only if it looks fine in the viewer.

Design

Words

  • Near block: today's records block of a cell. Far block: the block of Design 3.
  • Lookup page / stroke page: a page that the stamp pass makes from a near block with model_at, or from the
    drawn strokes of a far block.
  • split: rule.range / 2^18: where level 18 and the mesh fade end.
  • Mesh cell: a cell of meshCells() (plan/pieces.ts). Ring cell: one of the eight neighbours of a mesh
    cell that is not a mesh cell.

1. The source of a page, by its level

  • A page of level 18 is a lookup page, from its cell's near block. It waits for the near block and the mesh, as
    today; until then the level-17 page draws.
  • A page of level 17 or 16 is a stroke page, from its cell's far block. It waits for the far block only while that
    block is expected (its build is asked, or the rank of Design 4 expects to place it); until then the coarser page
    draws. A cell whose far block is not expected (past what the rows hold, over, failed) has its pages stamped
    without ways, as today's Records.waits decides for a cell past the target.
  • A level-18 page of a cell that is settled without a near block (its build failed, or its block found no room) is
    a stroke page.
  • With rows for every block no page changes its source: a level-18 page exists only inside split, in a cell that
    is a mesh cell. A page's source changes only when the rows are short, in two cases, and then the page is taken
    away and stamped anew (no page is stamped in place):
    1. A cell's near block arrives late or leaves for a nearer cell: Pages.restamp(cell, 18, 18) takes its level-18
      pages; the level-17 stroke pages draw until the level-18 pages are stamped again (lookup pages with the mesh,
      or stroke pages).
    2. A far block arrives for a cell whose pages were stamped without ways: Pages.restamp(cell, 16, 17) takes them.
      Pages.restamp(cell, first, last) (today restamp(cell), every level from the cell's) takes the drawn pages of
      those levels. A far block that leaves takes no page.
  • The stroke renderer draws lines, samples, widths, keys, the owner line's surface and the cones of fill and cut.
    It draws nothing that the lookup draws by its own rule (fans, regions, rounds, mouths, platforms, leg walls).

2. Trees: the reader, on the plan path only (pull request A)

kept_off (terrain/features.wgsl) reads the mask's distance only within keep metres.

  • keep is a new field of Masks (terrain/features.wgsl), after held; terrain/terrain.ts writes it once:
    CORE_REACH_M = 3.0 (the bin margin, M_MARGIN of terrain/records.wgsl) with ground=plan, else 12.75
    (MASK_M). The buffer grows by one word and the page layers start one word later (terrain.ts, pages.ts
    masks()). kept_off serves both road paths; the default path's mask is exact to 12.75 m and must not change.
    The field goes when the default road path goes.
  • With keep under 12.75: each of the four texels about the point counts as min(its distance, keep), and as
    keep where its road bit is 0; the gate on the nearest texel is "its counted distance is keep"; the thing keeps
    off where the filtered value is under min(clear, keep), or the nearest texel is taken. The trodden rule does
    not change. With keep = 12.75 the function computes today's values. (mask_at and mask_in take the reach;
    every caller but kept_off passes MASK_M.)
  • Why it is exact: a texel within 3 m of an edge is exact in every bin, and a texel past 3 m counts as 3 m whether
    its bin lists the edge or not. What is left: within one texel of the 3 m line the decision is soft, the same in
    both writers; and the shapes at junction corners.
  • No writer changes: a lookup page's mask, paint, snaps and moved share stay bit-equal.
  • The contract, in the comments of stamp.wgsl and features.wgsl: the mask's distance to a way's core and its
    road bit are sure within CORE_REACH_M in both writers of the plan path; a reader that decides yes or no must
    not use the distance past it; the snap and the water readers may.
  • What changes with ground=plan: a forest tree, a row tree or a shrub with a clearance over 3 m stands from 3 m
    off a way's core in every position. Ground plants, rocks and herds do not change.

Each channel has one meaning for both writers:

Channel Meaning Strokes take it from
mask.x, road bit metres to the core's edge (carriageway, shoulder, verge; a rail bed); a way within 12.75 m the least over the segments of distance − (half-width + shoulder + verge)
mask.y the trodden bit the owner line's finish is 6
mask.z, paint.z metres across of the painted way, signed; where no way is painted, the core distance alone the owner segment, where the least distance past a carriageway's edge is under two texels
CONFLICT, TAKEN, FORD from the stamp data; FORD only inside the core the same
paint.x metres to the paved edge the least over the segments of distance − half-width
paint.y, paint.w marked and trodden, or a track's sleeper phase; the finish code the owner line
moved, heights from the drawn height, as today the owner's surface on carriageway and shoulder; else the ground between the greatest fill and the least cut, faded at the band's edge; then stamp_bounded

They can differ within 3 m of an edge at junction corners (up to 0.41 × the corner radius), in a stop arm's mouth,
and in the heights at a junction blend.

3. The far block (pull request B1)

  • Crate: one encoder makes the far block from the lines of lines(): legs::record_ranges and line_words per
    leg, then the clip. No candidate, no slice, no bin. The module is faces/records/far.rs; its module comment
    holds the layout, as the near block's module comment holds the near layout.
    • A full build: pass() (faces/records/mod.rs) encodes it from the candidates' c.lines in the same pass (no
      second lines() call); records::near returns it; CellBuild.far: Result<Vec<u32>, String>. A far-block
      error does not fail the near block. records::build gives it as Built.far_block; the far-level records
      (the near candidates without the band layers) are Built.far_records.
    • A far-only build: records::far_block(graph, input, rules, cell) -> Result<Vec<u32>, String> calls lines()
      with the box of candidates(.., records = true) (faces::record_lines, ground level) and the same encoder;
      cell::far_request(request, cache, rules) -> Result<Vec<u32>, String> beside cell::build_request runs the
      stages input, graph, lines on the same request as a full build, with the whole 192 m input margin. It takes
      no clock: the worker times the job.
    • RecordsStats.failed (terrain/model.ts) counts the cells that the store holds whose build failed (state
      failed) or whose far block the crate refused (farFailed). Its test is in terrain/model.test.ts (B1).
  • Bridge: CellPlan.far() gives a build's far block, or throws the crate's refusal (the records and the rim of
    that plan are good); far(request) builds the far block alone and takes its request by value, as build does.
    Worker: the answer of a cell job carries far: Uint32Array | { error: string }; a job { type: 'far', id }
    with the inputs of a cell job answers FarBuilt { id, ok: true, far, ms, heap }, or Failed (ok: false)
    where the crate refuses the block, or Missing as a cell job does.
  • Words (little-endian; coordinates in frame units from the cell's origin). The head has the near block's word
    numbers, so h_line, h_sample, h_scale, m_line_finish and h_rules read both blocks:
Words Holds
0 MAGIC_FAR = 0x4f42_4601
1, 2 0
3 the count of record lines L
4, 5, 6 the offset of the LINE table = 15 + RULES
7, 8, 9 the offsets of the SAMPLE, KEY and SIDE tables
10 the cell's row of zoom 16
11, 12, 14 the length of the block: the near block's blend edges, junctions and outline edges are empty; 13 = 0
15 … the heights::RULES rule words
LINE LINE words per record line as line_words gives them, but word 2 = the first sample in this block, word 3 = the count of samples in this block
SAMPLE 12 words per sample as line_words gives them, but word 4 = the rank (0 to n − 1, below 2^20) of the sample's global name among the n names of this block's samples
KEY 1 word per record line: the key of its way's carriageway or rail bed candidate, rank << 16 | class << 8 | kind (way_key, key_word: the near block's WAY candidate key comes from the same function); its numeric order is the overlay's order of keys
SIDE 2 words per sample: the plain terrain input.terrain.height (f32 bits) at the sample ± (the shoulder's outer offset + reach_m × (1 − fade_share)) along the left normal (m.y, −m.x) of its mitre m, rounded to whole units: left, then right. m is the sample's own f32 mitre words (words 8 and 9, the GPU's value), not the f64 mitre. Unknown is the one NaN 0x7fc0_0000 (f32::NAN), never the NaN of a cast

Bytes: 4 × (15 + RULES + 17 L + 14 S). The near block does not change. Words 3, 6, 7 and 10, the rules, the
lines and the samples sit where the near block's do. Words 8 and 9 are the KEY and SIDE offsets, not the near
block's extras and bins: a reader of bins or candidates never reads a far block.

  • The clip. Per line: r = greatest half-width + max(shoulder + verge + reach_m, 12.75 m) + 1 m, in units at the
    cell edge nearer the pole. A segment is in reach when its box grown by r meets the cell square. A line with no
    segment in reach is left out with all its legs. Per leg with the samples [lo, hi] and the first and last segment
    in reach f and l: the record line holds the samples [max(lo, f − 5), min(hi, l + 6)] (segment i joins the samples
    i and i + 1); a leg with no segment in reach holds 0 samples. line_words runs on the whole leg first. A run over
    65,535 samples (RUN_MAX), or more than 2^20 names in the block (NAMES_MAX), is an error of the cell.
  • The pad of 5 (PAD = WINDOW + 1 in records::far): a stroke reads the segments within WINDOW = 4 of its
    own, and h_segment one more neighbour on each side. So every segment that a stroke of a segment in reach reads
    has in the run the neighbours that it has in the full leg, and h_segment takes the same branches. A run ends at
    its leg's end, or PAD segments before its first segment in reach and PAD + 1 samples after its last; at a run
    end that is not its leg's end, the end kinds (line words 12, 13) and h_segment's first and last are not
    true, and only a segment that does not reach the cell lies there.
  • A line with the WATER flag (after the water slice) is in the block and gets no instance.

Pull request B1 changed these points of the first text of this section:

  1. far(request) takes the request by value, as build (the design said &mut CellRequest).
  2. records::far_block and CellBuild.far are Result<Vec<u32>, String> (the design said Result<Records, String>).
  3. cell::far_request(request, cache, rules) has no clock argument.
  4. SIDE takes the sample's f32 mitre words (the GPU's value), not the spike's f64 mitre.
  5. An unknown SIDE height is the one NaN 0x7fc0_0000, not the NaN of a cast.
  6. The test "a failed block is counted" is in B1 (B1 adds the count).
  7. Names: records::Built.far (the far-level records) is now Built.far_records; the far block is
    Built.far_block, CellBuild.far, records::far_block; its check is records::check::far_matches_near; the
    debug tool model writes far_records_bytes and far_records_kB, and requests writes far_bytes for the
    far block.

4. Cells, builds and rows (pull request B2)

Kind of cell Build In the records texture Elsewhere
mesh cell full: near block, rim, far block; the mesh input kept near block and far block both in the device cache
ring cell full, for its rim far block the rim in memory; the near block in the device cache
other wanted cell far-only far block the far block in the device cache (x/y/far)
  • One nearest-first list of builds for all cells, as today; a ring cell counts as near as its mesh cell. Two
    workers, two jobs each.
  • One texture of 32 MiB and one allocator. One rank: the block of a nearer cell is better, by the cell's own
    distance to the eye (a ring cell does not take its mesh cell's distance here, as it does in the order of the
    builds); for one cell the far block is better than the near block.
    A block gets rows when it fits after the worse blocks leave, the worst first.
    A block that does not fit is over and asks again when there is room. A far-only build is asked only for a cell
    whose far block the rank expects to place; a block that is not built yet counts as the mean of the built blocks
    of its kind.
  • The strokes read only far blocks. The lookup and the meshes read only near blocks.

5. The passes (pull request B2)

  • Per far block on the CPU (strokesOf, spike, changed): one instance of four 32-bit words per segment whose
    stroke can reach the cell, of non-zero length, of a line without the WATER flag: the record line; the sample
    index (bits 0–15) with CUT_START (bit 16: the leg is not its way's first) and CUT_END (bit 17: the next record
    line continues the way); the key rank of each end. A key rank is the place of (KEY word, word 4 of the sample)
    among the block's sorted distinct pairs. Per instance its box.
  • Per stroke job: the instances whose box reaches the page go into one range of the frame's instance buffer, which
    grows to the need and drops nothing.
  • Four render passes a frame, before the stamp pass, draw all stroke jobs into an atlas of 2 × 2 tiles of 256²:
    owner (depth: part, key, distance), distances (blend min), fill (depth greater), cut (depth less; reads the
    fill). The shaders are the spike's terrain/strokes.wgsl with: the side words from the SIDE table; no discard
    (a fragment that draws nothing writes the failing depth, or the clear value in the distances pass);
    frag_depth stays.
  • Targets: r32float surface, rgba16float frame (metres across, sleeper phase, half-width), r32uint owner,
    rgba16float distances (past the carriageway's edge, the core's, the band's), r32float fill, r32float cut,
    depth32float. 9.0 MiB. No optional WebGPU feature.
  • A stroke job is a stamp job with the mode bit STROKED (8), the first word of the far block and its tile (0–3):
    StampJob grows from 32 to 40 bytes. At most 4 stroke jobs a frame; the other limits of a frame do not change.
    The stamp pass reads the job's tile in place of model_at and model_height, and builds the mask and the paint
    with mask_from and paint_from (new; the spike's mask_of and paint_of), which model_mask and
    paint_texel call too.
  • Switches (URL): far=lookup (every wanted cell builds in full and every page is a lookup page: today),
    far=strokes (this design), far=only (debug: no near build; level 18 as strokes too). B2 lands with the default
    far=lookup; B3 makes far=strokes the default.

For B2 (from the reviews of pull request B1)

  1. Instances. Draw an instance only for a segment whose stroke can reach the page. A padded segment cannot
    reach the cell, and at a run end that is not its leg's end its first / last and the end kinds are not true.
    Never trust a segment at run index < PAD unless the run starts at its leg's start, nor one within PAD + 1
    samples of a run end that is not its leg's end.
  2. Twin constants. The stroke shader's window must be records::far::WINDOW (4) = PAD − 1: tie it with a
    test when the shader lands. The mask reach 12.75 m has three copies: records::far::MASK_M is tied to
    MASK_M of terrain/features.wgsl by the crate test the_mask_reaches_as_far_as_the_viewers, and
    features.wgsl to MASK_RANGE of stamp.wgsl by terrain/bins.test.ts. Keep them equal.
  3. SIDE. The words of sample i of line l are at block + word 9 + 2 × (ln.first + i): left (+1 along
    (m.y, −m.x)), then + 1 right. They replace the spike's sample words 12 and 13 (left is the spike's 12). An
    exponent of all ones means unknown, as h_known_word reads it.
  4. KEY. It replaces the candidate scan and the rankOf fallback of strokesOf. The rank pair is (KEY,
    word 4); word 4 is below 2^20 (the crate refuses a block with more names).
  5. Far is not near. Words 8 and 9 of a far block are not extras and bins: never give a far block to a near
    reader (model_at, the bins). Words 11, 12, 14 are the length: the other near tables are empty.
  6. The plan worker protocol. Add FarBuilt to receive; tell it from CellBuilt by 'words' in data; add
    the carried tiles on a FarBuilt too (model.ts adds them only if ('words' in data)); let send post the
    job's own kind, so a Missing sends a far job again as a far job; a failed or lost far job sets "far block
    not expected", not the cell's state failed (today lose and !data.ok set failed).
  7. Failed cells. RecordsStats.failed mixes two meanings: a failed near build (state failed) and a refused
    far block (farFailed). Read the flags and the state, not the count: a failed near build gives level-18
    stroke pages, a refused far block gives pages without ways. plan/plan.ts has its own failed, which counts
    only the state.
  8. The device cache. Entries written before B2 hold [words, rim] and no x/y/far. A cell from the cache
    without a far block needs a far-only build.
  9. WASM budget (a reviewer's note). The WASM gzip budget has 4,020 B left (727,116 of 731,136 B). B2
    adds no Rust. A later Rust change needs the owner's raise; codegen-units = 1 for the bridge is worth a
    try then.
  10. Lucerne. About 10 mesh cells with both blocks and about 4 more far blocks fit in 32 MiB. Expect over far
    blocks there.
  11. Surface material. The stroke pages paint a way's surface material (concrete, setts, paving stones) from
    the owner line's word 1, through the shared paint_from, as issue TrailView: the far road paint keeps the surface material (concrete, setts, paving stones), so a road does not change colour where its mesh ends #3279 does for the lookup pages. A road must
    not change its colour where the lookup page ends and the stroke page begins.

Not in this issue

  • A cost-unit budget for stamp jobs (its own change).
  • Junctions, fans or mouths in the stroke look.
  • Ways on pages of level 13 to 15 (no cell is built that far; no page there has a paint layer; no lookup exists
    there to compare with).
  • A smaller input margin for the far build; packed far samples; the far block as a view into the near block; far
    water as strokes.
  • No code is deleted. The switch far=lookup goes after the phone run.

Invariants

  1. The source of a page is a function of its level and of which blocks its cell has on the device: no state, no
    history. A level-17 or level-16 page never reads a near block. A page's source changes only when a block of its
    cell arrives late or leaves; then the page is taken away and stamped anew.
  2. A reader of a page gets the same meaning from a lookup page and from a stroke page: the table of Design 2.
    kept_off is the only yes or no reader of the mask's distance, and it reads it only within CORE_REACH_M.
  3. A lookup page is bit-equal to today's. Without ground=plan every picture is bit-equal to today's.
  4. The far block against the near block of the same request: its record lines are a subsequence in the same order
    (matched by way and leg); every line word but 2 and 3 is bit-equal; its samples are a contiguous run of the near
    line's, with words 0–3 and 5–11 bit-equal and word 4 in the same order; KEY equals the key word of the line's WAY
    candidate; every segment in reach is there; every near segment within 5 of a segment in reach is there.
  5. A full build's far block, a far-only build's and the WASM build's are byte-equal.
  6. No cap drops a segment: the instance buffer grows; a run that the format cannot hold is an error of the cell.
  7. With far=lookup the builds, the blocks and the pictures are today's.
  8. A mesh draws only with its cell's near block on the device. A cell's far block leaves the device after its near
    block.

Done when

Every sheet names its build in each column. The orchestrator opens the pictures; the owner judges look. Every gate
that fails means: stop, and report with the numbers and the pictures.

Before B2: the owner's check. The owner flies the spike branch (the recipe in the first comment of this issue: nine places; the
level-17 stroke page without a mesh; a mesh over a level-17 stroke page, with the steps at the mesh's ground ring;
the pure stroke look). The orchestrator opens the 12 unreviewed "strict" sheets of the spike first. Pass: the
owner's yes to the first two looks. A "no": B2 does not start; the rule "in a mesh cell a page of level 17 is a
lookup page too" is measured on the spike first: its source change, its seam on level 17, and its morph band of two
sources between level 17 and level 16.

Pull request A (trees).

  • Step 0, before product code: the reader of Design 2 on the spike branch, with keep = 3; the view l6-oldtown-in-band-40m (Lucerne, the
    local demo release) with lookup pages and with stroke pages. Pass: the crop differs in ≤ 0.35 % of its pixels
    (three times the repeat noise); staged tree instances differ by < 1 %.
  • With ground=plan on the demo release, develop | base | head: a forest track at the eye, a tree-lined avenue, a
    stream beside a road, Lucerne old town; the count of staged trees per view. Pass: the owner accepts the look;
    outside trees ≤ 0.05 % of the frame differs between base and head.
  • Without ground=plan: the fixture's owner views and the same four demo-release views, base | head. Pass: 0
    pixels differ.

Pull request B1 (crate and bridge).

  • A Rust test of invariant 4 on every fixture cell, in the test that already builds every cell
    (host/obc-ground-plan/tests/records.rs,
    every_fixture_cell_gives_its_points_the_faces_labels_alike_near_far_and_across_borders): the check
    records::check::far_matches_near. It tests every near leg: a segment in reach whose leg has no far line, or no
    run that holds the samples its stroke reads, is a fault. A unit test
    (the_far_block_check_finds_a_way_in_reach_that_the_block_leaves_out) shows that it finds a way left out and
    an empty block. The debug tool's requests runs the same check on every cell it writes (the 12 Lucerne cells).
  • Far bytes native = WASM (check-bytes.sh). A full build, a far-only build and a build by named tiles give
    byte-equal far blocks.
  • RecordsStats.failed counts a failed build and a refused far block (terrain/model.test.ts).
  • Natively, the bytes of the clipped far block of every fixture cell and of the 12 Lucerne cells
    (measure/lucerne-fixture), and from them the count of mesh cells that 32 MiB holds with both blocks. Pass: the
    median Lucerne far block ≤ 390 KB. Fail: stop; pack the samples, or make the far block of a cell that holds both
    a view into its near block, before B2.

Pull request B2 (the viewer, default far=lookup).

  • Unit tests: the kinds of cell, the one build order, the rank of the rows, the size guess by kind, a cell whose
    far block is not expected does not make its pages wait (terrain/model.test.ts; the count of failed blocks came
    with B1);
    restamp(cell, 18, 18) takes only level-18 pages, a level-17 page waits for an expected far block, a level-17
    page without one is stamped without ways and again when the block comes, at most 4 stroke jobs a frame
    (terrain/pages.test.ts); instances, cut flags and a job's range from a hand-made far block
    (terrain/strokes.test.ts, new).
  • Mask probe (builder/web/tests/browser/trailview/mask-probe.mjs, new, manual): the pages of level 16 and 17 of a
    town view, a junction view and Lucerne old town, stamped with far=lookup and with far=strokes. Pass per page:
    the kept-off decision at clearances 0, 0.3, 1 and 2.5 m differs on ≤ 1 % of the texels; within 3 m of an edge the
    road bit and the paint code differ on ≤ 1.5 %; CONFLICT and TAKEN are equal; heights of untouched texels within
    2 mm.
  • Hand-over sheets, develop | far=lookup | far=strokes | differ: the spike's 16 hand-over, 8 town and 6 band
    views; Lucerne station and old town; a forest road and two far slope roads at 1 km to 2 km on the demo release.
    Pass: ≤ 0.3 % of the frame differs.
  • Motion: three drives at a fixed altitude in 10 m steps (two of the spike's evidence; one of 600 m in Lucerne that
    brings new cells into the mesh set). At each step the eye holds and the script takes frames 1, 2, 3, 5, 8, 13, 21,
    34 and the idle frame. Pass: the changed pixels per pair of frames ≤ those of far=lookup at the same step
    • 0.1 % of the frame; in Lucerne no more frames than with far=lookup in which a cell nearer than
      split × 2^-0.3 (where the meshes draw whole) has no mesh, no frame in which a cell inside split has neither a mesh
      nor ways, and no more frames without the eye's mesh. If the first count is worse, the remedy is the far block as a
      view into the near block.
  • Builds (the settle script and the probe patch of pull request TrailView load: a plan worker gets each tile once, and the request crosses into the crate once (#3264) #3266, 3 loads, median, base and head in one
    session). Pass at the Engelberg town view: 36 ± 2 full builds (base 62); busy time of both workers ≤ 85 % of the
    base; the median wall time of a far-only build ≤ 50 % of a full build's; no over block. Mountain view: busy time
    ≤ the base. Lucerne: busy time ≤ 110 % of the base. Far block bytes per cell reported.
  • Time to a clean frame, cold and warm, at the three views. Pass: cold ≤ the base's median + its spread.
  • GPU time per page of level 16 and 17. Pass: strokes ≤ 0.5 × lookup at the median. Atlas 9.0 MiB; records texture
    32 MiB.
  • With the default far=lookup: the 16 owner views at the eye, base | head: 0 pixels differ; the walk flight's
    frame time p50 and p95 within 3 %.

Pull request B3 (the default). The owner flies the B2 build with far=strokes and sees the hand-over sheets.

Before ground-plan goes to develop. A cold load of the town view on the owner's iPhone 13 in portrait with
far=strokes and with far=lookup. Pass: no crash; the worst frame and the time to a clean frame not worse with
strokes; the hand-over looks the same. Fail: the default goes back to far=lookup.

In each pull request: the test files that cover the changed code, obc test -p obc-ground-plan -p obc-ground-plan-bridge, clippy for both, npm run check, npm run check:wgsl, the WASM size guard,
obc suites check.

Risks

  • The owner's check can say no. Then level 17 of the mesh cells stays with the lookup, with a source change and a
    seam that nobody measured.
  • With a phone-sized page pool, meshes stand on level-17 stroke pages at about 300 m to split as a normal state
    (pull request trailview: a terrain page shortage leaves out the farthest fine pages; their parents draw in their place #3268 leaves level-18 pages out there).
  • The look evidence is from a 1920 × 960 desktop. On an iPhone 13 in portrait the same differences are about twice
    as many pixels (a junction corner: 3 to 11).
  • The cause of the tree fault is read from the code; its size is not shown before step 0.
  • The limit in kept_off changes the near field: a tree keeps off a way within 3 m at most.
  • A ring cell still builds in full: the saving is about a quarter of the worker time until the meshes need no rim,
    and less on a screen that renders more than 1,360 pixels high. An iPhone 13 in portrait is not one: the range
    rule takes the render height, 1,688 × 0.7 = 1,182 pixels, so its split is 480 m and its mesh cells are 14, as on
    the desktop.
  • In a dense town the records texture stays short, and a mesh cell's far block takes rows too: a cell inside split
    can be without its near block (stroke pages on level 18, no mesh) until the eye is nearer.
  • Under a mesh over a stroke page, the mesh's ground takes the stroke height and its paved faces the lookup's: a
    step with a kerb or wall look closes the difference, up to about 4 m at a hairpin island.
  • strokes.wgsl reads the height rules of heights.wgsl: a new height term needs a twin there.
  • No phone number exists for the passes.
  • The WASM bridge is at 99 % of its gzip budget after B1: 727,116 of 731,136 B, 4,020 B left. The next pull
    request that adds Rust to the bridge (the water slice, the record compaction, any crate change) needs a raise of
    the budget; the owner allows a few per cent when it is justified.
  • The near block's and the far block's layouts live in module comments while the format moves. B2 stores far
    blocks in the device cache (x/y/far), which makes the far block a stored format: both layouts move to
    specs/ before ground-plan goes to develop.

Activity

  1. timohueser commented on Nov 10, 2026

    @timohueser
    OwnerAuthor

    Owner check before pull request B2 (the flight recipe)

    Owner check: the stroke look near the eye, on the spike branch (version 4.1)

    Change note, 4 → 4.1: four more places (steep-hp, parallel, hairpin-town, the level crossing b4); the guard for a
    dropped cell in the hold lines; what look C shows at the mesh's ground ring; the orchestrator opens the 12
    unreviewed strict sheets before the flight.

    For the owner to fly, before the viewer work of the far level starts (gate G0 of DESIGN.md).
    Build: spike/far-strokes 7d36c4b, worktree /media/timo/OSM1/tmp/ground-plan/spike-strokes/wt, the Engelberg
    fixture. The orchestrator serves the built page as the spike's shoot.mjs does (serve() and routeFixture of
    builder/web/tests/browser/trailview/harness.js) and opens it in the headed GPU Chromium window. One page at a
    time under the GPU lock; MemoryMax 3G.

    Before the flight the orchestrator opens the 12 sheets in spike-strokes/pictures/strict/unreviewed/. They are
    look C at level 18, and nobody has opened them. A sheet that is plainly broken is said in words, not shown.

    Why

    The design takes level 18 from the lookup and levels 17 and 16 from the strokes. Loaded, that is the look of the 30
    evidence views. Three other looks can show near the eye. The owner said: fine "if it looks fine in the viewer".

    Look When the product shows it How often
    B: level-17 stroke page, no mesh while a mesh is late: a cold load, a jump seconds, at each load
    C: a mesh over a level-17 stroke page where the page pool leaves a level-18 page out under a mesh (PR #3268), at about 300 m to 480 m; and at the eye on a device whose finest level is 17 the normal state on a phone-sized pool
    A: level-18 stroke page, no mesh a cell whose near build failed or found no room; the same look at 1.6 m texels on a device whose finest level is 16 rare

    The sets of switches

    Add each set to the view's address after ground=plan.

    Set Switches Shows Code needed
    R far=strokes the design once loaded: mesh and lookup near, strokes past about 390 m none
    R0 (none) today none
    A far=strokes&pieces=off look A: the pure stroke look at 0.4 m texels none
    B far=strokes&finest=17&pieces=off look B: what the eye stands on while a mesh is late none
    B0 finest=17&pieces=off today's look while a mesh is late (the level-17 lookup page): compare with B none
    C far=strokes&finest=17&under=strokes look C: the meshes over level-17 stroke pages none
    C0 finest=17 today's meshes over level-17 lookup pages: compare with C none
    D far=strokes&hold=8 the real sequence: 8 s of look B, then the lookup pages and the meshes arrive a dozen lines, below

    pieces=off hides the meshes. finest=17 caps the terrain at level 17 (it exists in the product, view.ts
    finestOf). under=strokes makes the pages under a mesh stroke pages. Checked in the spike's code
    (terrain/strokes.ts:11-16, terrain/terrain.ts under); not run by me.

    The lines for set D (spike branch only, terrain/model.ts)

    The mesh of a cell arrives hold seconds late. Until then the cell counts as "mesh on its way", so its level-18
    pages wait and the level-17 stroke page draws, as in the product.

    /** Spike (`hold=S`): a cell's mesh arrives S seconds late. */
    const HOLD_MS = 1000 * (Number(new URLSearchParams(typeof location === 'undefined' ? '' : location.search).get('hold')) || 0);
    
    // in the type Cell:   held?: boolean;
    // at the start of `private mesh(cell: Cell, bytes: ArrayBuffer)`:
    if (HOLD_MS && !cell.held) {
        Object.assign(cell, { held: true, mesh: 'asked' });
        setTimeout(() => {
            // A cell that left during the hold (a lost device) must not mesh with freed rows.
            if (this.cells.get(key(cell.node)) !== cell) return;
            cell.mesh = undefined;
            this.mesh(cell, bytes);
            this.answered();
        }, HOLD_MS);
        return;
    }

    mesh: 'asked' keeps update() from asking the cell's build again and keeps settled() false. Use a fresh
    browser profile, or the device cache answers at once (it goes through the same function, so the hold still acts).

    The places

    All are views that the owner knows or that the evidence used. The address is trailview.html + the view + the set.

    # Place View Why
    1 Town junctions from above ?lat=46.818322&lon=8.397999&heading=89.7&pitch=-45.6&alt=1011.8&date=2026-08-15&time=10:30&weather=sunny (v12) corner rounds, edge lines at a cross street
    1b Town T-junction at the eye, with a stop arm ?lat=46.8200741&lon=8.4078216&heading=201.0&pitch=-4&eye=1.6&date=2026-08-15&time=10:30&weather=sunny (t-tertiary-eye) the mouth; square corners at walking height
    2 Town hairpin ?lat=46.821866&lon=8.404830&heading=153.3&pitch=-56.4&alt=1032.2&date=2026-08-15&time=10:30&weather=sunny (v17) the island; the wall between the arms (set C)
    3 Bridge end with a track mouth ?lat=46.815587&lon=8.393412&heading=350.0&pitch=-9.0&eye=60&date=2026-08-15&time=10:30&weather=sunny (b2), then fly down to the south end of the bridge in the lower left third the spike's known fault: grey over the tan mouth, a streak on the deck
    4 Track fan ?lat=46.821619&lon=8.376436&heading=312.6&pitch=-38.5&alt=959.9&date=2026-08-15&time=10:30&weather=sunny (v07) a V in place of a fan
    5 Road in a cut, for set C only ?lat=46.822051&lon=8.379572&heading=284.8&pitch=-34.2&alt=986.3&date=2026-08-15&time=10:30&weather=sunny (v06) the crease beside the road under a mesh
    6 A path that meets a road on a steep slope (the diffmap place steep-hp) ?lat=46.814645&lon=8.383842&heading=100&pitch=-3&eye=1.6&date=2026-08-15&time=10:30&weather=sunny (hp-eye) and ?lat=46.814560&lon=8.383700&heading=60&pitch=-30&alt=1175&date=2026-08-15&time=10:30&weather=sunny (hp-15m) the stroke height is about 1 m off the lookup's where the path meets the road: under a mesh (set C) a step at the mesh's ground ring
    7 A three-way junction (the diffmap place parallel) ?lat=46.820267&lon=8.418961&heading=0&pitch=-60&eye=80&date=2026-08-15&time=10:30&weather=sunny (the middle of level-18 page 137202/92394; derived, not a stored view: fly to the junction in that 100 m square) the stroke height is up to 1 m to 2 m off at the junction's blend
    8 The town hairpin's island (the diffmap place hairpin-town) place 2; then go down to the island between the arms at walking height the largest height difference of the spike: up to about 4 m on the island's slope, 3 m on its paved edge
    9 The level crossing (b4) ?lat=46.81982&lon=8.3970&heading=90&pitch=-10&eye=15&date=2026-08-15&time=10:30&weather=sunny (about 45 m west of the crossing at 46.81982, 8.397587, looking east; derived from the evidence's target point) the road over the rail bed: the lookup has a crossing label, the strokes only the road over the rail

    For look C at its real distance (300 m to 480 m, not at the eye), use the band views of the evidence with set C:
    ?lat=46.815587&lon=8.393412&heading=350.0&pitch=-15.2&eye=60&date=2026-08-15&time=10:30&weather=sunny
    (b2: its junction is 436 m away). Fly forward and back so that the junction crosses 300 m to 480 m.

    What to do and what to look for

    1. At each place open R0, then R: they must look the same near the eye. If not, stop: something is wrong with the
      build, not with the question.
    2. Look B (places 1, 1b, 2, 3, 4, 9): open B0, then B, and fly along the road at walking height and at 15 m.
      • Junction corners: square, with a small hook on the edge line, where B0 has rounds.
      • The fan at place 4: two ways that overlap in a V.
      • The mouth at 1b and 3: the side way's colour ends where the main road's grey begins, with no mouth shape.
      • The deck at 3: a dark streak.
      • Rails, a cut slope's edge, far paths: better in B than in B0.
        Question: is this fine for the seconds before a mesh arrives?
    3. Set D (places 1 and 3): reload and watch the 8 seconds and the change. Question: does the change from the
      stroke page to the mesh disturb more than today's change (R0 with hold=8 shows today's)?
    4. Look C (places 2, 5, 6, 7, 8, 9 at the eye; the band view at its real distance): open C0, then C.
      • The wall face between the hairpin's arms at place 2.
      • A dark crease in the grass beside the road at place 5.
      • Steps at the mesh's ground ring. The mesh's paved faces keep the lookup's height. The ground beside them
        takes the stroke page's height. Where the two differ, a step closes the gap, and it draws with a kerb or a
        wall look: about 1 m where the path meets the road at place 6, 1 m to 2 m at the junction of place 7, up to
        about 4 m on the hairpin island of place 8. No hole and no terrain through the road can show; a step that
        today's look does not have can.
      • Shading of the slopes beside the meshes; the mesh's edge against the ground.
        Question: is this fine at 300 m to 480 m on a phone, and at the eye on a device that draws no level 18?
    5. Look A (places 1b and 3): open A. Question: is this fine for a cell whose near build failed?

    The answers, and what follows

    Answer Follows
    B yes, C yes the design as it is: level 18 lookup, levels 17 and 16 strokes, on every device
    B no or C no in a mesh cell the pages of level 17 are lookup pages too. That brings a source change, a straight seam on level 17 and a morph band of two sources at 780 m to 960 m, which are measured on the spike branch (about ten lines) before the viewer work starts
    A no a failed cell's level-18 pages wait (the level-17 stroke page shows there); a device at the finest level 16 keeps the lookup

    Not shown by this check: a phone's screen (the same differences are about twice as many pixels on an iPhone 13 in
    portrait), Lucerne (the fixture is Engelberg), and trees (the fixture has none).

  2. timohueser commented on Nov 10, 2026

    @timohueser
    OwnerAuthor

    Owner check before pull request B2: done (2026-11-10)

    The owner looked at the stroke looks on the spike build (owner/far-strokes-check ca477e20d, the Engelberg fixture; 35 comparisons, the list is in the recipe above). His notes, in his words:

    Look Place Owner
    B, coarse stroke page near the eye town junction "yes this is fine, this actually looks decent to me."
    B bridge end with the track mouth (the worst case) "accept as a stand in."
    B track fan "this looks good to me"
    C, the road mesh over a stroke page steep hairpin "they're acceptable for now"

    Result: gate G0 passes. The per-level rule holds on every device: a level-18 page is a lookup page, every page of level 17 and 16 is a stroke page. The fallback rule of section 1.5 is not necessary.

    Two limits of the check:

    • The spike draws no way near the eye while a mesh is late, with strokes and without (its far pages read the full records block). Thus the load moment itself was not shown. Pull request B2 must show it in its own build.
    • The owner did not see the tree difference at Lucerne in the picture. Step 0 of pull request A measures it.
  3. timohueser commented on Nov 11, 2026

    @timohueser
    OwnerAuthor

    Points of this issue that the crossing block (#3105) touches:


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions