OME at LOCI –
Software – Bio-Formats library
Bio-Formats is a standalone Java library for reading and writing
microscopy file formats, written by Melissa Linkert, Curtis Rueden, Chris
Allan, Eric Kjellman and Brian Loranger. It is capable of parsing both
pixels and metadata for a large number of formats, as well as writing to
several formats. See the table below for a complete
list.
Purpose:
Bio-Formats's primary purpose is to convert proprietary microscopy data
into an open standard called the
OME data model,
particularly into the OME-TIFF file format.
See the Bio-Formats manifesto
for a thorough explanation and rationale.
For users:
Several software packages can use Bio-Formats to read and write
microscopy formats, including
ImageJ,
VisBio,
OME,
VisAD,
Endrov and
MATLAB.
See the Using Bio-Formats
sections below for a complete list.
For developers:
You can use Bio-Formats as a library to support these formats in your
software. See the Using
Bio-Formats as a Java library section below for more details.
License:
Bio-Formats is open source software licensed under the
GNU Lesser General Public License.
See the
LGPL Overview on OSS Watch
or the
Wikipedia entry on the LGPL
for more information.
Version history:
Bio-Formats is updated whenever there is a significant bugfix or new
feature. For simplicity, we use date stamps as version numbers. See the
what's new
list for a history of major changes in each release.
The following is a complete bundle of Bio-Formats with supporting libraries:
You can also download the unstable
trunk build
(updated within minutes of every SVN commit)
or daily build
(updated every night) for the latest bugfixes (and bugs).
Please note:
- Internet Explorer sometimes renames loci_tools.jar to
loci_tools.zip; if this happens to you, simply rename the file
back to loci_tools.jar afterwards.
- For some browsers, you may need to right-click or control-click the
link and choose "Save link as..." or similar option to download the
file.
- What to do with the file depends on how you want to use Bio-Formats;
see the next section.
For full details on using Bio-Formats in different contexts,
click an item below.
ImageJ is an image processing
and analysis application written in Java, widely used in the life
sciences fields, with an extensible plugin infrastructure.
You can use Bio-Formats as a plugin for ImageJ to read and write
images in the formats it supports.
Installation:
Download loci_tools.jar above, and drop it into your
ImageJ/plugins folder. Next time you run ImageJ, a new LOCI
submenu with several plugins will appear in the Plugins menu, including
the Bio-Formats Importer and Bio-Formats Exporter.
If you wish to read certain kinds of compressed DICOM files, you will
need to
set
up the optional native libraries.
The Bio-Formats Importer plugin can display image stacks in several ways:
- In a standard ImageJ window
- Using our Data Browser plugin
(included)
- With Joachim Walter's
Image5D
plugin (if installed)
- With Rainer Heintzmann's
View5D plugin
(if installed)
ImageJ v1.37 and later automatically (via HandleExtraFileTypes) calls the
Bio-Formats logic, if installed, as needed when a file is opened within
ImageJ—e.g., when using File/Open instead of explicitly choosing
"Bio-Formats Importer" from the Plugins/LOCI menu.
Upgrading:
To upgrade, just overwrite the old loci_tools.jar with the new
one. You may want to download the latest version of ImageJ first, to
take advantage of new features and bugfixes.
|
Sample ImageJ macros and plugins that use Bio-Formats
|
|---|
basicMetadata.txt
|
A macro that uses the Bio-Formats macro extensions to print the
chosen file's basic dimensional parameters to the Log
|
recursiveTiffConvert.txt
|
A macro for recursively converting files to TIFF using Bio-Formats
|
bfOpenAsHyperstack.txt
|
This macro from Wayne Rasband opens a file as a hyperstack using
only the Bio-Formats macro extensions (without calling the
Bio-Formats Importer plugin)
|
zvi2HyperStack.txt
|
This macro from Sebastien Huart reads in a ZVI file using
Bio-Formats, synthesizes the LUT using emission wavelength
metadata, and displays the result as a hyperstack
|
dvSplitTimePoints.txt
|
This macro from Sebastien Huart splits timepoints/channels
on all DV files in a folder
|
Read_Image
|
A simple plugin that demonstrates how to use Bio-Formats to
read files into ImageJ
|
VisBio
is a biological visualization tool designed for easy visualization and
analysis of multidimensional image data.
VisBio uses Bio-Formats to import files—actually, the Bio-Formats
library originally grew out of our efforts to continually expand the
file format support within VisBio.
Installation:
VisBio is bundled with Bio-Formats,
so no further installation is necessary.
If you wish to read certain kinds of compressed DICOM files, you will
need to
set
up the optional native libraries.
Upgrading:
It should be possible to use a newer version of Bio-Formats by
overwriting the old bio-formats.jar and optional libraries
(see "Using Bio-Formats as a Java library" below) within the VisBio
distribution.
For Mac OS X, you'll have to control click the VisBio program icon,
choose "Show Package Contents" and navigate into
Contents/Resources/Java to find the JAR files.
FocalPoint
is an image browser—similar to
Windows
Explorer or other
file manager
application—specifically designed to work with more complex image
types. FocalPoint uses Bio-Formats to generate thumbnails.
Installation:
FocalPoint is bundled with Bio-Formats,
so no further installation is necessary.
If you wish to read certain kinds of compressed DICOM files, you will
need to
set
up the optional native libraries.
Upgrading:
It should be possible to use a newer version of Bio-Formats by
overwriting the old loci_tools.jar within the FocalPoint
distribution.
For Mac OS X, you'll have to control click the FocalPoint program icon,
choose "Show Package Contents" and navigate into
Contents/Resources/Java to find the loci_tools.jar file.
OME
is a set of software that interacts with a database to manage images,
image metadata, image analysis and analysis results.
The OME system is capable of leveraging Bio-Formats to import files.
Installation:
For OME Perl v2.6.1 and
later, the command line installer automatically downloads the latest
loci_tools.jar and places it in the proper location. This location
is configurable, but is /OME/java/loci_tools.jar by default.
If you wish to read certain kinds of compressed DICOM files, you will
need to
set
up the optional native libraries.
Note that Li-Cor L2D files cannot be imported into an OME server. We are working to resolve this issue; see this Trac ticket for details.
Upgrading:
You can upgrade your OME server installation to take advantage of a new
Bio-Formats release by overwriting the old loci_tools.jar with
the new one.
OMERO
is a partial port of the OME Perl Server (OMEDS and OMEIS) to Java.
The
OMERO.importer
client uses Bio-Formats to read image pixels and propagate metadata into
the OMERO.server system.
Installation:
Everything you need comes with the OMERO clients,
with no further installation necessary.
If you wish to read certain kinds of compressed DICOM files, you will
need to
set
up the optional native libraries.
Upgrading:
The OMERO clients are currently distributed with a static version of
Bio-Formats bundled within the jar_0.jar or
omero.importer.jar file, and cannot be easily upgraded using the
latest loci_tools.jar on this web page. Instead, wait for a new
version of the OMERO.importer client.
The VisAD
visualization toolkit is a Java component library for interactive and
collaborative visualization and analysis of numerical data.
VisAD uses Bio-Formats to read many image formats, notably TIFF.
Installation:
The visad.jar file has Bio-Formats bundled inside,
so no further installation is necessary.
If you wish to read certain kinds of compressed DICOM files, you will
need to
set
up the optional native libraries.
Upgrading:
It should be possible to use a newer version of Bio-Formats by putting
loci_tools.jar (or bio-formats.jar—see
"Using Bio-Formats as a Java library" below) before visad.jar
in the class path.
Alternately, you can create a "VisAD Lite" using the
make lite command from VisAD source,
and use the resultant visad-lite.jar,
which is a stripped down version of VisAD
without sample applications or Bio-Formats bundled in.
The Endrov (EV) framework is an
extensible program to work with spatio-temporal data and the
OST imageset
format.
Installation:
The EV distribution comes bundled with the core Bio-Formats library
(bio-formats.jar), so no further installation is necessary.
If you wish to read certain kinds of compressed DICOM files, you will
need to
set
up the optional native libraries.
Upgrading:
It should be possible to use a newer version of Bio-Formats by putting
bio-formats.jar (see "Using Bio-Formats as a Java library" below)
into the libs folder of the EV distribution, overwriting the
old file. You could also include some of the optional libraries, to add
support for additional formats, if desired.
MATLAB
is a high-level language and interactive environment that facilitates
rapid development of algorithms for performing computationally intensive
tasks.
Calling Bio-Formats from MATLAB is fairly straightforward, since MATLAB
has built-in interoperability with Java. However, we have not yet had
time to develop serious tools to ease usage of Bio-Formats within MATLAB.
Our eventual goal is to provide M scripts that make it very simple to
read files directly from disk into MATLAB 3D matrices (which is what the
image processing toolbox uses to represent images) using the appropriate
data type.
In our brief investigation so far into using Bio-Formats with MATLAB, we
came up with a simple script for reading image files:
bfopen.m
function [result] = bfopen(id)
% A script for opening microscopy images in MATLAB using Bio-Formats.
%
% Portions of this code were adapted from:
% http://www.mathworks.com/support/solutions/data/1-2WPAYR.html?solution=1-2WPAYR
%
% Excluding figure creation, this method is ~1.5x-2.5x slower than
% Bio-Formats's command line showinf tool (MATLAB R14 vs. java 1.6.0_03),
% due to overhead from reshaping arrays and converting pixel types.
%
% Thanks to Ville Rantanen for his performance improvements and ideas.
% Thanks to Brett Shoelson of The MathWorks for his excellent suggestions.
%
% To install, download loci_tools.jar from:
% http://www.loci.wisc.edu/ome/formats.html
% Internet Explorer sometimes erroneously renames the Bio-Formats library
% to loci_tools.zip. If this happens, rename it back to loci_tools.jar.
% Place loci_tools.jar and this script (bfopen.m) in your MATLAB work folder.
% load Bio-Formats library into MATLAB environment
javaaddpath('loci_tools.jar');
% Alternately, you can add the library to MATLAB's static class path:
% 1. Type "edit classpath.txt" at the MATLAB prompt.
% 2. Go to the end of the file, and add the path to your JAR file
% (e.g., C:/Program Files/MATLAB/work/loci_tools.jar).
% 3. Save the file and restart MATLAB.
r = loci.formats.ChannelFiller();
r = loci.formats.ChannelSeparator(r);
r = loci.formats.FileStitcher(r);
tic
r.setId(id);
numSeries = r.getSeriesCount();
for s = 1:numSeries
fprintf('Reading series #%d', s);
r.setSeries(s - 1);
w = r.getSizeX();
h = r.getSizeY();
numImages = r.getImageCount();
for i = 1:numImages
fprintf('.');
img = r.openImage(i - 1);
% convert Java BufferedImage to MATLAB image
pix = img.getData.getPixels(0, 0, w, h, []);
arr = reshape(pix, [w h])';
% build an informative title for our figure
label = id;
if numSeries > 1
qs = int2str(s);
label = [label, '; series ', qs, '/', int2str(numSeries)];
end
if numImages > 1
qi = int2str(i);
label = [label, '; plane ', qi, '/', int2str(numImages)];
if r.isOrderCertain()
lz = 'Z';
lc = 'C';
lt = 'T';
else
lz = 'Z?';
lc = 'C?';
lt = 'T?';
end
zct = r.getZCTCoords(i - 1);
sizeZ = r.getSizeZ();
if sizeZ > 1
qz = int2str(zct(1) + 1);
label = [label, '; ', lz, '=', qz, '/', int2str(sizeZ)];
end
sizeC = r.getSizeC();
if sizeC > 1
qc = int2str(zct(2) + 1);
label = [label, '; ', lc, '=', qc, '/', int2str(sizeC)];
end
sizeT = r.getSizeT();
if sizeT > 1
qt = int2str(zct(3) + 1);
label = [label, '; ', lt, '=', qt, '/', int2str(sizeT)];
end
end
% plot the image plane in a new figure
figure('Name', label);
imagesc(arr);
% If you have the image processing toolbox, you could use:
%imshow(arr, []);
% You could do something else with each plane
% here, rather than just overwriting the result.
result = arr;
end
fprintf('\n');
end
toc
We are not MATLAB experts—any comments on improving the script are
welcome.
Performance:
In our tests (MATLAB R14 vs. java 1.6.0_03), the script executes at
approximately half the speed of our showinf command line
tool, due to overhead from reshaping arrays and converting pixel
types.
Installation:
To use the script, download bfopen.m and loci_tools.jar
(above) and place them in your MATLAB work directory.
If you wish to read certain kinds of compressed DICOM files, you will
need to
set
up the optional native libraries.
Upgrading:
To use a newer version of Bio-Formats, overwrite
loci_tools.jar with the newer version and restart MATLAB.
loci_tools.jar vs. bio-formats.jar
(or, "A note on Java Web Start")
To use Bio-Formats with your Java Web Start application, we recommend
using bio-formats.jar rather than
loci_tools.jar—the latter is merely a bundle of
bio-formats.jar plus all its optional dependencies.
The loci_tools.jar bundle is intended as a convenience (e.g.,
to simplify installation as an ImageJ plugin), but is by no means the
only solution for developers. We recommend using
bio-formats.jar as a separate entity depending on your needs
as a developer.
The bundle is quite large because we have added support for several
formats that need large helper libraries (e.g., Imaris's HDF-based
format). However, these additional libraries are
optional—Bio-Formats has been coded using reflection so that it
can both compile and run without them.
When deploying a JNLP-based application, using loci_tools.jar
directly is not the best approach, since every time Bio-Formats is
updated, the server would need to feed another 8+ MB JAR file to the
client. Rather, Web Start is a case where you should keep the JARs
separate, since JNLP was designed to make management of JAR
dependencies trivial for the end user. By keeping
bio-formats.jar and the optional dependencies separate, only a
<1 MB JAR needs to be updated when bio-formats.jar changes.
As a developer, you have the option of packaging
bio-formats.jar with as many or as few optional libraries as
you wish, to cut down on file size as needed. You are free to make
whatever kind of "stripped down" version you require. You could even
build a custom bio-formats.jar that excludes certain classes,
if you like.
For an explicit enumeration of all the optional libraries included in
loci_tools.jar, see the tools.libraries variable
of the
build.properties
file of the distribution. You can also read our notes about each in
the source distribution's Ant
build.xml
script.
If you wish to leverage Bio-Formats within your own software,
you can use it as a library. To do so, download the following file:
You can also download the unstable
trunk build
(updated within minutes of every SVN commit)
or daily build
(updated every night) for the latest bugfixes (and bugs).
No additional libraries are required. However, there are certain packages
that if present will be utilized to provide additional functionality:
| Optional libraries |
|---|
|
ome-java.jar
→ Java OME-XML library,
for image metadata standardization |
|
poi-loci.jar
→ Patched version of
Apache Jakarta POI,
for working with OLE-based formats (zvi, oib, ipw, cxd) |
|
jai_imageio.jar
→ Pure Java implementation of
JAI Image I/O Tools,
for Nikon ND2 and JPEG 2000 JP2 formats |
|
mdbtools-java.jar
→ Java port of
MDB Tools project,
for Zeiss LSM metadata in MDB database files |
|
netcdf-4.0.jar,
grib-5.1.03.jar,
bufr-1.1.00.jar,
slf4j-jdk14.jar
→
NetCDF
Java library,
for working with HDF5-based formats (Imaris 5.5) |
|
QTJava.zip
→
QuickTime
for Java, for better MOV support, including additional codecs |
To use Bio-Formats as a library, just add bio-formats.jar to your
CLASSPATH or build path. To include one of the optional libraries above,
just place it in the same folder as bio-formats.jar.
| Examples of usage |
|---|
ImageConverter
|
A simple command line tool for converting between formats
|
ImageInfo
|
A more involved command line utility for thoroughly reading an
input file, printing some information about it, and displaying
the pixels onscreen using the Bio-Formats viewer
|
Read_Image
|
A simple plugin for ImageJ demonstrating how to use Bio-Formats to
read files into ImageJ (see also
Using
Bio-Formats with ImageJ above).
|
Bio-Formats supports reading lossless JPEG compressed DICOM files.
However, it relies on the JAI ImageIO native (platform-specific) library,
which requires some extra steps to install:
- Download the appropriate
JAI
ImageIO tools native package for your platform.
- Install the package into the applicable Java Runtime Environment
(JRE).
Specific directions for Windows and Linux are below. The instructions are
tailored toward people using Bio-Formats with ImageJ, but can be adapted
for use in any of the other contexts as well.
Windows:
- Download and run
jai_imageio-1_1-lib-windows-i586-jre.exe.
- For the destination directory, choose:
C:\Program Files\ImageJ\jre
(unless you installed ImageJ somewhere else,
or are using a different JRE location).
- Start up ImageJ and give it a try.
Mac OS X:
- The JAI Image I/O Tools native library is not currently available
for Mac OS X.
- Issue #103
on the jai-imageio-core development site tracks the problem.
Linux:
- Download
jai_imageio-1_1-lib-linux-i586-jre.bin.
- Place the file in your ImageJ JRE directory
(e.g., ~/ImageJ/jre).
- From the console, run:
cd ~/ImageJ/jre
chmod 755 jai_imageio-1_1-lib-linux-i586-jre.bin
./jai_imageio-1_1-lib-linux-i586-jre.bin
- Once the files have unpacked,
start up ImageJ and give it a try.
The table below lists formats that Bio-Formats can read.
- Blue highlighted entries
can be written using Bio-Formats as well
(gray and white stripes are merely for ease of reading and signify
nothing in particular).
- INFO buttons in the Details column give more information about a
format when moused over.
- LEGEND button in the right-hand column heading gives details on the
rating system when moused over.
Tooltips in the above table made possible by Walter Zorn's
outstanding
tooltips
script. Icons are derived from Joe North's
Sweetie BasePack.
Last update: Thursday, May 9, 2008
Using Bio-Formats with ImageJ
