Package: diplomat-track
DIPLOMATDeep learning-based Identity Preserving Labeled-Object Multi-Animal Tracking.NOTE:DIPLOMAT is currently alpha software, there may be minor bugs and issues.AboutDIPLOMAT provides algorithms and tools for performing multi-animal identity preserving tracking on top of single animal and multi animal CNN based tracking packages. Currently, it supports running on both DeepLabCut and SLEAP projects.
Unlike other multi-animal tracking packages, DIPLOMAT's algorithms work directly off confidence maps instead of running peak detection, allowing for more nuanced tracking results compared to other methods.https://github.com/TravisWheelerLab/DIPLOMAT/assets/47544550/d805b673-4678-4297-b288-3fd08ad3cf62DIPLOMAT also includes a UI for performing tracking and several other tools for storing and visualizing confidence maps.InstallationDIPLOMAT also includes four environment configuration files for setting up DIPLOMAT withmamba, which can
be installed on Windows, Linux, or MacOS using theMiniforgeinstaller.
To create an environment using mamba, run one of these four commands:# Create the environment for using DIPLOMAT with DeepLabCut# GPU:mambaenvcreate-fhttps://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-DEEPLABCUT.yaml# CPU only:mambaenvcreate-fhttps://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-DEEPLABCUT-CPU.yaml# OR Create an environment for using DIPLOMAT with SLEAP instead...# GPU:mambaenvcreate-fhttps://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP.yaml# CPU only:mambaenvcreate-fhttps://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP-CPU.yamlAnd then activate the environment with one of these two commands:# Activate the DeepLabCut/DIPLOMAT environment...mambaactivateDIPLOMAT-DEEPLABCUT# Activate the SLEAP/DIPLOMAT environment...mambaactivateDIPLOMAT-SLEAPFor a more thorough explanation of the installation process and alternative installation methods, see thedocumentation.UsageRunning DIPLOMATTo run DIPLOMAT on a video once it is installed, simply use DIPLOMAT'sunsupervisedandsupervisedcommands to track a video:# Run DIPLOMAT with no UI...diplomattrack-cpath/to/config-vpath/to/video# Run DIPLOMAT with UI...diplomattrack_and_interact-cpath/to/config-vpath/to/videoMultiple videos can be tracked by passing them as a list:diplomattrack-cpath/to/config-v[path/to/video1,path/to/video2,"path/to/video3"]Once tracking is done, DIPLOMAT can create labeled videos via it'sannotatesubcommand:diplomatannotate-cpath/to/config-vpath/to/videoIf you need to reopen the UI to make further major modifications, you can do so using the interact subcommand:diplomatinteract-spath/to/ui_state.dipuiThis 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:diplomattweak-cpath/to/config-vpath/to/videoThis 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 thedocumentation.Additional HelpAll DIPLOMAT commands are documented via help strings. To get more information about a diplomat subcommand or command, simply run it with the-hor--helpflag.# Help for all of diplomat (lists sub commands of diplomat):diplomat--help# Help for the track subcommand:diplomattrack--help# Help for the predictors subcommand space:diplomatpredictors--helpDocumentationDIPLOMAT has documentation on ReadTheDocs athttps://diplomat.readthedocs.io/en/latest.DevelopmentDIPLOMAT 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 theDevelopment Usagesection in the documentation.ContributingWe 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 (seeLICENSE).To contribute:Fork the repoMake changes on a branchCreate a pull requestLicenseSeeLICENSEfor details.AuthorsIf you have any questions, feel free to reach out to Isaac Robinson, atisaac.k.robinson2000@gmail.comSeeAUTHORSthe full list of authors.