# Qurmmius owned reconstruction process

Qurmmius now has a local, KIRI/Meshy-independent reconstruction path for
EraWeaver and Qurmmius Palimpsest. Source photos stay on the owner's machine;
the browser receives only the reviewed PLY/GLB handoff and its provenance
manifest.

## What the process does today

1. **Ingest and validate** 3–150 JPG, PNG, or WebP source images. A folder
   `manifest.json` can mark files as `primary-reconstruction`; supplemental
   context images are excluded from geometry fitting.
2. **Fingerprint inputs** with SHA-256 and record dimensions, feature counts,
   and the selected reference view in the reconstruction manifest.
3. **Recover relative geometry** with SIFT (ORB is the fallback), mutual ratio
   matching across every distinct view pair, an essential-matrix solve,
   relative pose recovery, and triangulation for overlapping views.
4. **Keep the scene inspectable when archival overlap is weak** by adding a
   bounded image-derived depth proxy. This is explicitly labelled
   `hybrid-evidence-depth-proxy` or `evidence-billboard-fallback` rather than
   being presented as surveyed geometry.
5. **Build a textured-depth handoff** with the Qurmmius-owned CPU-safe dense
   stage. It creates a bounded textured GLB from the highest-resolution
   checked primary view, applies restrained luminance displacement, and keeps
   source hashes and the non-metric/review-required flags in the same manifest.
6. **Emit portable handoffs** at `splats/wce-administration.ply` and
   `eraweaver/scene/1893-wce/generated/wce-administration-qurmmius.glb`, copy
   the report into the scene folder, and expose vertex count, matches, inliers,
   confidence, coordinate uncertainty, and review gates to EraWeaver and
   Palimpsest.
7. **Calibrate a connected view subset (optional local stage)** with pycolmap.
   The stage deduplicates the JPG/PNG exports, scores SIFT homography overlap,
   runs an incremental COLMAP solve, and writes
   `splats/wce-administration-calibrated.ply` plus
   `splats/wce-administration-calibrated.json`. It also writes a textured GLB
   from that same overlap-connected subset at
   `eraweaver/scene/1893-wce/generated/wce-administration-calibrated-textured.glb`.
   The result recovers relative camera poses only; it has no absolute scale and
   stays review-required.
8. **Present safely in EraWeaver**: the clean panoramic world remains the
   default view, while **Inspect Qurmmius depth mesh** explicitly switches to
   the inferred GLB for technical review. This prevents a flat archival plate
   from being mistaken for the walkable world.
9. **Run optional true dense MVS locally** when CUDA COLMAP is installed. The
   overlap-connected views are processed with GPU PatchMatch stereo, geometric
   fusion, and Poisson meshing, then converted to a browser-ready GLB. The
   result is available at `?geometry=dense-mvs` and is labelled relative-scale,
   vertex-colorized, and review-required.

## Run it locally

From the project root:

```powershell
python -m pip install -r eraweaver/local/requirements-reconstruction.txt
.\scripts\reconstruct-wce.ps1
```

To run both stages (sparse PLY plus the local textured-depth GLB) in one
repeatable command:

```powershell
.\scripts\build-qurmmius-scene.ps1
```

With CUDA COLMAP, add the dense MVS handoff in the same repeatable command:

```powershell
.\scripts\build-qurmmius-scene.ps1 -Colmap "C:\tools\COLMAP.bat"
```

The script also checks `QURMMIUS_COLMAP`, then the local
`tmp\colmap-4.2.0-cuda\COLMAP.bat` launcher. If CUDA COLMAP is not present,
this stage is skipped without invalidating the sparse, textured, or calibrated
outputs.

For a browser-triggered run, start the loopback service in a second terminal:

```powershell
.\scripts\start-reconstruction-service.ps1
```

The scene's **Run Qurmmius locally** control posts only the explicitly chosen
photos to `http://127.0.0.1:8790/reconstruct`. The service deletes its temporary
upload directory after the job and only allows approved local/production
origins.

## Current WCE validation

- Inputs: 24 primary archival derivatives from `wce-source/manifest.json`
  (public-domain/CC0 research candidates; item-level rights review pending)
- Output: 2,099 vertices in an ASCII PLY
- Mode: `sparse-feature-triangulation` with all-pair SIFT
- Successful view pairs: 41
- Candidate matches: 8,920
- Triangulated inliers: 2,099
- Confidence: 49.7% (review required)
- Calibrated solve: the current batch did not recover a connected camera
  solution; a prior calibrated reference artifact remains separate and
  review-required
- CUDA dense MVS: the current batch did not produce a valid fused/meshed
  handoff; the existing dense artifact is retained as prior comparison only

This is a working, private reconstruction scaffold. The textured GLB is an
interpretive depth proxy (not calibrated photogrammetry or a photorealistic
survey). The CUDA dense MVS stage now replaces the single-view depth proxy when
available, behind the same manifest and handoff contract without changing the
EraWeaver viewer.

## Next quality stage

The current Qurmmius-owned textured-depth stage produces a browser-ready GLB
without uploading the photographs. It now runs a conservative multi-view
alignment pass: a straight-on official facade is locked as the sharp texture
anchor, overlapping views are scored with SIFT/ORB homographies, and weak
matches are recorded in the manifest without being blended into the image.
This prevents the ghosting that archival viewpoints can otherwise introduce.
The next quality upgrade is adding more overlap-connected archival angles,
recovering a connected calibrated camera solve, and rerunning the local CUDA
dense MVS stage on the same cleared set. Source hashes, uncertainty,
provenance, and the viewer's review gate remain intact.