From a8d375191abadfa4b78cbe464b55b97609d266f4 Mon Sep 17 00:00:00 2001
From: crosstyan <crosstyan@outlook.com>
Date: Sat, 7 Feb 2026 15:25:24 +0000
Subject: [PATCH] fix: enforce Y-up in visualize_extrinsics and sync README

---
 py_workspace/README.md               | 63 +++++++++++++++++++++++++++-
 py_workspace/visualize_extrinsics.py |  7 ++++
 2 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/py_workspace/README.md b/py_workspace/README.md
index bb6b18d..f685b00 100755
--- a/py_workspace/README.md
+++ b/py_workspace/README.md
@@ -41,6 +41,65 @@ Arguments:
  - Camera live point cloud is retreived
  - An OpenGL windows displays it in 3D
 
-## Support
+### Camera Extrinsics
+
+```bash
+uv run calibrate_extrinsics.py \ 
+   -s output/ -m aruco/markers/standard_box_markers_600mm.parquet \ 
+   --aruco-dictionary DICT_APRILTAG_36h11 \ 
+   --verify-depth -refine-depth -no-preview \ 
+   -—max-samples 20 \ 
+   --report-csv output/e2e_refine_depth_smoke.csv \ 
+   --auto-align \ 
+   --output output/e2e_refine_depth_smoke.json
+```
+
+### Visualize Extrinsics
+
+Visualize camera poses and frustums from a JSON extrinsics file using Plotly.
+
+**Basic 3D Visualization (Interactive HTML):**
+```bash
+uv run visualize_extrinsics.py -i output/extrinsics.json --show
+```
+
+**Static Image Export (PNG):**
+Requires `kaleido` (installed by default).
+```bash
+uv run visualize_extrinsics.py -i output/extrinsics.json -o output/viz.png
+```
+
+**Bird-Eye View:**
+Use `--birdseye` for a top-down X-Z view (looking down Y axis).
+```bash
+uv run visualize_extrinsics.py -i output/extrinsics.json --birdseye --show
+```
+
+**Using ZED Configs for Accurate Frustums:**
+Load intrinsics from ZED calibration files to render accurate frustum shapes.
+- **Directory**: Matches `SN<serial>.conf` files to camera serials in the JSON.
+- **Single File**: Applies one config to ALL cameras (useful for homogeneous setups).
+- **Defaults**: Uses `--resolution FHD1200` and `--eye left` unless overridden.
+
+*Example: Load from config directory*
+```bash
+uv run visualize_extrinsics.py -i output/extrinsics.json \
+    --zed-configs /workspaces/zed-playground/zed_settings \
+    --resolution HD1080 --show
+```
+
+**Troubleshooting:**
+- **Cameras bunched up?** Check `--pose-convention`. `world_from_cam` is typical for optimization outputs.
+- **Config not matching?** Ensure JSON keys match the serial numbers in `SN<serial>.conf` filenames.
+
+For full options:
+```bash
+uv run visualize_extrinsics.py --help
+```
+
+**Diagnostics Mode:**
+Run numerical sanity checks on the poses (orthonormality, coplanarity, consistency).
+```bash
+uv run visualize_extrinsics.py -i output/extrinsics.json --diagnose
+```
 
-If you need assistance go to our Community site at https://community.stereolabs.com/
\ No newline at end of file
diff --git a/py_workspace/visualize_extrinsics.py b/py_workspace/visualize_extrinsics.py
index 8952485..3f8a768 100644
--- a/py_workspace/visualize_extrinsics.py
+++ b/py_workspace/visualize_extrinsics.py
@@ -495,6 +495,7 @@ def main(
         yaxis_title="Y (m)",
         zaxis_title="Z (m)",
         aspectmode="data",  # Important for correct proportions
+        camera=dict(up=dict(x=0, y=1, z=0)),  # Enforce Y-up convention
     )
 
     if birdseye:
@@ -505,6 +506,12 @@ def main(
             # Wait, we want X-Z plane. So we look down Y.
             # Plotly default is Z up.
             # If our data is Y-up (standard graphics), then we look from +Y down to X-Z.
+            # Actually, for X-Z plane top-down, we want to look from +Y.
+            # So eye should be (0, high, 0).
+            # And "up" vector for the camera should be aligned with Z (or -Z) to orient the map correctly.
+            # Let's try Z-up for the camera orientation so X is right and Z is up on screen?
+            # No, usually map is X right, Z up (or down).
+            # If we look from +Y, and up is +Z, then Z is "up" on screen.
             eye=dict(x=0, y=2.5, z=0),
         )