Skip to content

TrailView ground plan GP1: the crate's base: frame, tile decoder, terrain heights, cross-section table, debug tool #3111

Closed

Description

@timohueser

Status: approved
Part of #3096. One pull request into ground-plan.
Depends on: GP0 (places and shots)

TL;DR

Goal: The crate host/obc-ground-plan exists, and it turns the inputs of one cell (the zoom-13 feature tiles about it, its stored terrain pages and the rule tables) into exact integer geometry, terrain heights and cross-sections, and a debug tool shows these inputs from above at any place of road-views-top.json.
Problem: Every later sub-issue needs one deterministic base: an integer frame, a Rust reader of format 4, the viewer's terrain heights, and one cross-section table. Today the only Rust decoder is a test helper (tiles.rs:227), the CPU terrain reads differ from the GPU (roads/ground.ts:66-80), and the half-widths live in bins.ts, section.ts and structures.rs with different numbers.
Decision: A pure Rust crate with four modules (frame, tile, terrain, sections) and one input type CellInput. All 2D values are i64 in 1/16 of a world unit; every transcendental goes through libm, and clippy.toml forbids the std ones and HashMap. A cell reads every zoom-13 tile that the cell plus its 192 m margin meets (one to four), takes each segment, edge and point from one of them by a fixed rule, and a tile cache decodes each tile once. One reach table bounds every chain at 191 m. Terrain heights are the Catmull-Rom of pages.wgsl over the stored pages' own r16 codes. roads.json gains four fields per class, and a new finishes.json holds the values by finish. The debug tool is a cargo example that writes PNG pictures (tiny-skia), stats and a glTF height field.
Rejected:

  • A join by OSM id: the tiles hold no id, and the owner rule (Design 3) needs none.
  • Reproduce the r16 steps of the synthesized level-18 pages: their extent depends on the stamp that the page takes (pages.wgsl:11,73), and a whole page costs 65,536 bicubics. The step is at most 0.8 mm (Design 4).
  • A WebP or gzip decoder in the crate: the viewer decodes both natively.
  • The finish values as rows of roads.json: each top-level key of roads.json is a class and a stamp profile row, and the stamp holds at most 32 rows (bins.ts:92-113, 31 now).
  • The debug tool as a binary with a cargo feature: an example takes dev-dependencies, so image and tiny-skia never reach the WASM build.
    Systems: trailview
    Contracts: specs/trailview-features.md (Readers, Test vectors, one sentence on the class table); docs/design/trailview.md (owns gains host/obc-ground-plan/**).
    Size: M (a crate of about 1,000 lines with tests, a debug tool of about 500 lines, four table fields and one new table, no viewer code)

Facts

  • A tile holds each feature that comes within the buffer, and a cut line keeps each segment that meets the buffered square whole, with one more vertex at each end (specs/trailview-features.md:37-47). The buffer is 40 m at the tile edge nearer the pole, so at least 40 m everywhere (tiles.rs:397-408). It does not limit the margin (Design 3).
  • The curves leave their chords by up to 2 m (specs/trailview-features.md:259-261).
  • A cell (zoom 16) is 1/64 of a zoom-13 tile. Its square plus 192 m (epic, section 2) meets one zoom-13 tile in the tile's middle, two at a tile line and four at a tile corner.
  • A tile holds kind, tags, geometry and parts per feature, and no OSM id (specs/trailview-features.md:76-89; no keep of data/trailview/kinds.json names an id).
  • Coordinates: tile units with the origin at the tile's north-west corner, quarters of them (FINE 4) for a feature with an alignment; a vertex shared with a river or a stream lies on a whole tile unit (specs/trailview-features.md:103-110, tiles.rs:21-24). At zoom 13 a tile unit is 2^7 = 128 frame units and a quarter is 32: both exact.
  • along_code is the decimetres along the stroke at the part's first vertex (specs/trailview-features.md:277). Two tiles start a part at different vertices.
  • At the last vertex of a part, a reader ignores walk, which the cut can leave set (specs/trailview-features.md:283).
  • The spec names two decoders, stream/features.ts and tools/planner_verify.py. The encoder's own decode is test-only (tiles.rs:227-349).
  • The fixture holds 3 × 3 zoom-13 feature tiles (columns 4286-4288, rows 2887-2889, gzip, 4 to 86 kB), the zoom-13 terrain tiles of the same squares and 2 × 2 zoom-12 terrain tiles (lossless WebP with alpha, Terrarium), bounds [8.37, 46.765, 8.46, 46.83] (builder/web/tests/browser/trailview/fixture/).
  • A stored terrain tile of 512 px holds four pages of 256² texels one level deeper; a height is R × 256 + G + B / 256 − 32768 where alpha is 255, else unknown; per page, offset = min and scale = max((max − min) / 65534, 1e-4), code = round((h − min) / scale), 0xffff for unknown (stream/heights.ts:16-38). The GPU decodes a texel as scale.x + f32(raw) * scale.y in f32 (terrain/drawn-height.wgsl:143-149).
  • Synthesized pages (levels 15 to 18) take the Catmull-Rom of the deepest stored level up to top that knows all 16 texels about the point, and fall back level by level (terrain/pages.wgsl:25-52). Their own r16 codes use the extent of the page, or of the stamped page (terrain/quantize.wgsl:35-48, pages.wgsl:11,73).
  • The deepest stored zoom is 13, so the deepest stored level is 14 (stream/terrain.ts:8). A texel of level L is 2^(22−L) world units: 6.5 m at level 14, 0.41 m at level 18.
  • window.trailView.check(points) returns drawnHeight at [lon, lat] points (engine.ts:284-287).
  • The bake's metres use EQUATOR_M = 40075016.686 (host/obc-trailview-features/src/lib.rs:23-28); the viewer's frame uses EARTH_RADIUS = 6371000 (frame/frame.ts:3, terrain/bins.ts:190). The format's metres (along, grades, widening) are the bake's.
  • Half-widths today: SURFACES, SHOULDER_M, PAVED, MAIN, PATH_HALF, surfaceOf, trackSurface, halfWidth (terrain/bins.ts:48-168), KERB_RISE_M (:435); KERB_TOP_M, SPILL_M (roads/section.ts:38-42); the bake's road_half with 6 m for every main class (structures.rs:26-41, :96-112).
  • A link with a paved surface gets the finish road, 3.0 m and a 0.4 m shoulder today; an untagged one main, 4.5 m and 0.6 m (bins.ts:141, :166, SHOULDER_M). The fixture has no link.
  • In the fixture, every primary (23) and secondary (15) feature has a lanes tag; no viewer code reads lanes.
  • The feature step's options keep only the CLASS_FIELDS of roads.json (kinds.rs:17-27, :205-212): new fields do not rebake the features. The ruleset digest covers every JSON file of data/trailview/ (planner.rs:1161-1180): the next bake runs the cheap trailview-rules step again, and its rules.json does not hold roads.json.
  • serde_json without preserve_order sorts object keys; its float parse depends on float_roundtrip. obc-trailview-features enables both (Cargo.toml:23); Cargo unifies features per build, so a crate that does not ask for them can parse differently in WASM.
  • libm = { version = "0.2", default-features = false } is a workspace dependency (Cargo.toml:108, 0.2.16 in Cargo.lock). tiny-skia 0.11.4 and image 0.25.10 are in Cargo.lock. Rust never fuses a multiply and an add unless the code calls mul_add.
  • clippy 0.1.99 reports f64::sin, f64::powi, f64::hypot in disallowed-methods and std::collections::HashMap in disallowed-types.
  • tools/testing/suites.toml:34-37 lists the data files that trigger obc-trailview-features: Cargo cannot see them.
  • road-views-top.json does not exist on 4f8b8b255: GP0 adds it. A view of road-views.json has name and a view query (?lat=…&lon=…&heading=…), no lat or lon fields.

Design

1. The crate

  • host/obc-ground-plan, a member of the root workspace, publish = false, license = "GPL-3.0-only".
  • Dependencies: libm (workspace); serde_json (workspace) with features = ["preserve_order", "float_roundtrip"], so every build parses the tables the same. No i_overlay or spade yet: GP3 and GP7 add them.
  • Dev-dependencies (tests and tool only): flate2, image with png and webp, tiny-skia = { version = "0.11", default-features = false, features = ["std", "simd"] }.
  • Determinism rules, enforced by host/obc-ground-plan/clippy.toml and -D warnings:
    • disallowed-methods: for f64 and f32: sin, cos, tan, sin_cos, asin, acos, atan, atan2, sinh, cosh, tanh, asinh, acosh, atanh, exp, exp2, exp_m1, ln, ln_1p, log, log2, log10, powf, powi, cbrt, hypot. Reason: "use libm: the same bytes native and in WASM". sqrt, abs, floor, ceil, round, trunc, min, max stay: IEEE gives them one result.
    • disallowed-types: std::collections::HashMap, HashSet. Reason: "the order changes per run: use BTreeMap, BTreeSet or a sorted Vec".
  • No threads, no unsafe, no I/O in src/. src/lib.rs holds CellInput and the modules frame, tile, terrain, sections.

2. The frame (src/frame.rs)

  • pub const FRAME_BITS: u32 = 34: a frame unit is 2^−34 of the Web Mercator square, 1/16 of a world unit, about 1.6 mm at 47° N.
  • pub struct GlobalPoint { pub x: i64, pub y: i64 }: x east, y south, origin at the north-west corner of the square. Copy, Eq, Ord, Hash, Debug.
  • pub const CELL_ZOOM: u32 = 16, pub const CELL_UNITS: i64 = 1 << 18.
  • pub struct CellKey { pub x: u32, pub y: u32 }, the zoom-16 tile. Methods:
    • of(p: GlobalPoint) -> CellKey: p >> 18 per axis.
    • origin() -> GlobalPoint; contains(p) -> bool with origin ≤ p < origin + CELL_UNITS on each axis, so a point on a shared line belongs to one cell, as a tile owns 0 to less than 16384.
    • margin() -> i64: floor((MARGIN_M + 2) / metres_per_unit(y_pole)) frame units, where y_pole is the cell's edge nearer the pole (north edge for y < 2^33). The 2 m: a curve leaves its chord by up to 2 m (spec, Alignment), so the curve within MARGIN_M lies on segments that meet the cell grown by margin(). pub const MARGIN_M: f64 = 192.0: the epic's input margin. pub const CHAIN_MAX_M: f64 = MARGIN_M - 1.0 (191 m): the longest chain of rules (Design 5, Reach table).
    • feature_tiles() -> Vec<(u32, u32)>: the zoom-13 tiles that the cell grown by margin() meets, in the order (row, column): one to four.
    • local(p) -> Option<CellPoint> and global(CellPoint) -> GlobalPoint.
  • pub struct CellPoint { pub x: i32, pub y: i32 }: frame units from the cell's origin. A cell plus its margin spans about 4 × 10^5 units, far inside i32 and inside i_overlay's range. local returns None for a point past i32; GP2 clips segments in i64 before it converts.
  • pub const EQUATOR_M: f64 = 40075016.686, as the bake.
  • pub fn metres_per_unit(y: i64) -> f64: EQUATOR_M / 2^34 / libm::cosh(π (1 − 2 y / 2^34)). Equal to the bake's metres(y) (cos(atan(sinh t)) = 1 / cosh t) within 1e-12 relative.
  • pub fn tile_point(z: u32, column: u32, row: u32, fine: bool, x: i64, y: i64) -> GlobalPoint: (column × 2^k + x) << s with k = 14 (16 for fine) and s = 34 − z − k. It rejects z > 18. Exact.
  • pub fn from_lon_lat(lon: f64, lat: f64) -> GlobalPoint through libm (asinh, tan), rounded half to even: for the debug tool and the tests only.

Invariants: every position is an integer; tile units to frame units is exact and reversible; metres come from metres_per_unit at the point (or a segment's middle) and enter a position only through one rounding.

3. The tile decoder (src/tile.rs)

Two layers.

Raw decode, the codes of format 4 as they are: pub fn decode(bytes: &[u8]) -> Result<Vec<RawFeature>, DecodeError>, for bytes after gzip. Port the logic of tiles.rs:227-349 and its stream order:

  • RawFeature { kind: String, tags: Tags, geometry: Geometry, fine: bool, parts: Vec<RawPart> }, Tags = BTreeMap<String, String>, Geometry { Point, Line, Area }. fine is the header's has_plan: such a feature counts in quarters also in a part without an alignment, so the frame form reads the bit, not the parts.
  • RawPart { outer: bool, xy: Vec<[i64; 2]>, z: Option<Vec<Option<i64>>> (centimetres), plan: Option<RawPlan> }.
  • RawPlan { along: u64 (along_code − 1), tangent: Vec<i64> (0..1024), grade: Vec<i64> (1/250), bank: Vec<i64> (1/1000), widen: Vec<u64> (cm), side: Vec<u8>, walk: Vec<u8> }.
  • DecodeError names what broke: a number or a string past the end, an index past the string table, an unknown geometry, invalid UTF-8, a coordinate past 2^40 tile units (so no frame point or difference overflows i64), bytes after the last feature. Varints read up to 64 bits; a varint longer than 10 bytes is an error.
  • It decodes specs/vectors/trailview-features.bin to specs/vectors/trailview-features.json.

Frame form: pub fn features(bytes: &[u8], column: u32, row: u32) -> Result<Vec<Feature>, DecodeError> for a zoom-13 tile:

  • Feature { kind, tags, geometry, parts: Vec<Part> }, Part { outer: bool, tile: (u32, u32), own: Vec<bool>, points: Vec<GlobalPoint>, heights: Option<Vec<Option<f64>>> (metres), plan: Option<Alignment> }.
  • Alignment { along_m: f64, backward: bool, tangent: Vec<f64> (radians, code × τ / 1024 with τ from core::f64::consts::TAU), grade: Vec<f64>, bank: Vec<f64>, widen: Vec<f64> (metres), side: Vec<u8>, walk: Vec<u8> }.
  • The decoder sets walk at the last vertex of each part to 0, so two tiles that hold a part give equal values.
  • It keeps the order of the tile. It changes no vertex.
  • Identity: the tiles hold no OSM id. Two features keep one relative order in every tile that holds both (the fixed order of specs/trailview-features.md:94-98). A segment's key is (kind, tags, its two global end points): the same in every tile that holds it, because the cut keeps a segment whole. GP2 takes its ids and tie-breaks from these keys, never from an index of the tile.

Tiles and owners. A cell reads each tile of feature_tiles(). A tile owns its square (spec Buffer) and holds whole each segment, ring edge and point that meets that square (Facts). The owner of an element is the first read tile, in the order (row, column), whose square it meets: a point the half-open square (a point on a tile line belongs to the tile east or south of it), a segment or an edge the closed square, by an exact integer test (tile::segment_meets, tile::owner). The read squares cover the cell grown by its margin, so each element there has one owner, and two cells that read the same tiles pick the same one. Each part gets own, one flag per segment (line), edge (ring) or point: true where its tile is the owner. A join of the cut lies outside its tile's square, so it is never owned. Readers use the owned elements; inside or outside of an area at a point comes from the copy of the tile that owns the point. along_m can jump by up to 10 cm where the owner changes (Facts).

Decode cache. TileCache holds the decoded Vec<Feature> of each tile, own unset, behind an Rc, keyed by (column, row) in a BTreeMap; a tile that the archive does not hold is stored as empty. TileCache::new(capacity); tile(column, row, load: impl FnOnce() -> Option<Vec<u8>>) -> Result<Rc<Vec<Feature>>, DecodeError> decodes on a miss and drops the tile used longest ago (a use counter) past capacity. A decode is pure, so the cache changes no output byte. The plan worker (GP5) and the bake keep one cache each.

CellInput (src/lib.rs):

  • pub struct CellInput { pub key: CellKey, pub features: Vec<Feature>, pub terrain: Terrain }.
  • CellInput::new(key, cache: &mut TileCache, load: impl FnMut(u32, u32) -> Option<Vec<u8>>, pages: Vec<StoredPage>) -> Result<CellInput, DecodeError>: it takes each tile of key.feature_tiles() from the cache, in that order; load gives a tile's decompressed bytes, or None (no features). It copies the parts, sets own, and keeps the parts whose bounding box meets the cell grown by margin(): per part for points and lines that own an element; for areas (all copies) per polygon, an outer ring and its holes as one, by the box of the outer ring. A feature with no kept part goes. Nothing is clipped: GP2 splits at the cell lines.

4. Terrain heights (src/terrain.rs)

Input. pub struct StoredPage { pub level: u8, pub x: u32, pub y: u32, pub offset: f32, pub scale: f32, pub codes: Vec<u16> }: one page of 256 × 256 codes, row by row from north, as the viewer's PageData gives it (texels, offset, scale). level is 13 or 14; the page is the terrain node (level, x, y). 0xffff is unknown. A page that the archive does not hold, or that knows no height, is absent.

  • pub fn pages_from_terrarium(rgba: &[u8], size: usize, z: u32, x: u32, y: u32) -> Result<[Option<StoredPage>; 4], String>: the port of tilePages and pageData (heights.ts:19-38): h as f32, min and max over the known heights of a quadrant, scale in f64 and then stored as f32, code = round((h as f64 − min) / scale). Quadrants north-west, north-east, south-west, south-east are pages (z + 1, 2x + (q & 1), 2y + (q >> 1)). It returns an error for size ≠ 512 or a buffer of another length. The viewer's decode worker gives the same pages; the bake and the tool decode WebP and call this.

Which pages a cell reads. Terrain::wanted(key: CellKey) -> Vec<PageKey>: for each level L of 14 and 13, every page that holds a texel of the square [origin − margin − 2 texels, origin + CELL_UNITS + margin + 2 texels] (a texel of level L is 2^(26−L) frame units, a page 2^(34−L)). PageKey { level, x, y } with tile() -> (z, x, y, quadrant). A caller gives every wanted page that exists, and no other. The viewer (GP5) and the bake hand over the same pages, so the same bytes.

The height. Terrain::new(key: CellKey, pages: Vec<StoredPage>) -> Terrain keeps only the pages of wanted(key), so the heights depend on the cell alone; Terrain::height(&self, p: GlobalPoint) -> Option<f64> (metres):

  1. For L in 14, then 13: let s = 26 − L, v = p − 2^(s−1) per axis, whole = v >> s (arithmetic shift), part = (v & (2^s − 1)) as f64 / 2^s.
  2. Weights spline(t) = 0.5 × (−t + 2t² − t³, 2 − 5t² + 3t³, t + 4t² − 3t³, −t² + t³) for part.x and part.y, as pages.wgsl:25-27.
  3. Read the 16 texels whole + (i − 1, j − 1) for j, i in 0..4. A texel's height is offset + (code as f32) × scale in f32, then f64. If a texel's page is absent or its code is 0xffff, go to the next L.
  4. Else return Σ_j Σ_i h × wx[i] × wy[j] in f64, j outer, i inner. The GPU sums in f32 (pages.wgsl:36-46): at most 32 roundings of half an f32 step, so under 4 mm, and under 1 mm in practice.
  5. After level 13: None.

This is stored_base of pages.wgsl:30-52 with top = 14: step 3 fails over to 13 as the GPU does. The crate stops at 13, the GPU goes on: they differ only where a zoom-12 tile knows no height (sea, no data), and there the crate answers None.

Invariants:

  • The stored r16 codes are those of the GPU, so a stored step (up to about 1.1 cm at level 14 in the Alps) is in the crate's heights too.
  • The crate leaves out the r16 step of the synthesized page: at most half of (relief over a level-18 node) / 65534, 0.8 mm for 100 m of relief.
  • The drawn terrain is the triangle grid of its level over bilinear texels, so it differs from the bicubic by its curvature over 1.63 m. Verification's measurement gates the whole difference.
  • height is a pure function of the pages and the point. It is continuous where all 16 texels are known at one level; it jumps where the level changes, as the GPU's.

5. The cross-section table (src/sections.rs, data/trailview)

Words. A finish is what a way's top is made of, in the order of the mask's surface code (index + 1): main, road, gravel, dirt, grass, path, oneway, paving, rail, narrow, rack, narrow-rack (bins.ts:48). It is not the epic's surface of a face. GP11 reads its code for the look word.

New fields of data/trailview/roads.json, in each class row, after the existing fields:

Field Unit Values Why
half_m m motorway 6, trunk 5, primary 4, secondary 3.25, tertiary 3, unclassified 2.5, residential 2.5, service 2, living_street 2, motorway_link 4.5, trunk_link 4.5, primary_link 4.5, secondary_link 3, tertiary_link 3, road 3, track 3; path 1, footway 1, cycleway 1.5, bridleway 1, steps 1, pedestrian 3, via_ferrata 0.6; rail, light_rail, narrow_gauge, rack, funicular 1.9 The carriageway's half-width without a width tag on a finish without a half_m of its own: today's PAVED, else SURFACES.main or SURFACES.road, capped by PATH_HALF (bins.ts:48-63, :163-168)
shoulder_m m the 7 classes of MAIN 0.6; the other road classes and track 0.4; the path classes 0; the track classes 0.35 The flat strip past the edge where no sidewalk is: SHOULDER_M (bins.ts:52); a track's is the spilt ballast, SPILL_M (section.ts:42); a path has none (shoulderOf)
kerb_m m 0.12 where sidewalk_m > 0, else 0 The kerb's rise over the carriageway's edge: KERB_RISE_M (bins.ts:435)
kerb_top_m m 0.16 where sidewalk_m > 0, else 0 The width of the kerb's top: KERB_TOP_M (section.ts:38)

The existing sidewalk_m, cut, fill and reach are the sidewalk's width and the slopes and their reach of the cross-section; no field repeats them.

New data/trailview/finishes.json: an object with the 12 finishes as keys in code order, each {"half_m": number | null, "shoulder_m": number | null}: main, oneway null and null; road 3 and 0.4; gravel 1.75 and 0.3; dirt 1.5 and 0.25; grass 1.25 and 0.2; path 0.6 and 0; paving 1.25 and 0; rail and rack 1.9 and 0.35; narrow and narrow-rack 1.5 and 0.35. Why: SURFACES and SHOULDER_M (bins.ts:48-52), SPILL_M. A number caps the class's value; null keeps it.

The rules (Sections):

  • Class: class_of(tags) as structures.rs:71-82 (a track is a railway of rail, narrow_gauge, light_rail or funicular with no highway; its class is rack with a rack tag other than no, else its railway; else the highway). The row of that name, else the row path for the kind path, else the row road (bins.ts:105). rank is the row's index in the table.
  • Finish (Finish::of(tags, town: bool)), a port of surfaceOf and trackSurface:
    1. A track: narrow when its gauge (leading integer, as JavaScript's parseInt) is below 1200, else when its railway is narrow_gauge or funicular; rack as above. Gives narrow-rack, narrow, rack or rail.
    2. Else, with main = oneway when the way is one-way (the oneway tag yes, true, 1, -1, reverse, reversible, alternating; with no tag, motorway, motorway_link and junction=roundabout), else main:
      surface of asphalt, paved, concrete, paving_stones, sett, chipseal: main for motorway, trunk, primary, secondary, else road. Of gravel, compacted, fine_gravel, pebblestone: gravel. Of dirt, ground, earth, mud, unpaved, sand: dirt. Of grass, grass_paver: grass. Then paving for town and footway, pedestrian, cycleway, steps. Then path for path, footway, bridleway, steps, pedestrian, via_ferrata. Then track by tracktype: grade1 road, grade2 gravel, grade3 dirt, else grass. Then main for the 7 classes of MAIN, else road.
  • Half-width: not a track, with a width tag whose leading number (JavaScript's parseFloat, as structures.rs:116-126) is finite: max(width / 2, 0.4). Else the class's half_m, capped by the finish's half_m. Then at most HALF_MAX_M = 15 m (specs/trailview-features.md:39-40: the buffer holds the cone of a road up to 30 m wide).
  • Shoulder: the class's shoulder_m, capped by the finish's shoulder_m.
  • Sidewalk, kerb, slopes: the class's sidewalk_m, kerb_m, kerb_top_m, cut, fill, reach. Where a sidewalk is, walk says (GP4).
  • Water: the row of the waterway value in waterways.json, else of the kind (river, stream); half-width = the width tag's leading number / 2 where finite and above 0, else width_m / 2; at most HALF_MAX_M. The water's own cross-section comes with GP14.

These rules give today's half-widths and shoulders in every case: the cap of road gives a link with a paved surface today's 3.0 m and 0.4 m, and every other class that takes road has a half_m of 3 m or less. Two differences are intended: HALF_MAX_M caps a way or water wider than 30 m, and a water width of 0 or less takes width_m (bins.ts:505 takes any finite width).

API:

  • Sections::embedded() -> &'static Sections: the three files through include_str!, parsed once (std::sync::OnceLock). It panics on an invalid table; a test parses the committed tables.
  • Sections::parse(roads: &str, finishes: &str, waterways: &str) -> Result<Sections, String>.
  • Sections::way(&self, kind: &str, tags: &Tags, town: bool) -> WaySection with class: &str, rank: usize, finish: Finish, half_m, shoulder_m, sidewalk_m, kerb_m, kerb_top_m, cut, fill, reach_m (all f64, metres or rise per metre).
  • Sections::water(&self, kind: &str, tags: &Tags) -> WaterSection with half_m, cut, fill, reach_m.
  • pub fn leading_number(&str) -> Option<f64> and leading_integer(&str) -> Option<i64>. GP18 moves the bake onto them.

Validation (parse rejects the table and names the row and the field):

  • each class row has the four new fields as numbers; 0.4 ≤ half_m ≤ 15; shoulder_m, kerb_m, kerb_top_m ≥ 0; kerb_m > 0 and kerb_top_m > 0 exactly where sidewalk_m > 0;
  • finishes.json has exactly the 12 finishes in code order; each value null or a number, half_m from 0.4 to 15;
  • A value by place (an object) is an error for now (epic, section 3).

Reach table. A rule reads data within R_d and changes results within R_e. A chain is the sum of the reaches of the stages that lead to one result. Every chain is at most CHAIN_MAX_M = 191 m (1 m for the Mercator scale over a cell and the rounding to frame units). This is the one list of every reach and chain; each other item states its own values and names it. Values today:

Reach or chain Owner Value
MARGIN_M GP1 192 m
HALF_MAX_M GP1 15 m
greatest reach of roads.json, of waterways.json GP1 10 m, 15 m
R_d, R_e per graph decision (GP2, Reach budget) GP2 R_d up to 70 m
B: GP3's own constructions read data GP3 40 m
H: a height reads faces GP6 51.5 m
heights.window_m past the cell GP6 86 m
D: edge features read heights past the cell GP16 27 m
R_P, R_L: point objects, lamps GP17 12 m, 35 m
chain: way slope, HALF_MAX_M + widen_m + max(shoulder_m, sidewalk_m) + reach (the greatest row sum) GP1 29 m
chain: water bank, HALF_MAX_M + reach GP1 30 m
F: a face reads data, R_d of room_m + R_e of the corner GP2, GP3 70 m + 30 m = 100 m
chain: H + F GP6 151.5 m
chain: window + F GP6 186 m, the longest
cover: D + 5 m + H + 2 m ≤ heights.window_m GP16 85.5 m
cover: max(R_L, R_P + H) + 2 m ≤ heights.window_m GP17 65.5 m

Reader assertion. Sections holds the rows (name, terms, owner; in code the owner is the crate module that owns the row, such as sections, never an issue number), each value from the tables or the owner's constant. parse rejects a chain over CHAIN_MAX_M and a cover past heights.window_m, with the row's name and each term, so a table that breaks the margin never loads. GP1 adds its own rows, later items theirs (Design 6). Only GP6 sets heights.window_m.

6. Interfaces with the other items

Item Takes from GP1 Gives back
GP2 CellInput, Feature, Part (with own), Alignment, GlobalPoint, CellKey::{contains, margin}, metres_per_unit, Sections::way (rank, half_m) Way, Junction, Crossing: GP2 fixes their names and bytes, as it builds them
GP3, GP4 Sections::way, CellPoint, the tool's layers pair tables, verge_m, driveway rules
GP5 CellInput::new, TileCache, CellKey::feature_tiles (the request carries each tile), Terrain::wanted, PageKey::tile, StoredPage (the viewer's PageData) the WASM bridge
GP6 Terrain::height (it steps where the level changes, at a national model's edge: T(x) is not continuous there), Sections::way (cut, fill, reach_m, kerb_m), the reach table the steepest slope, the return grade, the blend radius, H, heights.window_m
GP7 Terrain::height for the strip's inner border the mesh layer and the mesh in the glTF
GP8 the two tables and the rules of section 5, ported to TS
GP14 Sections::water the water's cross-section in waterways.json
GP18 Sections::way, leading_number the bake's half-widths from the table

A later rule field goes into Sections, with its validation and, if it has a reach, its rows in the reach table, in the item that first reads it.

7. The debug tool (examples/debug/)

Command.

obc exec cargo run --release -p obc-ground-plan --example debug -- \
  --places v06,v12,v13,v17,i07-hairpin,b45-bridge-junction \
  [--views builder/web/tests/browser/trailview/road-views-top.json] [--at NAME=LAT,LON]... \
  [--fixture builder/web/tests/browser/trailview/fixture] [--out .artifacts/ground-plan/debug] \
  [--size-m 128] [--px 1600] [--layers terrain,inputs,cells] [--gltf] [--probe N]
  • A place is a view of --views whose name ends in -top; its name is the view's name without -top, and its centre is the lat and lon of the view's view query. --places A,B selects each place whose name is A or starts with A-. --at NAME=LAT,LON adds a place by position. An unknown place is an error that lists the names.
  • --fixture DIR holds config.json, features/13/x/y.bin (gzip) and terrain/z/x/y.webp: the fixture's layout.
  • For each place: the square of --size-m metres about the centre, north up, --px pixels wide. The tool builds the CellInput of each cell that the square meets, from one shared loader (tests/fixture/mod.rs, included with #[path]) with one TileCache: it decodes each tile once and each WebP once. Each layer draws each cell's own content clipped to that cell's square, so every cell line shows two independent builds.

Layers of GP1 (later items add their own; --layers picks them):

  • terrain: per pixel the height of the cell that holds the pixel: a hillshade (light from 315°, 45° up, from the differences of neighbouring pixels), thin contour lines every 1 m and dark ones every 5 m (a pixel whose floor of h / 1 m differs from a neighbour's), magenta where height is None.
  • inputs: each line part as its chords, 1.5 px, by kind; the carriageway of each way of main-road, road, path, railway, tunnel, gallery as a band of its half_m (capsules, half transparent), its shoulder lighter; for each segment with a walk bit, a 1 px line at the sidewalk's outer edge on that side; waterways as bands of their half-width; vertices as dots, a vertex with a side bit as a square; areas filled (buildings grey, water blue, others outlined); points as dots. Ways tagged bridge or tunnel are dashed.
  • cells: the cell lines, the margin square of the centre's cell, the level-18 node lines (faint), the centre as a cross, a scale bar of 10 m.

Outputs in --out: <place>.png; <place>.json with the cells, the tiles read, the feature, part and vertex counts by kind and geometry, the parts with an alignment, the pixels of unknown height, the height range, the widths capped at HALF_MAX_M, the times (decode per tile, the terrain's build, mean nanoseconds per height). With --gltf: <place>.glb, the terrain under the square as one mesh on a 0.5 m grid (x east, y up, z south, metres about the centre and the centre's height), with the hillshade as vertex colours; GP6 and GP7 add their meshes to the same file. With --probe N: <place>.probe.json, N points [lon, lat, height] on level-18 grid vertices (multiples of 64 world units) of the square, free of every stamp: from each way or water line at least its half-width + shoulder + reach (from Sections) + 2 m (the snap); and 5 m outside every area (an area holds no ground past its edge, bins.ts:24-29). With fewer free points, the file holds those, and the stats count them.

Exit codes: 0, or 1 with a message (for a decode error, its tile).

8. Edge cases

  • Empty input: no tile, or the tile [0, 0]: no features from it. No pages: height is None, and the picture is magenta.
  • Malformed tile: DecodeError; the cell has no CellInput: the viewer (GP5, GP9) builds no plan there and shows the far stamp, and the bake's checks report the tile.
  • A far vertex: a cut end's extra vertex can lie kilometres away; i64 holds it.
  • Heights, alignment: z_code 0 is None; a part with along code 0 has plan = None; a tangent sums modulo 1024.
  • Tags: odd width values (3 m, 3,5, ~4, -2, 0, nan, 1e9) follow parseFloat, then 0.4 and HALF_MAX_M; gauge such as 1435;1000 follows parseInt; an unknown surface falls through to the class rules; an unknown highway takes its kind's row.
  • Cell and tile lines: a point on a cell or tile line belongs to the cell or tile east or south of it; a cell within its margin of a tile line reads the tiles across it, and its neighbours' terrain pages.
  • Steep ground: the Catmull-Rom overshoots at a cliff as on the GPU; no clamp.

Plan

  1. If origin/ground-plan does not exist (git ls-remote --heads origin ground-plan), create it from develop: git fetch origin && git push origin origin/develop:refs/heads/ground-plan. Branch claude/gp1-crate-base from origin/ground-plan.
  2. Cargo.toml (root): add "host/obc-ground-plan" to members and obc-ground-plan = { path = "host/obc-ground-plan" } to [workspace.dependencies].
  3. host/obc-ground-plan/Cargo.toml and clippy.toml as Design 1.
  4. src/frame.rs: GlobalPoint, CellKey, CellPoint, FRAME_BITS, CELL_ZOOM, CELL_UNITS, MARGIN_M, EQUATOR_M, metres_per_unit, tile_point, from_lon_lat, with unit tests.
  5. src/tile.rs: decode (raw), features (frame form), TileCache, RawFeature, RawPart, RawPlan, Feature, Part, Alignment, Geometry, Tags, DecodeError, with the vector test.
  6. src/terrain.rs: StoredPage, PageKey, Terrain::{new, wanted, height}, pages_from_terrarium, with unit tests on synthetic pages.
  7. data/trailview/roads.json: the four fields in every row. data/trailview/finishes.json: new. src/sections.rs: Sections, WaySection, WaterSection, Finish, leading_number, leading_integer, the validation and the reach table, with unit tests.
  8. src/lib.rs: the purpose line, the modules, CellInput::new.
  9. tests/fixture/mod.rs: Fixture::open(dir), tile(column, row) -> Option<Vec<u8>>, pages(&[PageKey]) -> Vec<StoredPage>, cell(key) -> CellInput, cells() -> Vec<CellKey> (the cells inside config.json's bounds). tests/fixture.rs: the fixture tests of Verification.
  10. examples/debug/main.rs (options, places, outputs), examples/debug/draw.rs (the layers, tiny-skia), examples/debug/gltf.rs (the GLB writer).
  11. host/obc-trailview-features: Cargo.toml gains [dev-dependencies] obc-ground-plan = { workspace = true }; in src/tiles.rs delete the test-only decode, and its tests decode with obc_ground_plan::tile::decode and turn a RawFeature into the test-only Feature with one small helper (z cm to metres, NaN for None).
  12. builder/web/src/lib/trailview/terrain/bins.test.ts: one test: for every class row and tag variant (no surface; surface asphalt, gravel, dirt, grass; tracktype 1 to 3; town), halfWidth(tags, surfaceOf(tags, town)) and SHOULDER_M (or SPILL_M, or 0 for a path) equal Design 5 on the two tables; the keys of finishes.json are those of SURFACES in order, and each number is its value in SURFACES or SHOULDER_M.
  13. specs/trailview-features.md: Readers add host/obc-ground-plan (src/tile.rs); Test vectors: "The encoder of the bake and the decoders of the readers read both"; Heights: "The other fields of the table are the stamp profile and the cross-section of the engine."
  14. docs/design/trailview.md: owns gains host/obc-ground-plan/**; then obc cairn map.
  15. tools/testing/suites.toml: [[package]] name = "obc-ground-plan", triggers = ["data/trailview/roads.json", "data/trailview/finishes.json", "data/trailview/waterways.json", "specs/vectors/trailview-features.*", "builder/web/tests/browser/trailview/fixture/**"], with a comment line (Cargo cannot see these inputs).
  16. data/trailview/README.md: the row of roads.json names the cross-section; a new row for finishes.json.
  17. host/obc-ground-plan/README.md: build and test, the debug tool and its colour legend, the pitfalls (determinism rules; include_str! of data/trailview).
  18. Run the checks, make the pictures and the measurements, open the pull request into ground-plan with Mode: change #<this issue>, Requirements: none, and "Public docs: none".

Files

  • create: host/obc-ground-plan/ (Plan 3-10, 17), data/trailview/finishes.json.
  • change: Cargo.toml, Cargo.lock (no new external crate); firmware/tools/dependency_rules.json (the crate is a host package); data/trailview/roads.json, data/trailview/README.md; host/obc-trailview-features/Cargo.toml, src/tiles.rs; builder/web/src/lib/trailview/terrain/bins.test.ts; specs/trailview-features.md; docs/design/trailview.md, and docs/design/README.md, map.json by obc cairn map; tools/testing/suites.toml.

Verification

  • Checks:
    • obc test -p obc-ground-plan. The unit tests assert:
      • frame: tile_point and back are exact for zoom 13 in units and in quarters, at both ends of the buffer; CellKey::of and contains put a point on a cell line in one cell; metres_per_unit equals EQUATOR_M × cos(atan(sinh t)) / 2^34 (through libm) within 1e-12 relative at 0°, 47° and 70°; for cells at those latitudes, margin() × the scale at the cell's edge nearer the pole lies in (194 − one frame unit, 194] m (a unit is 2.3 mm at 0°); feature_tiles() gives one tile for a cell in a tile's middle, two at a tile line, four at a corner.
      • tile: trailview-features.bin decodes to trailview-features.json; [0, 0] gives no feature; a truncated tile, an index past the table and trailing bytes give their DecodeError; features puts a quarter unit and a whole unit of one point on one GlobalPoint; walk of each last vertex is 0.
      • terrain: on synthetic pages of a quadratic surface, height equals the quadratic within the r16 step (Catmull-Rom reproduces a quadratic) and equals the texel's value at each texel centre; a point whose 4 × 4 texels cross a page border reads both pages and equals the same quadratic; one unknown texel at level 14 makes the points about it read level 13; unknown at both levels gives None; pages_from_terrarium gives the offset, scale and codes of heights.ts for a 512 px tile with an opaque gradient and a transparent pixel; wanted lists the pages of both levels about a cell at a page corner.
      • sections: the committed tables parse; golden cases from halfWidth and surfaceOf of bins.ts (at least primary with and without surface=gravel, residential + width=3 m, track with and without tracktype=grade1, path + surface=gravel, pedestrian + town, cycleway, railway=rail + gauge=1000, rack=yes, highway=raceway) give the finish, half-width and shoulder; width=60 gives 15; a table with kerb_m but no sidewalk_m, a missing field, a finish out of order, or a chain over 191 m fails with a message that names it.
      • TileCache: two neighbouring cells that read one tile call load once for it; a cache of capacity 1 gives the same CellInput bytes as a large one.
    • tests/fixture.rs (in the same command):
      • neighbour_tiles_agree_where_both_own: for each pair of neighbouring fixture tiles A and B: every segment, ring edge and point of A that meets B's square is in B, with the same global points and heights and the same decoded values per vertex (tangent mod 1024, grade, bank, widen, side; walk per segment). along_m is left out: each tile rounds its part's start by up to 5 cm.
      • each_element_has_one_owner: for each fixture cell whose read tiles are all in the fixture, the owned elements hold no key twice (Design 3), and every element of a read tile that meets the cell grown by margin() has an owned copy.
      • every_fixture_tile_decodes: all 9 tiles decode and print their counts by kind.
      • the_fixture_terrain_is_known_in_every_cell: on a 10 m grid over each fixture cell, height is Some and between 500 m and 3,500 m.
    • obc exec cargo clippy -p obc-ground-plan --all-targets -- -D warnings: no std transcendental, no HashMap or HashSet, in the crate, its tests and the tool.
    • obc test -p obc-trailview-features and obc exec cargo clippy -p obc-trailview-features --all-targets -- -D warnings: the encoder's tests pass with the crate's decoder.
    • npx vitest run src/lib/trailview and npm run check in builder/web: the parity test of the two tables, and the old path's tests unchanged.
    • uv run --locked --group trailview python -m tools.trailview.rules: the ruleset with the new file passes.
    • obc exec cargo fmt --all, obc suites check, obc cairn check, obc prose --check, obc test affected --base origin/ground-plan --dry-run (and run what it selects).
  • Measurements:
    • Times, native release, from the tool's <place>.json at the six places: decode per tile read (the largest, 4287/2887, among them), the terrain's build per cell, nanoseconds per height. No gate (GP7 sets the gates).
    • Terrain against the viewer: drawnHeight is the drawn triangle with the morph (drawn-mesh.wgsl:66-99), so each probe point must lie in a node that draws level 18 at morph 0. With --probe 20 at the six places, a one-off scratchpad script, under flock /tmp/trailview-gpu.lock, opens on the head of ground-plan (old path) a view at each centre, pitch −89, 150 m over the crate's height; it asserts trailView.stats().quality is 0, drops (and counts) each point at a LOD distance (lod.ts:62-90, eye height included) of 300 m or more, below the morph start of 390 m, calls trailView.check(points) as smoke.test.js:38 does and compares probe with the crate's heights. Gate: every difference at most 2 cm (half the floor's 5 cm), over at least 60 points; report the median and p95. Too few points: add an open place with --at.
  • Pictures: a new tool has no "before"; put each debug picture beside GP0's shot of the same -top view on develop.
    • Debug tool, from above, layers terrain,inputs,cells, at v06, v12, v13, v17, i07-hairpin, b45-bridge-junction, and at --at tile-line=46.819166,8.393555, where a secondary road crosses the line between fixture tiles 4286 and 4287. The owner looks for: the relief matches the shot; the ways lie where the shot draws them, with the viewer's widths; sidewalk lines sit where the shot shows sidewalks; lines, bands and contours run on across every cell line and the tile line, with no step; no magenta.
    • The glTF of i07-hairpin (--gltf): no seam at page or cell lines.

Done when

  • The crate is in the workspace as Design describes; its tests, fixture tests and clippy pass.
  • The test-only decoder of obc-trailview-features is gone; its tests pass with the crate's.
  • roads.json has the four fields, finishes.json exists, and the parity test passes.
  • The debug tool's files for the six places and tile-line are in the pull request beside GP0's shots; the probe holds the 2 cm gate; the times are reported.
  • The spec, docs/design/trailview.md, suites.toml and the README of data/trailview change as Plan says.
  • CI is green, the review's findings are resolved, and the pull request has merged into ground-plan.

Out of scope

  • Way, Junction, Crossing, curves, the cell split: GP2. Faces, verge_m, the minimum width, i_overlay: GP3. Sidewalks, driveways, town: GP4. The WASM bridge and the hand-over of tiles and pages: GP5. Heights past the terrain: GP6. The mesh, spade: GP7. The far stamp: GP8. The water's cross-section: GP14. The bake on the table, any rebake: GP18.
  • Any change to the viewer's code or look.

Questions for the owner

Owner decision (2026-11-03): every recommendation in this section is accepted.

  • Lanes. The epic lists "how width and lanes tags change" the half-width. Every primary and secondary of the fixture has a lanes tag, so a lanes rule widens every main road. Recommendation: GP1 leaves lanes out and keeps today's widths; a later change adds a lane_m field with pictures if you want it.
  • Epic note: of section 3's cross-section, GP1 adds the widths, shoulder, kerb and sidewalk; GP3 the verge, minimum width, corner radius and mouth rule; GP6 the steepest slope and return grade; lanes waits (above).

Review notes

  • Kept in part: "dedupe by GP1's segment key": a position rule picks the owner with no lookup and keeps each tile's area copy closed, which an edge dedupe breaks. The key stays GP2's id.

Activity

  1. timohueser commented on Nov 3, 2026

    @timohueser
    OwnerAuthor

    Implementation plan

    Frame. All positions are i64 frame units (2^-34 of the square). tile_point is one shift: exact. margin() uses the scale at the cell edge nearer the pole, so the margin is at least 194 m on the ground at every point of the cell, and at most one unit less than 194 m at that edge.

    Decoder. decode ports the stream order of the bake's decoder. Sums of coordinates and heights wrap, so a malformed tile gives an error or values, never a panic. RawFeature also keeps fine (the has_plan bit of the header): a feature with has_plan 1 counts in quarters also in a part without an alignment, so the frame form needs the bit, not the parts.

    Owner rule. The elements are the segments of a line, the edges of a ring (the last vertex to the first included) and the vertices of a point part. The owner of an element is the first read tile, in the order (row, column), whose square meets it:

    • a point meets the half-open square [0, 16384) of the tile (a point on a tile line belongs to the tile east or south of it);
    • a segment or an edge meets the closed square. The test is exact in integers (separating axes, i128 cross products).
      Invariants: every tile computes the owner from global points and the list of read tiles only, so exactly one copy of each element is owned. The owner holds the element, because its square lies inside its buffered square. A join of a ring cut lies outside the buffered square of its tile, so no read tile that holds it owns it.

    Kept parts. A point or a line part stays when its box meets the closed square of the cell grown by margin() and it owns at least one element. Area parts stay per polygon (an outer ring and its holes) when the box of the outer ring meets the grown square: all copies, owned or not.

    Terrain. Level 14, then 13: 16 texels about the point by Catmull-Rom weights in f64; a texel is offset + code as f32 * scale in f32. A missing page or code 0xffff falls back one level; past level 13 there is no height. wanted lists the pages of each level that hold a texel of the cell grown by the margin and 2 texels.

    Sections. The tables parse with preserve_order, so rank is the row order. way = class row (row of the class, else path for the kind path, else road), finish caps by min, width tag by parseFloat rules, then HALF_MAX_M. GP1's reach rows: MARGIN_M, HALF_MAX_M, the greatest reach of each table, and the chains "way slope" (per row: HALF_MAX_M + max(shoulder_m, sidewalk_m) + reach) and "water bank" (HALF_MAX_M + reach). parse rejects a chain over CHAIN_MAX_M.

    Debug tool. One TileCache and one WebP cache for all places; each layer draws a cell's own content under a clip mask of its cell square (an area copy under the cell square and its tile square).

  2. timohueser commented on Nov 3, 2026

    @timohueser
    OwnerAuthor

    Landed in ground-plan with #3117.

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