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:
|
loci_tools.jar
2008 April 17 – 16,372,372 bytes |
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:
For full details on using Bio-Formats in different contexts, click an item below.
Using Bio-Formats with ImageJ
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:
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 |
Using Bio-Formats with VisBio
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.
Using Bio-Formats with FocalPoint
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.
Using Bio-Formats with OME server
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.
Using Bio-Formats with OMERO
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.
Using Bio-Formats with VisAD
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.
Using Bio-Formats with Endrov
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.
Using Bio-Formats with MATLAB
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:
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.
Using Bio-Formats from the command line
We have created several scripts for using Bio-Formats on the command line. You can download them here:
|
bftools.zip
2007 December 12 – 12,309 bytes |
The zip file contains both Unix scripts and Windows batch files. Currently available tools include:
xmllint --format
but more robust in that it attempts to produce output regardless
of syntax errors in the XML.
All scripts require loci_tools.jar in the same directory as the command line tools.
Lastly, if you have checked out the source from our Subversion repository
(see the LOCI Software page for instructions)
you already have the command line tools in the java/tools
directory. You can configure the scripts to use your source tree instead
of loci_tools.jar in the same directory by following these steps:
java
directory and the JAR files in the java/jar folder.
C:\code\loci, set your CLASSPATH
environment variable to the value
C:\code\loci\jar\*;C:\code\loci. You can access the
environment variable configuration area by right-clicking on
My Computer, choosing Properties, Advanced tab, Environment
Variables button.
ant dev-compile.LOCI_DEVEL environment variable to any value.
(The variable just needs to be defined.)
Using Bio-Formats as a Java library
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.
|
bio-formats.jar
2008 April 17 – 807,871 bytes |
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 | |
|---|---|
| → Java OME-XML library, for image metadata standardization | |
| → Patched version of Apache Jakarta POI, for working with OLE-based formats (zvi, oib, ipw, cxd) | |
| → Pure Java implementation of JAI Image I/O Tools, for Nikon ND2 and JPEG 2000 JP2 formats | |
| → 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). |
| Other developer links | |
|---|---|
| Software overview | How to access the source code from our Subversion repository |
| Javadocs | Javadocs for Bio-Formats and other LOCI Java software |
| Using Bio-Formats Guide | How to use Bio-Formats as a library |
| File Format Reader Guide | How to add support for a new file format |
| Trac tickets | A list of outstanding bugs |
| Trac browser | Browse the source code and project history online |
| SVN browser | Browse the raw source code online |
Setting up native libraries
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:
Windows:
Mac OS X:
Linux:
The table below lists formats that Bio-Formats can read.
| # | Format | Extensions | Details | LEGEND![]() ![]() ![]() ![]() |
|---|---|---|---|---|
| Adobe Photoshop PSD | .psd | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Alicona 3D | .al3d | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Amersham Biosciences GEL | .gel | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Andor Bio-Imaging Division (ABD) TIFF | .tif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Aperio SVS TIFF | .svs | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| AVI (Audio Video Interleave) | .avi | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Becker & Hickl SPCImage | .sdt | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Bio-Rad PIC | .pic | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Bitplane Imaris | .ims | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| BMP (Windows Bitmap) | .bmp | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| DeltaVision | .dv, .r3d | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| DICOM | .dcm, .dicom | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| EPS (Encapsulated PostScript) | .eps | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Evotec Flex | .flex | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| FITS (Flexible Image Transport System) | .fits | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Gatan Digital Micrograph | .dm3 | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| GIF (Graphics Interchange Format) | .gif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| ICS (Image Cytometry Standard) | .ics | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Image-Pro Sequence | .seq | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Image-Pro Workspace | .ipw | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Improvision Openlab LIFF | .liff | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Improvision Openlab Raw | .raw | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Improvision TIFF | .tif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| InCell 1000 | .xdce, .tif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| IPLab | .ipl | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| JPEG | .jpg | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| JPEG 2000 | .jp2 | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Khoros VIFF (Visualization Image File Format) Bitmap | .xv | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Leica LAS AF LIF (Leica Image File Format) | .lif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Leica LCS LEI | .lei, .tif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Li-Cor L2D | .l2d, .tif, .scn | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| LIM (Laboratory Imaging/Nikon) | .lim | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| MetaMorph 7.5 TIFF | .tiff | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| MetaMorph Stack (STK) | .stk | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| μManager | .tif, .txt | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| MNG (Multiple-image Network Graphics) | .mng | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| MRC (Medical Research Council) | .mrc | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| NEF (Nikon Electronic Format) | .nef, .tif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Nikon NIS-Elements ND2 | .nd2 | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| nrrd (Nearly Raw Raster Data) | .nrrd | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Olympus 3i SlideBook | .sld | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Olympus FluoView FV1000 | .oib, .oif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Olympus FluoView TIFF | .tif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| OME-TIFF | .ome.tif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| OME-XML | .ome | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| PerkinElmer UltraView | .tif, .2, .3, .4, ... | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| PICT (Macintosh Picture) | .pict | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| PGM (Portable Gray Map) | .pgm | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| PNG (Portable Network Graphics) | .png | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Prairie Technologies TIFF | .tif, .xml | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| QuickTime Movie | .mov | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| SimplePCI | .cxd | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| TIFF (Tagged Image File Format) | .tif | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| VisiTech XYS | .xys, .html | INFO | ![]() ![]() ![]() ![]()
|
|
| Zeiss AxioVision ZVI (Zeiss Vision Image) | .zvi | INFO | ![]() ![]() ![]() ![]() ![]() |
|
| Zeiss LSM (Laser Scanning Microscope) 510 | .lsm | INFO | ![]() ![]() ![]() ![]() ![]() |
Tooltips in the above table made possible by Walter Zorn's outstanding tooltips script. Icons are derived from Joe North's Sweetie BasePack.
(5) Gold Star = Excellent
(4) Silver Plus Sign = Very Good
(3) Green Check Mark = Good
(2) Gray Minus Sign = Fair
(1) Red X = Poor
Each format is rated according to five categories, which convey diverse information.
For further details, mouse over each individual heading (Pixels, Metadata, Openness, Presence and Utility).
Pixels represents our estimation of Bio-Formats's ability to reliably extract complete and accurate pixel values from files in that format. The better this score, the more confident we are that Bio-Formats will successfully read your file without displaying an error message or displaying an erroneous image.