dustrack 1.0.0a1__tar.gz

dustrack-1.0.0a1/.gitignore

@@ -0,0 +1,163 @@
+.vscode/*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+.venv-dev
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

dustrack-1.0.0a1/.readthedocs.yaml

@@ -0,0 +1,29 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+  - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

dustrack-1.0.0a1/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024-present Praneeth Namburi <praneeth.namburi@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

dustrack-1.0.0a1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: dustrack
+Version: 1.0.0a1
+Summary: DUSTrack: Semi-automated point tracking in ultrasound videos.
+Keywords: video,tracking,computer-vision,motion-analysis,point-tracking
+Author-email: Praneeth Namburi <praneeth.namburi@gmail.com>
+Requires-Python: >=3.7,<=3.13
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+License-File: LICENSE
+Requires-Dist: numpy<2
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: portion
+Requires-Dist: ffmpeg-python
+Requires-Dist: tables
+Requires-Dist: dill
+Requires-Dist: tqdm
+Requires-Dist: scikit-image
+Requires-Dist: opencv-python
+Requires-Dist: pysampled
+Requires-Dist: decord
+Requires-Dist: pyfilemanager
+Requires-Dist: datanavigator>=1.1.3
+Requires-Dist: sphinx==6.2.1 ; extra == "docs"
+Requires-Dist: sphinx-rtd-theme==2.0.0 ; extra == "docs"
+Requires-Dist: myst-parser==1.0.0 ; extra == "docs"
+Requires-Dist: sphinxcontrib-youtube==1.4.1 ; extra == "docs"
+Project-URL: Home, https://github.com/praneethnamburi/DUSTrack
+Provides-Extra: docs
+
+# DUSTrack
+
+[![src](https://img.shields.io/badge/src-github-blue)](https://github.com/praneethnamburi/DUSTrack)
+[![PyPI - Version](https://img.shields.io/pypi/v/DUSTrack.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/DUSTrack/)
+[![Documentation Status](https://readthedocs.org/projects/DUSTrack/badge/?version=latest)](https://DUSTrack.readthedocs.io)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/praneethnamburi/DUSTrack/main/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](https://arxiv.org/abs/2507.14368).
+
+## 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:
+
+```sh
+pip install DUSTrack
+```
+
+**Troubleshooting dependencies**: If you encounter dependency issues, use conda with the provided `requirements.yml` file:
+
+```sh
+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](https://deeplabcut.github.io/DeepLabCut/docs/installation.html)
+2. Activate your DeepLabCut environment and install DUSTrack:
+   ```sh
+   conda activate <your-dlc-env>
+   pip install DUSTrack
+   ```
+
+## Quick Start
+
+```python
+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](https://github.com/praneethnamburi/DUSTrack/raw/main/docs/source/resources/keyboard_shortcuts.pdf))
+- 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](https://DUSTrack.readthedocs.io).
+
+## Documentation
+
+Full documentation is available at [DUSTrack.readthedocs.io](https://DUSTrack.readthedocs.io).
+
+## Citation
+
+If you use DUSTrack in your research, please cite our paper:
+
+```bibtex
+@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](https://praneethnamburi.com/contact/))
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+[Praneeth Namburi](https://praneethnamburi.com)
+
+Project Link: [https://github.com/praneethnamburi/DUSTrack](https://github.com/praneethnamburi/DUSTrack)
+
+
+## Acknowledgments
+
+[MIT.nano Immersion Lab](https://immersion.mit.edu)
+
+[NCSOFT](https://nc.com)
+

dustrack-1.0.0a1/README.md

@@ -0,0 +1,108 @@
+# DUSTrack
+
+[![src](https://img.shields.io/badge/src-github-blue)](https://github.com/praneethnamburi/DUSTrack)
+[![PyPI - Version](https://img.shields.io/pypi/v/DUSTrack.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/DUSTrack/)
+[![Documentation Status](https://readthedocs.org/projects/DUSTrack/badge/?version=latest)](https://DUSTrack.readthedocs.io)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/praneethnamburi/DUSTrack/main/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](https://arxiv.org/abs/2507.14368).
+
+## 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:
+
+```sh
+pip install DUSTrack
+```
+
+**Troubleshooting dependencies**: If you encounter dependency issues, use conda with the provided `requirements.yml` file:
+
+```sh
+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](https://deeplabcut.github.io/DeepLabCut/docs/installation.html)
+2. Activate your DeepLabCut environment and install DUSTrack:
+   ```sh
+   conda activate <your-dlc-env>
+   pip install DUSTrack
+   ```
+
+## Quick Start
+
+```python
+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](https://github.com/praneethnamburi/DUSTrack/raw/main/docs/source/resources/keyboard_shortcuts.pdf))
+- 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](https://DUSTrack.readthedocs.io).
+
+## Documentation
+
+Full documentation is available at [DUSTrack.readthedocs.io](https://DUSTrack.readthedocs.io).
+
+## Citation
+
+If you use DUSTrack in your research, please cite our paper:
+
+```bibtex
+@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](https://praneethnamburi.com/contact/))
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+[Praneeth Namburi](https://praneethnamburi.com)
+
+Project Link: [https://github.com/praneethnamburi/DUSTrack](https://github.com/praneethnamburi/DUSTrack)
+
+
+## Acknowledgments
+
+[MIT.nano Immersion Lab](https://immersion.mit.edu)
+
+[NCSOFT](https://nc.com)

dustrack-1.0.0a1/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

dustrack-1.0.0a1/docs/api.md

@@ -0,0 +1,16 @@
+# API Reference
+
+```{eval-rst}
+.. automodule:: dustrack
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: dustrack.dlcinterface
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: dustrack.postprocess
+    :members:
+```

dustrack-1.0.0a1/docs/conf.py

@@ -0,0 +1,48 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'dustrack' # pyfilemanager
+copyright = '2025-present, Praneeth Namburi'
+author = 'Praneeth Namburi'
+release = '1.0.0a1' # 0.1.0
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.duration",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.napoleon",
+    "sphinxcontrib.youtube",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "collapse_navigation": False,
+}
+html_static_path = []
+
+autodoc_member_order = "bysource"
+napoleon_use_ivar = True
+
+from sphinx.ext.autodoc import between
+
+
+def setup(app):
+    # Register a sphinx.ext.autodoc.between listener to ignore everything
+    # between lines that contain the word IGNORE
+    app.connect("autodoc-process-docstring", between("^.*IGNORE.*$", exclude=True))
+    return app

dustrack-1.0.0a1/docs/index.md

@@ -0,0 +1,12 @@
+% pyfilemanager documentation master file, created by
+% sphinx-quickstart on Tue Jan 23 10:31:39 2024.
+% You can adapt this file completely to your liking, but it should at least
+% contain the root `toctree` directive.
+
+```{include} ../README.md
+:relative-images:
+```
+
+```{toctree}
+api
+```

dustrack-1.0.0a1/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

dustrack-1.0.0a1/docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx==6.2.1
+sphinx-rtd-theme==2.0.0
+myst-parser==1.0.0
+sphinxcontrib-youtube==1.4.1