Trackpy is a package for finding blob-like features in video, tracking them through time, and analyzing their trajectories. It implements and extends the widely-used Crocker–Grier algorithm in Python.
There are many similar projects. (See table below.) Our implementation is distinguished by succinct and flexible usage, a thorough testing framework ensuring code stability and accuracy, scalability, and thorough documentation.
Several researchers have merged their independent efforts into this code. We would like to see others in the community adopt it and potentially contribute code to it.
- The widely-used particle tracking algorithm originally implemented by John Crocker and Eric Weeks in IDL is reimplemented in Python. Wherever possible, existing tools from widely-used Python modules are employed.
- This reimplemention is full-featured, including subpixel precision verified with test cases.
- The module is actively used and tested on Windows, Mac OSX, and Linux, and it uses only free, open-source software.
- Frames of video can be loaded from a video file (AVI, MOV, etc.), a multi-frame TIFF, or a directory of sequential images (TIFF, PNG, JPG, etc.).
- Results are given as DataFrames, high-performance spreadsheet-like objects from Python pandas which can easily be saved to a CSV file, Excel spreadsheet, SQL database, HDF5 file, and more.
- Particle trajectories can be characterized, grouped, and plotted using a suite of convenient functions.
- To verify correctness and stability, a suite of 150+ tests reproduces basic results.
- Both feature-finding and trajectory-linking can be performed on arbitrarily long videos using a fixed, modest amount of memory. (Results can be read and saved to disk throughout.)
- A prediction framework helps track particles in fluid flows, or other scenarios where velocity is correlated between time steps.
- Feature-finding and trajectory-linking works on images with any number of dimensions, making possible some creative applications.
- Uncertainty is estimated following a method described in this paper by Savin and Doyle.
- High-performance components (numba acceleration and FFTW support) are used only if if available. Since these can be tricky to install on some machines, the code will automatically fall back on slower pure Python implementations
- Adaptive search can prevent the tracking algorithm from failing or becoming too slow, by automatically making adjustments when needed.
Trackpy can be cited using a DOI provided through Zenodo. To direct your readers to the specific version of trackpy that they can use to reproduce your results, cite the release of trackpy that you used for your work. The record pages linked below contain author lists, other details, and complete citations in various formats. If your citation style allows for a URL, please include a link to the github repository: github.com/soft-matter/trackpy.
| Release (version) | Zenodo Record Pages with info and citations | DOI |
|---|---|---|
| v0.2.4 | Record Page | 10.5281/zenodo.12255 |
| v0.2.3 | Record Page | 10.5281/zenodo.11956 |
| v0.2.2 | Record Page | 10.5281/zenodo.11132 |
| v0.2 | Record Page | 10.5281/zenodo.9971 |
- Daniel Allan feature-finding, uncertainty estimation, motion characterization and discrimination, plotting tools, tests
- Nathan Keim alternative trajectory-linking implementations, major speed-ups, prediction, adaptive search
- Thomas Caswell multiple implementations of sophisticated trajectory-linking, tests
- Casper van der Wel anisotropic (3D) feature-finding, 3D plotting and analyses
This package was developed in part by Daniel Allan, as part of his PhD thesis work on microrheology in Robert L. Leheny’s group at Johns Hopkins University in Baltimore, MD. The work was supported by the National Science Foundation under grant number CBET-1033985. Dan can be reached at dallan@pha.jhu.edu.
This package was developed in part by Thomas A Caswell as part of his PhD thesis work in Sidney R Nagel’s and Margaret L Gardel’s groups at the University of Chicago, Chicago IL. This work was supported in part by NSF Grant DMR-1105145 and NSF-MRSEC DMR-0820054. Tom can be reached at tcaswell@gmail.com.
This package was developed in part by Nathan C. Keim, as part of his postdoctoral research in Paulo Arratia’s group at the University of Pennsylvania, Philadelphia. This work was supported by NSF-MRSEC DMR-1120901.
This package was developed in part by Casper van der Wel, as part of his PhD thesis work in Daniela Kraft’s group at the Huygens-Kamerlingh-Onnes laboratory, Institute of Physics, Leiden University, The Netherlands. This work was supported by the Netherlands Organisation for Scientific Research (NWO/OCW).