Repository navigation
Description
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.tson 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.jsonis a rule table;specs/trailview-features.mdkeeps 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 atz + LIFT_M + BED_M(0.28 m) and the sleeper top atSLEEPER_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 overz, 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
gaugeunder 1200 mm, else the classnarrow_gaugeorfunicular; rack means aracktag other thanno(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
bank0 indata/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 fromfract(along)andacrossfrom 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 pastDETAIL_END_M = 190(roads/roads.ts:20). - Rails end where a road crosses the track:
stoppeddrops every station withCUT.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).totalis 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 eachkthat is a multiple ofm = 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 ofkgives 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 atLIFT_M + 0.03over 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_BALLASTwith along in sleepers, platformsMAT_SIDEWALKwith 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'sCarriagewaywins and aRailBedcovers becomesCrossing, withcrossingthe least rail way.platform_reach_mis 3 (GP3, 4.7, 4.8, table). GP6'sblend_radius_mis 10 m. structures/rails.tsdraws, at every distance: the masts, the contact wire 5.5 m overz, and the platform slabs with sides 0.5 m into the drawn surface, in flat colours (structures/rails.ts:12-58,:112-161).kinds.jsonkeepsrailway,gauge,electrified,rack,bridge,bridge:structureandlayeronrailway(classesrail,narrow_gauge,light_rail,funicular; notram); nothing onplatform;widthonplatform-line(data/trailview/kinds.json:53-73). It has no kind forrailway=level_crossing; GP18 adds it withcrossing:barrier,crossing:lightandcrossing:saltire, and keepsrailwayand these tags oncrossing: a node withhighway=crossingstays acrossing.- GP2 gives
Crossing { pos, over, under, kind: LevelCrossing, source, angle_rad, owned }for a road or path over a ground rail withinsnap_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.alongjumps 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 fromparts.tsandtracks.ts(section 9).- The bed's owner height at a point with across
a(metres, left positive) and footu: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
RAILway lies atz − 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 atzexactly. - 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
RailBedand that a road's shoulder candidate also covers becomesCrossingtoo, with the road's owner and material. So the shoulders inside the bed are crossing face. ranksputsrail_bedbeforeplatform. 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:
- Crossing face:
Owner(track, rail tops): the height at a point isz(u_f) + bank(u_f) × a, whereu_fis the foot of the point on the track's curve andaits 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. - 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)|andL(b) = clamp(dh(b) / return_grade(road class), RAMP_MIN_M, blend_radius_m), with GP6'sreturn_grade(0.15 for roads, 0.3 for paths) and GP6'sblend_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 radiusmax(L(b_i), L(b_i+1))around each boundary piece between two neighbouring samples (i_overlayoffsets), 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. - 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. dh(b)andL(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).- The edge between a crossing face and the rail bed is a step edge (the bed lies
RAIL_TOP_Mlower): 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 takesMAT.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.
- 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 (withouter_m = gauge + 0.05) and in height, down to GP2'sMIN_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. - Ring at a sample:
p(u), the unit tangentt(u)from the curve (not from chords), the left normaln(u). For each point(a, up)of a profile: plan positionp + n × a, heightbed(u, a) + SLEEPER_UP_M + up × scale. Profiles fromtracks.ts:RAILata = ±g + a_k(gthe rail middle),RACKat the middle on rack lines,CABLEat the middle on funiculars. - 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.
- 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 underg + 0.1m at a sample also ends the run (countedrail_tight), so an inner rail never folds. - 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. - Tunnels: a
Tunnelway has no details; the ground way's face ends at the portal line, and its rails end there with a cap. - Vertex attributes: the look word of
tracks.ts(LOOK.RAIL,RAIL_HEAD,RACK,CABLE, the track's surface code, flags 0),across = ain metres,along = (along_m − base) / SLEEPER_Mwith GP11's base (the sleeper count, sorack_lookdraws its rungs as today). The normal field is 0: detail materials shade from screen derivatives (section 7).
4. Sleepers and rollers
- Positions: a sleeper's middle stands at
along_m = k × SLEEPER_Mon GP2's stroke metres,SLEEPER_M= 0.6 m (asstamp-core.wgsl:62), for every wholekwith that position on a ground or deck way piece. So the near sleepers lie on the painted ones oflooks.wgsl:452and GP11's frame. Every cell counts from the same start (epic, section 13).
Zoom-13 border: leta_Pbe thealongat the border from the tile on the side of loweralong, anda_Nfrom the other tile; both tiles lie in the work area of every cell that holds the border. The side of higheralongkeeps only thekwithk × 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. - Pose: the point
p(u)wherealong(u) = along_m(GP2's arc table, then a fixed number of Newton steps, so native and WASM agree), heading fromt(u),grade = dz/dsof the curve. Instance z =bed(u, 0) − PART_BASE_M[sleeper], withPART_BASE_M=LIFT_M + BED_M= 0.28 m for sleepers, timbers and rollers, so the part's top lands atbed + 0.05(section 9). - 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. - 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 standsSLEEPER_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. - Model:
SLEEPERorSLEEPER_NARROW(concrete),TIMBERorTIMBER_NARROWon funiculars and rack lines, asgaugeOfintracks.ts. - Rollers: on funiculars, a
ROLLERatalong_m = k × 8m, 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:
- If
S < 0.1m, the stretch joins its neighbour in the same span, or has no tread if it has none. count = max(1, round(R / RISE_M)),tread = clamp(S / count, TREAD_MIN_M, TREAD_MAX_M),n = max(1, round(S / tread)); treadkspans[s0 + kS/n, s0 + (k+1)S/n].- 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 ismin(h, clamp(0.8 h, 0.6, 1.4)),hthe flight's carriageway half from GP1's cross-section, so it stays on its own face. - 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.
- 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.
- Cheeks on both sides of each tread, from its level down to the plan's height at the side point minus
CHEEK_SINK_M0.05 m, so no gap opens on a slope. A cheek whose ground lies over its level is left out. - Attributes as
tracks.ts:LOOK.TREADandLOOK.RISER,acrossin metres, a tread'salongin 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:
- Edges: GP13 sets GP3's
platform_reach_mfrom 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 about0.55 + RAIL_TOP_Mhigh; 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 takeMAT.PLATFORM(section 2, step 5). - Look: GP13 replaces GP11's platform row (
MAT_SIDEWALK) byMAT.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), withMAT.PLATFORMand flag 1 (a light band). Its border is a constraint edge (GP11, step 8). It is wider than GP3'smin_width_m(0.15 m). - Far:
structures/rails.tskeeps its platform slabs. On the new path they go into GP12'sNodeMeshes.decksand 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. - 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 withinDETAIL_END_M= 190 m of the eye (the metres from the eye to the piece's square, asawayinroads/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 ofcorridor.wgsl:218. The ballast look paints the far sleepers and rails from 140 m on, from GP11's bed frame (alongin 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, ascorridor.wgsl:222does. 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 ofPARTSinroads/parts.ts. The crate groups the objects of a cell by piece (the level-18 node ofpos) 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) ormesh(crossing equipment: the mesh range with its fade). The draw loop skips a piece'sdetailmodels past 190 m. - Draw: the piece renderer of GP9 gets the part pipeline of
roads/roads.ts(drawPartsand the caster) and the vertex code ofcorridor.wgsl(part_vertex,part_caster), reading the samepartMeshes()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
PARTandPARTS, 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.
- Tags: a crossing takes the tags of the kind's point nearest to it within
match_m. With none:defaults[family], familyroad(road classes excepttrack),track, orpath. - Ends: a crossing is an end of its road on a side when no other crossing of that road lies within
group_malong the road on that side. Only an end puts masts, on its outward side. Its members are the crossings of the road withingroup_mof it on the other side (no chain). Its equipment:barrierthe strongest of the end and its members (full=gate=double_half>half=yes>no; other values count asyes),lightandsaltiretrue if any saysyes. So a yard of many tracks gets masts only outside its outer tracks, and an end reads only crossings withingroup_m+stand_max_m+match_m= 32 m < 40 m. - Approaches: each road arm that leaves an end outward: two for a road through, one per arm at a road junction on the track.
- Masts: on each approach, a mast on the side of the traffic that comes to the crossing (the cell's
trafficrule of GP11), and one on the other side too whenbarrierisfull,gateordouble_half. No mast when the end has no barrier, no light and no saltire. - 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 metress, the candidate isp(s) + side × (carriageway half + shoulder + post_offset_m) × n(s). Take the first candidate that lies at leastclear_mfrom every rail bed and crossing face and in no carriageway, junction area, rail bed or water face (check 6). With none, the mast goes (countedcrossing_no_room). - 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_WHITEandSALTIRE_REDifsaltire(traffic-side mast only);LIGHT_HOUSINGandLIGHT_LENSiflight;BARRIER_BOXif the mast has a barrier, and its arm. - 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. - 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
bedis 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.jsonkeeps notram, 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
Ljoins 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_mhas 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 (countedgrade_clamped). Steps at grade 1: the town rule gives treads of 0.26 m with risers of 0.26 m; logs followm. - 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
host/obc-ground-plan/src/heights (GP6's and GP12's owner rules): the offset− RAIL_TOP_Mon every face that reads a track (section 1); the crossing face ruleOwner(track, rail tops).- GP3's crossing face builder and table: shoulder patches on a bed are crossing face;
rail_bedbeforeplatform;platform_reach_m0; the ramp blend faces of section 2 (fn crossing_ramps(faces, graph) -> Vec<Face>).
2a. GP8's far stamp: theRAILcore plane atz − RAIL_TOP_M[gauge].
2b. GP11's look tables: the platform row, the coping part, the vertical row for platform and crossing walls. host/obc-ground-plan/src/details/mod.rs: create:pub fn details(graph: &WayGraph, plan: &FacePlan, heights: &Heights, rules: &Rules) -> CellDetailswithCellDetails { triangles per piece (detail range), objects: Vec<Object>, stats: DetailStats }; the constants of section 9.details/rails.rs: create: the refined samples, rings, runs against faces, caps, flush strips, sleepers with the footprint and stacking rules, rollers.details/steps.rs: create: stretches, stone treads, risers, end risers, cheeks, logs withsplitmix64.host/obc-ground-plan/src/place/mod.rswithObject, andplace/level_crossing.rs: create: tags, ends, approaches, mast spots, models.- The mesh stage (GP7's piece builder):
Piece.detailandPiece.objects; the detail vertices with normal 0. - GP5's WASM bridge and the plan worker: carry
detail, the objects and the instance bytes. builder/web/src/lib/trailview/roads/parts.ts: append the models of section 8 toPARTandPARTS.roads/section.ts:MAT.PLATFORM43,MAT.SIGNAL_WHITE51,SIGNAL_RED52,SIGNAL_POST53,SIGNAL_HOUSING54,SIGNAL_LENS55.roads/details.wgsl:platform_look(slabs, coping by flag 1) and the signal colours indetail_look.- 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.
structures/rails.ts: on the new path, platform slabs go intoNodeMeshes.decks(GP12).- 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. data/trailview/placement.json: thelevel_crossingblock. GP1's reader:LevelCrossingRules.builder/web/tests/browser/trailview/road-views.jsonandroad-views-top.json: the new views of Verification, by GP0's method.- 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:Objectand 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/webplan 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: readsparts.jsonagainstPART,parts.ts,tracks.tsand the WGSL constants.data/trailview/placement.json: create:level_crossing.- GP1's rule reader: change:
LevelCrossingRules. - GP1's debug tool: change: the
detailslayer. 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
zand the sleeper tops atz − 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 equalszwithin 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 ofroads/tracks.test.ts, ported (logs about 0.2 m of rise apart, none closer than 0.9 m). - Equipment:
halfgives one mast per approach on the traffic side,fulltwo; 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 withinstand_max_mgives none and counts it; a double track gives one set of masts; six tracks 8 m apart give masts only outside the outer two.
- Datum: on a straight track, the rail head tops lie at
- 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(withroads/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 withnpm run pretest:trailview:flock /tmp/trailview-gpu.lock node trailview/shoot.mjs --gpu --views trailview/road-views.json --width 1920 --height 960 --out DIRwithout the switch for the views of Pictures;cmpeach 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 aroundrail-close. Per cell: detail triangles, objects,DetailStatscounters. 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.jsonwith a flightrail-walk(eye 1.6 m, 600 frames) from therail-closeview toward the station and the funicular, pluswalkandvalley-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: onrail-walkthe 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.
- Cell build: GP7's timing command (
- 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-eyeand the newrail-narrow-top: the narrow gauge and its rack.funicular-eyeand the newfunicular-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, typeLevelCrossing, owned), and addlc-road-eye/lc-road-top,lc-track-eye/lc-track-top,lc-path-eye/lc-path-topfor 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-eyeandplatform-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'ssteps-town-top,b-steps-eyeand the newb-steps-top: stone treads, risers, cheeks to the ground, the first step at the seam.- The debug tool: layers
faces,details,objectsfrom above for the places above; a glTF ofrail-closeand oflc-roadfor a 3D look.
Done when
- The pull request into
ground-planhas 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.jsonandroad-views-top.jsonhold 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.tsand the old details: GP19.
Questions for the owner
Owner decision (2026-11-03): every recommendation in this section is accepted.
- 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.
- 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.
- 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.
- 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
timohueser commentedon Nov 6, 2026
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
timohueser commentedon Nov 10, 2026
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
timohueser commentedon Nov 11, 2026
Points of this issue that the crossing block (#3105) touches:
sheet (TrailView ground plan GP12.3a: deck sheets in the crate: storey records, one deck plan per storey, the shell with a real thickness (no pixel change) #3344) is the way's own surface, and the floor of a bore (TrailView ground plan GP12.4: bores and portals: the open cut, the cover, the end face with its opening, the frame, the bore sheet #3345) is the way's faces of a storey under the
ground.
one way is whole and the other ends at its body. Which one ends between a railway and a road is open for the owner
(TrailView ground plan GP12: bridges, tunnels, underpasses and galleries: decks, bores and roofs with the ladder (the contract of the crossing block) #3105, open point 2): today's
plan.jsonranksput every carriageway before a rail bed.Generated by Claude Code