DySTrack - Dynamic Sample Tracking

DySTrack ("diss track") is a simple, modular, python-based, open-source automated feedback microscopy tool for live tracking of moving samples like migratory cells or tissues during acquisition. It works with common commercial microscope control software through a minimal interface.

Please see the Documentation for more information!

Warning: Modern microscopes are expensive machines, and automating them comes with an inherent risk of damage. Appropriate care must be taken when installing, testing, and using DySTrack. The code and documentation are provided "as is", without warranty or liability of any kind (see LICENSE).

Quick start

It is strongly advised that first-time users consult the Documentation before installing and using DySTrack. These Quick Start instructions are intended solely for experienced users.

Install from cloned GitHub repo (recommended):

git clone https://github.com/WhoIsJack/DySTrack.git
cd DySTrack
conda create -n dystrack python=3.13
conda activate dystrack
pip install -e ".[full]"
pytest

Install from PyPI:

conda create -n dystrack python=3.13
conda activate dystrack
pip install "dystrack[full]"

Start a DySTrack manager session:

conda activate dystrack
python <path-to-config-file.py> <path-to-target-dir> [optional arguments]

Overview of repo structure

• run\: Config files
  • Specify the image analysis pipeline (and optionally other parameters) for a DySTrack run
  • Run a DySTrack session: python path\to\config_file.py path\to\target_dir [optional args]

• src\dystrack\manager\: Core module
  • Implements "DySTrack manager" sessions and a command line app to launch them
  • A manager session scans for new (prescan) images produced by the microscope
  • Upon detection of a new target image, an image analysis pipeline is triggered
  • The pipeline returns new coordinates, which are then forwarded to the microscope

• src\dystrack\pipelines\: Image analysis pipelines
  • Called by the DyStrack manager when a new target image is detected
  • A pipeline reads a target image and returns new coordinates for acquisition
  • Adapting DySTrack to new use cases is mainly a matter of developing new pipelines

• macros\: Interfacing with the microscope
  • Macros are run within commercial microscope software
  • They control all of the microscope's actual operations
  • They interface with DySTrack only by saving image files and reading new coordinates

• tests\: Automated testing with pytest
  • Run pytest to execute the complete test suite

• docs\: DySTrack documentation
  • Run make html to build a local version of the docs

• notebooks\: Some potentially useful Jupyter notebooks

Asking for help or contributing to DySTrack

We welcome Issues and Pull Requests that:

• Report or fix a bug or other problem
• Ask a question not answered in the Documentation
• Fix or improve something in the documentation
• (Aim to) add a new image analysis pipeline
• (Aim to) add support for an unsupported microscope
• Suggest or make (backwards-compatible) improvements to features or performance

When raising an Issue or PR, please give it a clear title and description, and include as much relevant information as possible.

For PRs, please follow the conventions in the existing code base as closely as possible, use black and isort for code formatting and numpy-style doc strings, and include/update unit tests and the documentation as necessary.

That said, if you are unsure how to do these things, please raise an Issue or PR anyway and just ask for support! If we find the time, we are happy to help; after all, most of us are scientists (not professional software developers), and we are all always still learning!

Disclaimer: We currently cannot guarantee any level of support whatsoever and retain full discretion to close Issues or reject Pull Requests for any reason. Nevertheless, we do aspire to be helpful and responsive to the extent our limited resources permit.

All interactions must abide by the Contributor Covenenat Code of Conduct.

Acknowledgements

The earliest prototype of DySTrack was created by Jonas Hartmann in the group of Darren Gilmour at EMBL Heidelberg, with support by the Advanced Light Microscopy Facility (ALMF) and especially Christian Tischer, Antonio Politi, and Aliaksandr Halavatyi, and with Elisa Gallo and Mie Wong providing user feedback.

The prototype was then modernized and further developed by Zimeng Wu and Jonas Hartmann at UCL, in the groups of Mie Wong and Roberto Mayor, respectively, with support by the Centre for Cell & Molecular Dynamics (CCMD), especially Virginia Silio, Mike Redd, and Alan Greig. Nicolas Sergent (Zeiss) supported development for ZEN Blue and Robert Tetley (Nikon) for NIS Elements. The chick node tracking experiments were developed with Octavian Voiculescu in the lab of Alessandro Mongera.

Citing DySTrack

If you are using DySTrack in your research, please cite the preprint:

@article {Wu2025.12.02.691816,
  author = {Wu, Zimeng and Voiculescu, Octavian and Mongera, Alessandro and Mayor, Roberto and Wong, Mie and Hartmann, Jonas},
  title = {DySTrack: a modular smart microscopy tool for live tracking of dynamic samples on modern commercial microscopes},
  elocation-id = {2025.12.02.691816},
  year = {2025},
  doi = {10.64898/2025.12.02.691816},
  publisher = {Cold Spring Harbor Laboratory},
  URL = {https://www.biorxiv.org/content/10.64898/2025.12.02.691816v1},
  journal = {bioRxiv}
}