feat(transformations): support custom reference timestamp in motion (de)compensation

[janickm]

Summary

Add an optional reference_timestamp_us parameter to MotionCompensator.motion_compensate_points and motion_decompensate_points, so callers can choose which in-frame timestamp the points are motion-compensated to / from.

It defaults to frame_end_timestamp_us, preserving the existing end-of-frame behavior used by the KITTI / nuScenes / Waymo converters.

Motivation

Different datasets motion-compensate lidar sweeps to different in-frame references. The API previously hard-coded the end-of-frame reference. Argoverse 2, for example, compensates each sweep to the sweep reference timestamp, which is the start of the sweep (offset_ns runs forward from it). Without an explicit reference, decompensating such data with the end-of-frame assumption applies the full intra-sweep ego motion (~1 m) as a systematic error.

This makes the compensation reference an explicit, optional parameter so converters can express their dataset's convention directly.

Changes

• motion_compensate_points / motion_decompensate_points: new reference_timestamp_us: Optional[int] = None (defaults to frame_end_timestamp_us), asserted to lie within [frame_start, frame_end].
• motion_decompensate_points is reimplemented as the exact inverse of motion_compensate_points: per point it evaluates the sensor pose at the point's own timestamp relative to the reference sensor pose (T_sensor_pointtime_world @ T_world_sensor_reftime) instead of linearly interpolating the end->start relative transform. This generalizes to any reference and is at least as accurate.
• MotionCompensationResult: fields renamed from the (now misleading) xyz_s_sensorend / xyz_e_sensorend to xyz_s_reftime / xyz_e_reftime, and the struct now carries reference_timestamp_us unconditionally.
• Internal transforms use the consistent T_<source>[_time]_<target>[_time] snake_case convention (no camelCase, no stray sensorend / sensorRef).
• All callers updated: ncore/impl/data/v4/compat.py, the nuScenes and Waymo converters, structured_lidar_model.py, and the ncore_project_pc_to_img / ncore_evaluate_lidar_model tools.

Testing

bazel test //ncore/impl/common:test_3_11 \
            //ncore/impl/data/v4:pytest_compat_3_11 \
            //ncore/impl/sensors:pytest_lidar_3_11

New tests:

• test_idempotence_custom_reference_timestamp -- compensate to a non-default reference (frame start) and decompensate back recovers the original points.
• test_default_reference_matches_explicit_end_of_frame -- omitting reference_timestamp_us equals passing frame_end explicitly.

The existing test_idempotence still passes, as do the compat and lidar sensor tests (which consume the renamed result fields). All of //ncore/... and the affected //tools/... packages build and type-lint cleanly.

---

This unblocks the Argoverse 2 converter (separate PR #145), which will call motion_decompensate_points(..., reference_timestamp_us=sweep_ts).

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[janickm]

This supersedes janickm#1 and addresses all the review feedback there:

• xyz_sensorend param -> renamed to xyz_reftime in motion_decompensate_points.
• MotionCompensationResult "sensorend" fields -> renamed to xyz_s_reftime / xyz_e_reftime, and the struct now carries reference_timestamp_us unconditionally.
• camelCase T_world_sensorRef etc. -> all internal transforms use the T_<source>[_time]_<target>[_time] snake_case convention.
• T_from_to frame-name consistency -> reworked so names match the actual composition (e.g. T_sensor_pointtime_sensor_reftime = T_world_sensor_pointtime @ T_sensor_reftime_world).
• stray "sensorend" in code + comments -> swept the whole repo; the only legitimate remaining T_world_sensor_end usages are the unrelated end-of-frame poses in the camera/lidar/common sensor modules.
• "make this free of the argoverse stuff" -> this branch is off main with no Argoverse 2 changes. The AV2 converter (PR feat(argoverse2): add Argoverse 2 Sensor Dataset to NCore V4 converter #145) goes on top afterwards and will call motion_decompensate_points(..., reference_timestamp_us=sweep_ts).

Targets main per the merge-first plan.

[janickm]

/ok to test b0556d4