Skip to content

Commit 94cc01f

Browse files
AnniekStokAnniekStok
committed
add tutorial to README
1 parent 5f3670a commit 94cc01f

File tree

3 files changed

+268
-1
lines changed

3 files changed

+268
-1
lines changed

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@
33
[![tests](https://github.com/funkelab/motile_tracker/workflows/tests/badge.svg)](https://github.com/funkelab/motile_tracker/actions)
44
[![codecov](https://codecov.io/gh/funkelab/motile_tracker/branch/main/graph/badge.svg)](https://codecov.io/gh/funkelab/motile_tracker)
55

6+
7+
An application for interactive tracking with [motile](https://github.com/funkelab/motile).
68
The full documentation of the plugin can be found [here](https://funkelab.github.io/motile_tracker/).
79

8-
An application for interactive tracking with [motile](https://github.com/funkelab/motile)
910
Motile is a library that makes it easy to solve tracking problems using optimization
1011
by framing the task as an Integer Linear Program (ILP).
1112
See the motile [documentation](https://funkelab.github.io/motile)
@@ -60,6 +61,8 @@ track objects in napari Labels or Points layers. For details, please read the
6061

6162
![motile_tracker_quick_demo](https://github.com/user-attachments/assets/07a4a954-3d2d-4d67-8f75-aec11ee14697)
6263

64+
If you are new to using motile-tracker, you can follow this [tutorial](./assets/motile-tracker_tutorial.pdf) to learn the basics.
65+
6366
## Package the application into an executable and create the installer
6467

6568
Tagging any branch will automatically trigger the deploy.yml workflow,

‎assets/motile-tracker_tutorial.md‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
# Interactive Cell Tracking with Motile-Tracker
2+
*January 2026 - motile-tracker v4.3.\* - Caroline Malin-Mayor - Anniek Stokkermans*
3+
4+
[`motile-tracker`](https://www.napari-hub.org/plugins/motile-tracker) is napari plugin implementing [`motile`](https://funkelab.github.io/motile/) for interactive cell tracking. You can find the full documentation [`here`](https://funkelab.github.io/motile_tracker/). Please follow the preparation instructions below before the workshop.
5+
6+
## Preparations
7+
8+
### Installing motile-tracker
9+
10+
You can install the plugin via `pypi` in the environment of you choice (e.g. `venv`, `conda`) with the command
11+
`pip install motile-tracker`.
12+
Currently, the motile_tracker requires python >=3.11.
13+
14+
For example, to create a new environment with conda:
15+
16+
```
17+
conda create -n motile_tracker python=3.11
18+
conda activate motile_tracker
19+
pip install motile-tracker
20+
pip install pyqt6
21+
```
22+
23+
To install the latest development version use:
24+
25+
```
26+
pip install motile-tracker --pre
27+
```
28+
29+
### Gurobi Optimizer license
30+
Using the Gurobi Optimizer software is not strictly necessary, but it speeds up the solving. It is free for academic use. You can download the Gurobi Optimizer and request a license key [`here`](https://www.gurobi.com/features/academic-named-user-license/). If Gurobi is detected on your computer, it will automatically use it for computing the tracks. You can also install it with:
31+
32+
```bash
33+
pip install motile-tracker[gurobi]
34+
```
35+
36+
If you have a Gurobi license and encounter an error about license version mismatch,
37+
you may need to install a specific version of `gurobipy` that matches your license.
38+
Use one of the version-specific extras:
39+
40+
```bash
41+
pip install motile-tracker[gurobi12] # For Gurobi 12.x licenses
42+
pip install motile-tracker[gurobi13] # For Gurobi 13.x licenses
43+
```
44+
45+
### Verify installation of the plugin
46+
If your installation was successful, you should be able to find 'Motile' under `Plugins`. Please go to `Plugins > Motile Tracker > All` to check if the start up screen looks like this:
47+
<figure style="margin: 10px; text-align: center;">
48+
<img src="./main_widget_startup.png" width="430" />
49+
<figcaption>Motile-tracker startup screen</figcaption>
50+
</figure>
51+
52+
53+
### Downloading sample data
54+
Two sample datasets are provided with the plugin:
55+
- Fluo-N2DL-HeLa is a 2D dataset of images and segmentations of HeLa cells from the [`cell tracking challenge`](https://celltrackingchallenge.net/2d-datasets/).
56+
- Mouse Embryo Membrane is a 3D dataset of images and segmentations of a membrane labeled developing early mouse embryo (4-26 cells)
57+
from [`Fabrèges et al (2024)`](https://www.science.org/doi/10.1126/science.adh1145) available [`here`](https://zenodo.org/records/13903500).
58+
59+
To download and open the sample data, click `File > Open Sample > Motile Tracker > Fluo-N2DL-HeLa (2D)` and `File > Open Sample > Motile Tracker > Mouse Embryo Membranes (3D)`. This may take a few minutes. After downloading, the data will remain available in the plugin for re-use.
60+
61+
If you see these images after opening the sample data, you are ready to start the workshop!
62+
63+
<div style="display: flex; justify-content: space-around;">
64+
<figure style="margin: 10px; text-align: center;">
65+
<img src="./sample1.png" width="400" />
66+
<figcaption>Fluo-N2DL-HeLa (2D)</figcaption>
67+
</figure>
68+
<figure style="margin: 10px; text-align: center;">
69+
<img src="./sample2.png" width="400" />
70+
<figcaption>Mouse Embryo Membranes (3D)</figcaption>
71+
</figure>
72+
</div>
73+
74+
## Generating Tracks
75+
76+
### Input data
77+
To track objects with the plugin, you need to either provide object segmentations on a napari Labels layer or object detections on a Points layer. If your data uses anisotropic scaling, make sure that the scaling is correctly set on the layer (`layer.scale`) via the console.
78+
79+
### Choosing tracking parameters
80+
Tracking parameters should be specified in the `Tracking` tab and are subdivided in hyperparameters, constant costs and attribute weights. Hovering over each of the parameters will display a tooltip, and more extensive information can be found in the documentation. Once the parameters are set, you can start the solver by clicking `Run Tracking`. After the solve is complete, you can find the Tracking Result in the `Tracks List` tab. Tracking Results will accumulate here for each set of parameters that you tried.
81+
82+
<div style="display: flex; justify-content: space-around;">
83+
<figure style="margin: 10px; text-align: center;">
84+
<img src="./tracking_parameters.png" width="200" />
85+
<figcaption>Enter tracking parameters</figcaption>
86+
</figure>
87+
<figure style="margin: 10px; text-align: center;">
88+
<img src="./tracks_list.png" width="200" />
89+
<figcaption>Tracking results</figcaption>
90+
</figure>
91+
</div>
92+
93+
<div style="background-color: #e6f7ff; border: 2px solid #104982; padding: 15px; border-radius: 10px;">
94+
<h2>Exercise 1 - Generating Tracking Results</h2>
95+
<p>1. Start the plugin via <code>Plugins > Motile Tracker > All </code> </p>
96+
<p>2. Go to <code>File > Open Sample > Motile Tracker > Fluo-N2DL-HeLa crop (2D)</code> to open the 2D HeLa cell test dataset, or load your own segmentation data.</p>
97+
<p>3. To compute tracks, go to the <code>Tracking</code> tab, and choose parameters for tracking. Use '01_ST' as input layer. Consult the
98+
<a href="https://funkelab.github.io/motile_tracker/motile.html" target="_blank" style="color: #0073e6; text-decoration: underline;">documentation</a> to help you decide on the different values. Click <code>Run Tracking</code> to start the computation. After the solver has finished, you should see that the Tree View is now populated with tracks and that the cells are relabeled.</p>
99+
<p>4. Click <code>Back to editing</code> and test multiple combinations of parameters. Note that you can also use the Points layer 'centroids' as input. Compare the different tracking results. Verify that you can find previous results in the <code>Tracks List</code> tab.
100+
</div>
101+
102+
## Viewing and navigating a tracking result
103+
104+
### Tracking views
105+
After a tracking solution is computed, they are displayed with:
106+
- a new **Points** layer, with nodes color-coded by track ID and with symbols matching the state of the node:
107+
- △ dividing node
108+
- ✕ end point node
109+
- ◯ linear node
110+
- a new **Segmentation** (Labels) layer (only if you provided a Labels layer as input), with label values matching node ids, but color-coded by track ID
111+
- a new **Tracks** layer, with tracks color-coded by track ID
112+
- a **Tree View** with nodes and edges color-coded by track ID and with symbols matching the state of nodes.
113+
114+
Optionally, you can activate orthogonal views to display the yz (or yt) and xz (or xt) dimensions.
115+
116+
<div style="display: flex; justify-content: space-around;">
117+
<figure style="margin: 10px; text-align: center;">
118+
<img src="./tracking_result.png" width="1200" />
119+
<figcaption>Viewing a 2D+time or 3D+time tracking result</figcaption>
120+
</figure>
121+
</div>
122+
123+
### Selecting nodes and creating groups.
124+
You can select one or multiple nodes for closer inspection. Selection of nodes is possible in the Points and Labels layers, and in the Tree View. Selecting a node will highlight it and center the object if it is outside the viewing range. Clicking it again deselects the node. You can center the view to any node by pressing `Control` or `CMD` when clicking, without selecting that node. You can select multiple nodes by holding down `SHIFT` when clicking. In the `Groups` tab you can create groups of nodes that you want to store to review later, for example because these are of particular interest, need to be corrected, or belong to a specific object/cell type. You can also find more selection controls here.
125+
126+
<div style="display: flex; justify-content: space-around;">
127+
<figure style="margin: 10px; text-align: center;">
128+
<img src="./groups.png" width="200" />
129+
<figcaption>Creating groups of nodes</figcaption>
130+
</figure>
131+
</div>
132+
133+
### Displaying selected lineages and object features
134+
You can restrict the display to the lineages of selected nodes. To do so, press `Q` in the napari Viewer and/or in the Tree View. To display all nodes in the current group, press `Q` once more. The current viewing mode ('All', 'Lineage', 'Group') is displayed as overlay on the viewer in the right bottom corner. The `Visualization` tab offers additional controls for the opacities for highlighted, foreground (in-group), and background (out-of-group) labels. By setting the contour value (in the Labels controls) to a non-zero value, it is possible to view lineage/group nodes as filled labels, while all other nodes are displayed as contours.
135+
The Tree View behaves independently of the napari layers, but also here you can choose between viewing all lineages or the selected lineages. It is also possible to plot other node features, such as the object size. Press `W` in the Tree View to toggle between the lineage view and the object feature view.
136+
137+
<div style="display: flex; justify-content: space-around;">
138+
<figure style="margin: 10px; text-align: center;">
139+
<img src="./all_vs_lineage.png" width="600" />
140+
<figcaption>View selected lineages</figcaption>
141+
</figure>
142+
<figure style="margin: 10px; text-align: center;">
143+
<img src="./tree_vs_size.png" width="600" />
144+
<figcaption>View object sizes of selected lineages</figcaption>
145+
</figure>
146+
</div>
147+
148+
<div style="background-color: #e6f7ff; border: 2px solid #104982; padding: 15px; border-radius: 10px;">
149+
<h2>Exercise 2 - View and explore Tracking Results</h2>
150+
<p>1. Explore your Tracking Result by clicking on nodes in the Points and/or Segmentation layer and in the Tree View. You can use scroll to zoom in to specific parts of the Tree View or of the napari layers. Use right-mouse click to reset the tree view.</p>
151+
<p>2. Try selecting multiple nodes with <code>SHIFT+CLICK</code> or <code>SHIFT+DRAG</code> (in the Tree View and Points layer, with the 'select points'-tool active) </p>
152+
<p>3. Switch the Tree View display mode to 'Lineage' to isolate viewed lineages. You can do the same for the napari layers by pressing <code>Q</code> when the napari viewer is active (click on the viewer to activate it).</p>
153+
<p>4. Display the object size for the lineages of selected nodes. Note that this is only possible if you have used a Labels layer as input for tracking, because points do not contain size information.</p>
154+
<p>5. Use the arrow buttons or arrow keys to follow nodes up or down the tree, or to jump to neighboring nodes.</p>
155+
<p>6. Create a group in the `Groups` tab and select and add some nodes, tracks, or lineages. Verify that you can restrict the display to the nodes in the group by changing the display mode to 'group' in the `Visualization` tab. </p>
156+
<p>7. While in lineage or group display mode, change the contour value of the Segmentation layer to 1, and change the opacity settings in the `Visualization` tab to your liking.
157+
</div>
158+
159+
## Editing Tracks
160+
161+
Predicted tracks can be corrected by deleting, adding, or modifying nodes and/or edges. You can edit the tracks using the buttons in the `Edit Tracks` widget or their corresponding keyboard shortcuts, or by editing the napari Points and Segmentation layers directly. To undo/redo an action, click `Undo`/`Redo` in the Edit Tracks menu or press `Z`/`R`. Find out more in [`documentation`](https://funkelab.github.io/motile_napari_plugin/editing.html).
162+
163+
<div style="display: flex; justify-content: space-around;">
164+
<figure style="margin: 10px; text-align: center;">
165+
<img src="./editing.png"/>
166+
</figure>
167+
</div>
168+
169+
170+
<div style="background-color: #e6f7ff; border: 2px solid #104982; padding: 15px; border-radius: 10px;">
171+
<h2>Exercise 3 - Editing Tracking Results</h2>
172+
<p>1. Open the <code>Edit Tracks</code> tab.</p>
173+
<p>2. Select one or multiple nodes, and use the <code>Delete</code> button or press <code>D</code> to delete them. What happens if you:</p>
174+
<ul style="padding-left: 60px;">
175+
<li>delete a linear node?</li>
176+
<li>delete a dividing node? </li>
177+
<li>delete an end point node? </li>
178+
<li>delete one of the two children of a dividing node?</li>
179+
You can undo your actions by pressing <code>Z</code> or with the <code>Undo</code> button.
180+
</ul>
181+
<p>3. Go to the Segmentation layer ('_seg') and activate the paint brush. Press <code>M</code> to select a new label. Paint a new node and observe the Tree View. Then move to the next time point and paint with the same color again. Observe that a new track is created as you are painting. </p>
182+
<p>4. Select a new node and display the object size in the Tree View. Then paint or erase (part of) it in the Segmentation layer. Observe how this affects the object size and the centroid location.</p>
183+
<p>5. Select two connected nodes and use the <code>Break</code> button or press <code>B</code> to break the connection. What happens to the two fragments?
184+
<p>6. Select two nodes and try to create an edge between them with the <code>Add</code> button or by pressing <code>A</code>. Can you connect any two nodes? </p>
185+
<p>7. Select two nodes in the same time point, and press <code>S</code> to swap the predecessors of those nodes, assigning them to each other's tracks.</p>
186+
</div>
187+
188+
## Saving and reopening Tracks
189+
You can save your tracking results in the `Tracks List` tab. This will save the parameters, the tracks graph, and the segmentation to a folder. You can load your results back in at the bottom of the `Tracks List` tab by loading a Motile Run and selecting the folder. In addition, motile-tracker allows you to export the result to the `csv` and [`geff`](https://github.com/live-image-tracking-tools/geff) file formats via the export (middle) button in the Tracks List.
190+
191+
<div style="display: flex; justify-content: space-around;">
192+
<figure style="margin: 10px; text-align: center;">
193+
<img src="./save_and_export.png" width="200"/>
194+
</figure>
195+
</div>
196+
197+
198+
<div style="background-color: #e6f7ff; border: 2px solid #104982; padding: 15px; border-radius: 10px; page-break-inside: avoid;">
199+
<h2>Exercise 4 - Save and load Tracking Results</h2>
200+
<p>1. Go to the <code>Tracks List</code> tab.</p>
201+
<p>2. Click the save button and save the tracks to a location on your computer.</p>
202+
<p>3. Click the trash can icon to delete the tracks from the list.
203+
<p>4. At the bottom of the <code>Tracks List</code> tab, choose <code>Motile Run</code> from the dropdown menu to load your saved tracks back into the plugin. </p>
204+
<p>5. Export your tracking results to csv with the export button in the Results list tab (next to the save and trash buttons) </p>
205+
<p>6. (Optional) Save the segmentation image by selecting the segmentation layer, and clicking <code>File</code> > <code>Save Selected Layers</code>.
206+
<p>7. At the bottom of the <code>Tracks List</code> tab, choose <code>External Tracks from CSV</code> from the dropdown menu to load the results back from the csv file. If you have tracks generated with a different (external) method, you must ensure that you have columns for the x, y, (z), id, parent_id, and time attributes and map them to the corresponding column names in the menu. If you have a segmentation image, you must also provide a segmentation id, which corresponds to the label value for each node in the segmentation image.</p>
207+
<p>8. Export your tracking result to geff. Note that the segmentation data is included in the geff, so you do not need to save it separately.</p>
208+
<p>9. Load the geff via <code>External Tracks from geff</code>.
209+
210+
</div>
211+
212+
## Future features to be implemented
213+
In the future, this plugin will be extended with additional features.
214+
- Allowing usage of user-defined Motile tracking parameters.
215+
- Recomputing tracks incorporating the manual edits from the user.
216+
- Fit tracking parameters based on user-provided ground truth tracks.
217+
- Tracking based on a multi-hypothesis segmentation input.
218+
- Support for viewing and editing big tracking results.
219+
220+
## Mouse and Keyboard bindings
221+
222+
### Napari viewer and layer key bindings and mouse functions
223+
224+
| Mouse / Key Binding | Action |
225+
| ------------------- | ------ |
226+
| Click on a point or label | Select this node (center view if necessary) |
227+
| `SHIFT` + click on point or label | Add this node to selection |
228+
| `CTRL`/`CMD` + click on point or label | Center view on node |
229+
| Mouse drag with point layer selection tool active | Select multiple nodes at once |
230+
| `Q` | Toggle between viewing all nodes in the points/labels or only those for the currently selected lineages or groups |
231+
| `T` | Center orthogonal views to mouse cursor location.
232+
233+
### Tree view key and mouse functions
234+
*********************************
235+
| Mouse / Key Binding | Action |
236+
| ------------------- | ------ |
237+
| Click on a point or label | Select this node (center view if necessary) |
238+
| `SHIFT` + click on node | Add this node to selection |
239+
| `CTRL`/`CMD` + click on node | Center view on node |
240+
| Scroll | Zoom in or out
241+
| Scroll + `X` / Right mouse click + drag horizontally | Restrict zoom to the x-axis of the tree view |
242+
| Scroll + `Y` / Right mouse click + drag vertically | Restrict zoom to the y-axis of the tree view |
243+
| Mouse drag | Pan |
244+
| `SHIFT` + Mouse drag | Rectangular selection of nodes |
245+
| Right mouse click | Reset view |
246+
| `Q` | Switch between viewing all lineages (vertically) or the currently selected lineages (horizontally) |
247+
| `W` | Switch between plotting the lineage tree and the object size |
248+
| `F` | Flip plot axes |
249+
| Left arrow | Select the node to the left |
250+
| Right arrow | Select the node to the right |
251+
| Up arrow | Select the parent node (vertical view of all lineages) or the next adjacent lineage (horizontal view of selected lineage) |
252+
| Down arrow | Select the child node (vertical view of all lineages) or the previous adjacent lineage (horizontal view of selected lineage) |
253+
254+
255+
### Key bindings for editing Tracks
256+
*********************************
257+
| Mouse / Key Binding | Action |
258+
| ------------------- | ------ |
259+
| `D` / `Delete` | Delete selected nodes |
260+
| `B` | Break edge between two selected nodes, if existing |
261+
| `A` | Create edge between two selected nodes, if valid |
262+
| `S` | Swap the predecessors of two nodes at the same time point, if possible |
263+
| `Z` | Undo last editing action |
264+
| `R` | Redo last editing action |

‎assets/motile-tracker_tutorial.pdf‎

1.99 MB
Binary file not shown.

0 commit comments

Comments
 (0)