This section discusses some common operations related to the OME-TIFF format, and provides example source code in Java for performing them. We strongly recommend you read and understand the OME-TIFF specification before attempting to deploy any of the following code.
The Bio-Formats library provides a lot of functionality related to OME-XML and OME-TIFF, to ease the burden of file format handling and conversions. Rather than offer source code that performs all of the above actions on its own, we instead offer examples that utilize Bio-Formats, for more robust and succinct operation.
To extract a comment from a TIFF file without the aid of a TIFF library, the following steps are required:
The Bio-Formats command line tools include a program, tiffcomment, that performs these steps using the getComment(String) method of TiffParser. You can produce a nicely formatted OME-XML string from an OME-TIFF file with:
tiffcomment file.ome.tif | xmlindent
Modifying a TIFF comment can be tricky because the length of the altered OME-XML string is unlikely to be the same as before. As such, the IFD’s ImageDescription directory entry must be updated to reflect the new byte count. In addition, if the string is longer than before, it will no longer fit at its old offset, unless the comment was at the end of the file, so the entry’s offset might need to change as well.
The TiffSaver.overwriteIFDValue() method within Bio-Formats, efficiently alters a directory entry with a minimum of waste. The count field of the entry is intelligently updated to match the new length. If the new length is longer than the old length, it appends the new data to the end of the file and updates the offset field; if not, or if the old data is already at the end of the file, it overwrites the old data in place.
The following program extracts comments from TIFF files, prompts the user to alter the comments on the command line, and writes updated comments back to the files. It requires the Bio-Formats library.
The comment string is acquired using new TiffParser(f).getComment(), and updated with
TiffSaver saver = new TiffSaver(f); RandomAccessInputStream in = new RandomAccessInputStream(f); saver.overwriteComment(in, xml);
To quickly edit an OME-TIFF files comment on the command line use tiffcomment -edit filename.ome.tiff from the Bio-Formats command line tools.
One of the major goals of Bio-Formats is to standardize the metadata from all supported third-party formats into OME-XML. Doing so makes conversion to OME-TIFF very straightforward—just write the pixels to TIFF however you want (e.g. with libtiff), and store the converted OME-XML metadata into the TIFF comment. The complicated part is doing the conversion from proprietary third-party metadata into OME-XML—a task that Bio-Formats greatly simplifies.
The code functions by creating an ImageReader for reading the input files’ image planes sequentially, and an OMETiffWriter for writing the planes to OME-TIFF files on disk. The OME-XML is generated by attaching an OMEXMLMetadata object to the reader, such that when each file is initialized, the object is automatically populated with the converted metadata. The OMEXMLMetadata object is then fed to the OMETiffWriter, which extracts the appropriate OME-XML string and embeds it into the OME-TIFF file properly.
While our ultimate goal is for the Bio-Formats metadata conversion facility to be a reference implementation for conversion of third-party formats into OME-XML and OME-TIFF, please be aware that the current code is a work in progress. We would greatly value suggestions and assistance regarding the OME-XML conversion relating to any specific format. If there is any metadata missing or converted incorrectly, please let us know.