Tracx- a toolbox for tracking non-motile 2D cell cultures¶
Tracx is a MATLAB generic toolbox for cell tracking from various microscopy image modalities such as Bright-field (BF), phase contrast (PhC) or fluorescence (FL) with an automated track quality assessment in absence of a ground truth. It allows to track cells of any shape independent of the cell type. Its modular design allows to use a labeled segmentation mask from any segmentation algorithm along with the raw images! It offers a variety of control and plotting options as well as the generation of animated movies. Additionally there are methods to reconstruct the genealogy for asymmetrical and symmetrically dividing cells.
Tracx allows users to define their own project specifications in xml format, making the toolbox suitable for automating the batch processing of large experiments with thousands of cells and images.
Why using Tracx?¶
The only tool giving you an estimate how good tracking was without the need of a manually curated ground truth.
Can be used independently from a segmentation software. Segmentation algorithms are often tuned for a specific image modality and cell type, therefore keeping segmentation and tracking seperate allows for more flexibility.
Frame by frame tracking allows for live interaction with running experiments (feed back microscopy)
Installation¶
If you run Tracx from source you need to have a fully licensed version of MATLAB (for GUI >R2020a) including the following toolboxes:
Image Processing Toolbox
Signal Processing Toolbox
Statistics and Machine Learning Toolbox
Parallel Computing Toolbox
Fuzzy Logic Toolbox (optional)
Mapping Toolbox (optional)
Installation with git:
Clone this repo including the submodules and add it to your MATLAB path.
$ git clone --recurse-submodules https://gitlab.com/csb.ethz/tracx.git
Then navigate to the folder you cloned the repo and then past the following code to your MATLAB terminal. This will add Tracx to the MATLAB path and makes its functionalities available to you.
addpath(genpath('tracx'));
Manual download of the repository:
Download this repo, unzip it and add it to your MATLAB path. Replace `C:PATHTO` with the actual path on your filesystem where you downloaded Tracx to and run the following code in your MATLAB terminal. This will add Tracx to the MATLAB path and makes its functionalities available to you.
addpath(genpath('C:\PATH\TO\tracxdevel-master\tracxdevel-master'));
Note
An error might occur depending on your platform and MATLAB version used in combination with your internet proxy / certificates. “Error using urlreadwrite (line 98) Error downloading URL. Your network connection may be down or your proxy settings improperly configured.” A potential fix is described here: https://ch.mathworks.com/matlabcentral/answers/92506-how-can-i-configure-matlab-to-allow-access-to-self-signed-https-servers
Usage¶
Start by first generating a new Tracx instance. See Extended usage for more details.
Tracker = TracX.Tracker();
Note
You can assign it to any other variable name of your liking instead of calling it Tracker. We will call it Tracker for simplicity throughout the documentation and demo scripts.
Optionally you can also start the GUI (graphical user interface). See GUI for details.
TracX.GUI.TracXGUI();
Note
The Tracx GUI requires MATLAB R2020a or newer.
Running Tracx for the first time will automatically check and install missing dependencies.
INITIALIZE: Welcome to TracX!
CHECK: Image Processing Toolbox, Signal Processing Toolbox, Parallel Computing Toolbox
DONE: Checking required Matlab Toolbox
CHECK: Full installation of external dependencies.
INFO: Download started
INFO: Download successfull https://gitlab.com/csb.ethz/cellxmaskinterface/-/archive/CellXMaskInterfaceTracX/cellxmaskinterface-CellXMaskInterfaceTracX.zip
INFO: Download started
INFO: Download successfull https://gitlab.com/csb.ethz/MatlabProgressBar/-/archive/MatlabProgressBarTracX/MatlabProgressBar-MatlabProgressBarTracX.zip
INFO: Download started
INFO: Download successfull https://github.com/siyideng/texttoimage/archive/refs/heads/master.zip
INFO: Download started
INFO: Download successfull https://gitlab.com/csb.ethz/matlab-tree/-/archive/tracx-tree/matlab-tree-tracx-tree.zip
DONE: All dependencies successfully installed.
INFO: INFO: TracX version 1.0.0 is ready.
Create a new Tracx project¶
Before creating a new Tracx project you need:
A set of brightfield or phase contrast or fluorescence microscopy images in the form of TIF files, one file per timepoint, position, channel, etc. These raw images (ideally 16 bit) will be used for the Tracx fingerprints.
A corresponding set of segmentation masks (segmented cells or nuclei). The segmentation masks need to be generated by third-party software (e.g. CellX or Cellpose or similar), as Tracx does not include a segmentation functionality. Labeled masks are preferred over binary masks. These files should also be provided as TIF files and have the same image dimensions as the raw images.
Optional: Any number of additional fluorescence channels that will then be quantified by the algorithm, provided in the same file format and image dimensions.
File names:
Ideally, the file names take the format ChannelName_positionXXYYZZZ_timeTTTT.tif, e.g. Brightfield_position0101000_time0001.tif. Position refers to the x and y component of the well position and to the z-plane; it can be set to 0101000 as a default, if this does not apply to your experiment. The GUI contains a name parser interface that can be used to transform your original file names to the Tracx format using MATLAB® regular expressions, if they do not yet conform to this format (see extended guide below).
Specific requirements for 3D-data (3D + time):
The file format should be in the form of one z-stack per timepoint and channel, as a multi-page TIF file containing the z-planes. If all z-planes are provided as separate files, or all planes and timepoints are provided as one single frame, these can be transformed in the GUI. However, the channels need to be separate.
If the above requirements are fulfilled you can create a new Tracx project as follows:
% [String] Name of the project / experiment.
projectName = 'myProject';
% [String] File name identifier of raw images used
% to calculate the fingerprint (i.e. Brightfield).
fileIdentifierFingerprintImages = 'BF';
% [String] Well position identifier if multi well
% experiment was performed to use.
fileIdentifierWellPositionFingerprint = [];
% [String] File identifier of fluorescent images to be used
% for asymmetrical lineage reconstruction.
fileIdentifierCellLineage = 'mKate';
% [Array, x, y, w, h] Image crop coordinates, in case only part
% of an image was segmented (CellX segmentation only).
imageCropCoordinateArray = [480 445 383 323];
% [Int] Max number of frames to track.
movieLength = 30;
% [String] Image directory to be used for the current project.
imageDir = 'C:\\myProject\\rawImages'
% [String] Directory containing the segmentation results for the current project.
segmentationResultDir = 'C:\\myProject\\CellXResults'
% [String] Cell division type. Either asymmetrical or symmetrical.
cellDivisionType = 'asym';
Tracker.createNewTrackingProject(...
projectName, imageDir, segmentationResultDir, ...
fileIdentifierFingerprintImages, ...
fileIdentifierWellPositionFingerprint, ...
fileIdentifierCellLineage, ...
imageCropCoordinateArray, movieLength, cellDivisionType);
Start tracking¶
Tracker.runTracker()
Post tracking¶
% Save tracking result control images
Tracker.saveTrackerProjectControlImages()
% Save current state of the tracker instance
Tracker.saveCurrentTrackerState()
% Export the project configuration
Tracker.saveTrackingProject()
% Save tracking results as csv table
Tracker.saveTrackerResultsAsTable()
Command-line interface¶
Tracx provides a command-line interface (CLI) that makes it possible to run tracking experiments without an interactive MATLAB session or the graphical user interface. The CLI is designed for batch processing, HPC cluster workflows, and pipeline integration where a single project XML file and a workflow file fully describe the run. It can be used directly from the MATLAB source or as a compiled standalone executable that requires only the free MATLAB Runtime and no MATLAB licence.
A minimal example that loads an existing project and runs the yeast tracking pipeline from the MATLAB command window:
tracx_main('MyExperiment_Project.xml', '--workflow', 'yeast', '--verbose');
The same command using the compiled executable on Linux:
./run_tracx.sh MyExperiment_Project.xml --workflow yeast --verbose
And on Windows:
run_tracx.bat MyExperiment_Project.xml --workflow yeast --verbose
For a full description of all options, workflow steps, project creation, generic segmentation mask support, inline method calls, and batch processing see Command-Line Interface.
Deployment¶
Tracx can be deployed as a standalone application for users who do not have a MATLAB licence. Deployment requires the MATLAB Compiler toolbox and produces a self-contained binary that depends only on the free MATLAB Runtime (MCR). Two deployment targets are supported: the graphical user interface and the command-line runner.
Deploying the command-line runner
Set the TRACX_ROOT environment variable to the root of your tracxdevel
checkout, then run the deployment script from the deploy/ folder inside
your MATLAB session.
setenv('TRACX_ROOT', 'C:\path\to\tracxdevel'); % Windows example
cd path/to/tracxdevel/deploy
deploy_tracx('windows'); % or 'linux'
The compiled binary and wrapper scripts are written to dist/windows/ or
dist/linux/. A GitHub Actions CI pipeline
(deploy/.github/workflows/deploy_tracx_ci.yml) is provided that builds
both platform binaries in parallel on tagged releases without requiring
manual compilation on each operating system.
Deploying the GUI
The Tracx GUI is deployed using the MATLAB Compiler deploytool or mcc from
the project files located in src/+TracX/+GUI/. The procedure mirrors the
CLI deployment: compile the GUI entry point with mcc, distribute the resulting
binary together with the MCR installer to end users.
End users install the MCR (free download, no MATLAB licence required) from:
The MCR version must match the MATLAB release used during compilation.
Read the Command-Line Interface and GUI section in the documentation for furhter information on the usage.
Further help / troubleshooting¶
For further help, such as how to convert your data into the proper format or how to define the Tracx parameters, please read the respective sections in Extended usage or GUI.
The API reference of the Tracx classes and methods can also provide further help in respect to which input and which output is expected as well as a short description about a function’s purpose.
License¶
Tracx is licensed under BSD-3 clause. Copyright © 2017-2026 ETH Zurich, Andreas P. Cuny, Tomas Kuendig, Aaron Ponti, Joerg Stelling; D-BSSE; CSB Group. For details License.
Contributing¶
The authors as well as the 3rd parties libraries we appreciate and use of Tracx are listed under Contributors .
If you like to contribute yourselves please read the section How to contribute.