dustrack 1.1.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

import dustrack
import datanavigator

# Launch the GUI with an example video
video_path = datanavigator.get_example_video()  # or use your own video path
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").

# To resume later, `dustrack.open(...)` auto-detects whether the path is a
# bare video (start fresh) or a DLC project (resume in place):
#   dustrack.open('video.mp4')                          # fresh, single video
#   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

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.

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