51 lines
4.3 KiB
Markdown
51 lines
4.3 KiB
Markdown
# Renderer Camera Pose Sweep
|
|
|
|
This offline M00 diagnostic recovers reproducible checkpoint framing when an original-client screenshot has no recorded camera yaw or pitch. It ranks a bounded grid; it does not change renderer or player-camera defaults and does not prove the exact build 12340 camera pose without human approval.
|
|
|
|
## Camera contract
|
|
|
|
`capture_render_checkpoints.gd` accepts additive `--camera-yaw-offset` and `--camera-pitch-offset` values in degrees. Yaw rotates the no-roll checkpoint basis around Godot world `Vector3.UP`; pitch then rotates around the camera-local right axis. Zero offsets preserve the manifest target exactly. `--single-pass` captures only `cold_process` and is intended for pose calibration, not performance baselines.
|
|
|
|
## Workflow
|
|
|
|
```powershell
|
|
.\tools\sweep_render_checkpoint_camera_pose.ps1 `
|
|
-ReferenceDirectory 'D:\private-fixtures\wow-3.3.5a-checkpoints' `
|
|
-Checkpoint elwynn_adt_boundary `
|
|
-YawOffsets -15,-10,-5,0,5,10,15 `
|
|
-PitchOffsets -10,-5,0,5,10 `
|
|
-ViewportWidth 1280 -ViewportHeight 960 `
|
|
-WaitSeconds 8
|
|
```
|
|
|
|
Each candidate receives its own output directory and comparison report. The viewport must exactly match the reference image dimensions; the runner fails on `size_mismatch` instead of inventing a score. The default 8-second wait matches the M00 manifest and is a readiness precondition: lowering it requires evidence that the checkpoint's WMO/M2 content has already appeared. `ranking.json` sorts candidates by mean perceptual error and then changed-pixel ratio. Use `-PlanOnly` to validate the Cartesian grid and output paths without rendering. Run a coarse grid first, then a finer grid around the best candidate.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Y[Yaw offsets in degrees] --> G[Bounded Cartesian grid]
|
|
P[Pitch offsets in degrees] --> G
|
|
G --> C[Single-pass checkpoint captures]
|
|
R[Original-client reference] --> D[Perceptual comparator]
|
|
C --> D
|
|
D --> J[ranking.json]
|
|
J --> H[Human framing approval]
|
|
```
|
|
|
|
## Interpretation and recovery
|
|
|
|
The smallest error is a candidate, not automatic fidelity approval. Geometry, materials, lighting and FOV can move the perceptual optimum away from the true original-client pose. Inspect the best images manually and retain the original reference outside Git. A missing matching reference or candidate is a hard error; correct the checkpoint filter or filenames and rerun. Generated PNG and JSON outputs are disposable local evidence.
|
|
|
|
## Verification
|
|
|
|
The headless capture dry-run must report requested yaw and pitch offsets. Comparator `--self-test` covers paired metrics. Sweep `-PlanOnly` covers deterministic grid expansion and output naming without requiring a display. A real ranked sweep requires a display and a private build 12340 reference image.
|
|
|
|
## Goldshire Inn evidence — 2026-07-12
|
|
|
|
The private `2560x1440` build 12340 `goldshire_inn_large_wmo` reference was evaluated at FOV 62 degrees. A coarse 5x5 grid over yaw/pitch `[-20, -10, 0, 10, 20]` reduced mean error from `0.099632` at `(0, 0)` to `0.077575` at `(-10, -20)`. Extending pitch produced `0.070901` at `(0, -40)` and `0.063574` at `(0, -60)` with changed-pixel ratio `0.549556`.
|
|
|
|
These values are invalid camera-pose evidence because the sweep used a 2-second wait. A subsequent readiness audit showed 9 WMO instances and no inn after 2 seconds, 113 instances with the inn visible after 8 seconds, and 328 instances after 15 seconds. The apparent monotonic improvement rewarded grass while the landmark was still absent; it does not demonstrate a spatial/placement defect. The manifest pose remains unchanged pending a ready-scene rerun.
|
|
|
|
The ready-scene 3x3 rerun at FOV 62 degrees ranked `(yaw=10, pitch=-10)` first with mean error `0.087952` and changed-pixel ratio `0.665527`, compared with `0.101402`/`0.702489` at zero offsets. Human inspection confirms that the inn is present and the direction is plausible. Pitch remains on the tested boundary and the building scale differs from the reference, so these offsets are coarse evidence only; a joint pitch/FOV refinement is required before changing manifest camera values.
|
|
|
|
During this run the sweep orchestration was hardened in two ways: expected comparator exit code `1` is now collected through an explicit child process, and viewport dimensions are explicit. A reference/candidate `size_mismatch` now fails before ranking instead of producing an empty metric.
|