dustrack 1.2.0

DUSTrack: Semi-automated point tracking in ultrasound videos.

DUSTrack

Semi-automated point tracking in videos. Designed for ultrasound videos, but works with natural videos as well.

DUSTrack (Deep learning and optical flow-based toolkit for UltraSound Tracking) is a semi-automated framework for tracking arbitrary points in B-mode ultrasound videos. It combines deep learning with optical flow to deliver high-quality, robust tracking across diverse anatomical structures and motion patterns. The toolkit includes a graphical user interface that streamlines the generation of high-quality training data and supports iterative model refinement. It also implements a novel optical-flow-based filtering technique that reduces high-frequency frame-to-frame noise while preserving rapid tissue motion.

Features

• Hybrid approach: Combines deep learning with optical flow for accurate tracking
• User-friendly GUI: Streamlines training data generation and model refinement
• Noise reduction: Novel optical-flow-based filtering preserves rapid motion while reducing frame-to-frame noise
• Versatile: Works with ultrasound and other video types
• Flexible installation: Use GUI + optical flow only, or add deep learning capabilities

Learn more about DUSTrack in our paper in Scientific Reports.

Installation

Option 1: GUI + Optical Flow Only (Recommended for Short Videos)

For tracking points in videos with a few hundred frames, this lightweight installation is sufficient:

pip install DUSTrack

Troubleshooting dependencies: If you encounter dependency issues, use conda with the provided requirements.yml file:

conda env create -n env-dustrack -f https://github.com/praneethnamburi/DUSTrack/raw/main/requirements.yml
conda activate env-dustrack
pip install DUSTrack

Option 2: Full Installation (Including Deep Learning)

For longer videos or ultrasound videos with repetitive motions, deep learning significantly reduces manual effort and improves tracking quality:

1. Create a conda environment and install DeepLabCut by following these instructions
2. Activate your DeepLabCut environment and install DUSTrack:

   conda activate <your-dlc-env>
   pip install DUSTrack
   

Quick Start

After installation, type dustrack at any shell prompt:

dustrack

A file picker opens — select one or more videos and DUSTrack launches on the first one. No Python code required.

Next steps:

• Use the GUI to mark points of interest in your video (see Keyboard shortcuts)
• Track points using optical flow and/or train a deep learning model
• Export tracking results as a .json file for further analysis

For detailed tutorials and examples, see the documentation.

Scripting and resume

The same workflow is reachable from Python via dustrack.open(...), which auto-detects whether the path is a bare video (start fresh) or a DLC project (resume in place):

import dustrack
import datanavigator

# Zero-argument launch (same as the `dustrack` shell command):
dustrack.open()                                      # pops the file picker

# Start fresh on a specific video:
video_path = datanavigator.get_example_video()       # or use your own
d = dustrack.open(video_path, "pn")
# The second argument is the name of the "layer" for storing tracking
# annotations. If you omit it, DUSTrack defaults to "iteration-0" -- the
# canonical seed name for the DLC training pipeline (next iteration
# lands as "iteration-1").

# Resume in place from a previous DLC project:
dustrack.open('path/to/project/')                    # resume from project root
dustrack.open('path/to/project/config.yaml')         # resume from config
dustrack.open('path/to/project/videos/video.mp4')    # resume on a specific video

Documentation

Full documentation is available at DUSTrack.readthedocs.io.

Citation

If you use DUSTrack in your research, please cite our paper:

@article{namburi2026dustrack,
  title={DUSTrack: Semi-automated point tracking in ultrasound videos},
  author={Namburi, Praneeth and Pallar{\`e}s-L{\'o}pez, Roger and Rosendorf, Jessica and Folgado, Duarte and Anthony, Brian W},
  journal={Scientific Reports},
  volume={16},
  pages={13340},
  year={2026},
  doi={10.1038/s41598-026-42795-3}
}

Contributing

Contributions are welcome! Please feel free to:

• Submit a Pull Request with improvements or bug fixes
• Share your use cases and feedback (contact)

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

Praneeth Namburi

Project Link: https://github.com/praneethnamburi/DUSTrack

Acknowledgments

MIT.nano Immersion Lab

NCSOFT