feat: Redesign orientation API with perpendicular vector and vector-from-to

[mujju-212]

Summary

Closes #616

This PR redesigns the orientation API as discussed in the issue and community call, adding composable vector computation and angle functions.

Changes

New Functions

Function	Purpose
compute_perpendicular_vector(data, left_keypoint, right_keypoint, camera_view)	Renamed from compute_forward_vector — same cross-product logic, clearer name reflecting that it produces a vector perpendicular to the left–right axis
compute_vector_from_to(data, from_keypoint, to_keypoint)	New — computes a direction vector between any two keypoints via subtraction (e.g., neck → nose for head direction)
compute_vector_angle(vector, reference_vector, in_degrees)	New — computes the signed angle of any pre-computed vector DataArray against a reference direction. Supports both static tuples and time-varying DataArray references

Deprecated Functions

Function	Replacement	Backward Compatible?
compute_forward_vector	compute_perpendicular_vector	✅ Yes — wrapper emits DeprecationWarning
compute_forward_vector_angle	compute_perpendicular_vector + compute_vector_angle	✅ Yes — wrapper emits DeprecationWarning

Design Decisions

• Follows the API design from Adding the option for front-back instead of left-right points for forward vector calculation. #616 comments (sfmig / niksirbi's decomposition into separate vector + angle steps)
• Composable: compute any vector first, then optionally get its angle — no tight coupling
• Backward compatible: existing code using compute_forward_vector / compute_forward_vector_angle continues to work with deprecation warnings
• Immutable: no input data is modified (per project conventions)

Example Usage

from movement.kinematics import compute_vector_from_to, compute_vector_angle

# Head direction from neck to nose
head_dir = compute_vector_from_to(ds.position, "neck", "nose")
head_angle = compute_vector_angle(head_dir, in_degrees=True)

# Perpendicular vector (replaces compute_forward_vector)
from movement.kinematics import compute_perpendicular_vector
perp = compute_perpendicular_vector(ds.position, "left_ear", "right_ear")

Tests

• Rewrote test_orientation.py with 26 tests covering all new and deprecated functions
• Organized into clear test classes: TestVectorFromTo, TestVectorAngle, TestForwardVectorAngle
• All 138 kinematics + ROI tests pass (backward compatibility confirmed)
• Deprecation warnings correctly emitted in downstream test_roi/test_angles.py

Files Changed

File	Description
movement/kinematics/orientation.py	Core implementation — 3 new functions + 2 deprecated wrappers
movement/kinematics/__init__.py	Updated exports
tests/test_unit/test_kinematics/test_orientation.py	Full test rewrite

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud