refactor: things

workspaces/py_workspace/.sisyphus/notepads/icp-registration/decisions.md

@@ -0,0 +1,9 @@
+## Notes
+- Used `scipy.spatial.transform.Rotation` with `xyz` Euler convention for gravity regularization to ensure consistent blending of pitch/roll.
+- `extract_near_floor_band` uses dot product with floor normal to handle arbitrary floor orientations (not just Y-up).
+- `refine_with_icp` uses a BFS-based connectivity check to ensure only cameras reachable from the reference camera are optimized.
+
+## Balanced SN442 Profile
+- Decided to document a "Balanced Profile" in the README to provide a standard recovery path for cameras that fail strict ground plane alignment.
+- Chose GICP over point-to-plane for the balanced profile due to its superior robustness with noisy ZED depth data in multi-camera setups.
+- Set `--seed 42` in the recommended command to ensure deterministic results for users debugging their calibration.

workspaces/py_workspace/.sisyphus/notepads/icp-registration/issues.md

@@ -0,0 +1,8 @@
+## Notes
+- `basedpyright` reports many warnings for `open3d` due to missing type stubs; these are suppressed/ignored as they don't indicate logic errors.
+- Synthetic smoke testing requires mocking `unproject_depth_to_points` or providing valid depth/K pairs that produce overlapping points.
+- Open3D PoseGraph requires careful indexing; ensuring reference camera is at index 0 and fixed helps stabilize global optimization.
+- Gravity constraint regularization is now correctly applied relative to the original extrinsic-derived transform, preserving the RANSAC-leveled orientation.
+
+- [BUG] `build_pose_graph` in `aruco/icp_registration.py` uses `result.transformation` (which is $T_{21}$) as the edge from `idx2` to `idx1` (which expects $T_{12}$). This causes global optimization to move cameras in the wrong direction and likely exceed safety bounds.
+- Pairwise ICP convergence depends on `min_overlap_area` and `min_fitness`; cameras failing these criteria are excluded from global optimization and logged as warnings.

workspaces/py_workspace/.sisyphus/notepads/icp-registration/learnings.md

@@ -0,0 +1,28 @@
+## Notes
+- Open3D `registration_generalized_icp` is more robust for noisy depth data but requires normal estimation.
+- Multi-scale ICP significantly improves convergence range by starting with large voxels (4x base).
+- Information matrix from `get_information_matrix_from_point_clouds` is essential for weighting edges in the pose graph.
+- Initial relative transform from extrinsics is crucial for ICP convergence when cameras are far apart in camera frame.
+- Pose graph optimization should only include the connected component reachable from the reference camera to avoid singular systems.
+- Transforming point clouds to camera frame before pairwise ICP allows using the initial extrinsic-derived relative transform as a meaningful starting guess.
+- Pose graph construction must strictly filter for the connected component reachable from the reference camera to ensure a well-constrained optimization problem.
+- Aligned build_pose_graph signature with plan (returns PoseGraph only).
+- Implemented disconnected camera logging within build_pose_graph.
+- Re-derived optimized_serials in refine_with_icp to maintain node-to-serial mapping consistency.
+
+- Open3D `PoseGraphEdge(source, target, T)` expects $T$ to be $T_{target\_source}$.
+- When monkeypatching for tests, ensure all internal calls are accounted for, especially when production code has bugs that need to be worked around or highlighted.
+- Integrated ICP refinement into `refine_ground_plane.py` CLI, enabling optional global registration after ground plane alignment.
+- Added `_meta.icp_refined` block to output JSON to track ICP configuration and success metrics.
+## ICP Registration
+- GICP method in  requires normals, which are estimated internally if not provided.
+- Synthetic tests for ICP should use deterministic seeds for point cloud generation to ensure stability.
+## ICP Registration
+- GICP method in `pairwise_icp` requires normals, which are estimated internally if not provided.
+- Synthetic tests for ICP should use deterministic seeds for point cloud generation to ensure stability.
+
+## Balanced SN442 Profile
+- A balanced profile was established to handle cameras (like SN44289123) that show significant floor disconnect (~5.5cm translation, ~1.5° rotation).
+- Permissive RANSAC threshold (0.05m) and min inlier ratio (0.01) allow recovery when strict defaults fail.
+- Safety limits were increased to `--max-rotation-deg 15` and `--max-translation-m 1.0` to accommodate observed disconnects.
+- GICP with 0.04m voxel size provides robust inter-camera alignment following ground plane correction.

workspaces/py_workspace/.sisyphus/notepads/icp-registration/problems.md

@@ -0,0 +1 @@
+## Notes