chore(metadata): update beads and sisyphus planning artifacts

py_workspace/aruco/alignment.py

@@ -1,8 +1,22 @@
 import numpy as np
 from loguru import logger
+from jaxtyping import Float
+from typing import TYPE_CHECKING
+
+# Type aliases for shape-aware annotations
+if TYPE_CHECKING:
+    Vec3 = Float[np.ndarray, "3"]
+    Mat33 = Float[np.ndarray, "3 3"]
+    Mat44 = Float[np.ndarray, "4 4"]
+    CornersNC = Float[np.ndarray, "N 3"]
+else:
+    Vec3 = np.ndarray
+    Mat33 = np.ndarray
+    Mat44 = np.ndarray
+    CornersNC = np.ndarray
 
 
-def compute_face_normal(corners: np.ndarray) -> np.ndarray:
+def compute_face_normal(corners: CornersNC) -> Vec3:
     """
     Compute the normal vector of a face defined by its corners.
     Assumes corners are in order (e.g., clockwise or counter-clockwise).
@@ -37,7 +51,7 @@ def compute_face_normal(corners: np.ndarray) -> np.ndarray:
     return (normal / norm).astype(np.float64)
 
 
-def rotation_align_vectors(from_vec: np.ndarray, to_vec: np.ndarray) -> np.ndarray:
+def rotation_align_vectors(from_vec: Vec3, to_vec: Vec3) -> Mat33:
     """
     Compute the 3x3 rotation matrix that aligns from_vec to to_vec.
 
@@ -100,7 +114,7 @@ def rotation_align_vectors(from_vec: np.ndarray, to_vec: np.ndarray) -> np.ndarr
     return R.astype(np.float64)
 
 
-def apply_alignment_to_pose(T: np.ndarray, R_align: np.ndarray) -> np.ndarray:
+def apply_alignment_to_pose(T: Mat44, R_align: Mat33) -> Mat44:
     """
     Apply an alignment rotation to a 4x4 pose matrix.
     The alignment is applied in the global frame (pre-multiplication of rotation).
@@ -127,7 +141,7 @@ def get_face_normal_from_geometry(
     face_name: str,
     marker_geometry: dict[int, np.ndarray],
     face_marker_map: dict[str, list[int]] | None = None,
-) -> np.ndarray | None:
+) -> Vec3 | None:
     """
     Compute the average normal vector for a face based on available marker geometry.
 
@@ -171,9 +185,9 @@ def get_face_normal_from_geometry(
 def detect_ground_face(
     visible_marker_ids: set[int],
     marker_geometry: dict[int, np.ndarray],
-    camera_up_vector: np.ndarray = np.array([0, -1, 0]),
+    camera_up_vector: Vec3 = np.array([0, -1, 0]),
     face_marker_map: dict[str, list[int]] | None = None,
-) -> tuple[str, np.ndarray] | None:
+) -> tuple[str, Vec3] | None:
     """
     Detect which face of the object is most likely the ground face.
     The ground face is the one whose normal is most aligned with the camera's up vector.