nordisk/facett

FLIGHT viewer — the Facet pane, pedestrian WALK, and the ONE world frame

nornir:class=design

The FLIGHT half of Rickard's two-viewer partition (see osm-3d-gaps.md) finally has a host-facing pane, a street-level walk, and — the load-bearing part — a single, unambiguous world frame. This doc names only the chosen design.

1. FlightFacet — the pane that was missing

facett-map3d-flight shipped a complete engine (floating origin · atmospheric scattering · 6DOF rig · CDLOD terrain · day cycle · tile streaming) and no Facet. osm-3d-gaps.md row C:69 recorded it as PARTIAL for that reason. The consequence was not cosmetic: with no Facet there was no way for a FacetDeck to mount it, no way for a robot script to drive it, and no state_json/pixel oracle over it — so the engine's correctness was only ever checked by its own unit tests, in its own vocabulary.

facett-map3d-flight/src/facet.rs is that pane. The design:

• It owns no renderer. The pane holds FLIGHT-side state (the FlightCamera rig, the DayCycle sun, the locomotion lane) and drives facett_map3d::Map3D as its shared render core. Extrusion, the watertight roof shell, ground-plane road ribbons and the CPU/wgpu painter are fixed once in facett-map3d and both viewers benefit — the partition doc's "shared render-core" rule, honoured literally (L5).
• It duplicates nothing from the NAVIGATOR side. No turn-by-turn, no route overlay, no ETA/next-turn HUD. Those belong to the navigator and stay there.
• The camera bridge is a translation, not a second camera model. The rig's yaw/pitch are pushed into the render core through its existing Garmin vocabulary (set_bearing_deg / set_tilt_deg), which is already the single source of truth both viewers read.
• Gated on the egui feature. A Facet is by definition an egui pane; the engine core stays egui-free and headless-testable.

state_json publishes the whole pose — lon/lat/altitude_m/ground_m/ eye_height_m, yaw_deg/pitch_deg/roll_deg, locomotion, hour, sun_elevation_deg, cloudiness — with the render core's own state folded in under map, so the pixel oracle (RenderReport.vertices + non-zero geometry) applies unchanged and the state oracle is exact.

2. Locomotion::Walk — the pedestrian street-level mode

osm-3d-gaps.md row C:72 was the last open FLIGHT-owned camera gap: "no pedestrian eye-height locomotion yet — the tour drive is a car-nav chase, not a first-person walk", explicitly a FLIGHT feature and explicitly not a navigator one.

Locomotion is a superset of the engine's FlyMode — Fly / Stick / Orbit map onto it one-to-one, and Walk rides the free-fly integrator with three pedestrian constraints layered on top. Each constraint is a separate contract with its own RED-when-broken test:

In Walk the render core's dolly is pulled to the closest legal radius, so the walker stands inside the extruded city rather than above it.

3. THE WORLD FRAME — one frame, one swap (the bug this round found)

The sharp finding. WorldPos defines, and its own methods enforce, the frame

WorldPos = { x: Mercator easting, y: Mercator northing, z: altitude }

from_lonlat writes it, to_lonlat reads y as the northing, ground_distance measures (x, y), and terrain.rs states the render swap explicitly at the boundary: positions.push([r[0], r[2], r[1]]) // → Y-up render frame [easting, elev, northing].

Three places disagreed with that, all in the same direction — they treated slot 1 as altitude:

1. camera_fly::forward() returned [cos·cp, sin(pitch), sin·cp], putting the vertical component in the northing slot. right() crossed against [0,1,0]. integrate_orbit built its offset the same way. Net effect: climbing moved the aircraft north (and to_lonlat() reported a changed latitude), while turning changed its altitude.
2. cinematic.rs documented the render layout inside a WorldPos and built its orbit that way — so an autopilot "altitude" was silently a northing and the floating-origin snap quantised the wrong axis.
3. facett-demo's osm_fly.rs and bin/flight_demo.rs stored the camera pre-swapped into a Y-up WorldPos to make it agree with (1).

Nothing caught it because every rig test was basis-relative: they compared motion against forward() itself, so a consistently-wrong basis passed all of them, and the crate had no Facet tying the rig back to the world frame. This is the same failure shape as the SCREEN_BOUND_K smear: a suite that measures a thing against itself.

The chosen design

origin.rs is the authority. There is one world frame, and exactly one swap, at the render boundary.

• camera_fly::forward() is [cos(yaw)·cp, sin(yaw)·cp, sin(pitch)]; right() crosses against world up [0,0,1]; integrate_orbit matches.
• cinematic.rs builds its orbit in the world frame (z is the lift axis).
• The demo binaries keep the camera in the world frame and apply [v0, v2, v1] once, to the camera basis, at the point where they already swap geometry.

The oracle that pins it

camera_fly::tests::rig_climbs_in_altitude_not_latitude is deliberately not basis-relative — it asks the world what happened:

• flying straight up gains > 99 m of z and moves < 2 m over the ground (ground_distance), where the pre-fix basis gained ~0 m of altitude and ~100 m of northing;
• level flight at yaw 0 increases the longitude and holds altitude exactly;
• move_up is a pure 250 m climb that moves you nowhere on the map.

The pane-level twin is climbing_changes_the_published_altitude_not_the_latitude in tests/facet_robot.rs, which reads the same contract off state_json.

4. What this leaves open

• The Walk mode has no collision: a walker passes through building walls. The render core carries no per-footprint identity yet (the picking gap, D:84), and collision wants the same footprint index. Do picking first, then collision.
• set_ground_m is host-pushed. Wiring it to terrain::elevation_at inside the pane would make the walk follow real DEM relief without host cooperation.
• The pane drives Map3D's orbit camera through bearing/tilt; a true 6DOF free-look (roll) is flattened, because the render core's camera is an orbit rig. A roll-capable core is a facett-map3d change, not a flight one.