nordisk/facett

map3d — the 3D spatial subsystem — for idiots

Class: idiot. Every step, nothing assumed. Goal: see a 3D map, a flying camera, and a spinning 3D model, each on your own screen, from a cold shell to green. If you already know Rust, read map3d-guide.md instead — this one spells out every keystroke.

What you need first

• A terminal (the black window where you type commands).
• The facett repo on disk. In the terminal, type this and press Enter:

cd /run/media/rickard/T9/git/facett

Part 1 — the 3D map (facett-map3d)

The one thing to remember

2D map shapes go up. A closed ring (a building outline, a lake outline) becomes a prism (a box lifted off the ground) or a flat cap. A road line stays flat as a thin ribbon. Everything sits on a terrain plane. A camera orbits it, and you can drag/scroll/zoom it around by hand.

Step 1 — run the demo with no data at all

Type and press Enter:

cargo run -p facett-demo --bin osm3d_demo

A window opens showing a synthetic procedural city (a grid of buildings + a road network) — no files needed. Drag with the mouse to orbit; scroll to zoom.

Step 2 — see the rabbit fixture

The test fixture used everywhere in this codebase is a rabbit, never a plain cube. To see it, type and press Enter:

FACETT_OSM_RABBIT=1 cargo run -p facett-demo --bin osm3d_demo

You should see a rabbit-shaped 3D skyline with a small spinning rabbit logo in a corner. If you ever see plain squares instead, something is wrong — the fixture is always the rabbit.

Step 3 — feed it real map data (optional)

If you have an OSM parquet file (from osm2geoparquet), type (replacing the path):

FACETT_OSM_PARQUET=/path/to/ways.parquet cargo run -p facett-demo --bin osm3d_demo --release

Step 4 — turn on the fancier GPU look (optional)

Type and press Enter:

cargo run -p facett-demo --bin osm3d_demo --features facett-map3d/wgpu

This turns on shadows, reflective water, and post-processing on supported hardware. Without this flag you still get a full lit 3D map — it's just drawn by the CPU instead of the graphics card, so it always works even with no GPU.

Step 5 — check it actually rendered (the self-test)

A picture on a GPU can't be checked automatically the normal way, so there is a special check that renders the map with nobody watching and counts lit pixels. Type and press Enter:

cargo run -p facett-map3d --example selftest --features testmatrix

You should see a line ending in ok=true. That means it worked.

Part 2 — the flying camera (facett-map3d-flight)

This crate is a code library today, not yet its own app window — you exercise it through its tests. Type and press Enter:

cargo test -p facett-map3d-flight

Green test result: ok means the floating-origin math, the flight camera, the atmosphere colours, and the tile planner all behave. There is nothing to look at yet for this part — it is the engine under the map, not a picture.

Part 3 — the 3D model viewer (facett-model3d)

Step 1 — see the spinning skull

Type and press Enter:

cargo run -p facett-model3d --example skull_demo

A window opens with a spinning skull. Drag the status slider at the top — watch the eyes fade from green (healthy) through yellow to red (critical). Drag the skull itself with the mouse to spin it by hand.

Step 2 — open your own 3D model (optional)

If you have a .glb file, type (replacing the path):

cargo run -p facett-model3d --example view_glb -- /path/to/model.glb

With no path given it shows the bundled skull instead.

Step 3 — run its tests

Type and press Enter:

cargo test -p facett-model3d

Green test result: ok = the loader, the rotation math, and the status colours all check out.

You're done

You have now: seen the 3D map (synthetic + rabbit + optionally real data + optionally GPU-accelerated), proven the flight-sim engine's tests pass, and seen the 3D model viewer with its status slider. That is the whole 3D spatial subsystem, cold shell to green.