Indoor Survey — design brief (v2)

Feature: Indoor coverage testing for the YANL logger (Android). Status: Design — not yet built. v2 incorporates external review feedback (see §18). One-line framing: the MVP is not “a map of indoor coverage.” It is an auditable indoor route with RF readings, explicit evidence, and uncertainty users can understand.

1. Problem and goal

Drive-test apps map outdoor coverage with GPS. Indoors there’s no GPS, so competitors fall back to either floor-plan + manual waypoints (a plan is rarely available) or AR/VIO (e.g. WiFiMan via ARCore — rough room shape, but gives the user no confidence it’s right, drifts, needs the phone held up).

Goal: record indoor RF coverage with good, honestly-quantified accuracy, without requiring a floor plan and without depending on AR.

Shaping insight: a bare phone has no drift-free indoor absolute reference, so we don’t chase “magic accuracy.” We win on (a) removing the floor-plan requirement, (b) an intuitive recognition-based anchoring gesture, and (c) honest, calibrated uncertainty — the thing the AR apps fail at. The product’s credibility is the feature.

2. Core concept

Walk; at each recognisable feature, mark where you are on a recognisable picture of the building; dead-reckoning fills the path between; the app shows — in plain language — how trustworthy each point is.

• The picture only needs to be recognisable, not metrically accurate — its job is to let the user say “yes, that’s the doorway I’m at.” Precision comes from the tap (an absolute anchor) plus pedestrian dead reckoning (PDR) measuring the legs. Rough satellite roof imagery is enough: rough picture, precise result.
• Mark-where-I-am is the default, not mark-where-I’ll-walk (see §5.1). Pre-marking a destination only works when you can see it on a floor plan.
• A reference layer is always shown, degrading gracefully: satellite → floor plan → metric grid.
• Short legs (≤ ~10 m, or corner-to-corner) keep PDR drift small before each correction.

3. Design principles (the trust rules)

These are non-negotiable and must be designed into the foundations, even where the surfaced UI is staged for later:

1. Anchors are evidence with a quality level. A roof-image tap, a calibrated plan doorway, a GPS entrance fix and a Wi-Fi RTT point are not equivalent. Confidence improvement scales with anchor quality — a weak anchor barely tightens it.
2. Confidence is per-sample and plain-language, never a single decorative “mean.” The user needs to know whether this coverage reading is trustworthy.
3. Never imply precision the data doesn’t have. Weakly-located readings must be blurred/faded/suppressed in the heatmap — not drawn as crisp dots. Honest on one screen and falsely precise on the next is a bug, not a polish item.
4. Separate data-correction from presentation. Anchor-based reconstruction changes the route (logged, reproducible); freehand visual alignment moves an overlay for readability and does not improve accuracy. Never let presentation silently upgrade credibility.
5. One supported operating model in v1. Trust rests on calibrated uncertainty, so don’t apply one PDR model to radically different carry styles. Support “upright in hand” first; detect and warn when reality diverges.
6. Validate calibration, not just average error. A claimed 90% region must contain the truth ~90% of the time — traded off against sharpness (a huge honest band is useless; a tight band that misses reality is worse).

4. Product features (tagged v1 / later)

• Recognition-based “mark my location” anchoring — v1
• Live breadcrumb + north arrow + scale bar — v1
• Graceful reference layers (satellite / grid; floor plan — later) — v1/later
• Continuous passive RF logging while walking; optional spot iPerf test at a point — v1
• Anchor quality model + pre-apply preview (“moves last leg ~4 m; reference: approximate satellite”) — v1 (model) / v2 (rich UI)
• Per-sample confidence, plain-language — v1
• Uncertainty-aware heatmap (blur/fade weak points) — v1 (must not fake precision)
• Anchor-based reconstruction (rubber-sheet, downstream, reproducible) — v1
• Return-to-start residual check (measures error; not “cancel drift”) — v1
• Sensor-health setup check + carry-change warnings + anchor prompts on pause/rotation/transition — v1
• Survey-quality verdict before save — v1 (basic) / v2 (calibrated thresholds)
• “What is this map based on?” panel — v1
• Floor-plan attach + GroundOverlay anchoring — later
• In-walk annotations (door/window/lift) — later
• Multi-floor — later
• Self-drawn outline (perimeter trace) — later
• Audited manual anchor edits / visual alignment (presentation-only, clearly labelled) — later
• Wi-Fi RTT ranging; deep-inertial model; ARCore booster — later (Phase 3)

5. User journeys

5.1 Primary — reactive “mark my location” (no floor plan)

1. Open Indoor Survey → pin start on Google Maps (entry GPS), choose floor, name the test.
2. Sensor-health check: hold still a few seconds; app confirms steps + stable rotation are detectable; set initial heading.
3. Reference defaults to satellite; building footprint visible. Start — RF logging begins; breadcrumb appears.
4. Walk (phone upright in hand). After a short distance or a major turn the app prompts: “At the next recognisable feature, mark your location.”
5. At a doorway/corner/lift, tap “Mark my location.”
6. Tap that feature on the reference image and confirm.
7. The app shows a preview: “This adjustment moves the last leg by ~4 m. Reference quality: approximate satellite.” → accept. Breadcrumb snaps; confidence updates by anchor quality.
8. Repeat 4–7. Per-sample confidence shown throughout.
9. Finish: optionally walk back to start → “Check return to start” reports the residual difference (e.g. “3.8 m — acceptable” or “large — review the last two anchors”).
10. Review → Save with a survey-quality verdict.

5.2 Floor-plan mode — “plan next point” (advanced)

With a plan attached, pre-marking the next destination on the plan is intuitive (you can see it). This is the only place the “tap where I’ll walk” flow belongs.

5.3 Fallback — no useful imagery

Satellite unhelpful + no plan → metric grid + north arrow. Walk-then-mark relative legs; the trace is the map; the return-to-start residual is the main quality signal. Verdict will likely be Relative-only.

5.4 Multi-floor (later)

At a stair/lift: “End floor” → “Start next floor” seeds the next floor at the same footprint x/y, new floor index. Vertical movement is a discrete event, not PDR-measured.

5.5 Recovery

Undo last leg; pause/resume (re-anchor on resume); process-death reload; carry-change warning prompts a fresh anchor.

6. Page / screen design

A. Setup sheet — start pin (GPS suggestion), floor (index + label), test name, sensor-health check + heading, optional plan attach.

B. Live survey (full-screen, like FullScreenMapScreen) — reference layer + layer switcher, live breadcrumb + north arrow + scale bar, uncertainty-aware path rendering. Bottom bar: “Mark my location”, optional spot test, undo last leg, annotate (later), floor controls (later). Compact live readout: current RF, distance, anchors, per-sample position quality. A small “What is this map based on?” affordance.

C. Mark-location flow — tap the feature on the image → preview adjustment + reference quality → confirm/cancel; snap animation proportional to correction.

D. Review — full trace; draggable anchors (audited edit → re-reconstruct); return-to-start residual readout; survey-quality verdict; presentation-only visual alignment behind a clearly-marked toggle (not in the main flow). CTA: Save / Discard.

E. “What is this map based on?” panel — one place that states the active layer’s meaning and limits (see §12), including the upper-floor roof caveat surfaced in-UI, not buried in docs.

7. Anchor model

Every anchor carries a quality, drives reconstruction weight, and is shown to the user:

Before applying, show the adjustment magnitude + reference quality (catches mistaps). An anchor never tightens confidence just because it exists — only by its quality and how well it agrees with the incoming PDR.

8. Confidence & calibration

