zephir 1.0.6

Multiple object tracking algorithm via image registration

ZephIR is a multiple object tracking algorithm based on image registration and built on PyTorch. Check out the publication and tutorial video!

Latest Updates in v1.0.6

• bug fixes for deprecated dependencies
• see release notes for full list of changes

About

ZephIR tracks keypoints in a 2D or 3D movie by registering image descriptors sampled around each keypoint. Image registration loss is combined with three additional regularization terms:

• spring connections between neighboring objects allow a flexible spatial model of loosely correlated motion
• feature detection optimizes results towards centers of detected features
• temporal smoothing of pixel intensity a small patch of frames limit fluctuations in activity

Overview of tracking loss:

ZephIR is fast, efficient, and designed to run on laptops instead of powerful desktop workstations. It requires no prior training of any model weights, and it is capable of generalizing to a wide diversity of datasets with small tweaks to parameters. This makes ZephIR ideal for analyzing datasets that lack a large corpus of training data, and for tracking fluorescent sources in moving and deforming tissue, both of which create a particularly challenging environment for modern deep learning techniques. ZephIR can also serve as a data augmentation tool in some cases. We provide some support for exporting ZephIR results to DeepLabCut.

Installation

Quick start

pip install zephir

Dependencies

Make sure that Python (>=3.11) and the following packages are installed (prefer uv over pip):

• dataclasses (>=0.8)
• docopt-ng (>=0.9.0)
• flask (>=3.1.2)
• gevent (>=25.9.0)
• h5py (>=3.15.1)
• matplotlib (>=3.10.7)
• numpy (>=2.0)
• opencv-python (>=4.6.0)
• pandas (>=2.3.3)
• scikit-image (>=0.19.2)
• scikit-learn (>=1.7.2)
• scipy (>=1.16.0)
• setuptools (>=80.9.0)
• torch (>=2.9.0) (see PyTorch.org for instructions on installing with CUDA)
• tqdm (>=4.64.0)

NOTE: To enable GPU acceleration, you need to compile PyTorch with CUDA by following the instructions on PyTorch.org. Using the quick installation command will not install CUDA-enabled PyTorch automatically. This installation may also produce an OMP: Error #15. If you run into this issue, check your numpy and numpy-base versions and if they disagree, update one or the other to match.

NOTE: If you run into an issue when launching the annotator, you may need to downgrade Flask (2.1.2) and Pandas (1.4.2).

Build from source

1. Clone git repository:

git clone https://github.com/venkatachalamlab/ZephIR.git

2. Navigate to the cloned directory on your local machine.

3. Checkout the current release:

git checkout v1.0.6

Use the following command to see what's new in the most recent release:

git show v1.0.6

4. Install:

python3 -m pip install .

or install in development mode:

python3 -m pip install -e .

Getting Started

Run from command line:

zephir --dataset=. [options]

We provide a detailed guide for running ZephIR as well as some example workflows for using ZephIR here.

Parameters

For a list of all CLI options and user-tunable parameters, see here.

To help figure out what options may be right for you, check out the list of examples with explanations for the chosen parameters here.

Interfacing with Annotator

ZephIR includes an annotator GUI with custom Python macros for interacting with the data from the GUI.

Run from command line:

annotator --dataset=. [--port=5005]

Learn more about the annotator and its features here.

We also provide a more detailed user guide for using the GUI as a part of a ZephIR workflow here.