PIMS: Python Image Sequence

PIMS is a lazy-loading interface to sequential data with numpy-like slicing.

Key features:

  • One consistent interface to many file formats
  • Numpy-like slicing returns lazy-loading, iterable, sliceable objects

Example

Everything is demonstrated in this IPython notebook.

Load a sequence of images from a directory, where the images are named img-0.png, img-1.png, etc.

In [1]: from pims import ImageSequence

In [2]: images = ImageSequence('img-*.png')

In [3]: images
Out[3]: 
<Frames>
Source: /home/casper/code/pims/doc/img-*.png
Length: 9 frames
Frame Shape: (256, 256)
Pixel Datatype: uint8

Images can be randomly accessed with standard Python slicing syntax.

In [4]: images[0]  # first image
Out[4]: 
Frame([[211, 152,  27, ..., 119, 172,  33],
       [175, 193, 188, ..., 219, 211,  91],
       [248,  60,  72, ...,  91,  98, 136],
       ..., 
       [246, 110,  87, ..., 123, 182,  25],
       [254,  34, 136, ...,  64, 114, 233],
       [132,  26, 208, ..., 152, 225,  35]], dtype=uint8)

In [5]: images[-5]  # fifth from the end
Out[5]: 
Frame([[204,  23, 241, ..., 191,  87, 173],
       [208, 179,  78, ..., 181, 236,  97],
       [  5, 143,  17, ..., 169, 213, 192],
       ..., 
       [213,  88, 108, ...,  42,  92,  87],
       [192,  84,  93, ..., 113,  15, 117],
       [202, 123, 250, ...,  70,  38, 138]], dtype=uint8)

The images are iterable. Data is loaded one image at a time, conserving memory.

In [6]: import numpy as np

In [7]: for image in images:
   ...:     np.sum(image)  # do something
   ...:

Slicing images returns another lazy-loading object that is also iterable and sliceable.

In [8]: subsection = images[:5]  # the first five images

In [9]: len(images)
Out[9]: 9

In [10]: len(subsection)
Out[10]: 5

In [11]: for image in subsection:
   ....:     np.sum(image)  # do something
   ....: 

In [12]: subsubsection = subsection[::2]  # every other of the first five images

Fancy numpy-like slicing is supported.

In [13]: subsection2 = images[[0, 3, 7]]

In [14]: mask = [True, False, False, False, False, True, False, False, False, False]

In [15]: subsection3 = images[mask]

Core Contributors

  • Daniel Allan founding contributor, slicing and iteration logic, basic readers, display tools
  • Thomas Caswell major refactor, abstract base class
  • Casper van der Wel bioformats readers, display tools
  • Thomas Dimiduk filetype-detecting dispatch logic

Support

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. Later work was supported by Brookhaven National Lab. Dan can be reached at dallan@bnl.gov.

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. Later work was supported by Brookhaven National Lab. Tom can be reached at tcaswell@gmail.com.

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).