docs: update README and finalize ground plane refinement integration

2026-02-09 08:30:50 +00:00
parent 9d9e95de81
commit ae3c9eba76
4 changed files with 221 additions and 0 deletions
@@ -131,3 +131,35 @@ Run numerical sanity checks on the poses (orthonormality, coplanarity, consisten
 uv run visualize_extrinsics.py -i output/extrinsics.json --diagnose
 ```

+### Ground Plane Refinement
+
+Refine camera extrinsics by aligning the ground plane detected in depth maps. This is useful when ArUco markers are not perfectly coplanar with the floor or when you want to ensure all cameras agree on the floor height.
+
+**1. Calibrate with Depth Saving:**
+Run calibration and save the depth data used for refinement/verification.
+```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 \
+   --save-depth output/depth_data.h5 \
+   --output output/extrinsics.json
+```
+
+**2. Refine Ground Plane:**
+Use the saved depth data to detect the floor and compute a global correction.
+```bash
+uv run refine_ground_plane.py \
+    --input-extrinsics output/extrinsics.json \
+    --input-depth output/depth_data.h5 \
+    --output-extrinsics output/extrinsics_refined.json \
+    --plot --plot-output output/ground_diagnostic.html
+```
+
+**Options:**
+- `--plot`: Generates an interactive 3D visualization of the detected floor points, consensus plane, and camera pose corrections.
+- `--max-rotation-deg`: Safety limit for the correction rotation (default: 5.0).
+- `--max-translation-m`: Safety limit for the correction translation (default: 0.5).
+- `--stride`: Pixel stride for depth sampling (default: 4). Increase for faster processing.
+