Bio-Formats as a Java Library
If you wish to leverage Bio-Formats within your own software, you can download bio-formats.jar to use it as a library. Just add bio-formats.jar to your CLASSPATH or build path. You will also need loci-common.jar for common I/O functions, ome-xml.jar for metadata standardization, and SLF4J for logging.
Beyond bio-formats.jar, loci-common.jar, ome-xml.jar, and SLF4J, no additional libraries are required. However, there are certain packages that if present will be utilized to provide additional functionality. To include one, just place it in the same folder.
| Package | Filename | License | Notes |
|---|---|---|---|
| Apache Jakarta POI library, LOCI fork | |||
| poi-loci.jar | Apache | For OLE-based formats (zvi, oib, ipw, cxd) | |
| MDB Tools project Java port, LOCI fork | |||
| mdbtools-java.jar | LGPL | For Olympus CellR and Zeiss LSM metadata (mdb) | |
| JAI Image I/O Tools pure Java implementation, LOCI fork | |||
| jai_imageio.jar | BSD | For JPEG2000-based formats (nd2, jp2) | |
| NetCDF Java library | |||
| netcdf-4.0.jar | LGPL | For HDF5-based formats (Imaris 5.5, MINC MRI) | |
| QuickTime for Java | |||
| QTJava.zip | Commercial | For additional QuickTime codecs | |
See the list in the LOCI Software build file for a complete and up-to-date list of all optional libraries, which can all be found in our Git repository.
| Examples of usage | |
|---|---|
Simple_Read |
A simple ImageJ plugin demonstrating how to use Bio-Formats to read files into ImageJ (see also Using Bio-Formats with ImageJ) |
Read_Image |
An ImageJ plugin that uses Bio-Formats to build up an image stack, reading image planes one by one (see also Using Bio-Formats with ImageJ). |
Mass_Importer |
A plugin for ImageJ that demonstrates how to open all image files in a directory using Bio-Formats, grouping files with similar names to avoiding opening the same dataset more than once (see also Using Bio-Formats with ImageJ) |
GetPhysicalMetadata |
A command line example demonstrating how to extract physical dimensions from a file |
PrintTimestamps |
A command line example demonstrating how to extract timestamps from a file |
MinimumWriter |
A command line utility demonstrating the minimum amount of metadata needed to write a file |
| Export examples | Very simple source code and narrative documentation for exporting and converting files. |
ImageConverter |
A sophisticated command line tool for converting between formats |
ImageInfo |
A sophisticated command line utility for thoroughly reading an input file, printing some information about it, and displaying the pixels onscreen using the Bio-Formats viewer |
| Other developer links | |
|---|---|
| Source Code | How to access the source code from our Git 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 |
| GitHub | Browse the source code and project history online |
A Note on Java Web Start (loci_tools.jar vs. bio-formats.jar)
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 loci-tools.libraries variable of the ant/toplevel.properties file of the distribution. You can also read our notes about each in the source distribution's Ant build.xml script.