Skip to content

Commit 60a5f09

Browse files
Add ultrack wiki page (#327)
* Add Ultrack Plugin wiki page * Some minor changes and acknowledgments inclusion. * Update figures references so it is rendered on MyST parser * Update ultrack figures * Update ultrack.md * Update ultrack.md
1 parent 019a0bc commit 60a5f09

10 files changed

+128
-0
lines changed

_pages/plugins/ultrack.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
mediawiki: Ultrack FIJI's plugin
3+
title: Large-scale cell tracking under segmentation uncertainty
4+
dev-status: Beta
5+
support-status: Active
6+
description: Cell tracking and segmentation software
7+
Creator:
8+
- Jordão Bragantini
9+
- Ilan Theodoro
10+
Developer:
11+
- "@ilan-theodoro"
12+
- "@JoOkuma"
13+
doi: 10.48550/arXiv.2308.04526
14+
categories: [Tracking]
15+
---
16+
17+
{% capture source%}
18+
{% include github org='royerlab' repo='ultrack' %}
19+
{% endcapture %}
20+
21+
# Overview
22+
23+
[Ultrack](https://github.com/royerlab/ultrack) is a method for large-scale 3D cell-tracking through a segmentation selection approach.
24+
It is effective at tracking cells across large microscopy datasets on two fronts: (i) It can solve
25+
problems containing millions of segmentation instances in terabyte-scale 3D+t datasets; (ii) It achieves competitive
26+
results with or without deep learning, which requires 3D annotated data, that is scarce in the fluorescence microscopy
27+
field. The proposed method computes cell tracks and segments using a hierarchy of segmentation hypotheses and selects
28+
disjoint segments by maximizing the overlap between adjacent frames. We show that this method achieves state-of-the-art
29+
results in 3D images from the cell tracking challenge and has a faster integer linear programming formulation. Moreover,
30+
our framework is flexible and supports segmentations from off-the-shelf cell segmentation models and can combine them
31+
into an ensemble that improves tracking.
32+
33+
# Description
34+
35+
## Installation
36+
37+
The Ultrack plugin is a Java client for Python's Ultrack tracking software. The user needs to have
38+
Python installed in the system, preferably managed by [conda](https://conda.io/projects/conda/en/latest/index.html).
39+
The FIJI plugin depends on Ultrack's optional functionalities.
40+
Therefore, installation must include `ultrack[api]`.
41+
For example:
42+
```bash
43+
pip install 'ultrack[api]'
44+
```
45+
46+
For additional installation instructions, please refer to the [Ultrack documentation](https://github.com/royerlab/ultrack).
47+
48+
This plugin will call the Ultrack routines under the hood, enabling cell tracking in 2D+t and 3D+t datasets.
49+
50+
### FIJI integration
51+
52+
The ultrack plugin is available after selecting the update site for ultrack in FIJI by clicking **HELP****Update**
53+
**Manage Update Sites** and then searching for **Ultrack**. To activate the update site, click the checkbox in the
54+
**Activate** column, the leftmost one. Right after that, click **Apply and Close** and then **Apply Changes** in the now-enabled
55+
button at the bottom of the previous **ImageJ Update** window. That will trigger the download of the Ultrack
56+
plugin.
57+
58+
After that, FIJI restart is required, and then the Ultrack plugin will be available in the **Plugins****Tracking**
59+
**Ultrack** menu.
60+
61+
## How to Use
62+
63+
The steps below describe how to use the Ultrack plugin:
64+
65+
1. Open the image sequence to be tracked.
66+
67+
2. Click on the **Plugins****Tracking****Ultrack** menu. The Ultrack GUI will open.
68+
69+
![Ultrack GUI](media/plugins/ultrack/00_init.png)
70+
71+
3. (Optional but required in the first run) If Ultrack is correctly installed and accessible through the system path,
72+
the user can proceed to the next step. Otherwise, the user needs to set the path to the Ultrack executable in the
73+
**Environment****Select Conda Path** menu. It will open a dialog to select the `conda` executable, and
74+
then the user needs to select the preferred environment, which should be one indicated with the `[Ultrack found]` flag.
75+
76+
4. Now you should be able to start the connection with the Ultrack software by clicking the **Start Ultrack Server**
77+
button. The plugin will update its GUI to show the available tracking options, as shown in the figure below.
78+
79+
![Ultrack GUI with server started](media/plugins/ultrack/01_gui.png)
80+
81+
4. The user should now select the desired tracking workflow in this section:
82+
83+
![Ultrack GUI with tracking workflows](media/plugins/ultrack/03_workflows.png)
84+
85+
in which the user can select the desired tracking workflow. The options are:
86+
- **Auto Detection From Image**: which provides a way to track cells using solely the image as input;
87+
- **Foreground & edges from user**: which is suitable for tracking cells using **edge** detection and **foreground**
88+
segmentation provided by the user;
89+
- and **Segmentation from user**: which is suitable for tracking cells using segmentation labels from your favorite
90+
segmentation software, such as [Stardist](https://github.com/stardist/stardist),
91+
[Cellpose](https://github.com/MouseLand/cellpose),
92+
[MicroSAM](https://github.com/computational-cell-analytics/micro-sam) or any other.
93+
94+
5. (Optional) After selecting your desired workflow, you can tune the tracking parameters in the **Settings** section.
95+
The parameters are workflow-dependent, and the user can
96+
[check here](https://github.com/royerlab/ultrack-dev/blob/main/ultrack/config/README.md) for more information about
97+
the parameters. Not all of them are available in the FIJI interface, Python is required for full customization.
98+
99+
![Ultrack GUI with tracking options](media/plugins/ultrack/02_options.png)
100+
101+
6. After setting the parameters, the user can click the **Select Images** button to select the image to be tracked.
102+
It is worth mentioning that some workflows, such as **Manual Detection**, require more than one image to be selected.
103+
104+
![Ultrack GUI with image opening](media/plugins/ultrack/04_image_opening.png)
105+
![Ultrack GUI with image selector](media/plugins/ultrack/05_image_selection.png)
106+
107+
7. Finally, the user can click the **Run** button to start the tracking process. The user can follow the tracking
108+
process in the **Ultrack Log** section.
109+
110+
![Ultrack GUI with tracking progress](media/plugins/ultrack/06_run.png)
111+
112+
8. To visualize the tracking results, the user can click the **View Tracks** button. Then, it will request a
113+
particular image to bind the tracks. In the end, The tracking results will be shown using the
114+
[TrackMate](https://imagej.net/plugins/trackmate/) plugin.
115+
116+
![Ultrack GUI with track image selection](media/plugins/ultrack/07_open_tracks.png)
117+
![Tracks Viewer it Trackmate](media/plugins/ultrack/08_trackmate.png)
118+
119+
# Acknowledgments
120+
121+
We thank the ImageJ community for providing the necessary tools to develop this plugin, such as
122+
the FIJI platform and integrations. We also acknowledge the developers from [Trackmate](https://imagej.net/plugins/trackmate/) plugin for their work
123+
in the tool, which we rely on to visualize the tracking results.
124+
125+
# Citation
126+
If you find ultrack useful, please cite Ultrack as follows:
127+
128+
{% include citation %}

media/plugins/ultrack/00_init.png

45.1 KB
Loading

media/plugins/ultrack/01_gui.png

103 KB
Loading

media/plugins/ultrack/02_options.png

84.8 KB
Loading
126 KB
Loading
174 KB
Loading
117 KB
Loading

media/plugins/ultrack/06_run.png

127 KB
Loading
141 KB
Loading
217 KB
Loading

0 commit comments

Comments
 (0)