49 lines
3.8 KiB
Markdown
49 lines
3.8 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 2
|
|
```
|
|
|
|
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. `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`.
|
|
|
|
This is not a camera-pose solution. Human inspection shows the original-client reference centered on the Goldshire Inn, while the zero-offset OpenWC candidate contains forest/roads and no inn; negative pitch increasingly fills the frame with grass. The monotonically improving full-frame metric rewards similar green color coverage rather than landmark alignment. Therefore the manifest pose is unchanged and this checkpoint remains spatial/placement-composition evidence. A future registration metric must use approved landmark or region masks before it can select camera pose automatically.
|
|
|
|
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.
|