Cell tracking in Fiji using Mastodon

Author

Bruno C. Vellutini

Published

January 5, 2026

Summary

This is a basic tutorial on how to track cells in Fiji (Schindelin et al. 2012) using Mastodon (Girstmair et al. 2025). The goals are to learn how to load and create Mastodon datasets, get familiar with navigating the BigDataViewer and TrackScheme windows, perform manual cell tracking with cell divisions and simple editing of lineages, perform semi-automated detection and tracking, and try some lineage analysis. We will use a demo Mastodon dataset (Girstmair 2024) generated with lightsheet data from the isopod Parhyale hawaiensis (Wolff et al. 2018). For more information and detailed instructions, please check Mastodon’s official documentation.

Requirements

Setup

Download Dataset

  • Download Mastodon_Auto-Tracking_Demo_Ph-limb-dev.zip dataset from this Zenodo repository (Girstmair 2024). The direct link to the file is here (4.3GB).
  • Move the ZIP file to a working directory.
  • Unzip Mastodon_Auto-Tracking_Demo_Ph-limb-dev.zip.

Working directory after downloading and unzipping the dataset file.

Working directory after downloading and unzipping the dataset file.

Contents of the dataset directory.

Contents of the dataset directory.

After unzipping, the contents will occupy 23GB of disk space.

Download Fiji

  • Go to https://fiji.sc, choose Distribution: Stable, and click the download button.
  • Copy the downloaded archive to the working directory and unzip it.
  • Open the Fiji.app directory and double-click on the launcher.
  • The main window of Fiji will open.

Install Mastodon

  • Click on Help > Update....

  • The updater will open and say Fiji is up-to-date.
  • Click Manage Update Sites.

  • A window will open with a list of plugins available to install in Fiji.

  • Search for “mastodon”.

  • Several Mastodon-related plugins will appear.
  • Click on the checkbox for Mastodon.

  • Click Apply and Close and then Apply Changes.

  • Wait… until the downloads are finished. Then, click OK.

  • Restart Fiji (close window and double-click the launcher).

Open Mastodon Project

  • In Fiji click on Plugins > Tracking > Mastodon > Mastodon Launcher.

The Mastodon Launcher window will open.

  • Click on open Mastodon project (top left) and Open another project (bottom right).

  • Navigate to the directory Mastodon_Auto-Tracking_Demo_Ph-limb-dev/.
  • Select the file Parhyale_LimbDev_30tps.mastodon.

Several new windows will open (Console, Mastodon, BigDataViewer, TrackScheme, Data table).

Inspect the Dataset

Let’s focus on the Mastodon window.

  • Close Console, BigDataViewer, TrackScheme, and Data table windows.

This is the main project menu from where we can open windows, set options, process data and save the project. The most important buttons for this tutorial are bdv (BigDataViewer) and trackscheme.

  • Click on bdv and make the window larger.

  • Drag the timepoint slider at the bottom to see cells moving and dividing.
  • Using our acquired BigDataViewer skills, focus on the surface of the embryo.
  • If you get lost, press Shift+Z to re-orient the embryo.
  • Find a cell that divides before timepoint 15 and looks trackable and zoom on it using Ctrl+Shift+Scroll.
  • Then center the view on it by holding the right button and dragging the mouse.
  • Use Shift+Scroll to navigate through Z and M/N to go through time.

We are ready to track.

Manual Tracking

  • On the Mastodon project window, click on the trackscheme button.

The TrackScheme window will appear.

  • Resize the BigDataViewer window to be side-by-side with the TrackScheme.
  • Click on the BigDataViewer window, set the timepoint to some frames before mitosis, Shift+Scroll to find the center of the nucleus, put the mouse pointer there and press A.

A round magenta circle will appear over the nucleus and in the TrackScheme.

  • With the mouse over the circle, use Shift+Q and Shift+E to adjust the size of the spot to roughly the nucleus diameter.

  • Zoom in on the new spot in the TrackScheme, hover and click on it and watch what happens in the BigDataViewer window.

  • Go back to the BigDataViewer, hover the pointer over the circle and hold the spacebar to adjust the position of the circle and the nucleus.

Now let’s add a second spot.

  • Hover the mouse inside the circle and hold A. This will advance to the next frame showing the first spot in white dashed line and the second spot in white solid line with a white solid link between the two.

  • Still holding A, position the second spot, then release A to create the new linked spot.

Check how the second spot and a link were created in the TrackScheme automatically.

  • Continue to track the nucleus for a few more frames, until the frame immediately before division.

Note that when clicking on a spot in the BigDataViewer window, the corresponding spot is highlighted in the TrackScheme window.

  • Now click on the spots in the TrackScheme and see what happens to the BigDataViewer (nothing will happen).

Let’s change that and link the BigDataViewer and TrackScheme windows. In the menu bar of BigDataViewer and TrackScheme windows there are lock symbols 1, 2, 3.

  • Click on Lock 1 in both windows.

  • Now click through spots in the TrackScheme.

The view in the BigDataViewer will change to show the selected spot at the center.

Before we continue tracking the cell division, let’s check one of the amazing Mastodon features.

  • Click on the BigDataViewer button in the Mastodon project window and another BigDataViewer window will open.

  • Now activate Lock 1 and click on one of the TrackScheme spots.

Both windows will be synchronized!

Why is this useful for manual tracking?

  • Adjust the view to center the spot in the second BigDataViewer window, press Shift+Y, and select a spot from the TrackScheme.

We can have both XY and ZY views of the same nucleus! This is great for tracking in 3D. We can check, for instance, that our spot is well centered in Z and adjust it in this window.

Continue tracking one of the daughter cells.

  • Select the last spot in the TrackScheme, go to the XY BigDataViewer, hover the mouse over the circle and hold A, move the spot, and release A to add it.
  • Do it for a few frames.
  • Then go back to the pre-division spot and add a linked spot corresponding to the other daughter cell.

This will create the first branch of the lineage tree.

  • Continue tracking the second daughter cell for a few frames.

  • Zoom out the TrackScheme view to see the full branched tree.

Semi-Automated Tracking

This mode will try to guess where the next nucleus is and automatically create the spots and links.

  • To start, choose a different nucleus to track and press A to add a new spot.

  • Now, hovering the pointer above the spot press Ctrl+T.

A lineage will appear in the TrackScheme.

Check how accurate it is by clicking on the spots and watching their position relative to the nucleus in the BigDataViewer windows. Try going further with the semi-automated tracking.

  • Hover a spot and press Ctrl+T to continue the semi-automated tracking.

See how long you can go, how it behaves with cell divisions, and which cells work well with it and which don’t. There are many parameters that can be adjusted to tweak the semi-automated tracking behavior. Please check Mastodon’s documentation for more details.

Automated Tracking

The final part of this tutorial is to try automatic detection and linking of spots. This is the dream: loading data and getting out a full lineage. However, in practice, it’s a lot messier. Cleaning, fixing, and curating the data is required to get a nice informative lineage. We will use a simplified version of the protocol included in this demo dataset. It is described in the file Protocol_Auto-Detection_Auto-Linking.docx.

Detection

  • In the Mastodon window, go to Plugins > Tracking > Detection....

  • Press Next twice (leave options as is).

  • Choose Advanced DoG detector and press Next.
  • Keep Detect: bright blobs.
  • Change Estimated diameter to 35px.
  • Change Quality threshold to 100.
  • Keep Behavior as Add.
  • Then, press Next.

  • Click Preview and see how well the detection will work by exploring a new BigDataViewer window.

Are there too many false positives? Try changing the diameter, for example, and run the preview again to see what happens to the detected spots.

  • Once satisfied, press Next and wait.

  • When the detection is done, press Finish.

The BigDataViewer windows and the TrackScheme will be showing a lot of new spots.

  • Explore the spots in the BigDataViewer and TrackScheme windows.
  • Zoom in to see the unlinked, individual spots per frame.

Cleaning

Before we try to automatically link these spots, let’s remove low quality detections.

  • On the Mastodon window click on Table, resize it to have more space, and resize the column Detection q... to show Detection quality.

  • Click on Detection quality to sort the table.

  • Click on the first row to select it. Select all rows where Detection quality is <400.
  • Then click Edit > Delete Selection.

  • Close the table.

We can also manually delete obviously wrong spots by hovering and pressing D.

  • Give it a try by cleaning up the spots outside the embryo.

Linking

Now let’s try linking spots.

  • In the main Mastodon window click on Plugins > Tracking > Linking....
  • Keep All spots selected for all timepoints (0-29) and press Next.
  • Choose Lap linker and click Next.

  • Change the parameters to:
    • Frame to frame linking: Max distance to 40px.
    • Gap closing: Max distance to 60px (keep others as is).
    • Track division: Check Allow track division, set Max distance to 40px, and press + to add a Feature penalty and set it to Center ch1 to 0.3.
  • Press Next to start linking and wait… then press Finish.

Note that there are now tracks in the BigDataViewer and TrackScheme windows.

  • Explore them a bit.

Mastodon can calculate features (position, displacement, velocity, etc.) of individual spots, links and branches. Let’s do that.

  • In the main Mastodon window press compute features.

A Feature calculation window will open.

  • Press compute and wait… when it’s done, close it.

Note that now the tracks in the BigDataViewer are showing colored links.

  • Open the table window from the main window.

It’ll be filled with computed features.

Basic Feature Visualization

Finally, let’s visualize the computed features that might be interesting or useful.

  • In the BigDataViewer window press File > Preferences to open the feature color coding visualization parameters.

  • On Settings > Feature Color Modes click on Duplicate (it’ll generate a Number of links (2)) and then Rename.
  • Rename it to Velocity.

  • On the Coloring Spots change Read spot color from to Incoming link and change Feature to Link velocity. Then click on autoscale in the range.
  • On the Coloring Links change Read link color from to Link and change Feature to Link velocity. Then also click on autoscale.
  • Click Apply (nothing will happen), then OK.

  • On the BigDataViewer window press View > Coloring > Velocity.

The spots and links in the BigDataViewer window will change colors.

  • Do the same for the other BigDataViewer window and the TrackScheme.

This gives a visual representation of cells which have a high displacement per frame. These might be artifacts in linking unrelated spots or, in a good processed lineage, reveal some biological process like cell migration.

Graph Plotting

To finalize, a simple example of plotting the lineage data.

  • Click on grapher in the main Mastodon window, a plot window will open.

  • Press the Lock 1 to lock the windows, select Link velocity - outgoing for X axis and Detection quality for Y axis and press Plot.

  • Find out if the spots with the highest link velocity are properly linked or if it is an artifact.

Citation

Vellutini, B. C. (2026). Cell tracking in Fiji using Mastodon. Zenodo. https://doi.org/10.5281/zenodo.18090897

License

This tutorial is available under a Creative Commons Attribution 4.0 International License.

References

Girstmair, Johannes. 2024. Mastodon Auto-Tracking Demo on Parhyale Hawaiensis Limb Development. Zenodo. https://doi.org/10.5281/ZENODO.13944688.
Girstmair, Johannes, Tobias Pietzsch, Vladimir Ulman, Stefan Hahmann, Matthias Arzt, Mette Handberg-Thorsager, Ko Sugawara, et al. 2025. “Mastodon: The Command Center for Large-Scale Lineage-Tracing Microscopy Datasets.” bioRxiv, December, 2025.12.10.693416. https://doi.org/10.64898/2025.12.10.693416.
Schindelin, Johannes, Ignacio Arganda-Carreras, Erwin Frise, Verena Kaynig, Mark Longair, Tobias Pietzsch, Stephan Preibisch, et al. 2012. “Fiji: An Open-Source Platform for Biological-Image Analysis.” Nat. Methods 9 (June): 676–82. https://doi.org/10.1038/nmeth.2019.
Wolff, Carsten, Jean-Yves Tinevez, Tobias Pietzsch, Evangelia Stamataki, Benjamin Harich, Léo Guignard, Stephan Preibisch, et al. 2018. “Multi-View Light-Sheet Imaging and Tracking with the MaMuT Software Reveals the Cell Lineage of a Direct Developing Arthropod Limb.” Elife 7 (March). https://doi.org/10.7554/eLife.34410.