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

py_workspace/docs/marker-parquet-format.md

@@ -0,0 +1,49 @@
+# Marker Parquet Format
+
+This document describes the expected structure for marker configuration files (e.g., `standard_box_markers_600mm.parquet`). These files define both the physical geometry of markers and their logical grouping into faces.
+
+## Schema
+
+The parquet file must contain the following columns:
+
+| Column | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | Name of the face (e.g., "bottom", "front"). Used for logical grouping. |
+| `ids` | `list<int64>` | List of ArUco marker IDs belonging to this face. |
+| `corners` | `list<list<list<float64>>>` | 3D coordinates of marker corners. Shape must be `(N, 4, 3)` where N is the number of markers. |
+
+## Example Data
+
+Based on `standard_box_markers_600mm.parquet`:
+
+| name | ids | corners (approximate structure) |
+| :--- | :--- | :--- |
+| "bottom" | `[21]` | `[[[-0.225, -0.3, 0.226], [0.225, -0.3, 0.226], [0.225, -0.3, -0.224], [-0.225, -0.3, -0.224]]]` |
+
+## Loader Behavior
+
+The system uses two different loading strategies based on this file:
+
+### 1. Geometry Loader (`load_marker_geometry`)
+- **Ignores**: `name` column.
+- **Uses**: `ids` and `corners`.
+- **Process**:
+  - Flattens all `ids` and `corners` from all rows.
+  - Reshapes `corners` to `(-1, 4, 3)`.
+  - Validates that each marker has exactly 4 corners with 3 coordinates (x, y, z).
+  - Validates coordinates are finite and within reasonable range (< 100m).
+- **Output**: `dict[int, np.ndarray]` mapping Marker ID → (4, 3) corner array.
+
+### 2. Face Mapping Loader (`load_face_mapping`)
+- **Uses**: `name` and `ids`.
+- **Process**:
+  - Reads face names and associated marker IDs.
+  - Normalizes names to lowercase.
+- **Output**: `dict[str, list[int]]` mapping Face Name → List of Marker IDs.
+- **Usage**: Used for ground plane alignment (e.g., identifying the "bottom" face).
+
+## Validation Rules
+Runtime validation in `marker_geometry.py` ensures:
+- `corners` shape is strictly `(4, 3)` per marker.
+- No `NaN` or `Inf` values.
+- Coordinates are absolute (meters) and must be < 100m.