If you wish to make use of Bio-Formats within your own software it can be included as a dependency in any Maven project. The dependency can be added to the project pom file and should include the desired Bio-Formats version. Using bioformats_package as the artifactId will include the complete Bio-Formats package, or individual components can be chosen as desired.
<dependency>
<groupId>ome</groupId>
<artifactId>bioformats_package</artifactId>
<version>5.3.0</version>
</dependency>
In order to include this Bio-Formats dependency a custom repository must also be added to the project pom or $user.home/.m2/settings.xml. The repositories element is inherited so for a group of projects the repositories element can be defined at the top of your inheritance chain.
<repositories>
<repository>
<id>ome</id>
<name>Bio-Formats Repo</name>
<url>http://artifacts.openmicroscopy.org/artifactory/maven</url>
</repository>
</repositories>
Alternatively Bio-Formats can be used by including its component jar files. 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.
The complete list of current dependencies is as follows:
As described in Versioning policy, the minor version number of a Bio-Formats release will always be increased if the version of a non-OME/external dependency is bumped.
MultiFileExample - Simple example of how to open multiple files simultaneously.
ParallelRead - Reads all files in given directory in parallel, using a separate thread for each.
ReadWriteInMemory - Tests the Bio-Formats I/O logic to and from byte arrays in memory.
MinimumWriter - A command line utility demonstrating the minimum amount of metadata needed to write a file.
TiledExport - Shows how to convert a file one tile at a time, instead of one plane at a time (needed for very large images).
GetPhysicalMetadata - Uses Bio-Formats to extract some basic standardized (format-independent) metadata.
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.
PrintLensNA - Uses Bio-Formats to extract lens numerical aperture in a format-independent manner from a dataset.
PrintROIs - A simple example of how to retrieve ROI data parsed from a file.
SubResolutionExample - Demonstration of the sub-resolution API.
EditImageName - Edits the given file’s image name (but does not save back to disk).
EditTiffComment - Allows raw user TIFF comment editing for the given TIFF files.
writeMapAnnotations - Example method to write MapAnnotations to the ome-xml.
CommentSurgery - Edits a TIFF ImageDescription comment, particularly the OME-XML comment found in OME-TIFF files.
ImageConverter - A simple command line tool for converting between formats.
ConvertToOmeTiff - Converts the given files to OME-TIFF format.
WritePreCompressedPlanes - Writes the pixels from a set of JPEG files to a single TIFF. The pixel data is used as-is, so no decompression or re-compression is performed.
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.