summaryrefslogtreecommitdiff
path: root/wasm-plan.md
diff options
context:
space:
mode:
authorJohannes Hofmann <Johannes.Hofmann@gmx.de>2026-10-27 10:33:00 +0100
committerJohannes Hofmann <Johannes.Hofmann@gmx.de>2026-10-27 10:33:00 +0100
commit236fcded5e7302c4b99f4626b4e8cbc35896ceee (patch)
treebb377ef43ac3929ba1075923397bbf7134f7aa98 /wasm-plan.md
parent459ecc314e082579d80d3b301e60360f32b63c5c (diff)
wasm: add plan for a real browser version
Scope (feature-parity map with binding v1 non-goals), architecture decisions (Yew, canvas 2D hybrid rendering, localStorage/PWA storage, byte-oriented core APIs), port map from the desktop app modules, milestones W1-W6 (~3 weeks), risks, and open questions to settle before W1.
Diffstat (limited to 'wasm-plan.md')
-rw-r--r--wasm-plan.md223
1 files changed, 223 insertions, 0 deletions
diff --git a/wasm-plan.md b/wasm-plan.md
new file mode 100644
index 0000000..d030b0d
--- /dev/null
+++ b/wasm-plan.md
@@ -0,0 +1,223 @@
+# gipfel-web — plan for a real browser (WASM) version
+
+Status: **planning**. Feasibility spike done and verified on this branch
+(`crates/gipfel-wasm`): the full computational core — hill DB, JPEG
+comment + EXIF I/O, geodesy, projections, Levenberg–Marquardt fit — runs
+in the browser at native speed (sub-pixel refit on a real 4080×3072
+photo in 50 ms). See `crates/gipfel-wasm/README.md`.
+
+This document defines scope, architecture, and milestones for turning
+that into a usable web app. It assumes the desktop app (master) stays
+the primary product; the web version is a second front end on the same
+`gipfel-core`.
+
+---
+
+## 1. Goals and non-goals
+
+### Goals
+- View a photo, place/move/delete markers, identify peaks, fit the
+ projection, save the annotated JPEG — the complete desktop workflow
+ minus OS-integration extras.
+- All processing local (client-side WASM); images never leave the
+ machine. This is a feature, say it loudly.
+- Works offline after first visit (PWA), including the hill database.
+- Reasonable on a mid-range phone, good on a desktop browser.
+
+### Non-goals (v1)
+- No panorama stitching / TIFF export (heavy, desktop-only; revisit as
+ W6 stretch — `stitch::resample` is already wasm-clean).
+- No GPX track loading initially (cheap to add later: `track.rs` is
+ pure Rust; deferred only to keep UI scope small).
+- No distortion-profile management UI beyond load/save (localStorage).
+- No i18n in v1 (same open question as desktop; gettext in wasm is its
+ own rabbit hole).
+- No multi-window, no screen dump (browser screenshots exist).
+
+### Feature parity map
+| Desktop feature | Web v1 | How |
+|---|---|---|
+| Load image (EXIF + gipfel comment) | ✅ | File input / drag-drop → `load_image_from_bytes` (done) |
+| Markers: add / move / delete / hide | ✅ | canvas hit-testing (port of viewport.rs logic) |
+| Fit (4/7-param, distortion lock) | ✅ | `comp_params[_with]` (proven in spike) |
+| Compass strip | ✅ | port `compass.rs` math (already wasm-clean) |
+| Sliders (lat/lon/height/az/pitch/roll/focal/visibility) | ✅ | HTML range inputs |
+| Save annotated JPEG | ✅ | `save_image_to_bytes` (done) + Blob download |
+| Screen dump with labels | ✅ | `dump.rs` is pixel-based — ports nearly unchanged |
+| Profiles | ✅ (basic) | `profile.rs` format in localStorage |
+| Hill DB | ✅ | bundled gzipped, user-overridable via file input |
+| GPX tracks | ⏳ v1.1 | `track.rs` ports directly |
+| Stitch export | ⏳ stretch | `stitch.rs` ports directly |
+| Menu bar / nav bar | ➡️ | HTML sidebar + keyboard shortcuts |
+
+---
+
+## 2. Architecture decisions
+
+### A1. UI framework: **Yew 0.21**
+- Most mature Rust web framework, stable API, plain Rust, plays well
+ with wasm-bindgen; no proc-macro magic beyond `#[function_component]`.
+- Alternatives considered: Leptos (finer-grained reactivity, faster
+ DOM updates — but newer API churn), Dioxus (nice, but its web backend
+ is Leptos-derived; adds a second dependency family). The app is
+ canvas-centric: 95 % of per-frame work is canvas drawing, not DOM, so
+ framework reactivity differences are second-order. Yew's maturity
+ wins.
+- The heavy widgets (viewport, compass) are **canvas**, not DOM — the
+ framework only manages the sidebar, dialogs, and file plumbing.
+
+### A2. Rendering: **canvas 2D, hybrid image layer**
+- Base image: decode once with `createImageBitmap` (browser-native,
+ fast, GPU-backed); draw with `drawImage` + transform for pan/zoom —
+ the browser does scaled blitting on the GPU. This is strictly better
+ than the desktop path (per-frame `putImageImageData`).
+- Overlays (markers, labels, leaders, compass): drawn per frame on the
+ same canvas with `ctx` primitives + `fillText`.
+- Export/dump: keep the pixel-based renderer (`dump.rs` port) — it
+ renders at full image resolution independent of the viewport and is
+ already proven.
+- **Not** wgpu/WebGPU: uneven support (Safari), and the desktop wgpu
+ path exists only because putImageData was too slow there; canvas 2D
+ removes the need.
+
+### A3. State: one reducer, ported 1:1 from `GipfelApp`
+- The desktop `Message` enum maps almost directly to a Yew `Msg` enum;
+ keep field names identical so bugs can be cross-checked between
+ front ends.
+- `Panorama` lives in a ` Rc<RefCell<>>` (or Yew state handle) inside
+ the root component; markers/params in reducer state.
+
+### A4. Storage
+- Settings + distortion profiles: `localStorage` (JSON), reusing the
+ `profile.rs` parameter semantics (k0/k1/x0 triples).
+- Hill DB: bundled `gipfel.dat.gz` (~300 KB gzipped) cached by the
+ service worker; decompressed with `flate2` (pure Rust, wasm-safe) or
+ `DecompressionStream` in JS. User may load a different DB file.
+- No IndexedDB needed for v1.
+
+### A5. Files in / out
+- In: `<input type="file">` + drag-drop → `Vec<u8>` → byte-oriented
+ core APIs (already exist).
+- Out: `Blob` + object URL + synthetic `<a download>` click.
+ `save_image_to_bytes` already produces the annotated JPEG bytes.
+
+### A6. Concurrency
+- Fit is 50 ms including DB parse — main thread is fine for v1.
+- Escape hatch if needed: move `Panorama` into a Web Worker
+ (`wasm-bindgen-worker`), messages map 1:1 to core calls. Do not
+ build this until a measurement demands it.
+
+### A7. Text / fonts
+- Canvas `fillText` with the CSS font stack; label layout code
+ (`layout_label_y`, collision push-up) ports unchanged — it is pure
+ math over widths, which come from `ctx.measureText`.
+
+---
+
+## 3. Crate / module layout
+
+New crate `crates/gipfel-web` (on this branch; `gipfel-wasm` folds into
+it or becomes its `demo/`):
+
+```
+crates/gipfel-web/
+ src/lib.rs Yew root component, routing between views
+ src/state.rs app state + reducer (port of GipfelApp fields/Message)
+ src/canvas_view.rs viewport canvas: bitmap layer + overlay layer,
+ zoom/pan, hit-testing, marker drag
+ src/compass.rs compass strip on canvas (port of app compass.rs)
+ src/sidebar.rs settings controls (sliders, checkboxes, file pickers)
+ src/dump.rs full-res annotated export (port of app dump.rs)
+ src/bridge.rs JS glue: downloads, localStorage, image bitmaps
+ www/ index.html, manifest.webmanifest, sw.js, gipfel.dat.gz
+ tests/ wasm-bindgen-test (headless browser)
+```
+
+Port map from the desktop app (`crates/gipfel-app/src/`):
+
+| Desktop | Web | Change required |
+|---|---|---|
+| `main.rs` state + `Message` | `state.rs` | cosmic → Yew plumbing; fields identical |
+| `viewport.rs` (iced Widget) | `canvas_view.rs` | draw calls → `ctx`; zoom/pan/hit-test/label layout port directly |
+| `compass.rs` | `compass.rs` | draw → `ctx`; `newton_inverse` unchanged |
+| `dump.rs` | `dump.rs` | nearly unchanged (already pixel-based) |
+| settings sidebar | `sidebar.rs` | cosmic sliders → `<input type=range>` |
+| config/profiles | `bridge.rs` | XDG file → localStorage |
+| file dialogs | `bridge.rs` | cosmic dialog → file input + Blob |
+
+`gipfel-core` is consumed **unchanged** — it is already wasm-clean and
+the byte-oriented APIs exist. If anything in core needs a change, it
+goes through the same golden-test gate as desktop work.
+
+---
+
+## 4. Milestones
+
+### W1 — Scaffold + image display (2–3 days)
+- Yew app, Trunk build, `www/` shell, wasm target wired in CI.
+- File input + drag-drop → `createImageBitmap` → pan (drag) + zoom
+ (wheel, cursor-anchored) on canvas.
+- **Accept:** photo loads, pans, zooms at 60 fps on a 4000×3000 image.
+
+### W2 — Core wiring (2–3 days)
+- Load bundled hill DB (gzip decompress + `load_data_from_bytes`).
+- `load_image_from_bytes` → EXIF/comment → initial viewpoint.
+- Marker add/move/delete with hit-testing; `comp_params` on ≥4
+ markers; distortion-lock checkbox.
+- **Accept:** on a gipfel-saved photo, markers reproduce the desktop
+ fit to the same parameters (compare against desktop on same image).
+
+### W3 — Overlays + controls (3–4 days)
+- Labels with collision layout, leader lines, known/hidden flags.
+- Compass strip (drag to rotate azimuth).
+- Sidebar sliders (lat/lon/height, azimuth, pitch, roll, focal,
+ visibility) with live update; visibility inversion parity.
+- **Accept:** visual parity review against desktop screenshots.
+
+### W4 — Save + profiles + settings (2 days)
+- Save annotated JPEG (dump renderer port + Blob download).
+- Profiles: list/save/load in localStorage; profile-name suggestion
+ from EXIF (same rule as desktop).
+- Persist app settings (last viewpoint params) across reloads.
+- **Accept:** round trip: save in browser → open in desktop app →
+ parameters identical.
+
+### W5 — PWA + polish (2–3 days)
+- manifest + service worker (offline incl. DB), loading states,
+ error surfaces (bad file, <2 visible hills, …), keyboard shortcuts
+ (fit, save, undo if trivial), mobile layout (sidebar → bottom sheet).
+- **Accept:** Lighthouse PWA pass; works in airplane mode after one
+ online visit.
+
+### W6 — Hardening + deploy (2 days, + stretch)
+- `wasm-pack test --headless` smoke tests (DB parse, fit on fixture
+ bytes); Playwright e2e against preview deploy.
+- Static hosting (any static host; `git.flpsed.org` pages if available),
+ CSP headers, size budget: initial download ≤ 1.5 MB gzipped
+ (wasm ~400 KB + DB ~300 KB + app shell).
+- Stretch: GPX tracks; TIFF stitch export via download.
+
+**Total: ~2.5–3 weeks focused**, matching the earlier estimate. The
+spike already retired the two scariest risks (core-in-wasm, fit speed).
+
+---
+
+## 5. Risks & mitigations
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| Canvas label metrics differ from iced → label layout drift | cosmetic | layout code is width-driven; tune line-height constant on real browser |
+| Memory on mobile (4080×3072 RGBA ≈ 50 MB + wasm heap) | OOM on low-end phones | downscale preview bitmap for display (keep full-res only in dump path); measure iOS Safari early (W1) |
+| `image`/`exif`/`flate2` wasm compile surprises | days | all pure Rust; verify in W1 scaffold (`cargo check --target wasm32-unknown-unknown -p gipfel-web`) |
+| Service worker caching stale DB/app | confusing updates | versioned cache keys, skipWaiting flow with "update available" toast |
+| Scope creep toward desktop parity | never ships | non-goals table is binding for v1; stitch/GPX explicitly deferred |
+| Two front ends drift apart (desktop fixes not applied to web) | long-term maintenance | shared core + shared golden tests; web-specific tests only for glue |
+
+---
+
+## 6. Open questions (decide before W1)
+1. **Where does it live?** subdomain (web.gipfel.flpsed.org?) + which static host.
+2. **Bundle the full 21k hill DB** (~1 MB gz ≈ 300 KB) or offer regional subsets? Default: full, it fits the budget.
+3. Name: same "gipfel" brand for web, or distinct (e.g. "gipfel web")?
+4. Does the web version need its own About/privacy page text (all-local processing statement)?
+5. Framework confirmation: Yew per A1, or do you want to evaluate Leptos first? (One-day spike would settle it; Yew default stands.)