org.dasein.media
Class ImageIngester

java.lang.Object
  org.dasein.media.ImageIngester

All Implemented Interfaces:

Ingester

public class ImageIngester
extends Object
implements Ingester

Provides meta-data for images of a variety of formats. Supported formats include:

• JPEG
• GIF
• BMP
• PCX
• PNG
• IFF
• RAS
• PBM
• PGM
• PPM
• PSD
• SWF

This class is based on the ImageInfo class originally written and placed into the public domain by Marco Schmidt. Valtira also places this class into the public domain. It may therefore be used, distributed, modified, and otherwise enjoyed without restriction. Its presence in packages or products from Valtira, however, does not impact the overall license agreement under which those packages or products are released.

Known limitations:

• When the determination of the number of images is turned off, GIF bits per pixel are only read from the global header. For some GIFs, local palettes change this to a typically larger value. To be certain to get the correct color depth, call setDetermineImageNumber(boolean) before calling ingest(). The complete scan over the GIF file will take additional time.
• Transparency information is not included in the bits per pixel count.

Last modification: $Date: 2006/05/21 20:34:38 $

Version:

$Revision: 1.1 $

Author:

Marco Schmidt, George Reese

Field Summary

static int	COLOR_TYPE_BLACK_AND_WHITE
static int	COLOR_TYPE_GRAYSCALE
static int	COLOR_TYPE_PALETTED
static int	COLOR_TYPE_TRUECOLOR_RGB
static int	COLOR_TYPE_UNKNOWN
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.
static int	FORMAT_SWF Return value of getFormat() for SWF (Shockwave) streams.

Fields inherited from interface org.dasein.media.Ingester

EXTENSION, HEIGHT, WIDTH

Constructor Summary

ImageIngester()

Method Summary

void	clear() Clears the ingester to handle a new media stream.
int	getBitsPerPixel() If ingest() was successful, returns the image's number of bits per pixel.
String	getComment(int index) Returns the index'th comment retrieved from the image.
int	getFormat() If ingest() was successful, returns the image format as one of the FORMAT_xyz constants from this class.
String	getFormatName() If ingest() was successful, returns the image format's name.
int	getHeight() If ingest() was successful, returns one the image's vertical resolution in pixels.
Map<String,Object>	getMetaData() Provides the meta-data associated with the last ingested media asset.
MimeType	getMimeType() If ingest() was successful, returns a String with the MIME type of the format.
int	getNumberOfComments() If ingest() 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 ingest() 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 ingest() 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.
long	getSize() If the ingest process requires multiple passes in order to determine file size, this method should return -1 to allow the requesting application to determine size on its own.
int	getWidth() If ingest() was successful, returns one the image's horizontal resolution in pixels.
void	ingest() Call this method after you have provided an input stream or file using setInput(InputStream) or setInput(DataInput).
boolean	isProgressive() Returns whether the image is stored in a progressive (also called: interlaced) way.
static void	main(String[] args)
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

clone, equals, finalize, 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. ImageIngester 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. ImageIngester can extract comments from GIFs and count the number of images (GIFs with more than one image are animations). If you know of a place where GIFs store the physical resolution of an image, please send me a mail! 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 ImageIngester 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

FORMAT_SWF

public static final int FORMAT_SWF

Return value of getFormat() for SWF (Shockwave) streams.

See Also:

Constant Field Values

COLOR_TYPE_UNKNOWN

public static final int COLOR_TYPE_UNKNOWN

See Also:

Constant Field Values

COLOR_TYPE_TRUECOLOR_RGB

public static final int COLOR_TYPE_TRUECOLOR_RGB

See Also:

Constant Field Values

COLOR_TYPE_PALETTED

public static final int COLOR_TYPE_PALETTED

See Also:

Constant Field Values

COLOR_TYPE_GRAYSCALE

public static final int COLOR_TYPE_GRAYSCALE

See Also:

Constant Field Values

COLOR_TYPE_BLACK_AND_WHITE

public static final int COLOR_TYPE_BLACK_AND_WHITE

See Also:

Constant Field Values

Constructor Detail

ImageIngester

public ImageIngester()

Method Detail

clear

public void clear()

Description copied from interface: Ingester

Clears the ingester to handle a new media stream.

Specified by:

clear in interface Ingester

ingest

public void ingest()
            throws InvalidMediaTypeException,
                   IOException

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.

Specified by:

ingest in interface Ingester

Throws:

InvalidMediaTypeException - the media in the input stream is not one supported by this ingester

IOException - an error occurred reading the input stream

getBitsPerPixel

public int getBitsPerPixel()

If ingest() 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 image.

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 ingest() 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 ingest() was successful, returns the image format's name. Use getFormat() to get a unique number.

Returns:

file format name

getHeight

public int getHeight()

If ingest() was successful, returns one the image's vertical resolution in pixels.

Returns:

image height in pixels

getMetaData

public Map<String,Object> getMetaData()

Description copied from interface: Ingester

Provides the meta-data associated with the last ingested media asset.

Specified by:

getMetaData in interface Ingester

Returns:

the asset's meta-data

getMimeType

public MimeType getMimeType()

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

Specified by:

getMimeType in interface Ingester

Returns:

MIME type, e.g. image/jpeg

getNumberOfComments

public int getNumberOfComments()

If ingest() 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 ingest(). 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 ingest() was successful. Returns -1 on failure.

Returns:

physical height (in dpi)

See Also:

getPhysicalWidthDpi(), getPhysicalHeightInch()

getPhysicalHeightInch

public float getPhysicalHeightInch()

If ingest() 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 ingest() 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()

getSize

public long getSize()

Description copied from interface: Ingester

If the ingest process requires multiple passes in order to determine file size, this method should return -1 to allow the requesting application to determine size on its own.

Specified by:

getSize in interface Ingester

Returns:

the size in bytes of the asset or -1

getWidth

public int getWidth()

If ingest() 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

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 ingest().

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).

Specified by:

setInput in interface Ingester

Parameters:

inputStream - the input stream to read from

main

public static void main(String[] args)