How to annotate tracked particles in videos using Pimsviewer

In this brief tutorial, I’ll show you how to plot the positions of your tracked particles on top of your experimental movies using Pimsviewer, a Python image viewer that uses PIMS as it’s backend and can open various (scientific) image formats.

First, install Pimsviewer either via Conda forge:

conda install -c conda-forge pimsviewer

Or alternatively, via pip:

pip install pimsviewer

Pimsviewer should work with all the formats that can be handled by PIMS, this includes TIFF images or stacks and Nikon ND2 microscopy files. Start the viewer by running the following command:


You should be presented with a GUI similar to the images below. Open your video file via the ‘File’ menu.

The annotation is available as a plugin via ‘Plugins -> Annotate plugin’. Also included is a dummy processing plugin (it simply adds noise to the images). It serves as an example of how to write your own plugins to extend the functionality of Pimsviewer. For more details on how to write your own plugins, see the README on Github.

Trajectories can then be loaded from a CSV file, which contains a column with the frame number, the x and y coordinates and optionally the radius (for example, as generated with TrackPy). As of now, the plugin only draws circles, but it could be easily extended to draw other particle shapes. By setting a custom scaling factor, you can convert the units of the x, y, r columns to pixels.

Now a circle is drawn on each frame of your video, corresponding to the data in the CSV file. You can then play the video to ensure your particles are properly tracked.

I hope you’ll find Pimsviewer useful, any bug reports or pull request are very welcome via our Github page. Please leave a comment to let me know how you use Pimsviewer and how it could be improved.