org.jboss.dna.sequencer.image
Class ImageMetadata

java.lang.Object
  extended by org.jboss.dna.sequencer.image.ImageMetadata

public class ImageMetadata
extends Object

Get file format, image resolution, number of bits per pixel and optionally number of images, comments and physical resolution from JPEG, GIF, BMP, PCX, PNG, IFF, RAS, PBM, PGM, PPM and PSD files (or input streams).

Use the class like this:

 ImageMetadata ii = new ImageMetadata();
 ii.setInput(in); // in can be InputStream or RandomAccessFile
 ii.setDetermineImageNumber(true); // default is false
 ii.setCollectComments(true); // default is false
 if (!ii.check()) {
     System.err.println("Not a supported image file format.");
     return;
 }
 System.out.println(ii.getFormatName() + ", " + ii.getMimeType() + ", " + ii.getWidth() + " x " + ii.getHeight() + " pixels, "
                    + ii.getBitsPerPixel() + " bits per pixel, " + ii.getNumberOfImages() + " image(s), "
                    + ii.getNumberOfComments() + " comment(s).");
 // there are other properties, check out the API documentation
 
You can also use this class as a command line program. Call it with a number of image file names and URLs as parameters:
   java ImageMetadata *.jpg *.png *.gif http://somesite.tld/image.jpg
 
or call it without parameters and pipe data to it:
   java ImageMetadata < image.jpg  
 

Known limitations:

Requirements:

The latest version can be found at http://schmidt.devlib.org/image-info/.

Written by Marco Schmidt.

This class is contributed to the Public Domain. Use it at your own risk.

History:

Author:
Marco Schmidt

Field Summary
static int FORMAT_BMP
          Return value of getFormat() for BMP streams.
static int FORMAT_GIF
          Return value of getFormat() for GIF streams.
static int FORMAT_IFF
          Return value of getFormat() for IFF streams.
static int FORMAT_JPEG
          Return value of getFormat() for JPEG streams.
static int FORMAT_PBM
          Return value of getFormat() for PBM streams.
static int FORMAT_PCX
          Return value of getFormat() for PCX streams.
static int FORMAT_PGM
          Return value of getFormat() for PGM streams.
static int FORMAT_PNG
          Return value of getFormat() for PNG streams.
static int FORMAT_PPM
          Return value of getFormat() for PPM streams.
static int FORMAT_PSD
          Return value of getFormat() for PSD streams.
static int FORMAT_RAS
          Return value of getFormat() for RAS streams.
 
Constructor Summary
ImageMetadata()
           
 
Method Summary
 boolean check()
          Call this method after you have provided an input stream or file using setInput(InputStream) or setInput(DataInput).
 int getBitsPerPixel()
          If check() was successful, returns the image's number of bits per pixel.
 String getComment(int index)
          Returns the index'th comment retrieved from the file.
 int getFormat()
          If check() was successful, returns the image format as one of the FORMAT_xyz constants from this class.
 String getFormatName()
          If check() was successful, returns the image format's name.
 int getHeight()
          If check() was successful, returns one the image's vertical resolution in pixels.
 String getMimeType()
          If check() was successful, returns a String with the MIME type of the format.
 int getNumberOfComments()
          If check() was successful and setCollectComments(boolean) was called with true as argument, returns the number of comments retrieved from the input image stream / file.
 int getNumberOfImages()
          Returns the number of images in the examined file.
 int getPhysicalHeightDpi()
          Returns the physical height of this image in dots per inch (dpi).
 float getPhysicalHeightInch()
          If check() was successful, returns the physical width of this image in dpi (dots per inch) or -1 if no value could be found.
 int getPhysicalWidthDpi()
          If check() was successful, returns the physical width of this image in dpi (dots per inch) or -1 if no value could be found.
 float getPhysicalWidthInch()
          Returns the physical width of an image in inches, or -1.0f if width information is not available.
 int getWidth()
          If check() was successful, returns one the image's horizontal resolution in pixels.
 boolean isProgressive()
          Returns whether the image is stored in a progressive (also called: interlaced) way.
