The Java™ Image I/O API

• Daniel Rice

• Staff Engineer

  Sun Microsystems, Inc.

The Java Image I/O API—Outline

• What Is It?

• Using the API

• Working With Metadata

• Writing Plug-Ins

• Getting More Information

• Q&A

What Is the Java™ Image I/O API?

• A new API for the Java 2 Platform, Standard Edition, version 1.4 (“JDK 1.4”)

• Provides a pluggable architecture for new image formats

• Uses image datatypes based on the Java2D™ API

• GIF (read only), JPEG, PNG are standard

• Simple, high-level APIs for ease of use; lower level APIs for more control

What Is the Java™ Image I/O API?

• Strong support for Metadata

  • Metadata is all non-pixel data
  • XML Document Object Model (DOM) tree
    • Lossless, format-specific representation
    • Lossy, format-neutral representation

• Migration path for com.sun.image.jpeg classes, Java Advanced Imaging API codecs

Using the API—Outline

• The javax.imageio.ImageIO class

• ImageReader and ImageReadParam

• ImageWriter and ImageWriteParam

• ImageInputStream and ImageOutputStream

• Code Examples

Using the API— javax.imageio.ImageIO Class

• javax.imageio.ImageIO contains static methods for simple I/O:

  BufferedImage read(File) (also takes an InputStream or URL)
  • Auto-detects format
  void write(RenderedImage,String formatName,File) (also takes an OutputStream)
  • Most apps will use BufferedImage

Using the API— javax.imageio.ImageIO (Cont.)

• Query for information about plug-ins:

  get{Read,Writ}erFormatNames

• Query for plug-ins:

  getImage{Read,Writ}ersByFormatName
  getImage{Read,Writ}ersBySuffix
  getImage{Read,Writ}ersByMIMEType
  getImageReaders(Object input)
  

• Call scanForPlugins to load plug-ins from CLASSPATH

Using the API—ImageIO Examples

File infile = new File("image.png");
BufferedImage im =
ImageIO.read(infile);

File outfile = new File("image.jpg");
ImageIO.write(im, "jpg", outfile);

String[] reader_names =
ImageIO.getReaderFormatNames();

String[] writer_names =
ImageIO.getWriterFormatNames();

Iterator iter =
getImageReadersBySuffix("png");

Using the API—ImageReader

• Locate an ImageReader for a File:

  

• Use ImageReader to query the file, get an image:

  

Using the API—ImageReader (Cont.)

• getNumImages(boolean allowSearch)

  • May require scanning the entire input
  • Parameter disables scanning

• get{Width,Height}(imageIndex)

• getNumThumbnails(imageIndex)

• readThumbnail

• readTile, readRaster

• Add/remove event listeners

Using the API—ImageReadParam

• Read only a given rectangle from the image

• Read every nth pixel (subsampling)

• Read only certain bands, progressive passes

• Write into a given portion of the destination

• Every ImageReader must implement

Using the API—ImageWriter

• Write images, thumbnails, metadata

• Add/remove event listeners

• Optional features:

  • Insert an image into a sequence
  • Replace a portion of an image
  • Replace metadata
  • Not supported by standard (JPEG, PNG) writers

Using the API—ImageWriteParam

• Write only a rectangle of the source image

• Subsample source image

• Optional features:

  • Set compression type, quality
  • Set tiling parameters

Using the API—ImageInputStream

• Readers and writers use ImageInputStream and ImageOutputStream classes

  • Handle arrays of primitive types, bits
  • Big- or little-endian layouts
  • Allow seeking backwards and forwards
  • Cached in memory or a temp file

• ImageIO.createImageInputStream

  • File, RandomAccessFile, InputStream args supported by default

Using the API— ImageOutputStream

• ImageIO.createImageOutputStream

  • File, RandomAccessFile, OutputStream args supported by default

• Extends ImageInputStream so writers need not represent entire file contents internally (backpatching)

Using the API—Example: Creating a “Contact Sheet”

Using the API—Writing Thumbnails

Working With Metadata—Outline

• Definitions

• Metadata DOM Trees

• Format-Independent Metadata

Working With Metadata— Definitions

• Metadata is “everything that's not pixels”

• PNG “chunks,” JPEG “markers,” TIFF “tags,”…

• Per-stream and per-image metadata

• In general, a tree of keyword/value pairs

• Maps well onto an XML DOM structure

  • See org.w3c.dom package

Working With Metadata— Sample Metadata DOM Tree

• PNG file with IHDR, cHRM, and gAMA chunks

• IDAT chunks contain pixel data and are not included in metadata

  

Working With Metadata— Sample Metadata DOM Tree

Working With Metadata— Traversing a Format-Specific Tree

• Retrieve “gamma” from a PNG image:

  

Working With Metadata— Format-Independent Metadata

• Every image format has its own metadata format, app must know details

• The API defines a standard format containing common information

• Usually some information loss involved

• In the future, could support new metadata formats such as DIG35, EXIF, ???

Working With Metadata— Traversing a Format-Neutral Tree

• Retrieve “gamma” from any image:

  

Writing Plug-Ins—Outline

• Implementing ImageReader

• Implementing ImageWriter

• Implementing IIOMetadata

• Implementing an ImageTranscoder

Writing Plug-Ins— Implementing ImageReader

• Essential methods:

  • int getNumImages(boolean allowSearch)
  • int get{Width,Height}(imageIndex)
  • Iterator getImageTypes(imageIndex)
  • IIOMetadata getStreamMetadata()
  • IIOMetadata getImageMetadata(imageIndex)
  • BufferedImage read(imageIndex, ImageReadParam)

Writing Plug-Ins— Implementing ImageWriter

• Essential methods:

  • convertImageMetadata
  • convertStreamMetadata
  • getDefaultImageMetadata
  • getDefaultStreamMetadata
  • write(IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param)

Writing Plug-Ins— Implementing IIOMetadata

• Essential methods:

  • getAsTree(formatName)
  • isReadOnly
  • mergeTree
  • reset

Writing Plug-Ins— ImageTranscoders

• An interface for metadata conversion

• Each transcoder understands two or more different metadata formats

• None supplied by default

• Highly application-specific

Summary

• Use ImageIO methods for simple things

• Query for readers and writers

• Use param objects for more control

• Use metadata objects for non-pixel info

• Extend the API with new readers and writers, transcoders

Getting More Information

• Join our BOF this evening!

  • 7 p.m., Marriot Salon 1-2

• Subscribe to java-imageio-interest @java.sun.com

• Send comments to jsr015-comments @java.sun.com

• View mailing list archives at: http:// archives.java.sun.com/archives/ java-imageio-interest.html