See also

The section Multidimensional Readers describes how to deal with multidimensional files.

The Bioformats reader interfaces with Bio-Formats, an open-source Java library for reading and writing multidimensional image data, especially from file formats used in microscopy.

See the list of supported formats.


To interface with the java library, we use JPype, which allows fast and easy access to all java functions. JRE or JDK are not required.

For Anaconda users, platforms, jpype is available via the conda-forge channel:

conda install jpype1 -c conda-forge

For installation with pip, type in the following into the terminal:

pip install jpype1

Or, for windows users, download the binary from Christoph Gohlke’s website.

On first use of pims.Bioformats(filename), the required java library loci_tools.jar will be automatically downloaded from

Special functions

Some files contain multiple experiments. The series argument or property switches between them:

# open a multi-experiment file and read the first experiment
reader = pims.BioformatsReader('path/to/file', series=0)
# switch to the third experiment
reader.series = 2

Very large files may need more Java memory. If you ever encounter a memory error, open a file with for instance 1 GB of java memory:

reader = BioformatsReader('path/to/file', java_memory='1024m')


The Bioformats reader can be used to access the metadata stored in the image, including physical dimensions pixel, instrument parameters, and other useful information. For performance increase, this function may be toggled off using the meta=False keyword argument.

meta = images.metadata

image_count = meta.ImageCount()
print('Total number of images: {}'.format(image_count))

for i in range(image_count):
    print('Dimensions for image {}'.format(i))
    shape = (meta.PixelsSizeX(i), meta.PixelsSizeY(i), meta.PixelsSizeZ(i))
    dxyz = (meta.PixelsPhysicalSizeX(i),
    print('\tShape: {} x {} x {}'.format(*shape))
    print('\tDxyz:  {:2.2f} x {:2.2f} x {:2.2f}'.format(*dxyz))

See the documentation for the Metadata retrieve API for more details.