docs(calibration): document auto-align and refine-depth workflows
This commit is contained in:
@@ -26,7 +26,16 @@
|
||||
## 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.
|
||||
|
||||
## Test Collection Noise
|
||||
|
||||
## Debugging Heuristics
|
||||
|
||||
## Documentation Gaps
|
||||
- Users were unclear on how `--auto-align` made decisions (heuristic vs explicit) and what `--refine-depth` actually did. The new documentation addresses this by explaining the decision flow and the optimization objective function.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -57,7 +57,17 @@
|
||||
|
||||
## Fast Iteration
|
||||
- Added `--max-samples` CLI option to `calibrate_extrinsics.py` to allow processing a limited number of samples (e.g., 1 or 3) instead of the full SVO.
|
||||
- This significantly speeds up the development loop when testing changes to pose estimation or alignment logic that don't require the full dataset.
|
||||
|
||||
## Test Configuration
|
||||
- Configured `pytest` in `pyproject.toml` to explicitly target the `tests/` directory and ignore `loguru`, `tmp`, and `libs`.
|
||||
|
||||
## Debug Visibility
|
||||
|
||||
## Documentation
|
||||
- Created `docs/calibrate-extrinsics-workflow.md` to document the runtime behavior of the calibration tool, specifically detailing the precedence logic for ground plane alignment and the mathematical basis for depth verification/refinement.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -51,7 +51,7 @@ Enable `calibrate_extrinsics.py` to detect the ground-facing box face and apply
|
||||
- [x] `uv run calibrate_extrinsics.py --auto-align ...` produces extrinsics with Y-up
|
||||
- [x] `--ground-face` and `--ground-marker-id` work as explicit overrides
|
||||
- [x] Debug logs show which face was detected as ground and alignment applied
|
||||
- [ ] Tests pass, basedpyright shows 0 errors
|
||||
- [x] Tests pass, basedpyright shows 0 errors
|
||||
|
||||
### Must Have
|
||||
- Heuristic ground detection using camera up-vector
|
||||
@@ -155,11 +155,11 @@ Task 5: Add tests and verify
|
||||
- Rodrigues formula: `R = I + sin(θ)K + (1-cos(θ))K²` where K is skew-symmetric of axis
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] File `aruco/alignment.py` exists
|
||||
- [ ] `compute_face_normal` returns unit vector for valid (4,3) corners
|
||||
- [ ] `rotation_align_vectors([0,0,1], [0,1,0])` produces 90° rotation about X
|
||||
- [ ] `uv run python -c "from aruco.alignment import compute_face_normal, rotation_align_vectors, apply_alignment_to_pose"` → no errors
|
||||
- [ ] `.venv/bin/basedpyright aruco/alignment.py` → 0 errors
|
||||
- [x] File `aruco/alignment.py` exists
|
||||
- [x] `compute_face_normal` returns unit vector for valid (4,3) corners
|
||||
- [x] `rotation_align_vectors([0,0,1], [0,1,0])` produces 90° rotation about X
|
||||
- [x] `uv run python -c "from aruco.alignment import compute_face_normal, rotation_align_vectors, apply_alignment_to_pose"` → no errors
|
||||
- [x] `.venv/bin/basedpyright aruco/alignment.py` → 0 errors
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(aruco): add alignment utilities for ground plane detection`
|
||||
@@ -210,9 +210,9 @@ Task 5: Add tests and verify
|
||||
- Face c: IDs [24-27], normal ≈ [1,0,0]
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] `FACE_MARKER_MAP` contains mappings for both parquet files
|
||||
- [ ] `get_face_normal_from_geometry("b", geometry)` returns ≈ [0,1,0]
|
||||
- [ ] Returns `None` for unknown face names
|
||||
- [x] `FACE_MARKER_MAP` contains mappings for both parquet files
|
||||
- [x] `get_face_normal_from_geometry("b", geometry)` returns ≈ [0,1,0]
|
||||
- [x] Returns `None` for unknown face names
|
||||
|
||||
**Commit**: YES (group with Task 1)
|
||||
|
||||
@@ -254,9 +254,9 @@ Task 5: Add tests and verify
|
||||
- Dot product alignment: `np.dot(normal, up_vec)` → highest = most aligned
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Function returns face with normal most aligned to camera up
|
||||
- [ ] Returns None when no mapped markers are visible
|
||||
- [ ] Debug log shows which faces were considered and scores
|
||||
- [x] Function returns face with normal most aligned to camera up
|
||||
- [x] Returns None when no mapped markers are visible
|
||||
- [x] Debug log shows which faces were considered and scores
|
||||
|
||||
**Commit**: YES (group with Task 1, 2)
|
||||
|
||||
@@ -301,13 +301,13 @@ Task 5: Add tests and verify
|
||||
- `aruco/alignment.py` - New utilities from Tasks 1-3
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] `--auto-align` flag exists and defaults to False
|
||||
- [ ] `--ground-face` accepts string face names
|
||||
- [ ] `--ground-marker-id` accepts integer marker ID
|
||||
- [ ] When `--auto-align` used, output poses are rotated
|
||||
- [ ] Debug logs show: "Detected ground face: X, normal: [a,b,c], applying alignment"
|
||||
- [ ] `uv run python -m py_compile calibrate_extrinsics.py` → success
|
||||
- [ ] `.venv/bin/basedpyright calibrate_extrinsics.py` → 0 errors
|
||||
- [x] `--auto-align` flag exists and defaults to False
|
||||
- [x] `--ground-face` accepts string face names
|
||||
- [x] `--ground-marker-id` accepts integer marker ID
|
||||
- [x] When `--auto-align` used, output poses are rotated
|
||||
- [x] Debug logs show: "Detected ground face: X, normal: [a,b,c], applying alignment"
|
||||
- [x] `uv run python -m py_compile calibrate_extrinsics.py` → success
|
||||
- [x] `.venv/bin/basedpyright calibrate_extrinsics.py` → 0 errors
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(calibrate): add --auto-align for ground plane detection and Y-up alignment`
|
||||
@@ -315,7 +315,7 @@ Task 5: Add tests and verify
|
||||
|
||||
---
|
||||
|
||||
- [ ] 5. Add tests and verify end-to-end
|
||||
- [x] 5. Add tests and verify end-to-end
|
||||
|
||||
**What to do**:
|
||||
- Create `tests/test_alignment.py`:
|
||||
@@ -341,9 +341,9 @@ Task 5: Add tests and verify
|
||||
- `/workspaces/zed-playground/zed_settings/inside_network.json` - Reference for Y-up verification
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] `uv run pytest tests/test_alignment.py` → all pass
|
||||
- [ ] `uv run pytest` → all tests pass (including existing)
|
||||
- [ ] Manual verification: aligned poses have Y-axis column ≈ [0,1,0] in rotation
|
||||
- [x] `uv run pytest tests/test_alignment.py` → all pass
|
||||
- [x] `uv run pytest` → all tests pass (including existing)
|
||||
- [x] Manual verification: aligned poses have Y-axis column ≈ [0,1,0] in rotation
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `test(aruco): add alignment module tests`
|
||||
@@ -389,5 +389,5 @@ uv run python -c "import json, numpy as np; d=json.load(open('aligned_extrinsics
|
||||
- [x] Heuristic detection works without explicit face specification
|
||||
- [x] Output extrinsics have Y-up when aligned
|
||||
- [x] No behavior change when `--auto-align` not specified
|
||||
- [ ] All tests pass
|
||||
- [ ] Type checks pass
|
||||
- [x] All tests pass
|
||||
- [x] Type checks pass
|
||||
|
||||
Reference in New Issue
Block a user