Introduction to Bio-Formats

What is Bio-Formats?

  • Java library for reading image-based datasets
    • Reads images, but also acquisition metadata
  • One API, many applications
  • A complete implementation of OME-XML and OME-TIFF

A brief historical overview

  • 2005 - work began on Java library
  • 2006 March 31 - first official release of Bio-Formats
  • late 2006 - OMERO begins using Bio-Formats
  • early 2008 - MATLAB first supported
  • 2008 - major effort standardize metadata handling across all formats
  • 2009 (v4.0.0) - unified version numbers with OMERO
  • late 2012/early 2013 - work began on C++ library
  • 2014/2015 - major effort to improve performance
  • 2015 - increasing number of contributed code changes
  • 2016 - data model refinements and work on targeted projects (e.g. IDR)

The history in numbers

What can you do now?

Read images and metadata across many domains...

  • light microscopy
  • electron microscopy
  • medical imaging (CT, PET, ...)
  • high content screening (HCS)
  • digital pathology/whole slide imaging (WSI)
  • FLIM
  • SPIM

...and in many different applications

ImageReader reader = new ImageReader();
IMetadata omeMetadata = MetadataTools.createOMEXMLMetadata();
for (int plane = 0; plane < reader.getImageCount(); plane++) {
  byte[] image = reader.openBytes(plane);
  Number timestamp = omeMetadata.getPlaneDeltaT(0, plane).value();

ImageJ macro:
run("Bio-Formats Macro Extensions");
timestamps = newArray(imageCount);
for (plane=0; plane < imageCount; plane++) {
  Ext.openImage("image #" + plane, plane);
  Ext.getPlaneTimingDeltaT(timestamps[plane], plane);
r = bfGetReader("/PATH/TO/FILE");
imageCount = r.getImageCount();
omeMetadata = r.getMetadataStore();
for plane = 1:imageCount
  image = bfGetPlane(r, plane, varargin{:});
  timestamp = omeMetadata.getPlaneDeltaT(0, plane - 1).value().doubleValue();
reader = bioformats.get_image_reader(None, path="/PATH/TO/FILE")
imageCount = reader.rdr.getImageCount()
omeMetadata = javabridge.JWrapper(reader.rdr.getMetadataStore())
for plane in range(0, imageCount):
    image =, index=plane, rescale=False)
    timestamp = omeMetadata.getPlaneDeltaT(0, plane)
reader = .jnew("loci.formats.ImageReader")
.jcall(reader, , "setId", file)
omeMetadata = .jcall(reader, "", "getMetadataStore")
image = .jcall(reader, "[B", "openBytes", 0)
timestamp = .jcall(omeMetadata, "", "getPlaneDeltaT", 0, 0)

Extensions to image reading

("reader wrappers")
  • cache reader state (Memoizer)
  • group independent files into a single dataset (FileStitcher)
  • return images in a specific layout (ChannelSeparator, ChannelMerger)


IFormatReader reader = new Memoizer(new ImageReader());
  • uses Kryo to serialize the reader's initialized state to a file
  • initializing the same data file again uses the serialized state (i.e. faster)


IFormatReader reader = new FileStitcher();
// reads 001.tiff, 002.tiff, ..., 010.tiff together
reader.setId("0< 01-10>.tiff");
  • groups together files not otherwise detected as part of the same dataset
  • useful for files with missing or unreadable metadata


IFormatReader grayscaleImageReader = new ChannelSeparator();

IFormatReader rgbImageReader = new ChannelMerger();
  • ChannelSeparator guarantees only grayscale images are returned
  • ChannelMerger guarantees multi-channel datasets are returned as RGB images

Putting everything together...

IFormatReader reader = new Memoizer(new FileStitcher(new ChannelSeparator()));
  • any combination of wrappers can be chained together

What we've done recently

  • maintenance of 5.1.x
  • 5.2.0
  • performance and metadata updates for IDR

Bio-Formats 5.1.x series

See the Bio-Formats version history

  • Reader bug fixes
  • Support for native units across readers
  • OMERO / Bio-Formats decoupling
  • Documentation improvements

Bio-Formats 5.1.x series: community

See the Bio-Formats version history

  • Readers (Metamorph, Slidebook, Fei, Imspector OBF)
  • MATLAB toolbox
  • Octave package
  • OME-XML validation

Bio-Formats 5.2.0

Breaking changes

  • New OME Data model
  • Code generation improvements
  • Drop of support for Java 6
  • API (logging)

Bio-Formats IDR

  • Lots of performance improvements for HCS formats
  • Improved support for different types of Opera Flex plates
  • More options for grouping together files without acquisition metadata

What's next?

  • OME data model refinements
    • Making existing features easier to use (e.g. units, MapAnnotation)
    • Modernizing the data model development process
  • Supporting our own formats
    • Expanding examples and best practices documentation
    • Working with other projects to support usage of OME-TIFF
    • OME-HDF?


  • Supporting and maintaining OME file formats
  • Questions? Concerns?
  • Breakouts/technical discussion - look for the Bio-Formats sign!


Contributing to Bio-Formats