nordisk/facett

OSM region picker in facett-demo — 🌍 clip a region from the cached planet (design + guide)

A 🌍 Region button → modal that clips a country/region out of the already-cached planet OSM (via osm-katana) and loads the result into the OSM 2D/3D viewer tabs. Hardcoded v1 presets: Sverige / Skandinavien / Europa. The clip runs on a background thread with live status, the result is cached so a repeat pick loads instantly, and everything observable lands in state_json so the test matrix validates it as DATA (no pixels).

The pipeline (UI → clip → cache → load → swap)

🌍 Region button ─▶ modal (Sverige / Skandinavien / Europa)
        │ pick(preset)
        ▼
  background thread (run_pipeline)
        │
        ├─ cache_hit(out)?  ──yes──▶ skip clip ─┐
        │                                       │
        └─no─▶ planet_source()  (cached, never re-download)
                │  clip_supported(bin)? ──no──▶ Status::Error("clip CLI not available")
                │  osm-katana convert --clip <arg> <PLANET> -o <out>
                ▼                                       │
        load_from(out/nodes.parquet, out/ways.parquet) ◀┘
                │  Status::Loading → Msg::Loaded(geo)
                ▼
  UI thread: poll() → Status::Ready → take_loaded()
                │
                ▼
  DemoState::apply_loaded_region() → deck.replace_facet("OSM 2D"/"OSM 3D", …)

Preset → clip-arg mapping (load-bearing)

nordics/europe already exist as osm-katana region-clip presets; sweden (and --poly) are being added on znippy fix/osm-katana-gatling-saturation. The argv is convert --clip <arg> <PLANET> -o <out> (region_picker::clip_args).

Source = the ALREADY-CACHED planet (never re-download)

planet_source() reuses the bench's cached planet, in order:

1. /home/rickard/work/planet-260427.osm.bz2 (the bench PLANET_BZ2, fast disk)
2. /run/media/rickard/T9/planet-260427.osm.bz2 (fallback)

TODO (F2, future): the planet + borders will be hosted & versioned in znippy and pulled from there (torrent / object store). v1 strictly reuses the cached file — planet_source() is the single hook to swap when that lands.

Cache hit / miss

region_cache_dir(preset) = ~/.cache/facett-osm/<arg>-geo (honours $XDG_CACHE_HOME). cache_hit(dir) ⟺ both nodes.parquet and ways.parquet exist. On a hit the clip is skipped and the GeoParquet is read straight into the viewer (instant). Outputs are always on /home or ~/.cache — never T9 (asserted in cache_dir_is_stable_under_home_cache).

Guard: --clip not available yet

If the osm-katana binary doesn't understand convert --clip (probed via clip_supported() → convert --help contains --clip), the pipeline surfaces Status::Error("clip CLI not available: … has no convert --clip yet") instead of running a doomed subprocess — the dialog + invoke + cache logic are all wired and go live the moment the --clip build lands. The binary is resolved as ~/.cache/znippy-target/release/osm-katana, falling back to osm-katana on $PATH.

state_json surface (the test contract)

DemoState::state_json()["region_picker"] =

{ "region": "Sverige", "clip_arg": "sweden",
  "source": "/home/rickard/work/planet-260427.osm.bz2",
  "out": "…/facett-osm/sweden-geo",
  "cache_hit": true, "status": "ready",
  "open": false, "presets": ["Sverige","Skandinavien","Europa"] }

status ∈ idle | clipping | loading | ready | error.

Loading into the viewer (runtime path, not just env)

osm_tabs::load_from(nodes, ways, OsmSource::Region(label)) is the runtime-path entry the picker uses (load() is now the env/default wrapper over it), so the OSM tabs accept a clipped region at runtime, not only via $FACETT_OSM_PARQUET. The host rebuilds osm2d_view/osm3d_view from the loaded geometry and swaps them into the deck in place via the new FacetDeck::replace_facet(title, …) — keeping the stable OSM 2D / OSM 3D slots (so the mega-matrix / robot coverage gates over the 23 LEGEND components are untouched; the picker is a toolbar control, not a new tab).

Where it's covered in the matrix (validated as DATA)

• facett-demo/src/region_picker.rs unit tests (7): presets list + order, preset→clip-arg mapping, clip_args argv, cache dir stability (+ not on T9), cache_hit detection, state_json keys, and pick→poll reaching a terminal status without panicking.
• facett-demo/tests/region_picker.rs (3): the dialog lists the 3 presets + mapping; a cache-hit short-circuit using liechtenstein staged into the sweden-geo slot as the tiny clip stand-in, flowing pick→poll→ready→ take_loaded through to a headless-rendered non-blank OSM 2D (real vertices + the tab's state_json geometry); and the host swap (DemoState::apply_loaded_region → replace_facet) re-rendered non-blank. Each emits a nornir_testmatrix row under --features testmatrix.

We do not run a real planet→Sweden clip in a test (hours); that is the integration step once the --clip CLI lands on znippy.

Manual run

cargo run -p facett-demo        # click 🌍 Region → pick Sverige/Skandinavien/Europa
# (needs the cached planet on /home + an osm-katana with `convert --clip`)