Skip to content

feat: add lightweight trajectory re-identification utility#139

Open
AnandMayank wants to merge 13 commits into
neuroinformatics-unit:mainfrom
AnandMayank:feat/reid-trajectory-utility
Open

feat: add lightweight trajectory re-identification utility#139
AnandMayank wants to merge 13 commits into
neuroinformatics-unit:mainfrom
AnandMayank:feat/reid-trajectory-utility

Conversation

@AnandMayank
Copy link
Copy Markdown

Description

What is this PR

  • Bug fix
  • Addition of a new feature
  • Other

Why is this PR needed?

Current pose estimation pipelines (e.g. DLC, SLEAP) assume a fixed pool of individual IDs defined at training time. In ethology and field recordings, this assumption often breaks:

  • animals leave and re-enter the frame,
  • long occlusions occur,
  • multiple similar-looking individuals appear sequentially.

This can result in identity reuse, where different individuals are incorrectly merged into a single ID, leading to fragmented or semantically incorrect trajectories and unreliable downstream analysis.

While gap-based splitting (e.g. split_trajectories_by_gap, see #801) provides a useful baseline, it is insufficient for long-horizon recordings, where:

  • the same individual may reappear after long gaps, or
  • different individuals may appear after short gaps.

What does this PR do?

This PR introduces a lightweight, optional re-identification utility in ethology that operates as a post-processing step on existing trajectory data:

  • adds a new utility for trajectory re-identification based on simple motion consistency
  • operates on gap-split trajectories (e.g. output of split_trajectories_by_gap)
  • maintains a short-term trajectory memory (position and velocity statistics)
  • attempts to re-associate new segments with previous trajectories when:
    • motion similarity is high, and
    • the implied motion is physically plausible
  • assigns a new ID when no plausible match exists
  • preserves all original coordinates, metadata, and attributes
  • designed as an experimental ethology utility, not a replacement for full tracking systems

The association logic is inspired by boxMOT-style multi-object tracking, in the sense that:

  • detection/trajectory generation is decoupled from identity association, and
  • re-identification is handled via lightweight motion-based heuristics.

boxMOT itself is not introduced as a dependency — the implementation remains fully self-contained and Ethology-native.


References

  • Related discussion in Movement: #792 (Support re-IDing data)
  • Related Movement PR: #801 (trajectory gap splitting)
  • boxMOT (conceptual inspiration for association logic)

How has this PR been tested?

Unit tests were run locally with pytest, including:

  • basic re-association of split trajectories,
  • correct handling of long vs short gaps,
  • rejection of physically implausible matches,
  • multiple individuals processed independently,
  • edge cases (no candidates, empty memory),
  • preservation of metadata and coordinates.

Is this a breaking change?

No.
This feature is optional and does not affect existing pipelines.


Does this PR require an update to the documentation?

Not strictly required.
A short usage example can be added in a follow-up PR once the API stabilizes.


Checklist

  • The code has been tested locally
  • Tests have been added to cover new functionality
  • Documentation has been updated (optional follow-up)
  • Code has been formatted with pre-commit

sfmig and others added 13 commits April 25, 2025 10:12
…and BoxMOT-style model loading\n\n- Add reid module with motion-based re-identification\n- Refactor OSNet and TensorRT model loading to match BoxMOT approach (auto-download/cache)\n- Add unit tests for reid utility\n\nThis closes the gap for robust ID handling in long ethology recordings and improves reproducibility for all users.
Signed-off-by: Mayank Anand <anandmayank698@gmail.com>
… docstrings\n- Use super() instead of super(Class, self)\n- Avoid mutable default arguments\n- Fix long lines and other ruff issues
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants