feat: add explicit 4x4 transformation matrix validation to compare_pose_sets.py

2026-02-09 03:24:36 +00:00
parent d6c7829b1e
commit c497af7783
3 changed files with 165 additions and 39 deletions
@@ -352,6 +352,69 @@ though the absolute world coordinates differ.

 ---

+## `compare_pose_sets.py` Input Formats
+
+The `compare_pose_sets.py` tool is designed to be agnostic to the source of the JSON files.
+It uses a **symmetric, heuristic parser** for both `--pose-a-json` and `--pose-b-json`.
+
+### Accepted JSON Schemas
+
+The parser automatically detects and handles either of these two structures for any input file:
+
+**1. Flat Format (Standard Output)**
+Used by `calibrate_extrinsics.py` and `refine_extrinsics.py`.
+```json
+{
+  "SERIAL_NUMBER": {
+    "pose": "r00 r01 r02 tx r10 r11 r12 ty r20 r21 r22 tz 0 0 0 1"
+  }
+}
+```
+
+**2. Nested Fusion Format**
+Used by ZED Fusion `inside_network.json` configuration files.
+```json
+{
+  "SERIAL_NUMBER": {
+    "FusionConfiguration": {
+      "pose": "r00 r01 r02 tx r10 r11 r12 ty r20 r21 r22 tz 0 0 0 1"
+    }
+  }
+}
+```
+
+### Key Behaviors
+
+1.  **Interchangeability**: You can swap inputs. Comparing A (ArUco) vs B (Fusion) is valid,
+    as is A (Fusion) vs B (ArUco). The script aligns B to A.
+2.  **Pose Semantics**: All poses are interpreted as `T_world_from_cam` (camera-to-world).
+    The script does **not** invert matrices; it assumes the input strings are already in the
+    correct convention.
+3.  **Minimum Overlap**: The script requires at least **3 shared camera serials** between
+    the two files to compute a rigid alignment.
+4.  **Heuristic Parsing**: For each serial key, the parser looks for `FusionConfiguration.pose`
+    first, then falls back to `pose`.
+
+### Example: Swapped Inputs
+
+Since the parser is symmetric, you can verify consistency by reversing the alignment direction:
+
+```bash
+# Align Fusion (B) to ArUco (A)
+uv run compare_pose_sets.py \
+    --pose-a-json output/e2e_refine_depth.json \
+    --pose-b-json ../zed_settings/inside_network.json \
+    --report-json output/report_aruco_ref.json
+
+# Align ArUco (B) to Fusion (A)
+uv run compare_pose_sets.py \
+    --pose-a-json ../zed_settings/inside_network.json \
+    --pose-b-json output/e2e_refine_depth.json \
+    --report-json output/report_fusion_ref.json
+```
+
+---
+
 ## Appendix: Stale README References

 The following lines in `py_workspace/README.md` reference removed flags and should be