Summary

Doc-only fix for src/alpamayo_r1/visualization/viz.py:project_waypoints_ftheta. No behavior change.

Issue #34 reports that GT trajectory projections do not align with the road in the camera image. The current docstring says:

wp: 3D waypoints in world coordinates, shape (N, 3).

…but the function actually expects rig-frame coordinates. The transformation chain is:

cam_points = (wp - cam_t) @ cam_rot

with cam_t = camera origin in the rig frame (as stored in the PAI extrinsics table) and cam_rot = R_cam_to_rig. This formula resolves to the camera frame only when wp is also in the rig frame. If a user reads the docstring literally and passes world-frame waypoints (e.g. egomotion().pose.translation), the projection lands on a different surface — exactly what #34 reports.

What this PR does

Updates the docstring to:

1. State explicitly that wp, cam_t, and cam_rot must all be in the rig frame (which is what the PAI loader's ego_future_xyz and ego_history_xyz already are at t0).
2. Show the world→rig transformation users must apply if they start from world-frame waypoints:

   p_rig = R_t0_inv @ (p_world - t0_xyz)
   

3. Document the extrinsic convention: cam_rot is the camera-to-rig rotation as returned by Rotation.from_quat([qx,qy,qz,qw]).as_matrix() with the quaternion taken directly from the PAI extrinsics.
4. Document the camera frame convention (right-handed, +z forward) and the visibility filter.
5. Add a one-line inline comment over the (wp - cam_t) @ cam_rot step explaining the row-vector / right-multiplication trick.

Why this matters

The issue's reporter tried both ego_future_xyz (already correct) and ego_future_xyz_world → ego(t0) local paths and reported failure on both. With the clearer docstring + inline comment, future readers can sanity-check their inputs against the documented conventions. (If the reporter is in fact passing rig-frame waypoints and still seeing misalignment, the issue lies elsewhere — most likely an extrinsic-quaternion convention mismatch — and the clearer docstring at least narrows the search space.)

Test plan

• python -c \"import ast; ast.parse(open('src/alpamayo_r1/visualization/viz.py').read())\" — syntax OK.
• No code paths changed; only the docstring + a comment line above the existing arithmetic.
• Reviewer: confirm the rig-frame extrinsic convention I documented matches the PAI dataset spec (I inferred it from the code at viz.py:106-109 and load_physical_aiavdataset.py:128-144).

Related

• Refs GT trajectory projection to camera image looks incorrect for PhysicalAI-AV dataset #34 — GT trajectory projection looks incorrect.