Sovereign 8s.is mirror of standardgalactic/DUSTrack
  • Python 95.9%
  • Shell 4.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-02-04 11:06:11 -05:00
.idea add finger vibration processing 2025-12-22 12:42:49 -05:00
docs add documentation 2025-12-06 22:31:58 -05:00
dustrack add toggal gamma correction 2026-02-04 10:58:20 -05:00
pia02_workflow update all 2026-01-13 15:50:24 -05:00
.gitignore initial commit 2025-05-02 10:04:12 -04:00
.readthedocs.yaml initial commit 2025-05-02 10:04:12 -04:00
LICENSE initial commit 2025-05-02 10:04:12 -04:00
pyproject.toml bugfix 2025-12-03 00:20:03 -05:00
README.md improved documentation 2025-12-03 16:54:22 -05:00
requirements.yml refactor: update imports and dependencies for optional use, edit Readme, add keyboard shortcuts 2025-12-02 17:37:32 -05:00

DUSTrack

src PyPI - Version Documentation Status GitHub license

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 preprint.

Installation

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

from dustrack 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(video_path, "pn") 
# The second argument is the name of the "layer" for storing tracking annotations

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{namburi2025dustrack,
  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={arXiv preprint arXiv:2507.14368},
  year={2025}
}

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