static void main(String[] args)
          To use this class as a command line application, give it either some file names as parameters (information on them will be printed to standard output, one line per file) or call it with no parameters.
 void setCollectComments(boolean newValue)
          Specify whether textual comments are supposed to be extracted from input.
 void setDetermineImageNumber(boolean newValue)
          Specify whether the number of images in a file is to be determined - default is false.
 void setInput(DataInput dataInput)
          Set the input stream to the argument stream (or file).
 void setInput(InputStream inputStream)
          Set the input stream to the argument stream (or file).
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FORMAT_JPEG

public static final int FORMAT_JPEG
Return value of getFormat() for JPEG streams. ImageMetadata can extract physical resolution and comments from JPEGs (only from APP0 headers). Only one image can be stored in a file. It is determined whether the JPEG stream is progressive (see isProgressive()).

See Also:
Constant Field Values

FORMAT_GIF

public static final int FORMAT_GIF
Return value of getFormat() for GIF streams. ImageMetadata can extract comments from GIFs and count the number of images (GIFs with more than one image are animations). It is determined whether the GIF stream is interlaced (see isProgressive()).

See Also:
Constant Field Values

FORMAT_PNG

public static final int FORMAT_PNG
Return value of getFormat() for PNG streams. PNG only supports one image per file. Both physical resolution and comments can be stored with PNG, but ImageMetadata is currently not able to extract those. It is determined whether the PNG stream is interlaced (see isProgressive()).

See Also:
Constant Field Values

FORMAT_BMP

public static final int FORMAT_BMP
Return value of getFormat() for BMP streams. BMP only supports one image per file. BMP does not allow for comments. The physical resolution can be stored.

See Also:
Constant Field Values

FORMAT_PCX

public static final int FORMAT_PCX
Return value of getFormat() for PCX streams. PCX does not allow for comments or more than one image per file. However, the physical resolution can be stored.

See Also:
Constant Field Values

FORMAT_IFF

public static final int FORMAT_IFF
Return value of getFormat() for IFF streams.

See Also:
Constant Field Values

FORMAT_RAS

public static final int FORMAT_RAS
Return value of getFormat() for RAS streams. Sun Raster allows for one image per file only and is not able to store physical resolution or comments.

See Also:
Constant Field Values

FORMAT_PBM

public static final int FORMAT_PBM
Return value of getFormat() for PBM streams.

See Also:
Constant Field Values

FORMAT_PGM

public static final int FORMAT_PGM
Return value of getFormat() for PGM streams.

See Also:
Constant Field Values

FORMAT_PPM

public static final int FORMAT_PPM
Return value of getFormat() for PPM streams.

See Also:
Constant Field Values

FORMAT_PSD

public static final int FORMAT_PSD
Return value of getFormat() for PSD streams.

See Also:
Constant Field Values
Constructor Detail

ImageMetadata

public ImageMetadata()
Method Detail

check

public boolean check()
Call this method after you have provided an input stream or file using setInput(InputStream) or setInput(DataInput). If true is returned, the file format was known and information on the file's content can be retrieved using the various getXyz methods.

Returns:
if information could be retrieved from input

getBitsPerPixel

public int getBitsPerPixel()
If check() was successful, returns the image's number of bits per pixel. Does not include transparency information like the alpha channel.

Returns:
number of bits per image pixel

getComment

public String getComment(int index)
Returns the index'th comment retrieved from the file.

Parameters:
index - int index of comment to return
Returns:
the comment at the supplied index
Throws:
IllegalArgumentException - if index is smaller than 0 or larger than or equal to the number of comments retrieved
See Also:
getNumberOfComments()

getFormat

public int getFormat()
If check() was successful, returns the image format as one of the FORMAT_xyz constants from this class. Use getFormatName() to get a textual description of the file format.

