Research handoff: live survey findings, options and tested prototypes

README.md

@@ -44,6 +44,7 @@ A convincing 3D view can still miss an obstacle or get a distance wrong, so ever
 | [docs/03-stack-research.md](docs/03-stack-research.md) | The open-source projects and libraries we build on, and the ones we skip |
 | [docs/04-prior-art-and-codes.md](docs/04-prior-art-and-codes.md) | Base's public rules, similar products, and electrical-code citations |
 | [docs/05-live-guided-survey-hld.md](docs/05-live-guided-survey-hld.md) | Proposed live guidance and automatic capture architecture, diagrams, evidence flow, and technical resources |
+| [docs/06-research-handoff.md](docs/06-research-handoff.md) | Research findings, recommended architecture, tested prototypes, alternatives, and remaining field-validation work |
 | [docs/eli5.html](docs/eli5.html) | A visual walkthrough with an interactive demo of the placement search |
 
 Contributors and coding agents start with [AGENTS.md](AGENTS.md). This repository is public, so materials Base gave the team stay in the git-ignored `private/` folder.

docs/06-research-handoff.md

@@ -0,0 +1,83 @@
+# Live survey research: findings and handoff
+
+September 26, 2026. Research stopped at the user's request. This report packages the completed work, useful implementation proposals, and remaining validation gaps. It is a research handoff, not a production-readiness or installation-accuracy claim.
+
+**Recommendation: build a hybrid evidence loop around native capture.** Use Swift, ARKit and RealityKit for the open camera, pose tracking, photo selection and immediate guidance. Save each useful original photograph with its own calibration and pose. Let asynchronous services perform heavier recognition and reconstruction, then evaluate requirements with explicit evidence and uncertainty. A complete photorealistic house model should not block a useful, source-backed answer.
+
+## What was achieved
+
+| Area | Completed work | Practical outcome |
+| --- | --- | --- |
+| Camera and capture | Compared native iOS, Android, browser and native-module paths; typechecked relevant ARKit still-capture and guidance APIs; built a durable capture-admission prototype | Native iOS is the leading integration path. Progress must follow the returned, accepted, durably saved photograph—not the preview that triggered it |
+| Coverage and guidance | Explored surface coverage, unknown space, task evidence, next-view policies and screen projection; exercised synthetic policies and actual native coverage code | Separate **where to move**, **where to aim**, and **what evidence is still missing**. Geometry revisions can invalidate earlier coverage |
+| Reconstruction and visualization | Audited classical, learned batch, streaming and phone-depth alternatives; ran bounded DA3, MoGe, Apple depth and COLMAP probes | Several components run locally, but none establishes exterior measurement accuracy. Keep fast local geometry and slower reconstruction revisions separate |
+| Recognition and association | Tested OCR/barcodes, box trackers, image correspondence and causal point tracking; built a revision-aware association prototype | Recognition confidence and a persistent tracking ID do not prove the correct equipment or exact label value |
+| Architecture and integration | Checked camera/calibration conversions, evidence admission, reset races, export/version semantics and deployment limits | Preserve originals and coordinate epochs; use resumable object storage separately from compact placement requests |
+| Reviewable implementation | Published two standalone Python prototypes and two isolated Swift patch proposals; existing camera-conversion work remains in [PR #9](https://github.com/SamGu-NRX/house-scanning/pull/9) | Useful work is available for selective integration without changing teammates' application branches |
+
+The detailed [options and resources](research/2026-09-26-options-and-resources.md) retain alternatives. The [experiment evidence](research/2026-09-26-experiment-evidence.md) records positive, negative, blocked and unrun outcomes.
+
+## Recommended flow
+
+```mermaid
+flowchart TD
+    A[Open camera and capability checks] --> B[Local tracking and image-quality checks]
+    B --> C[Coverage and missing task evidence]
+    C --> D[Move cue or aim cue]
+    D --> E[Select a useful still]
+    E --> F[Assess actual returned image and metadata]
+    F --> G[Durably admit original and evidence]
+    G --> C
+    G --> H[Resumable upload to object storage]
+    H --> I[Asynchronous recognition and reconstruction]
+    I --> J[Versioned geometry and sourced observations]
+    J --> K[Deterministic checks with uncertainty]
+    K --> L[Supported result or specific missing evidence]
+    L --> C
+    J --> M[Inspectable 3D preview with original photos]
+```
+
+Local feedback continues while uploads and workers are pending. Capture completion, upload completion, analysis completion and assessment completion are separate states. A newer result is accepted only when its evidence and coordinate dependencies are still valid.
+
+## Findings that change the design
+
+1. **A view is useful only after the actual still is assessed and saved.** A preview may look sharp while the returned still is late, blurred, from another pose, or associated with an obsolete task. The capture prototype makes admission and progress transactional, preserves original evidence, and prevents old coordinate epochs from silently satisfying current spatial requirements.
+
+2. **Fog of war needs more than the path the customer walked.** Surface coverage, unknown/occupied space and required close-up evidence need separate records. A missed ray in an incomplete mesh means unknown. It does not establish open space or a safe route. If ground or wall geometry changes, dependent coverage must be recomputed or invalidated.
+
+3. **Coverage can become stale in the current native implementation.** At the inspected source commit, changing only the ground height retained 14 covered cells; a fresh map with the same cameras and new height had zero covered cells. This is a reproducible software-state inconsistency, not a sensor-accuracy result. The published replay helper is a limited, unrun proposal; its refusal of an unresolved horizontal cell shift still needs an integration policy.
+
+4. **Reconstruction updates can revise earlier geometry.** Adding a fourth image to the DA3 batch changed earlier depth estimates: 3.06% mean absolute relative revision before alignment and 6.51% after it. These describe change, not improved accuracy. Measurements and results derived from revised geometry need revalidation.
+
+5. **Tracking needs a recovery path and independent context checks.** BootsTAPIR processed all 175 frames of one public indoor book sequence. Only **457/1,392** point-frame opportunities were both marked visible and inside the object mask, despite **457/458** containment among visible outputs. There were 77 frames with no visible query. Mask containment cannot establish exact point correspondence or equipment identity. This Mac run also does not establish real-time phone performance.
+
+6. **OCR confidence is insufficient for exact identifiers.** Synthetic native and portable OCR checks produced identifier mistakes at high confidence. Preserve original crops, text spans and field associations; keep unreadable or conflicting values unresolved. Two inspected real photographs supplied observations, not an independently adjudicated accuracy benchmark.
+
+7. **Use separate transport for original photographs.** Vercel documents a 4.5 MB Function request/response envelope. Send original media to a suitable storage endpoint and submit compact scene/placement data separately. Live checks covered only health and schema reads; no upload recovery or placement service was validated. [Vercel limit](https://vercel.com/docs/functions/limitations#request-body-size)
+
+## Implementation delivered
+
+| Artifact | What it contains | Validation boundary |
+| --- | --- | --- |
+| [Capture admission](../experiments/research-handoff/capture-admission/README.md) | SQLite prototype for request/returned-still separation, atomic evidence admission, epoch/revision checks, crash rollback and acknowledgments | Synthetic bytes and supplied assessments; no camera, real upload or production storage integration |
+| [Equipment association](../experiments/research-handoff/equipment-association/README.md) | State machine separating observations, nominated equipment, context revisions and reviewed label associations | Synthetic in-memory transitions; no physical identity or image-recognition validation |
+| [Native patch proposals](../experiments/research-handoff/native-proposals/README.md) | Small current-source reset patch plus a separate ground-coverage replay helper proposal | Reset patch passed nine paired harness cases; ground helper remains unrun. Neither was applied to the app |
+| [Camera metadata adapter, PR #9](https://github.com/SamGu-NRX/house-scanning/pull/9) | Camera coordinate conversion and input-validation experiment | Existing mathematical tests; not physical calibration or field accuracy |
+
+The public package contains original reusable code, synthetic tests, patch proposals and curated results. Downloaded datasets, model weights, build caches, private source material and detailed local run receipts remain outside Git. Historical failures are retained locally rather than silently replaced by later passes.
+
+Publication validation: the exported capture-admission suite passed **26 tests** and equipment-association suite passed **11 tests** on Python 3.13.7. Their READMEs contain the exact commands. Python syntax, JSON, relative document links and patch hashes were checked; the published implementations match the reviewed source. The app/server/web files were not changed or built in this handoff.
+
+## What remains unresolved
+
+**The largest gap is a real-phone session on representative exterior geometry with independently measured dimensions.** Desktop API checks and synthetic controls cannot answer whether still capture disrupts tracking, whether arrows remain aligned, or whether a phone can sustain the workload without thermal or battery problems.
+
+The next useful work, if resumed, is:
+
+1. **One small field capture:** ordinary supported iPhone first, optional LiDAR comparison. Keep per-image pose, calibration, original bytes and coordinate epochs. Record interruptions, bad captures and recovery—not just the happy path.
+2. **Independent geometry checks:** measure identified endpoints with a separate method. Reserve held-out distances when fitting scale or alignment. The acquired TUM reference sequence is ready for a fixed depth-consistency diagnostic, but that diagnostic and model evaluation were not run.
+3. **Focused guidance validation:** test move-versus-aim behavior, viewport/orientation changes, stale results and geometry revisions. Observe whether customers follow the cues and whether missing evidence remains visible.
+4. **Durable end-to-end integration:** review the isolated reset patch, implement qualified observation replay, test interrupted/background uploads, and bind each assessment to exact image, scene and rules versions.
+5. **Representative recognition and identity evaluation:** use adjudicated labels and per-point correspondence/visibility truth. Compare abstention and wrong associations as well as successful reads.
+
+Keep browser coaching, ARCore, alternate reconstruction models and simpler evidence-first outputs available when device reach, measured quality or deployment costs change the tradeoff. No permanent model winner or whole-house accuracy claim was established.

docs/research/2026-09-26-evidence-index.json

@@ -0,0 +1,97 @@
+{
+  "schemaVersion": 1,
+  "date": "2026-09-26",
+  "purpose": "Selected local evidence identities for the public research handoff. Paths are relative to the retained, ignored private/research archive; these files are not shipped in this commit. Hashes do not make unshipped evidence independently reproducible. Read the accompanying experiment-evidence report for the status and scope of each result; a preparation manifest does not imply execution.",
+  "records": [
+    {
+      "localArchiveRelativePath": "experiments/capture-admission/REPORT.md",
+      "bytes": 9448,
+      "sha256": "548df37bfd2d537f96cb170805c97822e0c715f678e9ade08cdf469fdc7dfbf2"
+    },
+    {
+      "localArchiveRelativePath": "experiments/capture-admission/review/fix-receipts.json",
+      "bytes": 11513,
+      "sha256": "702ccf8d1ab1ea22d3f847f69e1b3ce0d5986685d750405c461aec3883f5aee5"
+    },
+    {
+      "localArchiveRelativePath": "experiments/equipment-association/fix-v2/REPORT.md",
+      "bytes": 2151,
+      "sha256": "bb033b9af77b95854a3f81d227911242574c246e6694d835f0eb40486ad69588"
+    },
+    {
+      "localArchiveRelativePath": "native-producer-update-20260926-1217/reset-review/current-patch/REPORT.md",
+      "bytes": 5509,
+      "sha256": "03606b7c18994aa4a4dfb84e24078cffab8dbf2433d58bdc6e950d547047709d"
+    },
+    {
+      "localArchiveRelativePath": "native-producer-update-20260926-1217/reset-review/current-patch/final-manifest.json",
+      "bytes": 18424,
+      "sha256": "2a41a977e0a209d54963e263b59a8e77ff57663f41821d68d3610e05acceee56"
+    },
+    {
+      "localArchiveRelativePath": "native-producer-update-20260926-1217/geometry-review/ground-update-probe/REPORT.md",
+      "bytes": 4505,
+      "sha256": "678428ffb39c1cb24c9b0a77426335a4cf3424faa780cde7e78098756ff3ab29"
+    },
+    {
+      "localArchiveRelativePath": "native-producer-update-20260926-1217/geometry-review/ground-update-probe/artifact-manifest.json",
+      "bytes": 15089,
+      "sha256": "329968483d233783d6df0334f6c890b37b8fd0e7bc41b5a8bcf4b7cdae38f658"
+    },
+    {
+      "localArchiveRelativePath": "experiments/bootstapir-book/REPORT.md",
+      "bytes": 5189,
+      "sha256": "1224f49aa3c3a936366c5f3393a40107a5c712bc4ce626ff73b54999315d8dde"
+    },
+    {
+      "localArchiveRelativePath": "experiments/bootstapir-book/independent-review.md",
+      "bytes": 4276,
+      "sha256": "849b343413af50acab3fbdb98095b65daef77a5a443bce34731aabb26b24be85"
+    },
+    {
+      "localArchiveRelativePath": "experiments/bootstapir-book/final-manifest.json",
+      "bytes": 5108,
+      "sha256": "eecfbf6500a0191b5d9c9abc9c6181bac00f6b9a225ffec26c3f2d6912db7fb9"
+    },
+    {
+      "localArchiveRelativePath": "experiments/da3-prefix-update/REPORT.md",
+      "bytes": 8270,
+      "sha256": "0d9ebcd60a0a4fa85e09b9919fa9d2e7cce685227df0007a28049116dfde2550"
+    },
+    {
+      "localArchiveRelativePath": "experiments/apple-depth-runtime/README.md",
+      "bytes": 7200,
+      "sha256": "a5e0d85923ae53ec6327cec6ef1a72d625814d0fee075b9462f8f617bde2715b"
+    },
+    {
+      "localArchiveRelativePath": "experiments/tum-fr3-reference-prep/acquisition-prep/REPORT.md",
+      "bytes": 4680,
+      "sha256": "36d99f7567d7dd36ce52cc157616082ab66e2b79b4a0147a89ef9cac220c2d21"
+    },
+    {
+      "localArchiveRelativePath": "experiments/tum-fr3-reference-prep/acquisition-prep/artifact-manifest.json",
+      "bytes": 200386,
+      "sha256": "7ce8dc59d2d75cc9830b099779969c7997f917a171313645fe07a838772b66cf"
+    },
+    {
+      "localArchiveRelativePath": "experiments/tum-fr3-reference-consistency/prepared-manifest.json",
+      "bytes": 1120,
+      "sha256": "133358bd1281c13530e1335d4044c831856d550f9643458f96a899bed2c0d2f8"
+    },
+    {
+      "localArchiveRelativePath": "deployment-input-limits/REPORT.md",
+      "bytes": 4991,
+      "sha256": "1e72c6f955242fda08d6e0ea54ca35eb3cf1c7d4dce67fb03639989918973124"
+    },
+    {
+      "localArchiveRelativePath": "experiments/upload-direct-build/runtime-prep/RUNTIME-RESULT.md",
+      "bytes": 2636,
+      "sha256": "7f63c04670ab85431fcf15aad3fede592b160ee2e5753eb20a6d11fdf63dea29"
+    },
+    {
+      "localArchiveRelativePath": "point-reference-options.md",
+      "bytes": 7286,
+      "sha256": "5e3135236423f859f83829e683dcf637f627e2f60632bce1f1faf2fed101e30e"
+    }
+  ]
+}