Java Image I/O API Guide: 3 - Writing Image I/O Applications

3.5 Handling Metadata

Data stored in an image file that does not represent actual pixel values is referred to as metadata. The javax.imageio.metadata package contains classes and interfaces for accessing metadata.

Metadata may contain complex, hierarchical structures. The Java XML Document Object Model (DOM) API is used to represent these structures, allowing developers to leverage their knowledge of these interfaces.

The Image I/O API differentiates between stream metadata, which is associated with all images stored in an image file, and image metadata which is associated with a single image. For image formats that contain a single image, only image metadata is used.

Metadata may be obtained by calling the ImageReader.getStreamMetadata and getImageMetadata(int imageIndex) methods. These return an object that implements the IIOMetadata interface. The actual class type of the returned object is up to the ImageReader, and will usually be a unique class used only by that reader. This object should be designed to store as much of the metadata allowed by the format as possible, as losslessly as possible. However, this fidelity to the specifications of the image format comes at a cost, as access to the metadata becomes format-specific.

In order to allow access to the metadata without the need for format-specific application code, IIOMetadata objects expose their internal information in the form of an XML DOM structure, which is essentially a tree of nodes of various types that may contain a set of attributes (String values accessed by name), and which may reference a set of child nodes.

A single plug-in may support multiple document formats, which are distinguished by a format name. Typically, at least two formats will be supported by a given plug-in. The first is a common, plug-in neutral format called com.sun.imageio_1.0, which is defined in the class comment for the IIOMetadata interface. The second will be a highly plug-in specific format that exposes all of the internal structure of the IIOMetadata object in the form of a DOM. The latter format is referred to as the native format of the plug-in; its name may be determined by calling the getNativeMetadataFormatName method of the IIOMetadata object returned by the reader (advanced users may call a method of the same name on the ImageReaderSpi object used to instantiate the reader. The latter approach is useful for selecting a plug-in based on its support for a particular format). The names of all of the supported document formats may be determined similarly by calling getMetadataFormatNames.

The contents of an IIOMetadata object may be accessed in the form of a tree of XML Node objects by calling its getAsTree method. This method takes a String argument which is the name of one of the document formats supported by the plug-in. This document may then be manipulated as a standard XML DOM tree.

As an example, to print the contents of an XML DOM tree, the following code may be used:

public void displayMetadata(Node root) {
        displayMetadata(root, 0);
}

void indent(int level) {
        for (int i = 0; i < level; i++) {
                System.out.print("  ");
        }
} 

void displayMetadata(Node node, int level) {
        indent(level); // emit open tag
        System.out.print("<" + node.getNodeName());
        NamedNodeMap map = node.getAttributes();
        if (map != null) { // print attribute values
                int length = map.getLength();
                for (int i = 0; i < length; i++) {
                        Node attr = map.item(i);
                        System.out.print(" " + attr.getNodeName() +
                                         "=\"" + attr.getNodeValue() + "\"");
                }
        }

        Node child = node.getFirstChild();
        if (child != null) {
                System.out.println(">"); // close current tag
                while (child != null) { // emit child tags recursively
                        displayMetadata(child, level + 1);
                        child = child.getNextSibling();
                }
                indent(level); // emit close tag
                System.out.println("</" + node.getNodeName() + ">");
        } else {
                System.out.println("/>");
        }
}

Executing displayMetadata on the metadata from a PNG test image yields the output:

<com.sun.imageio.png_1.0>
  <IHDR width="32" height="32" bitDepth="8" colorType="RGB"
compressionMethod="deflate" filterMethod="adaptive" interlaceMethod="none"/>
  <cHRM whitePointX="31270" whitePointY="32900" redX="64000" redY="33000"
greenX="30000" greenY="60000" blueX="15000" blueY="6000"/>
  <gAMA value="100000"/>
</com.sun.imageio.png_1.0>

We see that the image contains IHDR, cHRM, and gAMA chunks. The interpretation of the attribute values requires an understanding of the PNG format; however, it is still possible for an application that does not understand PNG internals to display the values and allow them to be edited interactively.

3.5.1 The `IIOMetadataFormat` Interface

An IIOMetadataFormat object is used to describe the legal structure of a metadata document format. It constrains the types of nodes that may appear, the types of nodes that may be children of a node of a given type, the names and data types of the attributes that may appear at a node of a given type, and the audiotape of an Object value that may be stored at a node of a given type. In XML terms, the information provided by the IIOMetadataFormat interface is somewhere in between a DTD (Document Type Definition), which gives information about node types, children, and attributes, and an XML Schema, which provides detailed information about data types.

For simplicity, only a subset of legal DTD structures can be described by IIOMetadataFormat. For example, the children of a node may be defined in an IIOMetadataFormat as a sequence in which each child must appear once (a, b, c), a sequence in which each child is optional (a?, b?, c?), a choice of a single child (a | b | c), or a repetition of a single node type (a)*, whereas a DTD allows many more combinations.

A node may not contain any textual data, but may contain a reference to an arbitrary Object. The IIOMetadataFormat indicates the class type and optionally the legal enumerated values or a range of values for the Object. Arrays are supported as well.

A DTD does not allow any attribute data types other than character strings; an XML Schema allows extremely complex data types to be built up from simpler ones. IIOMetadataFormat occupies a middle ground; it allows attributes to be constrained to belong to one of a predefined set of simple data types, including integers, floating-point decimals, and dates. Lists of these data types are also allowed.

Since an IIOMetadataFormat might be used to automatically construct a user interface for displaying and editing metadata, restricted the set of legal structures greatly simplifies the mapping between formats and user interface designs.

CONTENTS | PREV | NEXT

3.5 Handling Metadata

3.5.1 The IIOMetadataFormat Interface

3.5.1 The `IIOMetadataFormat` Interface