Multi Animal Tracking

---
name: multi-animal-tracking
description: "Route maDLC tracking, tracklet conversion, stitching, and
  transformer reID for DeepLabCut."
disable-model-invocation: true
metadata:
  disco-role: operating
license: LGPL 3.0
---

# Multi-Animal Tracking

Use this sub-skill for multi-animal pose outputs that must become stable identities and tracks.

## Use this sub-skill for
- choosing the tracking branch for a multi-animal project
- validating `multianimalproject`, `individuals`, `multianimalbodyparts`, `uniquebodyparts`, and `identity`
- converting analyzed detections into tracklets
- stitching tracklets into final tracks
- using transformer reID when animals cross or baseline tracking swaps identities
- checking whether the output files and track counts match the project configuration

## Route elsewhere when needed
- project creation, new project config layout, and data-path setup -> `install-and-project-setup`
- frame extraction, labeling, training-dataset creation, and data conversion -> `data-labeling-and-training-datasets`
- pose-network training, evaluation, and analysis -> `pytorch-training-evaluation-inference`
- filtering, labeled videos, trajectory plots, 3D utilities, and export tasks -> `postprocessing-3d-video-exports`

## Fast decision order
1. Confirm the project is multi-animal and that the names in the config are consistent.
2. If the model is conditional top-down, tracking happens during analysis and the manual convert/stitch steps are skipped.
3. If `auto_track=True`, `analyze_videos` already performs conversion and stitching.
4. If `auto_track=False`, use `convert_detections2tracklets` followed by `stitch_tracklets`.
5. If identity supervision was learned, try `identity_only=True` before adding more complex reID logic.
6. If identities still swap during crossings, use `transformer_reID` to mine triplets, train a transformer, and stitch with the resulting checkpoint.

## Key API anchors
- `analyze_videos(..., auto_track, n_tracks, animal_names, identity_only, ctd_tracking, ctd_conditions)`
- `convert_detections2tracklets(..., track_method, identity_only)`
- `stitch_tracklets(..., track_method, n_tracks, animal_names, transformer_checkpoint)`
- `transformer_reID(..., track_method, n_tracks, n_triplets, train_epochs)`

Baseline tracker families are `ellipse`, `box`, and `skeleton`; `ctd` is a direct-tracking branch during analysis, not a manual convert/stitch setting.

## Config facts to keep aligned
- `multianimalproject: true` enables the multi-animal tracking path.
- `individuals` sets the default output identity list and usually the default track count.
- `identity: true` should be set before training when animals can be told apart consistently.
- `multianimalbodyparts` are shared body parts for each individual.
- `uniquebodyparts` are seen once per frame and are stored as a `single` channel in the outputs.
- Keep individual names, body-part names, and `animal_names` stable so output columns stay consistent.
- If `animal_names` is used, keep its length aligned with `n_tracks`.

## Bundled runtime aids
- `references/api-reference.md`
- `references/workflows.md`
- `references/troubleshooting.md`
- `scripts/plan_tracking_workflow.py`

## Output families to expect
- raw detections: `_full.pickle` and `_meta.pickle`
- multi-animal assemblies: `_assemblies.pickle`
- baseline tracklets: `_el.pickle`, `_bx.pickle`, or `_sk.pickle`
- reID training artifacts: `_bpt_features.pickle`, `_triplet_vector.npy`, and `dlc_transreid_<epochs>.pth`
- stitched tracks: `.h5` and optional `.csv`, with transformer-assisted runs carrying a `tr` suffix

## What not to do here
- do not route project setup or labeling into this sub-skill
- do not route network training or evaluation into this sub-skill
- do not route generic labeled-video or filtering tasks here
- do not call manual convert/stitch for CTD models
- do not use `identity_only` unless the model learned identity supervision

## Validation reminder
Use the bundled planner script to print a safe call order before running anything, then confirm the expected output files and track counts.