Feature/u turn detection

[vtushar06]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
This PR introduces a method to detect U-turn behavior in tracked trajectories, which is useful for downstream behavioral analysis and trajectory interpretation.

What does this PR do?

• Adds the detect_u_turns() function to movement.kinematics.kinematics to detect U-turn behavior using angular changes in displacement or forward vectors.
• Supports both forward_vector and displacement based detection with a threshold.
• Adds detect_u_turns to __all__ and exposes it in the kinematics API.
• Adds a new test fixture valid_data_array_for_u_turn_detection.
• Adds detailed tests for U-turn detection:
  • forward vector mode
  • displacement mode
  • edge cases and threshold sensitivity
  • invalid parameter checks
• Adds a dedicated test suite for compute_forward_vector_angle, covering:
  • antisymmetry under keypoint/camera swap
  • scale/translation invariance
  • NaN handling
  • in-degrees vs radians toggle
  • invalid dimension handling
• Ensures code quality:
  • All pre-commit hooks (ruff, mypy, codespell) pass
  • All test coverage is verified via pytest

References

Closes #362 (U-turn detection enhancement request)
Related to previous effort: PR #507

How has this PR been tested?

• ✅ pytest tests/test_unit/test_kinematics/ --cov=movement
• ✅ All new test cases pass
• ✅ pre-commit run --all-files passes with no issues

Is this a breaking change?

• No

Does this PR require an update to the documentation?

• No. The added function is documented via docstrings and integrated into the module-level exports.

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[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

[codecov]

Codecov Report

Attention: Patch coverage is 93.75000% with 1 line in your changes missing coverage. Please review.

Project coverage is 99.94%. Comparing base (20ca1b9) to head (9d55b37).

Files with missing lines	Patch %	Lines
movement/kinematics/kinematics.py	93.75%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##              main     #634      +/-   ##
===========================================
- Coverage   100.00%   99.94%   -0.06%     
===========================================
  Files           32       32              
  Lines         1859     1874      +15     
===========================================
+ Hits          1859     1873      +14     
- Misses           0        1       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[vtushar06]

Hii @niksirbi ,
can you please review these feature whenever you are available,
thanks
@vtushar06

[niksirbi]

Thanks @vtushar06. I'll prioritise reviewing #623 first, and leave this one for later in August as its not a priority right now.
That said, it's definitely a useful feature and in scope, so I'm grateful for you bearing with me on this.

[vtushar06]

Thanks so much @niksirbi, I really appreciate you prioritizing the review!
Let me know if there’s anything else I can assist with or pick up in the meantime—happy to contribute wherever needed.