Skip to content

Add world_up config flag so Y-up scenes render right-side up - #5

Open
alexmgee wants to merge 1 commit into
nigelhartman:mainfrom
alexmgee:feat/world-up-flag
Open

Add world_up config flag so Y-up scenes render right-side up#5
alexmgee wants to merge 1 commit into
nigelhartman:mainfrom
alexmgee:feat/world-up-flag

Conversation

@alexmgee

Copy link
Copy Markdown

Closes #4

What

Adds an opt-in world_up setting so splats stored with a Y-up world axis render upright instead of upside down. Default ("y-down", the standard 3DGS/COLMAP convention) leaves current behavior byte-for-byte unchanged.

  • config.py - PipelineConfig.world_up: str = "y-down" plus a WORLD_UP_CHOICES constant (single source of truth for CLI + API validation, same as QUALITY_PRESETS)
  • render_cameras.py - _build_poses() picks the camera up-vector from world_up ([0,1,0] for y-down, [0,-1,0] for y-up) and passes it to _lookat; the standalone CLI gains --world_up
  • run_local.py / pipeline.py - --world_up {y-down,y-up} argparse flags, threaded through PipelineConfig.from_overrides exactly like score_threshold
  • server.py - world_up form param on /api/v1/detect with a 400 on invalid values (mirrors the quality check), passed through the pipeline.py subprocess call, included in the job log lines
  • README.md - parameter table row + the orientation warning now offers the flag as the remedy instead of re-exporting the file

Why

In the OpenCV-convention c2w built by _lookat, image-down for a level view equals the up argument, so it must point at the scene's floor. The hardcoded [0,1,0] is correct for Y-down scenes but renders every view upside down for Y-up scenes, and detections silently collapse to orientation-tolerant classes. On a real 5.08M-splat Y-up indoor scene (medium quality, 12-label prompt, identical gates), fixing orientation took raw OWLv2 detections from 663 to 1,255 and default-gate clusters from 3 (1 label) to 12 (6 labels) - full numbers and mechanism in #4.

Design notes

  • Camera-side flip only. Re-orienting the splat data itself would require rotating quaternions and SH coefficients; flipping the up-vector is equivalent for rendering and risk-free.
  • Elevation sweep mirrors (−55°…+40° becomes +55°…−40° relative to the scene) when the up-vector flips. Intended: coverage stays symmetric-ish either way for an opt-in flag.
  • Camera placement is untouched - the density-aware sampler is orientation-agnostic.
  • Web upload form deliberately not extended (API/CLI only), matching min_peak_score which is also API-only today. Happy to add a form control if you'd like it exposed there.
  • Naming: went with world_up to describe the scene's up-axis convention; happy to rename (up_axis?) if you prefer.

Testing

  • Unit: for level views the c2w image-down column is [0,1,0] under y-down and [0,-1,0] under y-up; default poses are identical to pre-change output; rotations stay orthonormal.
  • Determinism: camera positions + all 90 medium-quality pose matrices recomputed on the 5.08M-splat test scene match the pre-refactor prototype run exactly (max abs diff 0.0).
  • Server: FastAPI TestClient: invalid world_up → 400 naming the valid choices; y-up reaches the pipeline subprocess argv; omitted → default y-down.
  • End-to-end: full medium runs on the real Y-up scene produced the before/after numbers above.

The camera up-vector in _lookat was hardcoded to [0,1,0], which is
correct for standard Y-down 3DGS/COLMAP scenes but renders every view
upside down for Y-up scenes (some exporters and converted .spz files),
silently collapsing detections to orientation-tolerant classes.

Adds PipelineConfig.world_up ("y-down" default, behavior unchanged;
"y-up" flips the camera up-vector to [0,-1,0]), threaded through the
run_local.py / pipeline.py / render_cameras.py CLIs and the
/api/v1/detect form param with the same validation pattern as quality.
README documents the new parameter and offers it as the remedy in the
orientation warning.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Y-up splats render upside down - detections silently collapse (camera up-vector is hardcoded)

1 participant