If you wish to make use of Bio-Formats within your own software, you can download formats-gpl.jar to use it as a library. Just add formats-gpl.jar to your CLASSPATH or build path. You will also need common.jar for common I/O functions, ome-xml.jar for metadata standardization, and SLF4J for logging.
There are also 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 | ome-poi.jar | Apache | OME fork; for OLE-based formats (zvi, oib, ipw, cxd) |
| MDB Tools | mdbtools-java.jar | LGPL | Java port, OME fork; for Olympus CellR and Zeiss LSM metadata (mdb) |
| JAI Image I/O Tools | jai_imageio.jar | BSD | Pure Java implementation, OME fork; for JPEG2000-based formats (nd2, jp2) |
| NetCDF | netcdf-4.3.19.jar | LGPL | Java library; for HDF5-based formats (Imaris 5.5, MINC MRI) |
| QuickTime for Java | QTJava.zip | Commercial | For additional QuickTime codecs |
See the list in the Bio-Formats toplevel build file for a complete and up-to-date list of all optional libraries, which can all be found in our Git repository.
MinimumWriter - A command line utility demonstrating the minimum amount of metadata needed to write a file.
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.
PrintTimestamps - A command line example demonstrating how to extract timestamps from a file.
Simple_Read - A simple ImageJ plugin demonstrating how to use Bio-Formats to read files into ImageJ (see ImageJ overview).
Read_Image - An ImageJ plugin that uses Bio-Formats to build up an image stack, reading image planes one by one (see ImageJ overview).
Mass_Importer - A simple 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 ImageJ overview).
To use Bio-Formats with your Java Web Start application, we recommend using formats-gpl.jar rather than bioformats_package.jar—the latter is merely a bundle of formats-gpl.jar plus all its optional dependencies.
The bioformats_package.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 formats-gpl.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’ 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 bioformats_package.jar directly is not the best approach, since every time Bio-Formats is updated, the server would need to feed another 15+ 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 formats-gpl.jar and the optional dependencies separate, only a <1 MB JAR needs to be updated when formats-gpl.jar changes.
As a developer, you have the option of packaging formats-gpl.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 formats-gpl.jar that excludes certain classes, if you like.
For an explicit enumeration of all the optional libraries included in bioformats_package.jar, see the package.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.
