docs: add visualization conventions and update visualizer defaults

2026-02-08 07:38:23 +00:00
parent d07c244817
commit dc2d34dd7c
9 changed files with 392 additions and 7 deletions
@@ -0,0 +1,6 @@
+## Semantic Priority in detect_ground_face
+- Decision: Explicitly check for 'bottom' face in  and return it immediately if any of its markers are visible.
+- Rationale: For the , the 'bottom' face is guaranteed to be the ground. Geometric heuristics might pick other faces (like 'front' or 'back') if they happen to align better with the camera's 'up' vector due to camera tilt or marker placement.
+## Semantic Priority in detect_ground_face
+- Decision: Explicitly check for 'bottom' face in face_marker_map and return it immediately if any of its markers are visible.
+- Rationale: For the standard_box_markers_600mm.parquet, the 'bottom' face is guaranteed to be the ground. Geometric heuristics might pick other faces (like 'front' or 'back') if they happen to align better with the camera's 'up' vector due to camera tilt or marker placement.
@@ -0,0 +1,6 @@
+## Ground Face Heuristic Priority
+- Prioritizing semantic face names (specifically 'bottom') over purely geometric dot-product heuristics significantly improves robustness for marker parquets with named faces.
+- Geometric heuristics can be noisy due to marker frame orientation or slight misalignments.
+## Ground Face Heuristic Priority
+- Prioritizing semantic face names (specifically 'bottom') over purely geometric dot-product heuristics significantly improves robustness for marker parquets with named faces.
+- Geometric heuristics can be noisy due to marker frame orientation or slight misalignments.
@@ -0,0 +1,3 @@
+## Decisions
+- Use `--diagnose` in `visualize_extrinsics.py` to verify world-frame orientation.
+- Prefer explicit `--ground-face` over heuristic detection to avoid 90-degree flips.
@@ -0,0 +1,5 @@
+## Ground Plane Orientation Analysis
+- `calibrate_extrinsics.py` uses `--auto-align` to rotate the world frame.
+- Alignment maps a detected face normal to `[0, 1, 0]` (Y-up).
+- Heuristic detection (`detect_ground_face`) depends on camera being roughly upright.
+- `inside_network.json` uses a world frame where the ground is at Y=0 and cameras have specific offsets (e.g., -1.17m Y).
@@ -0,0 +1,17 @@
+
+## 2026-02-08: Visualization Conventions Documentation
+
+### Key findings from codebase analysis:
+- `visualize_extrinsics.py` went through 7+ iterations (commits `6113d0e` → `d07c244`)
+- The core confusion was conflating Plotly view transforms with data-frame transforms
+- `world_to_plot()` is now a no-op identity function — all data stays in OpenCV frame
+- Plotly `camera.up = {y:-1}` is the correct way to render Y-down data without transforming it
+- `autorange: "reversed"` was a red herring — it flips tick labels, not data
+- `inside_network.json` uses a different world frame (Fusion/gravity-aligned) than calibrate_extrinsics.py (ArUco marker object frame)
+- README.md has 3 stale references to removed flags: `--pose-convention`, `--world-basis`, `--diagnose`
+
+### Conventions confirmed:
+- Poses are `world_from_cam` (solvePnP result is inverted before saving)
+- RGB = XYZ color convention for axis triads
+- All units are meters
+- `--origin-axes-scale` controls origin triad independently from `--scale`