Multi-Animal Individual Support in PoseEstimation

[maryapp]

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)