| CONTENTS | PREV | NEXT | JavaTM Image I/O API Guide |
Data stored in an image file that does not represent actual pixel values is referred to as metadata.The javax.imageio.metadatapackage 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.getStreamMetadataandgetImageMetadata(int imageIndex)methods. These return an object that implements theIIOMetadatainterface. The actual class type of the returned object is up to theImageReader, 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,
IIOMetadataobjects 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 (Stringvalues 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 theIIOMetadatainterface. The second will be a highly plug-in specific format that exposes all of the internal structure of theIIOMetadataobject 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 thegetNativeMetadataFormatNamemethod of theIIOMetadataobject returned by the reader (advanced users may call a method of the same name on theImageReaderSpiobject 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 callinggetMetadataFormatNames.The contents of an
IIOMetadataobject may be accessed in the form of a tree of XMLNodeobjects by calling itsgetAsTreemethod. This method takes aStringargument 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("/>");
}
}
ExecutingdisplayMetadataon the metadata from the standard PNG test imagehttp://www.schaik.com/pngsuite/ccwn2c08.pngyields 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 containsIHDR,cHRM, andgAMAchunks. 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.
IIOMetadataFormat Interface
An
IIOMetadataFormatobject 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 anObjectvalue that may be stored at a node of a given type. In XML terms, the information provided by theIIOMetadataFormatinterface 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 anIIOMetadataFormatas 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. TheIIOMetadataFormatindicates the class type and optionally the legal enumerated values or a range of values for theObject. 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.
IIOMetadataFormatoccupies 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
IIOMetadataFormatmight 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.