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

• 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

Test Collection Noise

Debugging Heuristics

Documentation Gaps

Jaxtyping Runtime Dependencies

• jaxtyping imports failed at runtime because it expects a backend (jax, torch, or tensorflow) to be installed.

Depth Refinement Failure

• Depth refinement was failing (0 iterations, no improvement) because the depth map was in millimeters (~2500) while the computed depth from extrinsics was in meters (~2.5). This resulted in huge residuals (~2497.5) that the optimizer couldn't handle effectively. Fixed by normalizing the depth map to meters immediately upon retrieval.