Skip to content

TrailView ground plan GP13: railways and steps: rails, sleepers, rack and cable, platforms, level crossings with gates and lights, step treads #3106

Open

Description

@timohueser

Status: approved
Part of #3096. One pull request into ground-plan.
Depends on: GP12 (and through it #3112 (GP3) to #3104 (GP11)), #3109 (GP18)
Blocked by: the owner's answers to Questions 1 and 4; both change GP3, GP6 and the epic.

TL;DR

Goal: On the new path, every track near the eye has rails, sleepers, a rack or a haul cable built along its curve, every platform is a face at its height with walls and a coping, every level crossing has flush rails in the road and its barriers, lights and crosses at the right spots, and every flight of steps has its stone treads or its logs, the same in every cell.
Problem: On the new path no track, platform or flight has details: GP8 turned the corridors off, and the crate builds only faces, heights, mesh and decks. Today's details (roads/tracks.ts) come from corridor stations, end where a road crosses, and divide a flight by the length that one tile holds, so two cells can disagree. Level crossings have no flush rails and no equipment. Platforms are slabs of structures/rails.ts that sit 7 cm over the rail heads.
Decision: A new crate stage, details, sweeps the rail, rack and cable profiles of tracks.ts along each track's curve (refined to 1 cm), puts sleepers, rollers and logs at global stroke metres or heights, and builds town treads per span. Inside crossing faces the rails become flush strips. A track's z is the top of its rails (the spec's datum), so every face whose owner rule reads a track lies RAIL_TOP_M under it. A crossing face takes the track's plane at the rail tops, and the road returns to its own heights over a blend ramp. Platforms get walls on every free edge, a platform look and a coping. The placement module puts level crossing equipment as Objects from the tags of GP18's kind, else from table defaults; the viewer draws them with today's part meshes.
Rejected:

  • Keep tracks.ts on the new path: it reads corridor stations, which the new path does not build, and it is not the same in every cell.
  • Rails as instanced 1 m parts: they kink in curves and show seams.
  • Flush rails painted by the road look: the road faces would need a distance to each rail per vertex, a second input for one case.
  • A crossing face at the road's height (the epic's words): the rails would lie up to 0.3 m off the road surface inside the face (Question 4).
  • Keep today's datum (bed toe at z): every level crossing becomes a hump of 0.48 m, and platforms stay 7 cm over the rails (Question 1).
  • Skip a sleeper that overlaps another track's sleepers: the rails over it then float over the ballast.
  • Equipment as triangles of the piece: its models would exist twice, in the crate and in parts.ts.
    Systems: trailview
    Contracts: none (data/trailview/placement.json is a rule table; specs/trailview-features.md keeps its words, and GP18 holds the level crossing kind)
    Size: L (the epic says M): a crate stage, a placement module, and changes in GP3, GP6, GP12, GP7, GP8, GP11, GP9's renderer, GP5's bridge and GP1's debug tool; about 1,300 changed lines in Rust, 400 in TypeScript and WGSL; no format change. One pull request, as the epic plans one item.

Facts

  • A track vertex has the height of its rails (specs/trailview-features.md:127-128). The class table lists the tracks first, so at a level crossing the road meets the track (:131-133). A road banks through a level crossing (:250-251).
  • A platform vertex lies 0.55 m, or 0.35 m for a narrow gauge, over the rail of the nearest track within 15 m (specs/trailview-features.md:361-363, host/obc-trailview-features/src/rails.rs:27-30). A platform with no track near has no heights (rails.rs:180-184).
  • Today's viewer puts the bed's toe at the line's z, the ballast top at z + LIFT_M + BED_M (0.28 m) and the sleeper top at SLEEPER_TOP_M = LIFT_M + BED_M + 0.05 (0.33 m) (roads/section.ts:29, roads/parts.ts:27-28). The rail is 0.125 m high, scaled 1.2 for a standard gauge (roads/tracks.ts:19, :41). So today's rail tops lie 0.48 m over z, and a platform 0.07 m over them.
  • Rail middles lie 0.7525 m (standard) or 0.53 m (narrow) from the track's middle; sleepers are 2.6 m or 1.8 m long, 0.26 m wide, 0.12 m deep (roads/parts.ts:27-32). The shaders hold the same values (roads/track-looks.wgsl:9-13).
  • Narrow means a gauge under 1200 mm, else the class narrow_gauge or funicular; rack means a rack tag other than no (terrain/bins.ts:155-160, rails.rs:40-49). Timber sleepers stand on funiculars and rack lines; a funicular has a haul cable on rollers every 8 m (roads/tracks.ts:25, :39-43, :89-96).
  • Rail classes have bank 0 in data/trailview/roads.json:2-6, so a track never banks.
  • Today a sleeper stands at each whole count of sleepers, a count that is whole at each tile vertex, about 0.6 m apart (terrain/bins.ts:404-416, terrain/stamp-core.wgsl:62). The ballast look paints sleepers and rails from fract(along) and across from 140 m on (roads/looks.wgsl:450-460), and the detail faces fade out from 140 m to 190 m (roads/track-looks.wgsl:5-8, :39-47; roads/corridor.wgsl:218). Corridors cull details past DETAIL_END_M = 190 (roads/roads.ts:20).
  • Rails end where a road crosses the track: stopped drops every station with CUT.ROAD (roads/tracks.ts:16, :180). There are no flush rails.
  • Town steps: count = round(rise / 0.16), tread = clamp(total / count, 0.26, 1.6), n = round(total / tread) over the run's whole length; a tread lies at the level of its higher end plus 4 cm; risers face down; cheeks reach the drawn ground (roads/tracks.ts:99-130). total is the length that one tile holds, so a flight across a tile border splits differently in two tiles.
  • Trail steps: a log where the way crosses a height k × 0.2 m, for each k that is a multiple of m = ceil(0.9 × |grade| / 0.2); a crossing of the same height within 0.9 m lays none; a flight with crossings but no kept log lays one log at the height nearest its middle (roads/tracks.ts:132-158). A hash of k gives each log its length, turn and shift (:167-176). The owner approved this look in TrailView G4: log steps on trails #3060.
  • A way frays (gravel, dirt or trail look) gets logs, else stone treads (roads/section.ts:75, roads/tracks.ts:182).
  • Part meshes are fixed: each row has its faces, one material and one surface code (roads/parts.ts:52-62). An instance has 16 bytes: whole world units x and y, z (float32), and a word with the turn (16 bits), the fine x and y (4 bits each) and the grade (8 bits, 1/64 steps) (roads/piece.ts:18-19, :112-117, :133-140). The part mesh of a log has its axis at LIFT_M + 0.03 over the instance's z (roads/parts.ts:39-45).
  • Track details live in pieces of level 18 that cast shadows (roads/mesh.ts:77-83, roads/piece.ts:161).
  • Materials 31 to 39 are the track and step details; 40 to 49 are the roadside details, and 43, 47 and 50 up are free on develop (roads/section.ts:17, :19; roads/details.wgsl:7-14; roads/looks.wgsl:62). GP11 takes 4 and 50 (MAT.CUT_WALL).
  • GP11 gives the rail bed LOOK_BALLAST with along in sleepers, platforms MAT_SIDEWALK with across 2 and half 12 (GP11).
  • GP3 ranks carriageway, junction, platform, rail_bed, then the shoulders; the least key wins, so two overlapping beds become one face of one track. A patch that a road's Carriageway wins and a RailBed covers becomes Crossing, with crossing the least rail way. platform_reach_m is 3 (GP3, 4.7, 4.8, table). GP6's blend_radius_m is 10 m.
  • structures/rails.ts draws, at every distance: the masts, the contact wire 5.5 m over z, and the platform slabs with sides 0.5 m into the drawn surface, in flat colours (structures/rails.ts:12-58, :112-161).
  • kinds.json keeps railway, gauge, electrified, rack, bridge, bridge:structure and layer on railway (classes rail, narrow_gauge, light_rail, funicular; no tram); nothing on platform; width on platform-line (data/trailview/kinds.json:53-73). It has no kind for railway=level_crossing; GP18 adds it with crossing:barrier, crossing:light and crossing:saltire, and keeps railway and these tags on crossing: a node with highway=crossing stays a crossing.
  • GP2 gives Crossing { pos, over, under, kind: LevelCrossing, source, angle_rad, owned } for a road or path over a ground rail within snap_height_m, at a shared vertex or by rule; a crossing under 20° is no crossing, and GP3's overlay decides (GP2, stage 4). GP2 samples every curve on a dyadic grid of the stroke metres with a sag test that reads only the interval, and breaks it at every cell line. along jumps by up to about 10 cm, forward or backward, at a zoom-13 border, which is a cell line (GP2, Arc).

Design

1. The rail datum

  • A track's curve height z(u) is the top of its rails, as the spec says.
  • RAIL_TOP_M[gauge] = SLEEPER_UP_M + RAIL_HIGH_M × scale: 0.05 + 0.15 = 0.20 m (standard), 0.05 + 0.125 = 0.175 m (narrow). Code constants, mirrored from parts.ts and tracks.ts (section 9).
  • The bed's owner height at a point with across a (metres, left positive) and foot u: bed(u, a) = z(u) + bank(u) × a − RAIL_TOP_M. GP13 puts this offset into the owner rule of every face whose owner rule reads a track's curve: rail beds on the ground, GP12's rail decks, and the host parts of a track junction (a switch). The crossing face is the one exception (section 2).
  • GP8's far stamp takes the same datum: the core plane of a RAIL way lies at z − RAIL_TOP_M[gauge]. So the far stamp and the plan agree at the end of the mesh range.
  • Sleeper tops lie at bed + SLEEPER_UP_M (0.05 m). Rail feet stand on the sleeper tops. Rail heads end at z exactly.
  • So a platform (bake: z + 0.55) lies 0.55 m over the rail heads, and a road that meets the track at a shared vertex meets the rail tops.

2. Level crossing faces and the road's ramp

GP13 changes GP3 in two places:

  • A patch whose winner is a RailBed and that a road's shoulder candidate also covers becomes Crossing too, with the road's owner and material. So the shoulders inside the bed are crossing face.
  • ranks puts rail_bed before platform. Reason: OSM often draws a platform to the track's middle, and it would then cover the rails. GP6's wall stands at their shared edge all the same.

Heights:

  1. Crossing face: Owner(track, rail tops): the height at a point is z(u_f) + bank(u_f) × a, where u_f is the foot of the point on the track's curve and a its across. So the rail tops are flush everywhere in the face. GP3 gives each patch the least rail way that covers it. Where two beds overlap (a switch in the road), the face takes that track's plane, and the other track's rail tops differ from it by the few centimetres of a switch.
  2. Ramp: the points of C's boundary that touch a face of its road are sampled at C's vertices and where the boundary meets the normal lines of the road's global stroke metres k × 0.5 m. At each sample b: dh(b) = |crossing height(b) − road owner height(b)| and L(b) = clamp(dh(b) / return_grade(road class), RAMP_MIN_M, blend_radius_m), with GP6's return_grade (0.15 for roads, 0.3 for paths) and GP6's blend_radius_m (10 m) as the cap. RAMP_MIN_M = 0.5 m (a code constant: shorter ramps are below the mesh's edge length). The ramp region is the union of the capsules of radius max(L(b_i), L(b_i+1)) around each boundary piece between two neighbouring samples (i_overlay offsets), cut to the road's carriageway, shoulder and junction area faces, minus C, then GP3's minimum width rule. These faces become blend faces. They join every blend part that they touch, so the two sides of a double track and the strip between them are one blend face. They keep their owner, surface, material, GP11's frame and markings; only their height rule changes.
  3. The blend rule of GP6 then interpolates between the crossing faces' edges and the road's owner edges at distance L. Sidewalks and kerbs follow by the kerb offset rule; slope bands follow by the slope rule.
  4. dh(b) and L(b) read only the two curves near b, and a ramp point reads only samples within 10 m. So stage 2 knows the ramps before any height is solved, and two cells give the same faces, also for a crossing face longer than the margin (a light rail along a street).
  5. The edge between a crossing face and the rail bed is a step edge (the bed lies RAIL_TOP_M lower): rule 6 of GP6 makes it. GP13 adds a row to GP11's vertical table: a wall whose higher side is a crossing or platform face takes MAT.PLATFORM (concrete).

