Repository navigation
Description
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 ofroads.jsonis 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
imageandtiny-skianever reach the WASM build.
Systems: trailview
Contracts:specs/trailview-features.md(Readers, Test vectors, one sentence on the class table);docs/design/trailview.md(ownsgainshost/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; nokeepofdata/trailview/kinds.jsonnames 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_codeis 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.tsandtools/planner_verify.py. The encoder's owndecodeis 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 asscale.x + f32(raw) * scale.yin f32 (terrain/drawn-height.wgsl:143-149). - Synthesized pages (levels 15 to 18) take the Catmull-Rom of the deepest stored level up to
topthat 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)returnsdrawnHeightat[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 usesEARTH_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'sroad_halfwith 6 m for every main class (structures.rs:26-41,:96-112). - A link with a paved
surfacegets the finishroad, 3.0 m and a 0.4 m shoulder today; an untagged onemain, 4.5 m and 0.6 m (bins.ts:141,:166,SHOULDER_M). The fixture has no link. - In the fixture, every
primary(23) andsecondary(15) feature has alanestag; no viewer code readslanes. - The feature step's options keep only the
CLASS_FIELDSofroads.json(kinds.rs:17-27,:205-212): new fields do not rebake the features. The ruleset digest covers every JSON file ofdata/trailview/(planner.rs:1161-1180): the next bake runs the cheaptrailview-rulesstep again, and itsrules.jsondoes not holdroads.json. serde_jsonwithoutpreserve_ordersorts object keys; its float parse depends onfloat_roundtrip.obc-trailview-featuresenables 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 inCargo.lock).tiny-skia0.11.4 andimage0.25.10 are inCargo.lock. Rust never fuses a multiply and an add unless the code callsmul_add.- clippy 0.1.99 reports
f64::sin,f64::powi,f64::hypotindisallowed-methodsandstd::collections::HashMapindisallowed-types. tools/testing/suites.toml:34-37lists the data files that triggerobc-trailview-features: Cargo cannot see them.road-views-top.jsondoes not exist on4f8b8b255: GP0 adds it. A view ofroad-views.jsonhasnameand aviewquery (?lat=…&lon=…&heading=…), nolatorlonfields.
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) withfeatures = ["preserve_order", "float_roundtrip"], so every build parses the tables the same. Noi_overlayorspadeyet: GP3 and GP7 add them. - Dev-dependencies (tests and tool only):
flate2,imagewithpngandwebp,tiny-skia = { version = "0.11", default-features = false, features = ["std", "simd"] }. - Determinism rules, enforced by
host/obc-ground-plan/clippy.tomland-D warnings:disallowed-methods: forf64andf32: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,maxstay: 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 insrc/.src/lib.rsholdsCellInputand the modulesframe,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 >> 18per axis.origin() -> GlobalPoint;contains(p) -> boolwithorigin ≤ p < origin + CELL_UNITSon 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, wherey_poleis the cell's edge nearer the pole (north edge fory < 2^33). The 2 m: a curve leaves its chord by up to 2 m (spec, Alignment), so the curve withinMARGIN_Mlies on segments that meet the cell grown bymargin().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 bymargin()meets, in the order (row, column): one to four.local(p) -> Option<CellPoint>andglobal(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 insidei32and insidei_overlay's range.localreturnsNonefor a point pasti32; GP2 clips segments ini64before 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'smetres(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) << swith k = 14 (16 forfine) and s = 34 − z − k. It rejectsz > 18. Exact.pub fn from_lon_lat(lon: f64, lat: f64) -> GlobalPointthroughlibm(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 }.fineis the header'shas_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> }.DecodeErrornames 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 overflowsi64), 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.bintospecs/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 τ fromcore::f64::consts::TAU), grade: Vec<f64>, bank: Vec<f64>, widen: Vec<f64> (metres), side: Vec<u8>, walk: Vec<u8> }.- The decoder sets
walkat 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 ofkey.feature_tiles()from the cache, in that order;loadgives a tile's decompressed bytes, orNone(no features). It copies the parts, setsown, and keeps the parts whose bounding box meets the cell grown bymargin(): 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 oftilePagesandpageData(heights.ts:19-38): h asf32, min and max over the known heights of a quadrant, scale inf64and then stored asf32, 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 forsize ≠ 512or 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):
- 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. - Weights
spline(t) = 0.5 × (−t + 2t² − t³, 2 − 5t² + 3t³, t + 4t² − 3t³, −t² + t³)forpart.xandpart.y, aspages.wgsl:25-27. - Read the 16 texels
whole + (i − 1, j − 1)for j, i in 0..4. A texel's height isoffset + (code as f32) × scaleinf32, thenf64. If a texel's page is absent or its code is0xffff, go to the next L. - Else return
Σ_j Σ_i h × wx[i] × wy[j]inf64, j outer, i inner. The GPU sums inf32(pages.wgsl:36-46): at most 32 roundings of half anf32step, so under 4 mm, and under 1 mm in practice. - 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.
heightis 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)asstructures.rs:71-82(a track is arailwayofrail,narrow_gauge,light_railorfunicularwith nohighway; its class israckwith aracktag other thanno, else itsrailway; else thehighway). The row of that name, else the rowpathfor the kindpath, else the rowroad(bins.ts:105).rankis the row's index in the table. - Finish (
Finish::of(tags, town: bool)), a port ofsurfaceOfandtrackSurface:- A track: narrow when its
gauge(leading integer, as JavaScript'sparseInt) is below 1200, else when itsrailwayisnarrow_gaugeorfunicular; rack as above. Givesnarrow-rack,narrow,rackorrail. - Else, with
main=onewaywhen the way is one-way (theonewaytagyes,true,1,-1,reverse,reversible,alternating; with no tag,motorway,motorway_linkandjunction=roundabout), elsemain:
surfaceofasphalt,paved,concrete,paving_stones,sett,chipseal:mainformotorway,trunk,primary,secondary, elseroad. Ofgravel,compacted,fine_gravel,pebblestone:gravel. Ofdirt,ground,earth,mud,unpaved,sand:dirt. Ofgrass,grass_paver:grass. Thenpavingfortownandfootway,pedestrian,cycleway,steps. Thenpathforpath,footway,bridleway,steps,pedestrian,via_ferrata. Thentrackbytracktype:grade1road,grade2gravel,grade3dirt, elsegrass. Thenmainfor the 7 classes ofMAIN, elseroad.
- A track: narrow when its
- Half-width: not a track, with a
widthtag whose leading number (JavaScript'sparseFloat, asstructures.rs:116-126) is finite:max(width / 2, 0.4). Else the class'shalf_m, capped by the finish'shalf_m. Then at mostHALF_MAX_M = 15m (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'sshoulder_m. - Sidewalk, kerb, slopes: the class's
sidewalk_m,kerb_m,kerb_top_m,cut,fill,reach. Where a sidewalk is,walksays (GP4). - Water: the row of the
waterwayvalue inwaterways.json, else of the kind (river,stream); half-width = thewidthtag's leading number / 2 where finite and above 0, elsewidth_m / 2; at mostHALF_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 throughinclude_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) -> WaySectionwithclass: &str,rank: usize,finish: Finish,half_m,shoulder_m,sidewalk_m,kerb_m,kerb_top_m,cut,fill,reach_m(allf64, metres or rise per metre).Sections::water(&self, kind: &str, tags: &Tags) -> WaterSectionwithhalf_m,cut,fill,reach_m.pub fn leading_number(&str) -> Option<f64>andleading_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 > 0andkerb_top_m > 0exactly wheresidewalk_m > 0; finishes.jsonhas exactly the 12 finishes in code order; each value null or a number,half_mfrom 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
--viewswhose name ends in-top; its name is the view's name without-top, and its centre is thelatandlonof the view'sviewquery.--places A,Bselects each place whose name is A or starts withA-.--at NAME=LAT,LONadds a place by position. An unknown place is an error that lists the names. --fixture DIRholdsconfig.json,features/13/x/y.bin(gzip) andterrain/z/x/y.webp: the fixture's layout.- For each place: the square of
--size-mmetres about the centre, north up,--pxpixels wide. The tool builds theCellInputof each cell that the square meets, from one shared loader (tests/fixture/mod.rs, included with#[path]) with oneTileCache: 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 whereheightisNone.inputs: each line part as its chords, 1.5 px, by kind; the carriageway of each way ofmain-road,road,path,railway,tunnel,galleryas a band of itshalf_m(capsules, half transparent), its shoulder lighter; for each segment with awalkbit, 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 asidebit as a square; areas filled (buildings grey, water blue, others outlined); points as dots. Ways taggedbridgeortunnelare 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:heightisNone, and the picture is magenta. - Malformed tile:
DecodeError; the cell has noCellInput: 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;
i64holds it. - Heights, alignment:
z_code0 isNone; a part withalongcode 0 hasplan = None; a tangent sums modulo 1024. - Tags: odd
widthvalues (3 m,3,5,~4,-2,0,nan,1e9) followparseFloat, then 0.4 andHALF_MAX_M;gaugesuch as1435;1000followsparseInt; an unknownsurfacefalls through to the class rules; an unknownhighwaytakes 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
- If
origin/ground-plandoes 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. Branchclaude/gp1-crate-basefromorigin/ground-plan. Cargo.toml(root): add"host/obc-ground-plan"tomembersandobc-ground-plan = { path = "host/obc-ground-plan" }to[workspace.dependencies].host/obc-ground-plan/Cargo.tomlandclippy.tomlas Design 1.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.src/tile.rs:decode(raw),features(frame form),TileCache,RawFeature,RawPart,RawPlan,Feature,Part,Alignment,Geometry,Tags,DecodeError, with the vector test.src/terrain.rs:StoredPage,PageKey,Terrain::{new, wanted, height},pages_from_terrarium, with unit tests on synthetic pages.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.src/lib.rs: the purpose line, the modules,CellInput::new.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 insideconfig.json's bounds).tests/fixture.rs: the fixture tests of Verification.examples/debug/main.rs(options, places, outputs),examples/debug/draw.rs(the layers, tiny-skia),examples/debug/gltf.rs(the GLB writer).host/obc-trailview-features:Cargo.tomlgains[dev-dependencies] obc-ground-plan = { workspace = true }; insrc/tiles.rsdelete the test-onlydecode, and its tests decode withobc_ground_plan::tile::decodeand turn aRawFeatureinto the test-onlyFeaturewith one small helper (zcm to metres, NaN forNone).builder/web/src/lib/trailview/terrain/bins.test.ts: one test: for every class row and tag variant (nosurface;surfaceasphalt,gravel,dirt,grass;tracktype1 to 3;town),halfWidth(tags, surfaceOf(tags, town))andSHOULDER_M(orSPILL_M, or 0 for a path) equal Design 5 on the two tables; the keys offinishes.jsonare those ofSURFACESin order, and each number is its value inSURFACESorSHOULDER_M.specs/trailview-features.md: Readers addhost/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."docs/design/trailview.md:ownsgainshost/obc-ground-plan/**; thenobc cairn map.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).data/trailview/README.md: the row ofroads.jsonnames the cross-section; a new row forfinishes.json.host/obc-ground-plan/README.md: build and test, the debug tool and its colour legend, the pitfalls (determinism rules;include_str!ofdata/trailview).- Run the checks, make the pictures and the measurements, open the pull request into
ground-planwithMode: 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, anddocs/design/README.md,map.jsonbyobc cairn map;tools/testing/suites.toml.
Verification
- Checks:
obc test -p obc-ground-plan. The unit tests assert:frame:tile_pointand back are exact for zoom 13 in units and in quarters, at both ends of the buffer;CellKey::ofandcontainsput a point on a cell line in one cell;metres_per_unitequalsEQUATOR_M × cos(atan(sinh t)) / 2^34(throughlibm) 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.bindecodes totrailview-features.json;[0, 0]gives no feature; a truncated tile, an index past the table and trailing bytes give theirDecodeError;featuresputs a quarter unit and a whole unit of one point on oneGlobalPoint;walkof each last vertex is 0.terrain: on synthetic pages of a quadratic surface,heightequals 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 givesNone;pages_from_terrariumgives the offset, scale and codes ofheights.tsfor a 512 px tile with an opaque gradient and a transparent pixel;wantedlists the pages of both levels about a cell at a page corner.sections: the committed tables parse; golden cases fromhalfWidthandsurfaceOfofbins.ts(at leastprimarywith and withoutsurface=gravel,residential+width=3 m,trackwith and withouttracktype=grade1,path+surface=gravel,pedestrian+ town,cycleway,railway=rail+gauge=1000,rack=yes,highway=raceway) give the finish, half-width and shoulder;width=60gives 15; a table withkerb_mbut nosidewalk_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 callloadonce for it; a cache of capacity 1 gives the sameCellInputbytes 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;walkper segment).along_mis 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 bymargin()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,heightisSomeand between 500 m and 3,500 m.
obc exec cargo clippy -p obc-ground-plan --all-targets -- -D warnings: no std transcendental, noHashMaporHashSet, in the crate, its tests and the tool.obc test -p obc-trailview-featuresandobc 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/trailviewandnpm run checkinbuilder/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>.jsonat the six places: decode per tile read (the largest, 4287/2887, among them), the terrain's build per cell, nanoseconds perheight. No gate (GP7 sets the gates). - Terrain against the viewer:
drawnHeightis 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 20at the six places, a one-off scratchpad script, underflock /tmp/trailview-gpu.lock, opens on the head ofground-plan(old path) a view at each centre, pitch −89, 150 m over the crate's height; it assertstrailView.stats().qualityis 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, callstrailView.check(points)assmoke.test.js:38does and comparesprobewith 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.
- Times, native release, from the tool's
- Pictures: a new tool has no "before"; put each debug picture beside GP0's shot of the same
-topview 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.
- Debug tool, from above, layers
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-featuresis gone; its tests pass with the crate's. roads.jsonhas the four fields,finishes.jsonexists, and the parity test passes.- The debug tool's files for the six places and
tile-lineare 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.tomland the README ofdata/trailviewchange 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
widthandlanestags change" the half-width. Everyprimaryandsecondaryof the fixture has alanestag, so alanesrule widens every main road. Recommendation: GP1 leaveslanesout and keeps today's widths; a later change adds alane_mfield 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;
laneswaits (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
timohueser commentedon Nov 3, 2026
Implementation plan
Frame. All positions are
i64frame units (2^-34 of the square).tile_pointis 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.
decodeports 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.RawFeaturealso keepsfine(thehas_planbit of the header): a feature withhas_plan1 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:
[0, 16384)of the tile (a point on a tile line belongs to the tile east or south of it);i128cross 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 isoffset + code as f32 * scaleinf32. A missing page or code0xfffffalls back one level; past level 13 there is no height.wantedlists 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, sorankis the row order.way= class row (row of the class, elsepathfor the kindpath, elseroad), finish caps bymin, width tag byparseFloatrules, thenHALF_MAX_M. GP1's reach rows:MARGIN_M,HALF_MAX_M, the greatestreachof 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).parserejects a chain overCHAIN_MAX_M.Debug tool. One
TileCacheand 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).timohueser commentedon Nov 3, 2026
Landed in
ground-planwith #3117.