|
| 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 | + |
| 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 | + |
| 80 | + |
| 81 | +4. The user should now select the desired tracking workflow in this section: |
| 82 | + |
| 83 | + |
| 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 | + |
| 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 | + |
| 105 | + |
| 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 | + |
| 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 | + |
| 117 | + |
| 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 %} |
0 commit comments