DIPLOMAT

Usage

Overview

DIPLOMAT offers a range of commands and interfaces designed to facilitate multi-animal identity-preserving tracking. Each command and interface serves a specific purpose, from initial tracking to detailed adjustments and annotations. The following sections provide detailed descriptions and use cases for each component of the DIPLOMAT framework.

1. Tracking with DIPLOMAT

The track command is the primary tool for processing videos through the DIPLOMAT framework. It utilizes pre-trained models to detect and track animals within video footage, ensuring that the identity of each tracked animal is preserved throughout the sequence. This command can be run with or without a user interface (UI).

# 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

Use the track_and_interact command if you prefer a more interactive approach, allowing you to visualize and adjust the tracking in real-time as the video is processed.

2. Multiple Video Tracking

DIPLOMAT supports batch processing of multiple videos in a single command. This feature is especially useful for researchers who need to analyze large datasets efficiently.

# Track multiple videos by passing them as a list:
diplomat track -c path/to/config -v [path/to/video1, path/to/video2, "path/to/video3"]

3. Annotating Videos

After tracking, the annotate command can be used to generate labeled videos. This command overlays tracking data onto the original footage, providing a visual representation of the tracking results.

# Create annotated videos with tracking labels:
diplomat annotate -c path/to/config -v path/to/video

Annotated videos are valuable for presentations, publications, and further analysis.

4. Interacting with the UI

The interact subcommand opens the full interactive UI for major adjustments and detailed editing. This interface provides tools for adjusting tracked points, correcting errors, and refining the tracking results.

# Open the interactive UI for detailed adjustments:
diplomat interact -s path/to/ui_state.dipui

This UI is essential for ensuring high-quality tracking data, allowing users to manually correct any inaccuracies in the automated tracking.

5. Tweaking Minor Adjustments

For minor adjustments, the tweak subcommand offers a streamlined version of the interactive UI. This tool is perfect for quick fixes and minor corrections without the need to open the full interface.

# Make minor adjustments to tracking data:
diplomat tweak -c path/to/config -v path/to/video

6. Additional Help

All DIPLOMAT commands include built-in help documentation. Use the -h or --help flags to access detailed information about each command and its options.

# Help for all of DIPLOMAT (lists subcommands of DIPLOMAT):
diplomat --help 

# Help for the track subcommand:
diplomat track --help

# Help for the predictors subcommand space:
diplomat predictors --help

Documentation

DIPLOMAT has comprehensive documentation available on ReadTheDocs. The documentation covers installation, basic usage, advanced features, and troubleshooting tips. Access the documentation at https://diplomat.readthedocs.io/en/latest.

Development

DIPLOMAT is written entirely in Python. To set up a development environment for DIPLOMAT, you can clone the repository and install its dependencies using pip. Detailed instructions are available in the Development Usage section of the documentation.

Contributing

We welcome external contributions. Before starting any significant development work, it is advisable to contact the maintainers to ensure the proposed changes are a good fit for the project. Contributors agree to license their code under the project's license (see LICENSE).

To contribute:

1. Fork the repository
2. Make changes on a branch
3. Create a pull request