Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/royerlab/ultrack
Cell tracking and segmentation software
https://github.com/royerlab/ultrack
cell-segmentation cell-tracking cell-tracking-challenge gurobi
Last synced: about 2 months ago
JSON representation
Cell tracking and segmentation software
- Host: GitHub
- URL: https://github.com/royerlab/ultrack
- Owner: royerlab
- License: bsd-3-clause
- Created: 2022-08-24T20:57:40.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-16T16:30:02.000Z (about 2 months ago)
- Last Synced: 2024-08-16T18:04:12.063Z (about 2 months ago)
- Topics: cell-segmentation, cell-tracking, cell-tracking-challenge, gurobi
- Language: Python
- Homepage: https://royerlab.github.io/ultrack
- Size: 109 MB
- Stars: 75
- Watchers: 5
- Forks: 10
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-biological-image-analysis - Ultrack - Versatile cell tracking method for 2D, 3D, and multichannel timelapses, overcoming segmentation challenges in complex tissues. (Cell migration and particle tracking)
README
# ULTRACK
[](https://codecov.io/gh/royerlab/ultrack)
[](https://badge.fury.io/py/ultrack)
[](https://pepy.tech/project/ultrack)
[](https://pepy.tech/project/ultrack)
[](https://pypistats.org/packages/ultrack)
[](https://github.com/royerlab/ultrack/blob/main/LICENSE)
[](https://github.com/royerlab/ultrack/graphs/contributors)
[](https://github.com/royerlab/ultrack/)
[](https://git:hub.com/royerlab/ultrack/)
Large-scale cell tracking under segmentation uncertainty.
## Overview
Ultrack is a versatile and scalable cell tracking method designed to address the challenges of tracking cells across 2D, 3D, and multichannel timelapse recordings, especially in complex and crowded tissues where segmentation is often ambiguous. By evaluating multiple candidate segmentations and employing temporal consistency, Ultrack ensures robust performance under segmentation uncertainty. Ultrack's methodology is explained [here](https://arxiv.org/pdf/2308.04526).
https://github.com/royerlab/ultrack/assets/21022743/10aace9c-0e0e-4310-a103-f846683cfc77
Zebrafish imaged using [DaXi](https://www.nature.com/articles/s41592-022-01417-2) whole embryo tracking.
## Features
- **Versatile Cell Tracking:** Supports 2D, 3D, and multichannel datasets.
- **Robust Under Segmentation Uncertainty:** Evaluates multiple candidate segmentations.
- **High Performance:** Scales from small in vitro datasets to terabyte-scale developmental time-lapses.
- **Integration:** Compatible with FiJi, napari, and high-performance clusters via SLURM.
## Installation
Install or update [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html).
To avoid conflicts between different packages, we recommend using conda to create an isolated environment:
```bash
conda create --name tracking -c conda-forge python=3.10 pyqt
conda activate tracking
pip install ultrack
```
## Usage
**ATTENTION**: every time you need to run this software you'll have to activate this environment
```bash
conda activate tracking
```
Here is a basic example to get you started:
```python
import napari
from ultrack import MainConfig, Tracker
# __main__ is recommended to avoid multi-processing errors
if __name__ == "__main__":
# Load your data
foreground = ...
contours = ...
# Create config
config = MainConfig()
# Run tracking
tracker = Tracker(config)
tracker.track(foreground=foreground, edges=contours)
# Visualize results in napari
tracks, graph = tracker.to_tracks_layer()
napari.view_tracks(tracks[["track_id", "t", "z", "y", "x"]], graph=graph)
napari.run()
```
More usage examples can be found [here](examples), including their environment files and installation instructions.
## Documentation
Comprehensive documentation is available [here](https://royerlab.github.io/ultrack/).
These additional developer documentation are available:
- Parameter [configuration schema](docs/source/configuration.rst).
- Intermediate segmentation and tracking SQL database are [here](ultrack/core/README.md).
## Gurobi Setup
### Install Gurobi using Conda
In your existing Conda environment, install Gurobi with the following command:
```bash
conda install -c gurobi gurobi
```
### Obtain and Activate an Academic License
1. Register at [Gurobi's website](https://portal.gurobi.com/iam/login/) with your academic email.
2. Navigate to the Gurobi's [named academic license page](https://www.gurobi.com/features/academic-named-user-license/)
3. Follow the instructions to get your license key.
4. Activate your license, In your Conda environment, run:
```bash
grbgetkey YOUR_LICENSE_KEY
```
5. Replace YOUR_LICENSE_KEY with the key you received. Follow the prompts to complete activation.
### Verify Installation
Verify Gurobi's installation by running:
```bash
ultrack check_gurobi
```
Depending on the operating system, the gurobi library might be missing and you need to install it from [here](https://www.gurobi.com/downloads/gurobi-software).
## Who is using Ultrack?
Here is a list of projects and papers that are and have used ultrack:
- DaXi Project: Ultrack was used for tracking zebrafish embryos using high-resolution light-sheet microscopy as part of the DaXi project, demonstrating its capability to handle large-scale datasets efficiently. See paper [here](https://www.nature.com/articles/s41592-022-01417-2).
- [Zebrahub.org](zebrahub.org) project: Ultrack is employed in projects hosted on ZebraHub.org to track and analyze zebrafish embryonic development. See preprint [here](https://www.biorxiv.org/content/10.1101/2023.03.06.531398v2).
- Single-cell transcriptional dynamics in a living vertebrate: Ultrack was used for segmenting and tracking nuclei in light-sheet microscopy datasets of developing zebrafish embryos. See preprint [here](https://www.biorxiv.org/content/10.1101/2024.01.03.574108v1).
## Contributing
We welcome contributions from the community! To get started, please read our [contributing guidelines](CONTRIBUTING.md). Then, report issues and submit pull requests on GitHub.
## License
This project is licensed under the BSD-3 License - see the [LICENSE](LICENSE) file for details.
## Citing
If you use ultrack in your research, please cite the following [paper](https://arxiv.org/pdf/2308.04526):
```
@misc{bragantini2023ucmtracking,
title={Large-Scale Multi-Hypotheses Cell Tracking Using Ultrametric Contours Maps},
author={Jordão Bragantini and Merlin Lange and Loïc Royer},
year={2023},
eprint={2308.04526},
archivePrefix={arXiv},
primaryClass={cs.CV}
}
```
Include citations for auxiliary methods (e.g., Cellpose, napari) depending on your usage.
## Acknowledgements
We acknowledge the contributions of the community and specific individuals. Detailed acknowledgments can be found in our documentation.