open-wc/docs/CAMERA_POSE_SWEEP.md

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

.\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 `
  -WaitSeconds 2

Each candidate receives its own output directory and comparison report. 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.

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.