Skip to main content
v2026.11,986 entries · CC-BY 4.0

trackpy: Python Particle Tracking for Microscopy Video

How trackpy finds particles in video frames and links them into trajectories: install, core commands, parameter defaults, MSD output and citation.

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.

  1. 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.pipeline that 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 the minmass setting below.
  2. Test feature finding on one frame. Call tp.locate(frames[0], 11, minmass=...). The second argument is diameter, 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.
  3. Locate features in every frame. tp.batch(frames, diameter, ...) runs locate over a set of frames and returns one DataFrame. Extra keyword arguments (such as minmass) are passed to locate. For long videos, the output argument accepts trackpy.PandasHDFStore so results are written frame by frame, and meta can save a YAML file recording how the batch was run.
  4. Link the features into trajectories. tp.link(f, search_range, memory=...) takes the feature table f. search_range is the maximum distance a feature may move between frames; memory is 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 a particle column.
  5. Remove short tracks. tp.filter_stubs(t, threshold) drops trajectories with too few points; the API documents them as often spurious. The default threshold is 100 frames, so set it deliberately for videos shorter than that.
  6. Correct for drift. tp.compute_drift(traj, smoothing=0) returns the ensemble drift per frame, and tp.subtract_drift(traj, drift) returns a copy of the trajectories with it removed.
  7. Compute mean squared displacement. tp.imsd(traj, mpp, fps) gives one MSD curve per particle; tp.emsd(traj, mpp, fps) gives the ensemble MSD. Here mpp is microns per pixel and fps is 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.

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 minmass to discard dim detections; lower it if real particles are missing. Check diameter against the feature size and recall it must be odd and rounded up when in doubt.
  • Intensity scale surprises. The suggested minmass depends 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_range to stop distinct particles being joined; increase memory to 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, link shrinks search_range on oversized subnetworks (by the factor adaptive_step, default 0.95) and raises SubnetOversizeException when the stop value is reached. Reducing search_range up 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 processes argument of batch.
  • Collective motion in the sample. Use compute_drift and subtract_drift before 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

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.

trackpy core parameters: defaults and meaning by function
ParameterFunctionType or unitDefault and meaning
diameterlocate / batchodd integer or tuple of odd integersRequired; round up when unsure
minmasslocateintegerMinimum integrated brightness; suggested >=100 for integer images, 1 for float images
separationlocatepixelsDefault is diameter + 1
percentilelocatepercentileDefault 64
thresholdlocateintensityDefault 1 for integer images, 1/255 for float images
search_rangelinkposition unitsMaximum distance a feature moves between frames
memorylinkframesFrames a feature may vanish and remain the same particle; default 0
adaptive_steplinkfactorDefault 0.95; search_range shrink factor when adaptive_stop is set
threshold (filter_stubs)filter_stubsframesMinimum points for a trajectory to survive; default 100
max_lagtimeimsd / emsdframe intervalsMSD computed out to this lag; default 100

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about trackpy: Python Particle Tracking for Microscopy Video

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →