Getting started with Motile Tracker

Installation

Install from PyPI in the environment of your choice (e.g. venv, conda):

pip install motile-tracker

Currently, motile_tracker requires Python >=3.11.

If this is successful, you can then run napari from your command line, and the motile tracker should be visible in the Plugins drop down menu. Clicking the Main Motile Widget should open the menu widget on the right of the viewer, and a lineage tree view in the bottom of the viewer.

Recommended extras

For better performance, you can install optional extras:

numba: Speeds up candidate graph construction significantly.:
```
pip install motile-tracker[numba]
```
gurobi: Uses the Gurobi solver instead of the default open-source solver. Gurobi is much faster but requires a license (free for academics).:
```
pip install motile-tracker[gurobi]
```

You can install multiple extras at once: pip install motile-tracker[numba,gurobi]

Gurobi license version mismatch

If you have a Gurobi license and encounter an error about license version mismatch, you may need to install a specific version of gurobipy that matches your license. Use one of the version-specific extras:

pip install motile-tracker[gurobi12]  # For Gurobi 12.x licenses
pip install motile-tracker[gurobi13]  # For Gurobi 13.x licenses

Tutorial video

This video walks through tracking an example dataset from the Cell Tracking Challenge, covering most of the same information as the rest of this getting started guide.

You can also follow this tutorial.

Input data

Motile Tracker does not perform detection: you must provide a Labels layer or a Points layer containing the objects you want to track. The Labels layer must have time as the first dimension followed by the spatial dimensions (no channels). The Points layer must have the point locations with time as the first number, followed by the spatial dimensions. While source images are nice to qualitatively evaluate results, they are not necessary to run tracking.

There are two example datasets provided in File -> Open Sample -> Motile Tracker. A 2D HeLa dataset from the Cell Tracking Challenge is provided, both in full and a cropped subset for testing features on smaller data, and has both a Labels layer and Points layer. There is also a 3D dataset of images and segmentations of a membrane-labeled developing early mouse embryo (4-26 cells) from Fabrèges et al (2024), automatically downloaded from zenodo.

In the future, we could also support Shapes layers as input (for example, for bounding box tracking) - please react to Issue #48 if this is important to your use case, and give feedback on what type of shape linking you want.

Tracker widgets

Motile Tracker comes with several widgets for tracking, viewing, and editing. You can open all widgets via Plugins -> Motile Tracker -> Open all widgets, or select individual from the same dropdown menu. You can optionally close or hide widgets via the close (x) button, or via right mouse-click on the ‘eye’ button. Optionally, you can float individual widgets and place them somewhere else (for example, you can move the lineage view to a secondary monitor). If you press the / key, you can hide/show all Tracker widgets.

Running tracking

The Tracking tab by default opens to the Run Editor view. In this view, you can pick a name for your run, select an input layer, set hyperparameters, and start a motile run. Hovering over the title of each element in the widget will make a tooltip appear describing the purpose of the element. All hyperparameters are explained in the tracking with motile docs page. When you are ready, click the Run Tracking (SCIP) button to start tracking.

Viewing and editing run results

Clicking the Run Tracking (SCIP) button will automatically take you to the motile Run Viewer menu, display a points and a tracks layer in the napari viewer, and populate the Lineage Tree view. If your input was a segmentation, there will also be a new segmentation layer where the IDs have been relabeled to match across time, and the input segmentation layer will be hidden to avoid confusion.

You can view the results using the synchronized napari layers and tree view, and edit the detections and links to correct any mistakes that you find. You can also re-run the tracking step with different parameters. Re-running the motile tracking will only take into account the detection corrections if you select the new labels/points layer as input: our next major feature to add is incorporating the detection and linking corrections into the optimization task in a more principled manner.

Each Tracking Run will be stored in the Tracks List widget. These are the runs that are stored in memory - if you run tracking multiple times with different inputs or parameters, you can click back and forth between the results here. Here you can also save any runs that you want to store for later, or export the tracks to geff or csv, optionally including the (relabeled) segmentation. If your input was a Labels layer, the node_id will be determined by segmentation label id. If your original segmentation repeated labels across time, the application will relabel them all to be unique, and the new label id will be used as the node id. If your input was a Points layer, the node_id is simply the index of the node in the list of points. Deleting runs you do not want to keep viewing is a good idea, since these are stored in memory. Runs that were saved in previous sessions do not appear here until you load them from disk with the Load Tracks button. The tracking results can also be visualized as a lineage tree. You can open the lineage tree widget via Plugins > Motile Tracker > Widget - Lineage View. For more details, go to the Tree View documentation.