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

also now in C++

We talk about Bio-Formats a lot, but what exactly is it? Primarily, it's a Java library that reads files in many different imaging formats. Not only does it provide unified access to the image data from over 140 different formats, but critically it also provides the acquisition information that is associated with the images. I'll show an example shortly, but the goal in effect is to have a single API that can give you an image, the time at which is was acquired, which objective was used, the wavelength of the laser used, and any other acquisition information - independent of the file format and in any application that supports Java. To facilitate this, Bio-Formats implements the OME-XML schema, and thus provides a complete reference implementation of the two formats that we develop ourselves - OME-XML and OME-TIFF. With the recent 5.1.2 release, we also now have complete OME-XML and OME-TIFF support natively in a Bio-Formats C++ library. I won't go into much detail here as that is the topic of the next talk, but we're pretty exicted about this as it means that roughly the same API can be used for both formats in both Java and C++ applications.

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
2015+ - more frequent releases

So to give a little history, development on the Java library began in mid-2005, so it is currently in its 10th year of active development. The first public release was March 31 2006; the primary usage in the early days was as a plugin for ImageJ. Around the same time, the first versions of OMERO were being released, and so in late 2006 OMERO began using Bio-Formats to import files. In early 2008, we added official support for MATLAB through a set of example scripts, which evolved into the current MATLAB framework that is widely used today. Also in 2008, both Bio-Formats and OMERO had been in the field for a couple of years, and were starting to experience some growing pains. Up until this point, both projects were developed largely independently, without a complete awareness of how implementation choices in Bio-Formats might affect OMERO or vice versa. This was most challenging in terms of how acquisition metadata was handled by Bio-Formats - it was a this point that we made a major effort to fully implement the OME-XML schema and to use that as the primary means of describing the metadata contained in a file. Prior to this, metadata was primarily stored in what we call the "original metadata table", which is a free-form and format-dependent hashtable. This effort helped to stabilize file import in OMERO, and greatly improved the interaction between the two projects. So in 2009, with version 4.0.0, we decided to unify the planning and release processes for Bio-Formats and OMERO, to more easily prevent changes in one project from negatively impacting the other. This is the same strategy we use today of releasing Bio-Formats and OMERO on the same day and with the same version number. Development then progressed for a while without major incident - we fixed bugs, and added more formats - but based on feedback on the mailing lists and in these meetings, we realized that a Java library alone wouldn't be sufficient. So in late 2012/early 2013 we began work on a C++ version of the Bio-Formats API. The initial goal, which is now largely realized, was to provide reading and writing support for our two formats - OME-XML and OME-TIFF. In parallel, we've spent much of the last 1.5-2 years improving the read time for many formats - this has been driven by the rise of high throughput imaging modalities where each fileset might be on the order of several terabytes. In recent months, we've noted a distinct increase in the level of engagement with developers who are using Bio-Formats. In particular, we've had an increasing number of code contributions via GitHub pull requests - on average about one every 2 weeks. Finally, we know that many of our users would like to see more frequent releases, so that bug fixes are available within days, not weeks or months. So far in the 5.1 line, we've been announcing one new release per month; we're planning ways to make this even faster, though this may mean that Bio-Formats and OMERO are no longer released at the same time.

The history in numbers

A more quantitative look at the history... you can see in green the number of contributors over time - this is the number of people both in OME and from the community who authored at least one Git commit in a particular year. To date in 2015, we have 21 contributors, which is the highest it's ever been. You can also see in red how the number of supported formats has increased, from 43 in 2006 to 142 today. We've also had a substantial increase in the number of people using Bio-Formats over the years - we currently estimate this to be around 60,000 (though estimating usage is a bit tricky). Any questions so far?

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

Java:
ImageReader reader = new ImageReader();
IMetadata omeMetadata = MetadataTools.createOMEXMLMetadata();
reader.setMetadataStore(omeMetadata);
reader.setId("/PATH/TO/FILE");
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");
Ext.setId("/PATH/TO/FILE");
Ext.getImageCount(imageCount);
timestamps = newArray(imageCount);
for (plane=0; plane < imageCount; plane++) {
  Ext.openImage("image #" + plane, plane);
  Ext.getPlaneTimingDeltaT(timestamps[plane], plane);
}

MATLAB:
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();
end

Python:
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 = reader.read(series=0, index=plane, rescale=False)
    timestamp = omeMetadata.getPlaneDeltaT(0, plane)

What we've done recently

full support for Windows
performance improvements, especially over network file systems
added units for most metadata values
lots of bug fixes!

Over the last few releases this year, we've made several notable changes in the Java library. We now have full support for Windows - so we are testing our entire repository of filesets on both Linux and Windows at least twice per week. Hand in hand with that, we've put a lot of time into improving performance over network filesystems specifically, both for our own benefit when testing, and in recognition of the fact that many people are now working with files on shared storage systems instead of on a local disk. We've also updated the OME-XML schema and the corresponding Bio-Formats API to allow the units for metadata values to be recorded instead of being pre-defined by the schema - for example, the physical size of a pixel was previously only stored in micrometers. The same value can now be stored in whichever standard unit makes the most sense based upon the acquisition, such as angstroms for EM or centimeters for medical imaging. We did this to provide maximum flexibility across all of the imaging domains previously mentioned. Finally, we have as always fixed a lot of bugs - many of which were reported by the community, including almost everyone here. We're very grateful for this feedback.

What's next?

Updates to the development process

More releases, and faster

OME-HDF?
More usage examples and developer documentation
Updated bug reporting and QA process

Lastly, it's the time of year when we start planning what the next 12-18 months will look like. As I mentioned earlier, we intend to make some updates to the development process that has been in use since 2008, to allow for more frequent releases, while keeping the same high level of testing and QA that we have now. We're also considering whether to define a new format based upon HDF - some of yo uhave expressed interest in using an HDF format instead of OME-TIFF, and we'd like to accomodate that if possible. In recognition of the increasing number of developer users, we'ld like to put serious effort into expanding documentation and example code for developers, across all of the supported languages. We're also planning to make some updates to how we ask for bug reports. Our goal is to make it easier to provide detailed information about what a problematic file should look like, be it in screenshots or a list of the expected metadata - with the hope of reducing the time to fix bugs while also being able to more accurately test for regressions going forward.

What's next...today?

Introduction to working with the new C++ library
OME-HDF discussion
Breakouts/technical discussion - look for the Bio-Formats sign!