Feature/loader support idtracker

[ParthChatupale]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
This PR introduces I/O support for idtracker.ai, marking the first phase of integrating "centroid" tracking formats into movement (as discussed in #308). This enhances the library's data ingestion capabilities by empowering users to seamlessly bring idtracker trajectories directly into the movement ecosystem for filtering, processing, and analysis. Additionally, this work directly supports the project's newly published 2026 Roadmap goals, specifically the initiative to expand format support and validate the documented process for adding new loaders.

What does this PR do?
This PR implements the first phase of the idtracker.ai .h5 loader. Specifically, it:

• Adds ValidIdtrackerH5 for file validation.
• Implements from_idtracker_file and from_idtracker_style_dict to parse and reshape trajectories into the standard movement dataset format (n_frames, n_space, n_keypoints=1, n_individuals).
• Handles Edge Cases: Falls back to NaN arrays for trackless files (where id_probabilities are missing), and collapses an undocumented trailing dimension (N, M, 1) found in the probabilities array of some idtracker outputs.
• Adds Testing: Includes dynamic h5py pytest fixtures to validate these edge cases without requiring large static .h5 test files to be added to the repository.

References

#308 #349

How has this PR been tested?

I added new h5py and pytest fixtures in tests/fixtures/files.py and tests/test_unit/test_io/test_load_poses.py.

• Test files: Instead of adding large .h5 files to the repository, the tests use tmp_path to generate temporary test files on the fly.
• Test cases: The tests check the standard output, the (N, M, 1) trailing dimension shape, and files without tracks (verifying they return NaN arrays).
• Local testing: I ran the full existing test suite locally to make sure nothing else broke.

Is this a breaking change?

No. This PR strictly adds new I/O functionality and does not modify any existing loaders or core data structures.

Does this PR require an update to the documentation?

Does this PR require an update to the documentation?

Yes. I have added inline docstrings for the new functions. (Note: Further API references and user-facing examples will be finalized in Phase 2 of the idtracker integration roadmap).

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

[codecov]

Codecov Report

❌ Patch coverage is 95.55556% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.92%. Comparing base (3efc8ca) to head (a93e6fa).

Files with missing lines	Patch %	Lines
movement/io/load_poses.py	95.00%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##              main     #944      +/-   ##
===========================================
- Coverage   100.00%   99.92%   -0.08%     
===========================================
  Files           39       39              
  Lines         2678     2722      +44     
===========================================
+ Hits          2678     2720      +42     
- Misses           0        2       +2     

☔ 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.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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

[ParthChatupale]

Hello,

SonarCloud is currently flagging my "idtracker.ai" additions as "magic string" errors.

I noticed the codebase deliberately uses explicit string literals (like "DeepLabCut" and "SLEAP") throughout this file. To keep my code consistent with the existing design pattern and Python's Literal constraints, I matched that style instead of creating a new constant.

Would you prefer me to add a # noqa or Sonar suppression tag for these specific lines, or is there another workaround the project prefers for this?