• Per-sample, plain-language. e.g. “Position quality: Limited — likely within 4–7 m here. Reason: 16 m since the last high-quality anchor.”
• No headline mean as the story. A mean can hide a badly-located section.
• Heatmap must respect uncertainty. Render weak points blurred/faded/suppressed; only well-located readings get crisp markers. (Principle §3.3.)
• Validation = calibration + sharpness (see §16): the band’s claimed coverage must match reality; tighten only as far as honesty allows.

9. Correction vs presentation (three distinct operations)

1. Anchor-based reconstruction — derived route changes; logged; reproducible from raw PDR + anchors; affects confidence.
2. Manual anchor edit — creates an audited correction event (author/time/reason); re-runs reconstruction.
3. Visual alignment — moves an overlay for readability only; does not change positions or shrink the band; logged as presentation-only; kept out of the normal workflow.

Return-to-start is renamed and re-framed: it measures residual error and adds a constraint — it does not “cancel drift.”

10. Positioning pipeline

1. PDR (relative). Fuse accel + gyro + rotation-vector (+ step detector) at ~100–200 Hz → per-tick Δx/Δy + heading. v1 = step + stride + gyro-heading with zero-velocity updates. Expect ~5–10 % drift between anchors — fine on ≤10 m legs.
2. Anchors (absolute, quality-weighted). Manual tap, entry/exit GPS, return-to-start, (later) Wi-Fi RTT.
3. Reconstruction (downstream). Warp raw PDR onto anchors — similarity transform (2 anchors) → piecewise affine (more), weighted by anchor quality. Done by consumers (review screen + platform), not baked into the live log.
4. Confidence model (versioned). Per-point uncertainty = f(distance + turns since last good anchor, anchor quality, PDR residual at anchors).
5. Georeferencing. Start GPS + heading place the relative frame on the world.

11. Operating model & sensor health (v1 discipline)

• Supported carry: “upright in hand while walking.” Documented and detected.
• Setup check: hold still → confirm step detection + stable rotation; reject/​warn if the IMU looks unhealthy.
• Runtime watchdogs: warn when heading goes unreliable or the carry style appears to change; prompt for an anchor after a pause, a phone rotation, a lift/stair transition, or a long unanchored stretch.
• Pocket/swinging carry is explicitly out of scope for v1 (it would break calibration); revisit with deep-inertial in Phase 3.

12. Reference layers — meaning & limits (shown in-UI)

The upper-floor roof limitation is surfaced in the UI, not just documentation.

13. Libraries / APIs

14. Fit with the log (new joinable records; radio_sample untouched)

Positioning is added as new record types alongside the v3 stream; RF (radio_sample) is unchanged; we log raw data + evidence and reconstruct downstream. Bump to schema_version: 4 (existing parsers ignore unknown record_types).

Records and fields the reviewer correctly asked for:

• indoor_survey_start — survey_id, test_name, building_anchor {lat,lon,accuracy_m}, floor {index,label}, reference_layer {type, floorplan_ref?, expected_reference_uncertainty_m}, initial_heading_deg, position_algorithm_version, confidence_model_version, carry_mode.
• pose (per tick; joins to radio_sample by tick_index) — elapsed_realtime_nanos (monotonic, not just wall-clock), pdr_x_m, pdr_y_m, heading_deg, floor_index, confidence_m, position_source (raw_pdr / anchor_reconstructed / presentation), last_anchor_id, sensor_state.
• indoor_anchor — anchor_id, tick_index, raw pdr_x_m/pdr_y_m, truth {lat,lon}/{plan_x,plan_y}, label, method, quality (strong/moderate/weak/unverified), quality_reason.
• indoor_correction (audit) — for manual anchor edits and visual alignment: kind (anchor_edit / visual_alignment), author, time, reason, before/after, and a flag that visual alignment is presentation-only.
• indoor_survey_end — survey_id, anchor_count, path_length_m, calibration/quality summary, closure_residual_m, verdict.

The whole point: a reviewer can reproduce the route and understand exactly why each sample sits where it does, and can tell raw PDR from anchor-reconstructed from presentation-only.

15. Platform playback

1. Reconstruct the corrected trace web-side from pose + indoor_anchor (+ indoor_correction), using the logged position_algorithm_version so it matches the app deterministically.
2. Join each radio_sample to its pose by tick_index → place every RF reading.
3. Render on satellite / plan / grid, with uncertainty (weak points blurred — never crisp), anchors shown with quality, and the survey verdict surfaced.
4. Per-floor, per-metric heatmaps that fade with positional uncertainty.

Deliverable to the platform team: extend the v3 brief with these records + the reconstruction note + the raw/reconstructed/presentation distinction.

16. Survey-quality verdict (calibrated)

Classify each survey rather than letting all surveys look equivalent:

• Verified indoor route — enough high-quality anchors + acceptable closure.
• Usable with uncertainty — useful, but some sections weakly located.
• Relative-only survey — valid RF sequence, unsuitable for absolute map placement.

Don’t hard-code thresholds until field tests set them. The headline validation metric is calibration (a 90% region contains truth ~90% of the time), tracked alongside sharpness.

17. Implementation & testing phases

Phase 0 — spike: bare PDR on a few phones; walk a tape-measured rectangle; measure raw drift + per-device variance. Confirms the accuracy floor before UI.

Phase 1 — MVP (foundations + honesty): setup + sensor-health, satellite/grid, breadcrumb, mark-my-location + quality-weighted reconstruction, per-sample plain-language confidence, uncertainty-aware heatmap, return-to-start residual, basic verdict, one carry mode, the new log records (raw/reconstructed/presentation + audit), platform reconstruction parity. Single floor.

Phase 2 — depth + chrome: floor-plan attach + plan-mode flow, rich anchor-quality UI, in-walk annotations, multi-floor, self-drawn outline, calibrated verdict thresholds, audited manual edits, full platform heatmap.

Phase 3 — accuracy upgrades: Wi-Fi RTT, deep-inertial model, optional ARCore.

Testing (calibration-first):

• Unit/sim: PDR, reconstruction transform, confidence model, log round-trip (write → re-read → reconstruct identically), audit-record integrity.
• Ground-truth walks: tape-measured paths; metrics = anchor-to-anchor error, position error vs truth, and calibration (does the 90% band contain truth ~90% of the time?) + sharpness.
• Multi-device IMU matrix + carry-style enforcement (confirm out-of-mode carry is detected and warned).
• Closure/edit tests: deliberately drifted walk corrected to target; audit events created correctly.
• End-to-end parity: app review screen and platform reconstruct the same trace.
• Field beta: real buildings; collect “did it match reality?” and confidence-calibration feedback.

18. What changed from v1 (and why)

Driven by external review; the changes all serve the same principle — credibility through calibrated, auditable honesty:

• Primary flow flipped to mark-where-I-am (pre-marking only survives in floor-plan mode).
• Added the anchor-quality model + pre-apply preview.
• Confidence made per-sample and plain-language; heatmap must not fake precision.
• Correction vs presentation split into three audited operations; “drag-to-align” demoted to presentation-only, out of the main flow; “close the loop / cancel drift” renamed to return-to-start residual.
• One carry mode + sensor-health checks for v1.
• Reference-layer meaning/limits surfaced in-UI (incl. upper-floor roof caveat).
• Survey-quality verdict + calibration/sharpness as the validation metric.
• Log fields added: monotonic elapsed_realtime_nanos, algorithm/confidence-model versions, carry/sensor state, anchor quality + reason, reference provenance/uncertainty, audit records, and an explicit raw / reconstructed / presentation distinction.

19. Open questions

• Calibrating the confidence band (must not be over-confident) — the make-or-break validation.
• schema_version: 4 vs a capability flag — confirm with platform.
• Deep-inertial commercial licensing (Phase 3).
• Wi-Fi RTT AP availability — bonus, not baseline.
• Battery/thermal over long surveys.