With the spec's datum, dh(b) is the road's bank and grade across the bed: a few centimetres, at most about 0.3 m on a banked main road. A capped ramp is counted (ramp_capped).

3. Rails, rack and cable (details/rails.rs)

Input: the Ways of family Rail of the cell's graph on levels Ground and Deck, with their samples; the plan's faces with their surfaces; GP6's height function.

  1. Samples of a rail sweep: GP2's samples of the way, refined on GP2's dyadic grid by GP2's sag test with RAIL_SAG_M = 0.01 m in plan (with outer_m = gauge + 0.05) and in height, down to GP2's MIN_STEP_M. Reason: a sleeper and the rail over it must agree within 1 cm. The test reads only its interval, so the samples are the same in every cell.
  2. Ring at a sample: p(u), the unit tangent t(u) from the curve (not from chords), the left normal n(u). For each point (a, up) of a profile: plan position p + n × a, height bed(u, a) + SLEEPER_UP_M + up × scale. Profiles from tracks.ts: RAIL at a = ±g + a_k (g the rail middle), RACK at the middle on rack lines, CABLE at the middle on funiculars.
  3. Segments: each sample interval of the way gives one quad strip per profile edge. The cell that holds the midpoint of the interval's centre line builds it; the piece is the level-18 node of that midpoint. GP2 breaks every curve at the cell lines, so no interval crosses a cell line, and two cells meet at one ring, which both compute from the same curve.
  4. Where rails run: the rail's own middle line (offset ±g) is cut against the plan's faces. In any rail bed, track junction area or rail deck face of its level: the 3D profile. At a switch GP3 gives the two beds to one track, and that bed carries both tracks' rails. In a crossing face: flush strips (step 5). Elsewhere (a building, another carriageway that GP3 put first, a gap): none. Where a run ends on a step edge whose top is at or over the rail top (the wall into a crossing face), its last segment is clipped to the edge line and has no cap: the wall closes it, and no face lies in the wall's plane. Every other run ends at the cut point with a cap: the ring's polygon as a fan. A curve of radius under g + 0.1 m at a sample also ends the run (counted rail_tight), so an inner rail never folds.
  5. Flush strips: inside a crossing face, each rail is two flat strips at the face's height plus FLUSH_LIFT_M = 0.004 m: the head, [−0.031, 0.031] m about the rail middle, LOOK.RAIL_HEAD; and the flangeway, 0.045 m wide on the inner side, LOOK.RAIL. The 3D rail top meets them within 4 mm. Reason for the lift: the strip lies on the road face and must win the depth test to 190 m with the detail bias of today's details.
  6. Tunnels: a Tunnel way has no details; the ground way's face ends at the portal line, and its rails end there with a cap.
  7. Vertex attributes: the look word of tracks.ts (LOOK.RAIL, RAIL_HEAD, RACK, CABLE, the track's surface code, flags 0), across = a in metres, along = (along_m − base) / SLEEPER_M with GP11's base (the sleeper count, so rack_look draws its rungs as today). The normal field is 0: detail materials shade from screen derivatives (section 7).

4. Sleepers and rollers

  1. Positions: a sleeper's middle stands at along_m = k × SLEEPER_M on GP2's stroke metres, SLEEPER_M = 0.6 m (as stamp-core.wgsl:62), for every whole k with that position on a ground or deck way piece. So the near sleepers lie on the painted ones of looks.wgsl:452 and GP11's frame. Every cell counts from the same start (epic, section 13).
    Zoom-13 border: let a_P be the along at the border from the tile on the side of lower along, and a_N from the other tile; both tiles lie in the work area of every cell that holds the border. The side of higher along keeps only the k with k × SLEEPER_M ≥ a_P. So a backward jump (a_N < a_P) doubles no sleeper, and the gap at the border is 0.5 m to 0.7 m.
  2. Pose: the point p(u) where along(u) = along_m (GP2's arc table, then a fixed number of Newton steps, so native and WASM agree), heading from t(u), grade = dz/ds of the curve. Instance z = bed(u, 0) − PART_BASE_M[sleeper], with PART_BASE_M = LIFT_M + BED_M = 0.28 m for sleepers, timbers and rollers, so the part's top lands at bed + 0.05 (section 9).
  3. Footprint test: the sleeper's four corners and middle must lie in rail bed, track junction area or rail deck faces of its level, of any track. Else it goes (crossing faces, a street that a light rail runs along), counted sleeper_skipped.
  4. Stacking: where a sleeper's footprint overlaps the sleeper band (|across| ≤ sleeper half) of another track that comes first by class rank, then the global position (x, then y) of its sample nearest the overlap (as GP2; tiles hold no OSM id), the sleeper stands SLEEPER_STACK_M = 0.01 m lower per such track. So two sleepers never share a top at a switch or a diamond, and the rails over them still rest on sleepers. Its rails keep their height.
  5. Model: SLEEPER or SLEEPER_NARROW (concrete), TIMBER or TIMBER_NARROW on funiculars and rack lines, as gaugeOf in tracks.ts.
  6. Rollers: on funiculars, a ROLLER at along_m = k × 8 m, posed as a sleeper, with the border rule of step 1.

5. Steps (details/steps.rs)

A flight is a way piece of class steps. Its owner face and ramp come from GP3 and GP6. Its kind follows its look word: gravel, dirt or trail (today's frays) gives logs, every other look gives stone treads.

Stretches: the flight's curve breaks at every tile vertex (the span ends of format 4) and at every point where its middle line enters or leaves its own faces (at a seam, at a crossing face). A stretch inside its own faces gets treads; a stretch outside gets none. A span is whole in every tile that holds it, and the face cuts read only faces within the margin, so the stretches are the same in every cell.

Stone treads per stretch [s0, s1] (metres along, length S, rise R = |z(s1) − z(s0)|), with today's constants RISE_M 0.16, TREAD_MIN_M 0.26, TREAD_MAX_M 1.6, TREAD_LIFT_M 0.04:

  1. If S < 0.1 m, the stretch joins its neighbour in the same span, or has no tread if it has none.
  2. count = max(1, round(R / RISE_M)), tread = clamp(S / count, TREAD_MIN_M, TREAD_MAX_M), n = max(1, round(S / tread)); tread k spans [s0 + kS/n, s0 + (k+1)S/n].
  3. A tread's level is the higher of the plan's heights at its two ends on the middle line, plus TREAD_LIFT_M. Its half-width is min(h, clamp(0.8 h, 0.6, 1.4)), h the flight's carriageway half from GP1's cross-section, so it stays on its own face.
  4. Between two neighbouring treads whose levels differ by more than 1 cm: a riser at their shared end, facing down the flight. Neighbours across a span end are neighbours too.
  5. At an end with no neighbouring tread (the flight's two ends, a seam): an end riser from the plan's height at that point up to the tread's level, if it is more than 1 cm higher. So the first step stands at the seam.
  6. Cheeks on both sides of each tread, from its level down to the plan's height at the side point minus CHEEK_SINK_M 0.05 m, so no gap opens on a slope. A cheek whose ground lies over its level is left out.
  7. Attributes as tracks.ts: LOOK.TREAD and LOOK.RISER, across in metres, a tread's along in metres back from its nosing.

Logs: logsOf of tracks.ts, ported on GP2's samples of the flight's stretches inside its own faces, with the curve's heights. The fallback (one log at the height nearest the middle) applies only to a way piece of at most 40 m (the margin), so the cell that owns that log always holds both ends. A log's length, turn and shift come from splitmix64(k ⊕ salt) in integers, not a float hash, so native and WASM agree. Instance z = plan height at the log's point − PART_BASE_M[log] (LIFT_M, 0.03 m). Model LOG + j as today.

6. Platforms

GP3 builds the platform faces from platform areas and platform-line lines (width, else 3 m); GP6 gives their owner rule from the bake's vertex heights. GP13:

  1. Edges: GP13 sets GP3's platform_reach_m from 3 to 0, so a platform face has no slope band. Every free edge is a wall edge (rule 5 of GP6 with no slope): toward the bed it is about 0.55 + RAIL_TOP_M high; toward the terrain it shrinks to nothing where the ground meets the top. This is today's slab with sides into the ground, in the rules of the plan. The walls take MAT.PLATFORM (section 2, step 5).
  2. Look: GP13 replaces GP11's platform row (MAT_SIDEWALK) by MAT.PLATFORM (43) with the same frame: concrete slabs in today's colour #b4b0a6, from world x and y. The coping is a GP11 look part: the platform face ∩ the 0.35 m buffer of its edges to rail bed and crossing faces (i_overlay), with MAT.PLATFORM and flag 1 (a light band). Its border is a constraint edge (GP11, step 8). It is wider than GP3's min_width_m (0.15 m).
  3. Far: structures/rails.ts keeps its platform slabs. On the new path they go into GP12's NodeMeshes.decks and draw with its pipelines, as GP12's far decks hand over, so a platform draws once at every distance. Masts and the contact wire stay as they are.
  4. A platform with no heights (no track near, an underground station) is no face (GP3), and gets nothing.

7. Detail range and objects in the viewer

  • Piece.detail: a new index range of the piece: rails, rack, cable, flush strips, treads, risers, cheeks. It draws over the nodes where pieces draw, only within DETAIL_END_M = 190 m of the eye (the metres from the eye to the piece's square, as away in roads/roads.ts), and it draws into the shadow maps within the same range. Its faces fade from 140 m to 190 m by the dither of corridor.wgsl:218. The ballast look paints the far sleepers and rails from 140 m on, from GP11's bed frame (along in whole sleeper counts), at the same spots as the near sleepers.
  • Facet normals: for materials 31 to 39 and 51 to 55 (exactly these; 50 is GP11's MAT.CUT_WALL), the piece shader takes the normal from screen derivatives, as corridor.wgsl:222 does. Their vertices carry normal 0. So a rail's faces share vertices, as today.
  • Object: GP13 defines it (GP15, GP16 and GP17 build on it): { model: u16, pos: [i32; 2] (cell frame), z_m: f32, heading_rad: f32, grade: f32 }. The model is a row of PARTS in roads/parts.ts. The crate groups the objects of a cell by piece (the level-18 node of pos) and model: Piece.objects: Vec<ObjectRange { model: u16, first: u32, count: u32 }>, the instances in today's 16-byte layout.
  • Range per model: each model has a range class in the parts vector (section 9): detail (sleepers, timbers, rollers, logs: 190 m with the detail fade) or mesh (crossing equipment: the mesh range with its fade). The draw loop skips a piece's detail models past 190 m.
  • Draw: the piece renderer of GP9 gets the part pipeline of roads/roads.ts (drawParts and the caster) and the vertex code of corridor.wgsl (part_vertex, part_caster), reading the same partMeshes() buffers. The instances live in GP9's vertex pool as one range of each piece, bound at their own offset with a 16-byte stride. So pieces, instances, floors and indices together stay within GP9's 47 MiB.
  • Old path: unchanged. New rows go at the end of PART and PARTS, new materials only into free codes.

8. Level crossing equipment (place/level_crossing.rs)

Input: the cell's LevelCrossing crossings (owned or not, within the data square), their road way and track; GP18's level-crossing points and its crossing points with a railway tag (level_crossing or crossing), with crossing:barrier, crossing:light, crossing:saltire; the plan's faces and heights; the level_crossing block of data/trailview/placement.json.

  1. Tags: a crossing takes the tags of the kind's point nearest to it within match_m. With none: defaults[family], family road (road classes except track), track, or path.
  2. Ends: a crossing is an end of its road on a side when no other crossing of that road lies within group_m along the road on that side. Only an end puts masts, on its outward side. Its members are the crossings of the road within group_m of it on the other side (no chain). Its equipment: barrier the strongest of the end and its members (full = gate = double_half > half = yes > no; other values count as yes), light and saltire true if any says yes. So a yard of many tracks gets masts only outside its outer tracks, and an end reads only crossings within group_m + stand_max_m + match_m = 32 m < 40 m.
  3. Approaches: each road arm that leaves an end outward: two for a road through, one per arm at a road junction on the track.
  4. Masts: on each approach, a mast on the side of the traffic that comes to the crossing (the cell's traffic rule of GP11), and one on the other side too when barrier is full, gate or double_half. No mast when the end has no barrier, no light and no saltire.
  5. Spot of a mast: walk outward along the road's middle from the end crossing in steps of 0.25 m, from 0 to stand_max_m. At metres s, the candidate is p(s) + side × (carriageway half + shoulder + post_offset_m) × n(s). Take the first candidate that lies at least clear_m from every rail bed and crossing face and in no carriageway, junction area, rail bed or water face (check 6). With none, the mast goes (counted crossing_no_room).
  6. Models of a mast, all at the mast's point, z the plan's height there, heading the road's direction away from the crossing (so they face the traffic that comes to it), grade 0: SIGNAL_POST; SALTIRE_WHITE and SALTIRE_RED if saltire (traffic-side mast only); LIGHT_HOUSING and LIGHT_LENS if light; BARRIER_BOX if the mast has a barrier, and its arm.
  7. Arm: open (raised): n = max(1, round(cover / 0.5)) segments, cover = the mast's distance from the road's middle, stacked upward from 1.0 m over the ground, beside the box toward the road: ARM_WHITE, ARM_RED, alternating from the bottom.
  8. Each object belongs to the cell that holds its point. Equipment on a deck is left out (counted crossing_on_deck). A crossing under 20° has no record (GP2), so it gets flush rails and no equipment.

New rows of PARTS (models, built once, fixed): SIGNAL_POST (0.1 × 0.1 × 3.0 m, grey steel, MAT.SIGNAL_POST 53); SALTIRE_WHITE and SALTIRE_RED (two boards 1.2 × 0.2 m crossed at ±45° at 2.6 m, white middles and red borders 0.03 m wide as coplanar faces, 51 and 52); LIGHT_HOUSING (0.6 × 0.15 × 0.3 m black at 2.0 m, 54) and LIGHT_LENS (two discs of 8 facets, 0.2 m, dark red, unlit, 55); BARRIER_BOX (0.4 × 0.4 × 1.1 m grey, 53); ARM_WHITE, ARM_RED (0.1 × 0.1 × 0.5 m upright, 51 and 52). Their looks: plain colours with today's noise in details.wgsl detail_look. Base 0.

9. Shared constants

host/obc-ground-plan/tests/parts.json lists each part's name, id (its index in PARTS), base_m and range, and the constants that the crate mirrors from TypeScript and WGSL: SLEEPER_M, SLEEPER_UP_M, RAIL_HIGH_M, the gauge scales, the rail middles and sleeper halves, RAIL, RACK, CABLE, the step and log constants. A crate test reads it against the Rust constants; a vitest reads it against PART, parts.ts, tracks.ts and the WGSL constants (as GP8's cross-section vector). These are look geometry, not rules, so they stay in code.

10. Rule table

data/trailview/placement.json, block level_crossing (GP13 creates the file; values by place through GP1's reader):

Field Unit Default Why
match_m m 2.0 A node of a level crossing lies on the shared vertex; 2 m covers the rounding of a point against a line vertex and a node beside the vertex.
group_m m 15 Neighbouring tracks that a road crosses lie within 15 m of each other; one set of masts serves them.
clear_m m 2.0 A mast stands outside the track's clearance: 2 m past the bed edge, about 3.9 m from a standard track's middle.
post_offset_m m 0.6 The mast stands beside the road's edge, not on it.
stand_max_m m 15 Past 15 m a mast no longer belongs to the crossing; with group_m the reach stays under the margin.
defaults per family road: light, saltire, no barrier; track: saltire; path: nothing For a crossing whose node has no tags. See Questions.

GP13 adds no field to roads.json. It changes one value of GP3's table: platform_reach_m 0.

11. Edge cases

  • Empty input, no track and no steps: no details, no objects; the stage takes no time.
  • A track with no heights: no details, counted.
  • Ground to deck to ground: the samples at the joints are shared and bed is continuous, so the rails run on unbroken; on the deck the deck plan's bed faces carry the sleepers.
  • Tunnel: rails end at the portal line with a cap; no sleeper in the bore.
  • Switch, crossover, diamond: both tracks' rails run whole on the one bed face (section 3, step 4); where rail heads cross they meet at one height (a few centimetres of overlap). Sleepers stack by section 4.
  • Duplicate track: GP2's shared runs remove it.
  • Light rail along a street (no crossing record): GP3's overlay makes a long crossing face; the rails are flush strips along it, no sleepers, no equipment; the ramp of section 2 blends the street to the rail tops. kinds.json keeps no tram, so a tram line has no bed and no details.
  • Level crossing at a road junction: the junction area inside the bed is crossing face; the rest of it within L joins the ramp's blend face; masts per road arm.
  • Acute level crossing (20° to 30°): the crossing face is long; the mast search walks farther; a side with no room within stand_max_m has no mast, counted.
  • Steep grades: a funicular at grade 1.0: the rails follow z, sleepers tilt by the instance grade, which saturates at ±1.98 (counted grade_clamped). Steps at grade 1: the town rule gives treads of 0.26 m with risers of 0.26 m; logs follow m.
  • Steep ground beside a flight: cheeks reach the plan's height minus 5 cm; where the ground is higher than the tread, no cheek.
  • Cell and tile borders: rails meet at shared rings; sleepers, rollers and logs belong to the cell of their point; treads to the cell of the tread's middle; a riser and an end riser to the cell of the tread whose end they close.
  • Levels: platforms are ground faces; a level crossing on a deck gets flush rails and no equipment.
  • Platform over the bed (OSM draws it to the track's middle): the bed comes first (section 2), so the platform's wall stands at the bed edge, 1.9 m from a standard track's middle.
  • Island platform: coping on both sides.
  • A crossing node with no crossing near: ignored, counted crossing_node_alone.
  • A rule cannot fit: details never change the plan, except the crossing heights and ramps of section 2, which are blend faces of GP6 with its fallbacks. A detail that has no room, no height or no own face is left out and counted. GP13 emits no face to cover a case.

Plan

  1. host/obc-ground-plan/src/ heights (GP6's and GP12's owner rules): the offset − RAIL_TOP_M on every face that reads a track (section 1); the crossing face rule Owner(track, rail tops).
  2. GP3's crossing face builder and table: shoulder patches on a bed are crossing face; rail_bed before platform; platform_reach_m 0; the ramp blend faces of section 2 (fn crossing_ramps(faces, graph) -> Vec<Face>).
    2a. GP8's far stamp: the RAIL core plane at z − RAIL_TOP_M[gauge].
    2b. GP11's look tables: the platform row, the coping part, the vertical row for platform and crossing walls.
  3. host/obc-ground-plan/src/details/mod.rs: create: pub fn details(graph: &WayGraph, plan: &FacePlan, heights: &Heights, rules: &Rules) -> CellDetails with CellDetails { triangles per piece (detail range), objects: Vec<Object>, stats: DetailStats }; the constants of section 9.
  4. details/rails.rs: create: the refined samples, rings, runs against faces, caps, flush strips, sleepers with the footprint and stacking rules, rollers.
  5. details/steps.rs: create: stretches, stone treads, risers, end risers, cheeks, logs with splitmix64.
  6. host/obc-ground-plan/src/place/mod.rs with Object, and place/level_crossing.rs: create: tags, ends, approaches, mast spots, models.
  7. The mesh stage (GP7's piece builder): Piece.detail and Piece.objects; the detail vertices with normal 0.
  8. GP5's WASM bridge and the plan worker: carry detail, the objects and the instance bytes.
  9. builder/web/src/lib/trailview/roads/parts.ts: append the models of section 8 to PART and PARTS. roads/section.ts: MAT.PLATFORM 43, MAT.SIGNAL_WHITE 51, SIGNAL_RED 52, SIGNAL_POST 53, SIGNAL_HOUSING 54, SIGNAL_LENS 55.
  10. roads/details.wgsl: platform_look (slabs, coping by flag 1) and the signal colours in detail_look.
  11. GP9's piece renderer and GP11's piece shader: the detail range with its cull and fade, the instances in the vertex pool and the part pipelines, facet normals for materials 31 to 39 and 51 to 55.
  12. structures/rails.ts: on the new path, platform slabs go into NodeMeshes.decks (GP12).
  13. GP1's debug tool: a layer details (rails and strips as lines, sleepers and treads as footprints, masts as dots with their models) and the details and objects in the glTF.
  14. data/trailview/placement.json: the level_crossing block. GP1's reader: LevelCrossingRules.
  15. builder/web/tests/browser/trailview/road-views.json and road-views-top.json: the new views of Verification, by GP0's method.
  16. Tests (Verification), cargo fmt --all.

Files

  • host/obc-ground-plan/src/details/mod.rs, details/rails.rs, details/steps.rs: create: the details stage.
  • host/obc-ground-plan/src/place/mod.rs, place/level_crossing.rs: create: Object and crossing equipment.
  • host/obc-ground-plan/src/ faces of GP3 (crossing faces, ramps, ranks, platform_reach_m), heights of GP6 and GP12 (datum, crossing rule), looks of GP11 (platform): change.
  • GP8's far stamp (builder/web/src/lib/trailview/terrain/): change: the track datum.
  • host/obc-ground-plan/src/ mesh of GP7 (Piece.detail, Piece.objects): change.
  • host/obc-ground-plan/tests/parts.json: create: the shared models and constants.
  • host/obc-ground-plan/tests/ (GP1's test layout): change: the tests of Verification.
  • GP5's bridge crate and builder/web plan worker: change: carry details and objects.
  • builder/web/src/lib/trailview/roads/parts.ts, roads/section.ts: change: new models and materials at the end.
  • builder/web/src/lib/trailview/roads/details.wgsl: change: platform and signal looks.
  • GP9's piece renderer (builder/web/src/lib/trailview/) and GP11's piece shader: change: detail range, objects, facet normals.
  • builder/web/src/lib/trailview/structures/rails.ts: change: far platforms only.
  • builder/web/src/lib/trailview/roads/parts.test.ts: create: reads parts.json against PART, parts.ts, tracks.ts and the WGSL constants.
  • data/trailview/placement.json: create: level_crossing.
  • GP1's rule reader: change: LevelCrossingRules.
  • GP1's debug tool: change: the details layer.
  • builder/web/tests/browser/trailview/road-views.json, road-views-top.json: change: the new views.

Verification

  • Checks:
    • obc test -p obc-ground-plan, with these unit tests:
      • Datum: on a straight track, the rail head tops lie at z and the sleeper tops at z − RAIL_TOP_M + 0.05, within 1 mm; the faces of a switch lie at the bed's datum.
      • Cell border: a curved track across a cell line, built in both cells: the rings at the border are bit-equal; the union of both cells' sleepers equals the sleepers of one build over both, with none twice.
      • Sleepers at along_m = k × 0.6; none in a crossing face; at a 1:9 switch no two sleeper tops at one height overlap, and both tracks have rails on the one bed face; a track across a zoom-13 border with a backward and with a forward jump of 10 cm: gaps 0.5 m to 0.7 m, none doubled.
      • Level crossing: a banked road (bank 0.07) over a track at 60°: every flush strip lies within 1 mm of the face's height plus FLUSH_LIFT_M, the face's height on each rail line equals z within 1 mm, the ramp's steepest grade is at most the road's return grade plus GP6's tolerance, no 3D rail vertex lies more than 1 mm inside the crossing face, and no cap lies on its step edge. A light rail along a 60 m street: both cells give the same ramp faces.
      • Steps: a flight across a cell border gives the same treads in both cells as in one build; a 3 m rise over 15 m gives risers of 0.15 m to 0.17 m; the first tread at a seam has an end riser; logsOf's tests of roads/tracks.test.ts, ported (logs about 0.2 m of rise apart, none closer than 0.9 m).
      • Equipment: half gives one mast per approach on the traffic side, full two; no tags gives the family default; a mast never stands in a carriageway, junction area, rail bed or water face; a crossing with no room within stand_max_m gives none and counts it; a double track gives one set of masts; six tracks 8 m apart give masts only outside the outer two.
    • The fixture checks of section 14: check 1 and check 3 with the new ramp faces; check 2 with the details (rings and objects on shared borders); check 6 with the equipment; check 7 (native and WASM bytes equal) with details and objects. New hard check, target 0: every sleeper's footprint lies in rail bed, track junction area or rail deck faces of its level; every flush strip lies in a crossing face; every tread lies in its flight's faces.
    • obc exec cargo clippy -p obc-ground-plan --all-targets -- -D warnings; cargo fmt --all.
    • GP5's WASM size guard passes.
    • In builder/web: npx vitest run src/lib/trailview (with roads/parts.test.ts), npm run check, npm run check:wgsl.
    • Old path pixel-equal: from builder/web/tests/browser, on the merge base and on this branch, each built with npm run pretest:trailview: flock /tmp/trailview-gpu.lock node trailview/shoot.mjs --gpu --views trailview/road-views.json --width 1920 --height 960 --out DIR without the switch for the views of Pictures; cmp each pair. Gate: every pair is byte-equal.
    • obc suites check.
  • Measurements:
    • Cell build: GP7's timing command (nice -n 10 obc exec cargo run --release -p obc-ground-plan --example debug -- --places all --timing) on this branch and the merge base: median, p95 and max per cell, native; the same in Chrome on the GTX box with GP5's timing page for the cells around rail-close. Per cell: detail triangles, objects, DetailStats counters. Gate: p95 over the fixture grows by at most 10 % (chosen: tracks and steps are a small share of the ways) and stays within GP7's gate.
    • GPU: a scratch copy of flights.json with a flight rail-walk (eye 1.6 m, 600 frames) from the rail-close view toward the station and the funicular, plus walk and valley-drive, all with &ground=plan: flock /tmp/trailview-gpu.lock node trailview/flight.mjs --gpu --flights FILE, three runs, clock held, on this branch and the merge base. Report the passes of the pieces, the casters and the objects, median and p95, and the triangles. Gate: on rail-walk the pieces, casters and objects together grow by at most 0.15 ms median. Chosen: about a fifth of the epic's 0.8 ms.
    • Memory: the pools at the end of each flight: vertex pool (instances included), floors and index pool together within GP9's 47 MiB, and the worker heap within 55 MiB; dropped = 0.
  • Pictures (with ground=plan, from above at pitch −89 and at eye height, before = the merge base with the switch and develop's old path, after = this branch, on one slider page; each at 2×):
    • rail-close, rail-close-top: rails continuous through curves, sleepers evenly spaced on the bed, no rail floating or sunk, no flicker at the switches, the bed under the rails as the slope rule shapes it.
    • rail-narrow-eye and the new rail-narrow-top: the narrow gauge and its rack.
    • funicular-eye and the new funicular-top: timbers, the haul cable on its rollers, no gap on the steep grade.
    • v16-road-rail, v16-road-rail-top: the road and the rails where they meet; flush rails, the ramp.
    • The fixture's level crossings: list them with GP2's census of the debug tool (junctions, type LevelCrossing, owned), and add lc-road-eye/lc-road-top, lc-track-eye/lc-track-top, lc-path-eye/lc-path-top for one crossing of each family (a tagged one where the fixture has one), eye views at 1.6 m from the approach, 20 m out. The owner looks for: rails flush in the road, no hump the eye can see at a minor crossing, masts outside the bed, lights and crosses facing the traffic.
    • platform-eye and platform-top (new): the fixture's largest platform (the debug tool lists platform faces), eye at 1.6 m on it looking along it; the wall to the bed, the coping, the top 0.55 m over the rail heads.
    • v01-stairs: logs as the owner's reference of TrailView G4: log steps on trails #3060 (/media/timo/OSM1/tmp/road-epic/owner-views-2/owner-log-steps-reference.webp); steps-town-eye, GP0's steps-town-top, b-steps-eye and the new b-steps-top: stone treads, risers, cheeks to the ground, the first step at the seam.
    • The debug tool: layers faces,details,objects from above for the places above; a glTF of rail-close and of lc-road for a 3D look.

Done when

  • The pull request into ground-plan has merged with CI green and the reviewer's findings resolved.
  • Every check of Verification passes; the new hard check and checks 1, 2, 3, 6 and 7 are 0 over the fixture.
  • The old path is byte-equal in the shots of Pictures.
  • The measurements meet their gates, and the pull request reports them with their commands.
  • The pictures of every named view, before and after, are on one slider page, and the implementer has looked at each one at 2×.
  • road-views.json and road-views-top.json hold the new views.

Out of scope

  • Catenary masts and the test against other faces: GP17. The contact wire stays in structures/rails.ts.
  • The level crossing kind and its tags in the tiles: GP18.
  • Track bridges, their deck plans and their far structures: GP12. GP13 only puts rails and sleepers on their bed faces.
  • Culverts under tracks: GP15. Guardrails and walls beside tracks: GP16.
  • A sidewalk across a level crossing: GP4's taper before the bed stays.
  • The far look of tracks and steps: GP8's far stamp (GP13 changes only its track datum) and today's ballast paint.
  • Deleting roads/tracks.ts and the old details: GP19.

Questions for the owner

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

  1. The rail datum. The spec says a track's height is the top of its rails, and the bake lifts platforms 0.55 m over it. Today's viewer puts the ballast's toe there instead, so its rails lie 0.48 m higher and its platforms only 7 cm over the rails. With the spec's datum, the bed lies 0.2 m under the bake's line, so tracks sit lower in the terrain than today, often in a shallow cut. Level crossings and light rail streets are then flush with no hump. Recommendation: the spec's datum.
  2. Barrier arms: open (raised) or closed (across the road). Open is what a rider sees most of the time; closed reads more clearly as a level crossing from far. Recommendation: open.
  3. Level crossings without tags. Recommendation: a road gets lights and a cross but no barrier, a track gets a cross, a path gets nothing. A barrier that OSM does not map would be a guess that blocks half the road in the picture.
  4. Epic note: section 11 of the epic gives the crossing face "the road's surface and height". GP13 gives it the track's plane at the rail tops and a blend ramp back to the road's heights. Reason: the road banks through a level crossing (specs/trailview-features.md:250-251) and has its own grade, so at the road's height the rails would lie up to about 0.3 m off the road inside the face. The road keeps its surface.

Activity

  1. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    Owner feedback for the steps part of GP13, from the view conn-path-off-road-top (live viewer, ground plan): a flight of steps meets a road and a path T near the bottom. On ground-plan the joint to the road and the small path T beside the steps look broken: bands overlap, there are odd paved patches, and the edges are not clean. The owner expects the step treads to replace this. When GP13 builds the steps, use this view to check the steps' joint to the road and to the path T, top-down and at eye height.

    Picture: /media/timo/OSM1/tmp/ground-plan/gp4/m/crops4/conn-path-off-road-top.png (develop | ground-plan | stop-mouth branch).


    Generated by Claude Code

  2. timohueser commented on Nov 10, 2026

    @timohueser
    OwnerAuthor

    Deferred (owner, 2026-11-10): the level-crossing equipment (barriers, lights, crosses) and the rack and haul cable come after roads, water and structures are solid. Rails, sleepers, platforms and step treads stay in this issue. The body is rewritten before the build (see the epic comment of 2026-11-10).


    Generated by Claude Code

  3. timohueser commented on Nov 11, 2026

    @timohueser
    OwnerAuthor

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


    Generated by Claude Code

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions