feat(calibration): add data-driven ground alignment with debug and fast iteration flags

py_workspace/.sisyphus/notepads/ground-plane-alignment/issues.md

@@ -0,0 +1,32 @@
+- Fixed edge cases in `compute_face_normal` to use stable edge definition for quad faces (corners[1]-corners[0] x corners[3]-corners[0]).
+- Fixed edge cases in compute_face_normal to use stable edge definition for quad faces (corners[1]-corners[0] x corners[3]-corners[0]).
+- Added explicit shape validation and zero-norm guards in rotation_align_vectors.
+- Ensured concrete np.ndarray return types with explicit astype(np.float64) to satisfy type checking.
+
+## Type Checking Warnings
+- `basedpyright` reports numerous warnings, mostly related to `Any` types from `cv2` and `pyzed.sl` bindings which lack full type stubs.
+- Deprecation warnings for `List`, `Dict`, `Tuple` (Python 3.9+) are present but existing style uses them. Kept consistent with existing code.
+- `reportUnknownVariableType` is common due to dynamic nature of OpenCV/ZED returns.
+
+## Parquet Metadata Handling
+- `awkward` library used for parquet reading returns jagged arrays for list columns like `ids`.
+- `ak.to_list()` is necessary to convert these to standard Python lists for dictionary values.
+
+## Backward Compatibility
+- While `FACE_MARKER_MAP` constant remains in `aruco/alignment.py` for potential external consumers, it is no longer used by the CLI tool.
+- Users with old parquet files will now see a warning and no alignment, rather than silent fallback to potentially incorrect hardcoded IDs.
+
+
+
+- None encountered during test implementation. API signatures were consistent with the implementation in `aruco/alignment.py`.
+
+
+## Runtime Errors
+
+## Messaging Consistency
+
+## Iteration Speed
+- Processing full SVO files (thousands of frames) is too slow for verifying simple logic changes. The `--max-samples` option addresses this by allowing early exit after a few successful samples.
+
+
+