OME at LOCI –
OME-TIFF – Example source code
This page discusses some common operations related to the
OME-TIFF format, and gives 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:
- Read in the 8-byte header.
- Determine if the file is a valid TIFF, and if so, whether its byte
order is big endian or little endian. The first pair of bytes must
equal "II" (little endian, "Intel") or "MM" (big endian, "Motorola").
The next pair must equal 42 with the proper endianness.
- Determine the byte offset into the file of the first IFD. This
information is stored in bytes 4-7, with the proper endianness.
- Skip to the first IFD, and read in the IFD's header.
- Iterate through the directory entries looking for the
ImageDescription (270) tag.
- Jump to the offset given by the ImageDescription entry, and read the
number of bytes indicated by the entry.
- Convert the bytes to an ASCII string.
The Bio-Formats command line tools include
a program, tiffcomment, that performs these steps using the
getComment(String) method of
loci.formats.TiffTools.
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.
We have included a method within Bio-Formats,
TiffTools.overwriteIFDValue(), that 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.
EditTiff.java
//
// EditTiff.java
//
import java.io.*;
import java.util.Hashtable;
import loci.formats.RandomAccessStream;
import loci.formats.TiffTools;
/** Allows raw user TIFF comment editing for the given TIFF files. */
public class EditTiff {
public static void main(String[] args) throws Exception {
if (args.length == 0) {
System.out.println("Usage: java EditTiff file1 file2 ...");
return;
}
BufferedReader cin = new BufferedReader(new InputStreamReader(System.in));
for (int i=0; i<args.length; i++) {
String f = args[i];
// read comment
System.out.println("Reading " + f + " ");
String comment = TiffTools.getComment(f);
// or if you already have the file open for random access, you can use:
// RandomAccessStream fin = new RandomAccessStream(f);
// Hashtable ifd = TiffTools.getFirstIFD(fin);
// String comment = (String)
// TiffTools.getIFDValue(ifd, TiffTools.IMAGE_DESCRIPTION);
// fin.close();
System.out.println("[done]");
// display comment, and prompt for changes
System.out.println("Comment =");
System.out.println(comment);
System.out.println("Enter new comment (no line breaks):");
String xml = cin.readLine();
System.out.print("Saving " + f);
// save results back to the TIFF file
TiffTools.overwriteComment(args[i], xml);
// or if you already have the file open for random access, you can use:
// RandomAccessFile raf = new RandomAccessFile(args[i], "rw");
// TiffTools.overwriteIFDValue(raf, 0, TiffTools.IMAGE_DESCRIPTION, xml);
// raf.close();
System.out.println(" [done]");
}
}
}
The comment is acquired using TiffTools.getFirstIFD(fin) and
TiffTools.getIFDValue(ifd, TiffTools.IMAGE_DESCRIPTION).
(An even simpler method, TiffTools.getComment(f), could also
be used.) The comment string is updated with
TiffTools.overwriteComment(args[i], xml).
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 following program converts the files given on the command line into
OME-TIFF format. It requires the Bio-Formats
and OME-Java libraries.
ConvertToOmeTiff.java
//
// ConvertToOmeTiff.java
//
import java.awt.image.BufferedImage;
import loci.formats.ImageReader;
import loci.formats.MetadataTools;
import loci.formats.meta.MetadataRetrieve;
import loci.formats.meta.MetadataStore;
import loci.formats.out.OMETiffWriter;
/** Converts the given files to OME-TIFF format. */
public class ConvertToOmeTiff {
public static void main(String[] args) throws Exception {
if (args.length == 0) {
System.out.println("Usage: java ConvertToOmeTiff file1 file2 ...");
return;
}
ImageReader reader = new ImageReader();
OMETiffWriter writer = new OMETiffWriter();
for (int i=0; i<args.length; i++) {
String id = args[i];
int dot = id.indexOf(".");
String outId = (dot >= 0 ? id.substring(0, dot) : id) + ".ome.tif";
System.out.print("Converting " + id + " to " + outId + " ");
// record metadata to OME-XML format
MetadataStore omexmlMeta = MetadataTools.createOMEXMLMetadata();
reader.setMetadataStore(omexmlMeta);
reader.setId(id);
// configure OME-TIFF writer
writer.setMetadataRetrieve((MetadataRetrieve) omexmlMeta);
writer.setId(outId);
// write out image planes
int imageCount = reader.getImageCount();
for (int j=0; j<imageCount; j++) {
BufferedImage plane = reader.openImage(j);
// write plane to output file
writer.saveImage(plane, j == imageCount - 1);
System.out.print(".");
}
writer.close();
reader.close();
System.out.println(" [done]");
}
}
}
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 (at heart an XML DOM object in
memory) 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.
In some cases, it is useful to extract specific parameters or tweak
certain values in a dataset's OME-XML metadata block. We are actively
developing a module, OME Notes, offering this
ability to end users in a graphical user interface. It uses Bio-Formats
OMEXMLMetadata objects (see the "Converting other formats to
OME-TIFF" example above), and its backing
org.openmicroscopy.xml.OMENode objects, which are
part of OME's OME-Java library.
Working with XML is a major topic unto itself; here we provide a brief
example of the OMEXMLMetadata class (which implements the
MetadataStore and MetadataRetrieve interfaces)
to greatly simplify OME-XML-related development tasks.
The following program edits the "image name" metadata value for the file
given on the command line. It requires the
Bio-Formats and
OME-Java libraries.
EditImageName.java
//
// EditImageName.java
//
import loci.formats.ImageReader;
import loci.formats.MetadataTools;
import loci.formats.meta.MetadataRetrieve;
import loci.formats.meta.MetadataStore;
/** Edits the given file's image name (but does not save back to disk). */
public class EditImageName {
public static void main(String[] args) throws Exception {
if (args.length != 1) {
System.out.println("Usage: java EditImageName file");
return;
}
ImageReader reader = new ImageReader();
// record metadata to OME-XML format
reader.setMetadataStore(MetadataTools.createOMEXMLMetadata());
String id = args[0];
System.out.print("Reading metadata ");
reader.setId(id);
MetadataStore omexmlMeta = reader.getMetadataStore();
System.out.println(" [done]");
// get image name
String name = ((MetadataRetrieve) omexmlMeta).getImageName(0);
System.out.println("Initial Image name = " + name);
// change image name (reverse it)
char[] arr = name.toCharArray();
for (int i=0; i<arr.length/2; i++) {
int i2 = arr.length - i - 1;
char c = arr[i];
char c2 = arr[i2];
arr[i] = c2;
arr[i2] = c;
}
name = new String(arr);
// save altered name back to OME-XML structure
omexmlMeta.setImageName(name, 0);
System.out.println("Updated Image name = " + name);
// output full OME-XML block
System.out.println("Full OME-XML dump:");
String xml = MetadataTools.getOMEXML((MetadataRetrieve) omexmlMeta);
System.out.println(xml);
}
}
As in the ConvertToOmeTiff.java example above, we attach an
OME-XML MetadataStore object to the reader to extract OME-XML
metadata from the input file. We obtain the current image name (if any)
by calling the omexmlMeta.getImageName(0) method. The zero
indicates the Image within the OME-XML block about which we are interested;
in this case, we are asking for the name of the first Image.
After updating the name somehow (in our case, reversing the string),
we write the updated name back into the metadata structure via a call to
omexmlMeta.setImage(name, 0). Once again the zero indicates
that we wish to update the first Image.
Lastly, the MetadataTools utility class contains a number of
useful methods for working with Bio-Formats metadata objects (i.e.,
MetadataStore and MetadataRetrieve
implementations), including the getOMEXML method for easily
extracting an OME-XML string from a MetadataRetrieve object
(which we utilize here), as well the convertMetadata method
for transcoding between metadata object implementations.
Last update: Friday, May 30, 2008
