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.
This section is out of date, and in need of update.
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.
LOCI's 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.
The following program extracts comments from TIFF files, and outputs what
it finds to the standard output stream. It requires the Bio-Formats library
(bio-formats.jar).
TiffComment.java
//
// TiffComment.java
//
import loci.formats.TiffTools;
/** Extracts the comment from the first IFD of the given TIFF file(s). */
public class TiffComment {
public static void main(String[] args) throws Exception {
if (args.length == 0) {
System.out.println("Usage: java TiffComment file1 file2 ...");
return;
}
for (int i=0; i<args.length; i++) {
String comment = TiffTools.getComment(args[i]);
if (comment != null) System.out.println(comment);
}
}
}
The key lines are the construction of a
loci.formats.RandomAccessStream around the file, acquisition
of the first IFD as a Hashtable object with
TiffTools.getFirstIFD(in) and extraction of the comment string
using TiffTools.getIFDValue(ifd, TiffTools.IMAGE_DESCRIPTION).
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
(bio-formats.jar).
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 first IFD
System.out.println("Reading " + f + " ");
RandomAccessStream fin = new RandomAccessStream(f);
Hashtable ifd = TiffTools.getFirstIFD(fin);
fin.close();
if (ifd == null) System.out.println("Warning: first IFD is null!");
// extract TIFF comment from IFD
String ome = (String)
TiffTools.getIFDValue(ifd, TiffTools.IMAGE_DESCRIPTION);
System.out.println("[done]");
// display comment, and prompt for changes
System.out.println("Comment =");
System.out.println(ome);
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]");
}
}
}
Similar to the TiffComment.java example above, the comment is acquired
using TiffTools.getFirstIFD(fin). The major addition to this
example is the use of TiffTools.overwriteComment(args[i], xml)
to update the comment string.
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 library
(bio-formats.jar), as well as
the Java OME-XML library
(ome-java.jar).
ConvertToOmeTiff.java
//
// ConvertToOmeTiff.java
//
import java.awt.image.BufferedImage;
import loci.formats.ImageReader;
import loci.formats.ome.OMEXMLMetadata;
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
OMEXMLMetadata omexmlMeta = new OMEXMLMetadata();
reader.setMetadataStore(omexmlMeta);
reader.setId(id);
// configure OME-TIFF writer
writer.setMetadataRetrieve(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 Java OME-XML 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 library
(bio-formats.jar), as well as the
Java OME-XML library
(ome-java.jar).
EditImageName.java
//
// EditImageName.java
//
import loci.formats.ImageReader;
import loci.formats.MetadataTools;
import loci.formats.ome.OMEXMLMetadata;
/** 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(new OMEXMLMetadata());
String id = args[0];
System.out.print("Reading metadata ");
reader.setId(id);
OMEXMLMetadata omexmlMeta = (OMEXMLMetadata) reader.getMetadataStore();
System.out.println(" [done]");
// get image name
Integer zero = new Integer(0);
String name = omexmlMeta.getImageName(zero);
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.setImage(name, null, null, zero);
System.out.println("Updated Image name = " + name);
// output full OME-XML block
System.out.println("Full OME-XML dump:");
System.out.println(MetadataTools.getOMEXML(omexmlMeta));
}
}
As in the ConvertToOmeTiff.java example above, we attach an
OMEXMLMetadata 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(zero) 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, null, null, zero). The nulls
indicate that no change should be made to those metadata fields, and 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: Thursday, October 11, 2007