Returns:
file format as a FORMAT_xyz constant

getFormatName

public String getFormatName()
If check() was successful, returns the image format's name. Use getFormat() to get a unique number.

Returns:
file format name

getHeight

public int getHeight()
If check() was successful, returns one the image's vertical resolution in pixels.

Returns:
image height in pixels

getMimeType

public String getMimeType()
If check() was successful, returns a String with the MIME type of the format.

Returns:
MIME type, e.g. image/jpeg

getNumberOfComments

public int getNumberOfComments()
If check() was successful and setCollectComments(boolean) was called with true as argument, returns the number of comments retrieved from the input image stream / file. Any number >= 0 and smaller than this number of comments is then a valid argument for the getComment(int) method.

Returns:
number of comments retrieved from input image

getNumberOfImages

public int getNumberOfImages()
Returns the number of images in the examined file. Assumes that setDetermineImageNumber(true); was called before a successful call to check(). This value can currently be only different from 1 for GIF images.

Returns:
number of images in file

getPhysicalHeightDpi

public int getPhysicalHeightDpi()
Returns the physical height of this image in dots per inch (dpi). Assumes that check() was successful. Returns -1 on failure.

Returns:
physical height (in dpi)
See Also:
getPhysicalWidthDpi(), getPhysicalHeightInch()

getPhysicalHeightInch

public float getPhysicalHeightInch()
If check() was successful, returns the physical width of this image in dpi (dots per inch) or -1 if no value could be found.

Returns:
physical height (in dpi)
See Also:
getPhysicalHeightDpi(), getPhysicalWidthDpi(), getPhysicalWidthInch()

getPhysicalWidthDpi

public int getPhysicalWidthDpi()
If check() was successful, returns the physical width of this image in dpi (dots per inch) or -1 if no value could be found.

Returns:
physical width (in dpi)
See Also:
getPhysicalHeightDpi(), getPhysicalWidthInch(), getPhysicalHeightInch()

getPhysicalWidthInch

public float getPhysicalWidthInch()
Returns the physical width of an image in inches, or -1.0f if width information is not available. Assumes that check() has been called successfully.

Returns:
physical width in inches or -1.0f on failure
See Also:
getPhysicalWidthDpi(), getPhysicalHeightInch()

getWidth

public int getWidth()
If check() was successful, returns one the image's horizontal resolution in pixels.

Returns:
image width in pixels

isProgressive

public boolean isProgressive()
Returns whether the image is stored in a progressive (also called: interlaced) way.

Returns:
true for progressive/interlaced, false otherwise

main

public static void main(String[] args)
To use this class as a command line application, give it either some file names as parameters (information on them will be printed to standard output, one line per file) or call it with no parameters. It will then check data given to it via standard input.

Parameters:
args - the program arguments which must be file names

setCollectComments

public void setCollectComments(boolean newValue)
Specify whether textual comments are supposed to be extracted from input. Default is false. If enabled, comments will be added to an internal list.

Parameters:
newValue - if true, this class will read comments
See Also:
getNumberOfComments(), getComment(int)

setDetermineImageNumber

public void setDetermineImageNumber(boolean newValue)
Specify whether the number of images in a file is to be determined - default is false. This is a special option because some file formats require running over the entire file to find out the number of images, a rather time-consuming task. Not all file formats support more than one image. If this method is called with true as argument, the actual number of images can be queried via getNumberOfImages() after a successful call to check().

Parameters:
newValue - will the number of images be determined?
See Also:
getNumberOfImages()

setInput

public void setInput(DataInput dataInput)
Set the input stream to the argument stream (or file). Note that RandomAccessFile implements DataInput.

Parameters:
dataInput - the input stream to read from

setInput

public void setInput(InputStream inputStream)
Set the input stream to the argument stream (or file).

Parameters:
inputStream - the input stream to read from


Copyright © 2008-2009 JBoss, a division of Red Hat. All Rights Reserved.