Multi-Animal Individual Support in PoseEstimation #143
Description
Feature Request: Multi-Animal Individual Support in PoseEstimation
Problem
element-deeplabcut currently assumes single-animal pose estimation.
DeepLabCut supports multi-animal tracking, where outputs include:
- multiple individuals (e.g.,
animal0,animal1, …) - per-individual body part groupings
The current Element schema does not support:
- storing individual identities
- mapping body parts to each individual
- associating pose coordinates with specific individuals
As a result, multi-animal DLC outputs cannot be represented in the existing workflow.
Proposed Solution (Backward Compatibility, no migration)
1. Add PoseEstimation.Individual part table
A table to store individuals detected in the output:
| individual_id | individual_name |
|---|---|
| 0 | animal0 |
| 1 | animal1 |
This table should be automatically populated from the DLC result files.
2. Add PoseEstimation.IndividualMapping part table
A table mapping individuals → body parts:
| individual_id | bodypart_name |
|---|---|
| 0 | snout |
| 0 | left_ear |
| 1 | snout |
| 1 | left_ear |
This reflects the DLC multi-animal structure and allows correct interpretation of pose coordinates.
3. Update DLC readers to parse multi-animal outputs
dlc_reader.py should be updated to read:
- individual names from the DLC 3.x output (h5/csv)
- per-individual pose arrays
- per-individual likelihoods
- identity metadata
Then populate the new tables accordingly.
Expected Behavior
Running PoseEstimation on multi-animal DLC output should:
- detect and list all individuals
- populate
PoseEstimation.Individual - populate
PoseEstimation.IndividualMapping - store per-individual pose coordinates and metadata
- remain fully backward-compatible with single-animal data
(multi-animal tables will remain empty if only one animal is present)