Written and maintained by CASRAI Editorial Board
Published
On this page
trackpy is a Python package for tracking blob-like features in video images, following them through time and analysing their trajectories. It began as a Python implementation of the Crocker–Grier algorithm and works in two dimensions, three dimensions and higher. Positions, trajectories and mean squared displacements all come back as pandas DataFrames, so the results drop straight into the rest of a Python analysis. A lab that films colloids, beads, vesicles or labelled molecules under a microscope typically uses it to turn a stack of frames into a table of particle paths.
What trackpy is used for in research
The official introduction describes three stages: feature finding, sub-pixel position refinement, and linking features in successive frames into trajectories. Everything downstream (drift correction, mean squared displacement, filtering of short tracks) works on the trajectory table those stages produce. The package documents these capabilities:
- Frames are read through PIMS, so many image and video formats can be loaded as a sequence of frames, and long videos can be processed with modest, fixed memory use.
- A prediction framework helps linking when particles move in a correlated flow.
- Uncertainty in the located positions can be estimated with the Savin and Doyle method.
- Numba acceleration is used when Numba is installed, with a pure-Python fallback otherwise.
- Results can be saved to CSV, Excel, SQL or HDF5 through pandas.
The project documents more than 500 tests and states that it has been tested on Windows, macOS and Linux. It tracks features in images; it is not a segmentation tool for irregular cell shapes. For that kind of task see the CellProfiler guide, and for particle-style analysis on molecular-dynamics output rather than video see MDTraj.
Install or access
The installation page recommends conda from the conda-forge channel. Install trackpy and PIMS (the frame reader) with:
conda install -c conda-forge trackpy
conda install -c conda-forge pims
To keep trackpy in its own environment together with notebook support, the documentation gives conda create --name softmatter trackpy nb_conda. To update an existing install use conda update -c conda-forge trackpy. The development version can be installed with pip install https://github.com/soft-matter/trackpy/archive/master.zip. If you do not have conda yet, see Install Anaconda Python; for pinning an environment so collaborators get the same versions, see Sharing a Reproducible Conda Environment.
Required and optional dependencies
trackpy needs Python 3, setuptools, numpy, scipy, matplotlib, pandas, pyyaml and looseversion. PIMS is optional but strongly recommended because it supplies the frame readers. PyTables is needed for HDF5 storage, Numba accelerates the heavy loops, and Pillow (PIL) is listed as another optional dependency.
Step-by-step: from video frames to trajectories
The sequence below uses the function names and arguments from the current API reference. The numeric values (such as the diameter) are placeholders that depend on your images; replace them with values that match your features. The code is a template, not output from a specific dataset.
- Load the frames. Open the image sequence with PIMS. The official walkthrough opens a folder of PNG files with
pims.open('../sample_data/bulk_water/*.png')and wraps the result in a small function decorated with@pims.pipelinethat returns one colour channel (image[:, :, 1]) so the frames are greyscale. Whether your intensities run from 0 to 255 or from 0 to 1 matters for theminmasssetting below. - Test feature finding on one frame. Call
tp.locate(frames[0], 11, minmass=...). The second argument isdiameter, an odd integer that should be at least as large as the feature; when unsure, round up. Inspect the result visually before processing the whole video. - Locate features in every frame.
tp.batch(frames, diameter, ...)runslocateover a set of frames and returns one DataFrame. Extra keyword arguments (such asminmass) are passed tolocate. For long videos, theoutputargument acceptstrackpy.PandasHDFStoreso results are written frame by frame, andmetacan save a YAML file recording how the batch was run. - Link the features into trajectories.
tp.link(f, search_range, memory=...)takes the feature tablef.search_rangeis the maximum distance a feature may move between frames;memoryis the maximum number of frames a feature may vanish and still count as the same particle (default 0). The result is the original table plus aparticlecolumn. - Remove short tracks.
tp.filter_stubs(t, threshold)drops trajectories with too few points; the API documents them as often spurious. The defaultthresholdis 100 frames, so set it deliberately for videos shorter than that. - Correct for drift.
tp.compute_drift(traj, smoothing=0)returns the ensemble drift per frame, andtp.subtract_drift(traj, drift)returns a copy of the trajectories with it removed. - Compute mean squared displacement.
tp.imsd(traj, mpp, fps)gives one MSD curve per particle;tp.emsd(traj, mpp, fps)gives the ensemble MSD. Heremppis microns per pixel andfpsis frames per second.
import pims
import trackpy as tp
@pims.pipeline
def gray(image):
return image[:, :, 1] # as in the official walkthrough
frames = gray(pims.open('my_frames/*.png'))
f = tp.batch(frames, 11, minmass=100) # placeholder values
t = tp.link(f, 5, memory=3) # placeholder values
t1 = tp.filter_stubs(t, 20) # placeholder value
d = tp.compute_drift(t1)
t2 = tp.subtract_drift(t1, d)
em = tp.emsd(t2, 0.16, 24) # mpp, fps: use your calibration
The pixel size you pass as mpp should come from your own calibration; the stage micrometer calibration guide explains how pixel size per objective is obtained.
Key parameters at a glance
These are the settings that most change what trackpy finds and links. Defaults and meanings are quoted from the current API reference for locate and link; the data table below the article lists them together with their units and the function each belongs to.
- diameter: odd integer (or a tuple of odd integers, one per dimension, useful when dimensions have different resolution such as confocal stacks). Round up if unsure.
- minmass: the minimum integrated brightness a feature needs. The documentation suggests at least 100 for integer images and 1 for float images.
- separation: minimum distance between features; default is diameter + 1.
- percentile: default 64. threshold: default 1 for integer images, 1/255 for float images.
- search_range: maximum displacement between frames, in the same units as the position columns.
- memory: frames a feature may disappear for; default 0.
The invert argument of locate is deprecated; the documentation points to doing the inversion in the PIMS pipeline instead.
Output and how to read it
Feature table from locate and batch
Each row is one feature in one frame. Columns are x and y (and z for 3D), mass (total integrated brightness), size (radius of gyration of the Gaussian-like profile), ecc (eccentricity, where 0 is perfectly circular), signal and raw_mass. The locate reference lists all of these; batch documents the core set x, y, mass, size, ecc, signal. In practice, mass, size and ecc are what you inspect when deciding whether a detection is a real particle or a bright speck, and minmass is the main lever for removing the latter.
Trajectory table from link
The linked table keeps every original column and adds particle, an identifier shared by all rows belonging to the same trajectory, alongside the frame column. Grouping by particle gives one path per particle.
MSD tables
imsd returns a DataFrame with one column per particle, indexed by lag time. emsd returns a Series of the ensemble MSD (or a DataFrame with the extra moments when detail=True). Input units are pixels and frames and output units are microns and seconds, and max_lagtime (default 100) sets how many frame intervals the MSD is computed out to. imsd outputs NaN for lag times that could not be measured because of gaps. Because pandas holds these tables, a result can be written with the standard pandas writers; the project lists CSV, Excel, SQL and HDF5. For HDF5 files in general see h5py.
Troubleshooting
- Too many or too few features. Raise
minmassto discard dim detections; lower it if real particles are missing. Checkdiameteragainst the feature size and recall it must be odd and rounded up when in doubt. - Intensity scale surprises. The suggested
minmassdepends on whether images are integer (0 to 255) or float (0 to 1). A value tuned for one scale will misbehave on the other. - Particles swapping or tracks breaking. Reduce
search_rangeto stop distinct particles being joined; increasememoryto bridge frames where a particle briefly disappears. - SubnetOversizeException. Linking can become too expensive when many candidate links form one large subnetwork. If you set
adaptive_stop,linkshrinkssearch_rangeon oversized subnetworks (by the factoradaptive_step, default 0.95) and raisesSubnetOversizeExceptionwhen the stop value is reached. Reducingsearch_rangeup front avoids the problem. - Everything disappears after filter_stubs. The default threshold is 100 frames; a shorter video produces an empty table.
- Slow processing. Install Numba, which trackpy uses when available, and use the
processesargument ofbatch. - Collective motion in the sample. Use
compute_driftandsubtract_driftbefore computing MSD so that stage or flow drift is not read as diffusion.
Free alternatives and neighbouring tools
The table below places trackpy next to other free tools covered on this site. It describes scope only, taken from those guides, not a ranking.
| Tool | What it works on | Where to read more |
|---|---|---|
| trackpy | Blob-like features in video frames, linked into trajectories, in Python | This page |
| CellProfiler | Open-source cell image analysis | CellProfiler guide |
| MDTraj | Python analysis of molecular-dynamics trajectories | MDTraj guide |
| ImageJ / Fiji | Interactive image analysis | Fiji vs ImageJ |
Citing trackpy and reporting your settings
The documentation asks users to cite the specific release they used. Look up the release in your environment with trackpy.__version__ and cite the DOI for that release from the project’s Zenodo record, and also cite Crocker and Grier (1996), the paper the algorithm comes from. Report diameter, minmass, search_range, memory and the filter_stubs threshold alongside the version, because they determine the trajectories. Passing meta to batch saves a YAML record of how a batch was run. These habits are part of computational reproducibility; a software release with a DOI can also be archived as described in the Zenodo repository guide.
FAQ
What does trackpy do?
It finds blob-like features in each frame of a video, refines their positions to sub-pixel precision and links them across frames into trajectories, which it returns as pandas DataFrames.
How do I install trackpy?
The documentation recommends conda install -c conda-forge trackpy, plus conda install -c conda-forge pims for reading frames.
Does trackpy work in 3D?
Yes. The project describes tracking in 2D, 3D and higher dimensions, and diameter can be a tuple with one odd integer per dimension.
What is the difference between imsd and emsd?
imsd returns the mean squared displacement of each particle separately; emsd returns the ensemble MSD over many particles.
How should I cite it?
Cite the specific release via its Zenodo DOI and Crocker and Grier (1996).
Sources
- trackpy documentation, Introduction: soft-matter.github.io/trackpy/dev/introduction.html (read 2026-11-14)
- trackpy documentation, Installation: soft-matter.github.io/trackpy/dev/installation.html (read 2026-11-14)
- trackpy API reference: api.html, with the pages for
locate,batch,link,filter_stubs,compute_drift,subtract_drift,imsdandemsd(read 2026-11-14) - trackpy documentation, Walkthrough: soft-matter.github.io/trackpy/dev/tutorial/walkthrough.html (read 2026-11-14)
- trackpy source repository: github.com/soft-matter/trackpy (read 2026-11-14)
Data: trackpy core parameters: defaults and meaning by function
Parameter defaults and meanings for trackpy locate, link, filter_stubs and the MSD functions, compiled from the official API reference pages for each function.
| Parameter | Function | Type or unit | Default and meaning |
|---|---|---|---|
| diameter | locate / batch | odd integer or tuple of odd integers | Required; round up when unsure |
| minmass | locate | integer | Minimum integrated brightness; suggested >=100 for integer images, 1 for float images |
| separation | locate | pixels | Default is diameter + 1 |
| percentile | locate | percentile | Default 64 |
| threshold | locate | intensity | Default 1 for integer images, 1/255 for float images |
| search_range | link | position units | Maximum distance a feature moves between frames |
| memory | link | frames | Frames a feature may vanish and remain the same particle; default 0 |
| adaptive_step | link | factor | Default 0.95; search_range shrink factor when adaptive_stop is set |
| threshold (filter_stubs) | filter_stubs | frames | Minimum points for a trajectory to survive; default 100 |
| max_lagtime | imsd / emsd | frame intervals | MSD computed out to this lag; default 100 |
Sources
- trackpy.locate API reference (accessed 2026-11-14)
- trackpy.link API reference (accessed 2026-11-14)
- trackpy.filtering.filter_stubs API reference (accessed 2026-11-14)
- trackpy.motion.emsd API reference (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







