nordisk/facett

Cinematic flythrough — the watchable OSM 3D flight-sim

What it is

Map3D::with_flythrough(true) turns the static, densest-cluster-framed 3D city into a MOVING flight-sim you just WATCH: a smooth camera that continuously orbits the skyline, cruises in toward street level and pulls back out to a dramatic oblique, and gently tracks across the town — no keyboard. It rides on top of the existing GPU depth-tested render (lit prisms, SSAO, soft shadows, reflective water, HDR sky + bloom), so every "cooler graphics" pass is what you watch the flight through.

Sibling: facett-map3d-flight::CinematicFlight does the same for the full-screen planetary flight layer (6DOF FlightCamera over the real DEM + draped city).

Design (deterministic in the clock, FC-7)

• flythrough::CityFraming — captured by frame_densest_cluster (centroid, extent, roof height, base distance/azimuth of the framed town).

• flythrough::Flythrough::pose(t) — a PURE function of the clock giving (target, azimuth, elevation, distance):

  • orbit: azimuth = az0 + orbit_rate·t
  • dolly breathing: distance = base·(1 + amp·sin 2πt/period) (cruise in/out)
  • elevation sweep: elev = mid + amp·sin(2πt/period + φ) (phase-offset from dolly)
  • target tracking: a small Lissajous within the cluster (glide across quarters).

• render_camera() folds the flythrough in (like the spin auto-orbit): when on it drives a clone of the camera from clock_s (pinned → deterministic tests) or the live fly_clock the Frame tick advances, then settle() applies the elevation/ground clamps. Default OFF — additive, API-safe; the interactive orbit map is unchanged.

Why this shape

The camera clamps (elevation band, never-below-ground, dolly floor) already guarantee a legal pose, so the flythrough only has to choose a pose per clock — no new render pass, no new resource, no fork of the pipeline. The framing is captured once so the path never loses the town. Pinned-clock purity means a snapshot at a fixed clock is exact and a headless test flies a bit-reproducible path.

Tests

• flythrough.rs unit: the path MOVES (eye travels), is deterministic, and keeps the city framed (target stays over the cluster, distance in the cruise band, eye above ground) across a long sweep.
• tests/flythrough_render.rs (feature wgpu): renders the moving city through the GPU depth path at several clock steps — non-blank (lit city, content_ratio > 0.05) at EVERY step, and the render_camera eye moves a real distance between steps.

Watch it

DISPLAY=:0 cargo run -p facett-map3d --example flythrough --features wgpu --release

Untick "auto-fly" to grab the orbit controls; re-tick to resume the cinematic flight.

Known gaps / follow-ups

• Wiring facett-map3d-flight::CinematicFlight into facett-demo's osm_fly_demo / flight_demo as an auto-play-on-load autopilot (the autopilot + test already landed; facett-demo can't be built from a git worktree — it path-deps knut-popsim which hardcodes ../../../facett — so that one-line wire is left for an in-checkout change).
• Optional: a keyframe/Bezier path spec so a designer can author a named flight.