Deep learning-based Identity Preserving Labeled-Object Multi-Animal Tracking.
NOTE: DIPLOMAT is currently early beta software, there may be minor bugs and usability issues.
If you are a user (not a developer contributing code), you may want to visit:
- the software website: https://wheelerlab.org/DIPLOMAT
- in-depth documentation: https://diplomat.readthedocs.io
DIPLOMAT provides a multi-animal tracking/pose-estimation interface that (1) reduces identity swaps and body part losses, and (2) simplifies correction of automated tracking errors. After pre-processing a video with a pose estimation tool (currently supporting SLEAP and DeepLabCut packages), DIPLOMAT computes a multi-animal maximum-probability trace to Track multiple animals (and their body parts); it then provides an intuitive and memory/time efficient Interact interface to edit and re-track as needed. DIPLOMAT differs from other multi-animal tracking packages by working directly off of confidence maps instead of running peak detection, allowing for more accurate tracking results.
Correcting and re-tracing on the Interact Interface
Example of tracking 2 Degus in a Box | Example of tracking 3 Rats |
---|---|
![]() |
![]() |
For detailed installation instructions, please refer to the documentation!
To run DIPLOMAT on a video once it is installed, simply use DIPLOMAT's track
and track_and_interact
commands to track a video:
# Run DIPLOMAT with no UI...
diplomat track -c path/to/config -v path/to/video
# Run DIPLOMAT with UI...
diplomat track_and_interact -c path/to/config -v path/to/video
Multiple videos can be tracked by passing them as a list:
diplomat track -c path/to/config -v [path/to/video1, path/to/video2, "path/to/video3"]
Once tracking is done, DIPLOMAT can create labeled videos via it's annotate
subcommand:
diplomat annotate -v path/to/video -c path/to/csv
If you need to reopen the UI to make further major modifications, you can do so using the interact
subcommand:
diplomat interact -s path/to/ui_state.dipui
This displays the full UI again for making further edits. Results are saved back to the same files.
If you need to make minor modifications after tracking a video, you can do so using the tweak subcommand:
diplomat tweak -v path/to/video -c path/to/csv
This will display a stripped down version of the interactive editing UI, allowing for minor tweaks to be made to the tracks, and then saved back to the same file.
For a list of additional ways DIPLOMAT can be used, see the documentation.
All DIPLOMAT commands are documented via help strings. To get more information about a diplomat subcommand or command, simply run it with the -h
or --help
flag.
# Help for all of diplomat (lists sub commands of diplomat):
diplomat --help
# Help for the track subcommand:
diplomat track --help
# Help for the predictors subcommand space:
diplomat predictors --help
Some commands support passing frontend-specific arguments. To get frontend specific help, you can use the --help_extra
flag.
diplomat track -c /path/to/config --help_extra
diplomat track_and_interact -c /path/to/config --help_extra
diplomat track_with -c /path/to/config -p Predictor --help_extra
DIPLOMAT has documentation on ReadTheDocs at https://diplomat.readthedocs.io/en/latest.
DIPLOMAT is written entirely in python. To set up an environment for developing DIPLOMAT, you can simply pull down this repository and install its requirements using pip. For a further description of how to set up DIPLOMAT for development, see the Development Usage section in the documentation.
We welcome external contributions, although it is a good idea to contact the maintainers before embarking on any significant development work to make sure the proposed changes are a good fit.
Contributors agree to license their code under the license in use by this
project (see LICENSE
).
To contribute:
- Fork the repo
- Make changes on a branch
- Create a pull request
See LICENSE
for details.
If you have any questions, feel free to reach out to George Glidden, at help@diplomattrack.org
See AUTHORS
for the full list of authors.