com.sixlegs.image.png
Class PngImage

java.lang.Object
  com.sixlegs.image.png.PngImage

All Implemented Interfaces:

java.awt.image.ImageProducer

public final class PngImage

extends java.lang.Object

implements java.awt.image.ImageProducer

For more information visit http://www.sixlegs.com/

Version:

1.2.3 May 14, 2002

Author:

Chris Nokleberg <chris@sixlegs.com>

See Also:

ImageProducer

Field Summary

static int	COLOR_TYPE_GRAY
static int	COLOR_TYPE_GRAY_ALPHA
static int	COLOR_TYPE_PALETTE
static int	COLOR_TYPE_RGB
static int	COLOR_TYPE_RGB_ALPHA
static int	COMPRESSION_TYPE_BASE
static int	FILTER_TYPE_BASE
static int	FILTER_TYPE_INTRAPIXEL
static int	INTERLACE_TYPE_ADAM7
static int	INTERLACE_TYPE_NONE
static int	SRGB_ABSOLUTE_COLORIMETRIC
static int	SRGB_PERCEPTUAL
static int	SRGB_RELATIVE_COLORIMETRIC
static int	SRGB_SATURATION_PRESERVING
static int	UNIT_METER
static int	UNIT_MICROMETER
static int	UNIT_PIXEL
static int	UNIT_RADIAN
static int	UNIT_UNKNOWN

Constructor Summary

PngImage(java.io.InputStream is)
Constructs a PngImage object from an input stream.

PngImage(java.lang.String filename)
Constructs a PngImage object from a local PNG file.

PngImage(java.net.URL url)
Constructs a PngImage object from a URL.

Method Summary

void	addConsumer(java.awt.image.ImageConsumer ic) Adds an ImageConsumer to the list of consumers interested in data for this image.
java.awt.Color	getBackgroundColor() Get a suggested background color (from the bKGD chunk).
int	getBitDepth() Gets bit depth of image data.
int	getColorType() Gets the alpha and color properties of an image.
java.util.Enumeration	getErrors() Returns an Enumeration of all the errors that occurred during image production.
void	getEverything() Ensures that the entire PNG file has been read.
java.util.Enumeration	getGifExtensions() Returns all known GIF Application Extensions.
int	getHeight() Gets height of image in pixels.
int	getInterlaceType() Gets the interlacing method used by this image.
java.util.Enumeration	getProperties() Returns an Enumeration of the available properties.
java.lang.Object	getProperty(java.lang.String name) Gets a property of this image by name.
int[][]	getSuggestedPalette(java.lang.String name) Returns the suggested palette (sPLT chunk) specified by the palette name.
java.util.Enumeration	getSuggestedPalettes() Returns an Enumeration of the available suggested palette names.
TextChunk	getTextChunk(java.lang.String key) Returns the specified text chunk.
java.util.Enumeration	getTextChunks() Returns the keys of all known text chunks.
int	getWidth() Gets width of image in pixels.
boolean	hasAlphaChannel() Returns true if the image has an alpha channel.
boolean	hasChunk(java.lang.String type)
boolean	hasErrors() Checks if there were errors during image production.
boolean	hasFatalError()
boolean	isConsumer(java.awt.image.ImageConsumer ic) Determine if an ImageConsumer is on the list of consumers currently interested in data for this image.
boolean	isGrayscale() Returns true if the image is grayscale.
boolean	isIndexedColor() Returns true if the image is paletted.
static void	registerChunk(ChunkHandler handler, java.lang.String type) Register a ChunkHandler to handle a user defined chunk type.
void	removeConsumer(java.awt.image.ImageConsumer ic) Remove an ImageConsumer from the list of consumers interested in data for this image.
void	requestTopDownLeftRightResend(java.awt.image.ImageConsumer ic) Requests delivery of image data to the specified ImageConsumer one more time in top-down, left-right order.
static void	setAllErrorsFatal(boolean allFatal) Specifies whether all errors will abort the image production.
static void	setDisplayExponent(double exponent) Sets the default display exponent.
void	setFlushAfterNextProduction(boolean useFlush) Readies this PngImage to be flushed after the next image production, to free memory (default false).
static void	setProgressiveDisplay(boolean progressive) Interlaced images can either be displayed when completely read (default) or progressively.
static void	setUserExponent(double exponent) Sets the default desired final user exponent.
void	startProduction(java.awt.image.ImageConsumer ic) Adds an ImageConsumer to the list of consumers interested in data for this image, and immediately start delivery of the image data through the consumer/producer interface.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COLOR_TYPE_GRAY

public static final int COLOR_TYPE_GRAY

See Also:

Constant Field Values

COLOR_TYPE_GRAY_ALPHA

public static final int COLOR_TYPE_GRAY_ALPHA

See Also:

Constant Field Values

COLOR_TYPE_PALETTE

public static final int COLOR_TYPE_PALETTE

See Also:

Constant Field Values

COLOR_TYPE_RGB

public static final int COLOR_TYPE_RGB

See Also:

Constant Field Values

COLOR_TYPE_RGB_ALPHA

public static final int COLOR_TYPE_RGB_ALPHA

See Also:

Constant Field Values

INTERLACE_TYPE_NONE

public static final int INTERLACE_TYPE_NONE

See Also:

Constant Field Values

INTERLACE_TYPE_ADAM7

public static final int INTERLACE_TYPE_ADAM7

See Also:

Constant Field Values

FILTER_TYPE_BASE

public static final int FILTER_TYPE_BASE

See Also:

Constant Field Values

FILTER_TYPE_INTRAPIXEL

public static final int FILTER_TYPE_INTRAPIXEL

See Also:

Constant Field Values

COMPRESSION_TYPE_BASE

public static final int COMPRESSION_TYPE_BASE

See Also:

Constant Field Values

UNIT_UNKNOWN

public static final int UNIT_UNKNOWN

See Also:

Constant Field Values

UNIT_METER

public static final int UNIT_METER

See Also:

Constant Field Values

UNIT_PIXEL

public static final int UNIT_PIXEL

See Also:

Constant Field Values

UNIT_MICROMETER

public static final int UNIT_MICROMETER

See Also:

Constant Field Values

UNIT_RADIAN

public static final int UNIT_RADIAN

See Also:

Constant Field Values

SRGB_PERCEPTUAL

public static final int SRGB_PERCEPTUAL

See Also:

Constant Field Values

SRGB_RELATIVE_COLORIMETRIC

public static final int SRGB_RELATIVE_COLORIMETRIC

See Also:

Constant Field Values

SRGB_SATURATION_PRESERVING

public static final int SRGB_SATURATION_PRESERVING

See Also:

Constant Field Values

SRGB_ABSOLUTE_COLORIMETRIC

public static final int SRGB_ABSOLUTE_COLORIMETRIC

See Also:

Constant Field Values

Constructor Detail

PngImage

public PngImage(java.lang.String filename)
         throws java.io.IOException

Constructs a PngImage object from a local PNG file.

Parameters:

filename - full path to local PNG file

PngImage

public PngImage(java.net.URL url)
         throws java.io.IOException

Constructs a PngImage object from a URL.

PngImage

public PngImage(java.io.InputStream is)

Constructs a PngImage object from an input stream. Buffer the stream for better performance.

See Also:

BufferedInputStream

Method Detail

addConsumer

public void addConsumer(java.awt.image.ImageConsumer ic)

Adds an ImageConsumer to the list of consumers interested in data for this image.

Specified by:

addConsumer in interface java.awt.image.ImageProducer

See Also:

ImageConsumer

isConsumer

public boolean isConsumer(java.awt.image.ImageConsumer ic)

Determine if an ImageConsumer is on the list of consumers currently interested in data for this image.

Specified by:

isConsumer in interface java.awt.image.ImageProducer

Returns:

true if the consumer is on the list, false otherwise.

See Also:

ImageConsumer

removeConsumer

public void removeConsumer(java.awt.image.ImageConsumer ic)

Remove an ImageConsumer from the list of consumers interested in data for this image.

Specified by:

removeConsumer in interface java.awt.image.ImageProducer

See Also:

ImageConsumer

startProduction

public void startProduction(java.awt.image.ImageConsumer ic)

Adds an ImageConsumer to the list of consumers interested in data for this image, and immediately start delivery of the image data through the consumer/producer interface.

Specified by:

startProduction in interface java.awt.image.ImageProducer

See Also:

ImageConsumer

requestTopDownLeftRightResend

public void requestTopDownLeftRightResend(java.awt.image.ImageConsumer ic)

Requests delivery of image data to the specified ImageConsumer one more time in top-down, left-right order.

Specified by:

requestTopDownLeftRightResend in interface java.awt.image.ImageProducer

See Also:

startProduction(java.awt.image.ImageConsumer), ImageConsumer

setUserExponent

public static void setUserExponent(double exponent)

Sets the default desired final user exponent. Ideal setting depends on user viewing conditions. The default value is 1.0. Set greater than 1.0 to darken the mid-level tones, or less than 1.0 to lighten them.

This method sets the user exponent for new PngImage objects. It is not possible to change the user exponent of an existing PngImage.

Parameters:

exponent - desired user exponent

setDisplayExponent

public static void setDisplayExponent(double exponent)

Sets the default display exponent. Depends on monitor and gamma lookup table settings (if any). Default value is 2.2, which should work well with most PC displays. If the operating system has a gamma lookup table (Macintosh) the display exponent should be lower.

This method sets the display exponent for new PngImage objects. It is not possible to change the display exponent of an existing PngImage.

Parameters:

exponent - desired display exponent

hasErrors

public boolean hasErrors()

Checks if there were errors during image production. A good time to check this is when you implement the ImageObserver interface and the ERROR flag is set.

See Also:

ImageObserver, getErrors()

hasFatalError

public boolean hasFatalError()

getErrors

public java.util.Enumeration getErrors()

Returns an Enumeration of all the errors that occurred during image production. This includes any non-fatal errors.

See Also:

hasErrors()

setAllErrorsFatal

public static void setAllErrorsFatal(boolean allFatal)

Specifies whether all errors will abort the image production. Normally, a value error in a non-critical chunk causes the PNG loader to simply skip the offending chunk.

setProgressiveDisplay

public static void setProgressiveDisplay(boolean progressive)

Interlaced images can either be displayed when completely read (default) or progressively. When progressive display is enabled, a PngImage will call the imageComplete method of its registered image consumers with a SINGLEFRAMEDONE status after each pass. This, in turn, will trigger an imageUpdate with the FRAMEBITS flag set to watching ImageObservers.

Note: Images are only delivered progressively on the first production of the image data. Subsequent requests for the (cached) image data will send the image as a complete single frame.

See Also:

ImageConsumer, ImageObserver

getBackgroundColor

public java.awt.Color getBackgroundColor()
                                  throws java.io.IOException

Get a suggested background color (from the bKGD chunk).

Returns:

the suggested Color, or null if no valid bKGD was found.

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String)

getWidth

public int getWidth()
             throws java.io.IOException

Gets width of image in pixels.

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String)

getHeight

public int getHeight()
              throws java.io.IOException

Gets height of image in pixels.

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String)

getBitDepth

public int getBitDepth()
                throws java.io.IOException

Gets bit depth of image data.

Returns:

1, 2, 4, 8, or 16.

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String)

getInterlaceType

public int getInterlaceType()
                     throws java.io.IOException

Gets the interlacing method used by this image.

Returns:

one of the INTERLACE_TYPE_* constants.

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String)

getColorType

public int getColorType()
                 throws java.io.IOException

Gets the alpha and color properties of an image. An image can either be grayscale, grayscale with alpha channel, RGB, RGB with alpha channel, or paletted.

Returns:

COLOR_TYPE_GRAY
COLOR_TYPE_GRAY_ALPHA
COLOR_TYPE_PALETTE
COLOR_TYPE_RGB
COLOR_TYPE_RGB_ALPHA

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String)

hasAlphaChannel

public boolean hasAlphaChannel()
                        throws java.io.IOException

Returns true if the image has an alpha channel.

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String), getColorType()

isGrayscale

public boolean isGrayscale()
                    throws java.io.IOException

Returns true if the image is grayscale.

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String), getColorType()

isIndexedColor

public boolean isIndexedColor()
                       throws java.io.IOException

Returns true if the image is paletted.

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String), getColorType()

getProperty

public java.lang.Object getProperty(java.lang.String name)
                             throws java.io.IOException

Gets a property of this image by name. If a property is not defined for a particular image, this method returns null.

Note: This method will only read up to the beginning of the image data unless the image data has already been read, either through the consumer/producer interface or by calling getEverything.

The following properties are guaranteed to be defined:

Name	Type	Description
"width"	Integer	Image width in pixels
"height"	Integer	Image height in pixels
"interlace type"	Integer	See getInterlaceType
"compression type"	Integer	COMPRESSION_TYPE_BASE
"filter type"	Integer	FILTER_TYPE_BASE
"color type"	Integer	See getColorType
"bit depth"	Integer	1, 2, 4, 8, or 16 (1)
"gamma"	Long	File gamma * 100000 (2)
"significant bits"	byte[]	Significant bits per component: [r,g,b] or [r,g,b,alpha] (3)

¹ 16-bit pixel components are reduced to 8 bits
² Uses value from sRGB or gAMA chunks, or default (45455)
³ For grayscale images, r == g == b

The following properties are optional:

Name	Type	Description
"palette"	int[][]	Palette or suggested palette (PLTE chunk): [r,g,b][entry] or [r,g,b][entry]
"palette size"	Integer	Size of palette, 1 - 256
"histogram"	int[]	Palette entry usage frequency
"background"	java.awt.Color	Suggested background color
"background low bytes"	java.awt.Color	The low (least significant) bytes of a 16-bit background color
"background index"	Integer	The palette index of the suggested background color
"time"	java.util.Date	Time of last image modification
"pixel dimensions x"	Long	Pixels per unit, X axis
"pixel dimensions y"	Long	Pixels per unit, Y axis
"pixel dimensions unit"	Integer	UNIT_UNKNOWN or UNIT_METER
"image position x"	Integer	Horizontal offset from left of page
"image position y"	Integer	Vertical offset from top of page
"image position unit"	Integer	UNIT_PIXEL or UNIT_MICROMETER
"pixel scale x"	Double	Pixel width, physical scale of subject
"pixel scale y"	Double	Pixel height, physical scale of subject
"pixel scale unit"	Integer	UNIT_METER or UNIT_RADIAN
"chromaticity xy"	long[][]	CIE x,y chromaticities * 100000: [white,r,g,b][x,y]
"chromaticity xyz"	double[][]	CIE XYZ chromaticities: [white,r,g,b][X,Y,Z]
"srgb rendering intent"	Integer	SRGB_PERCEPTUAL or SRGB_RELATIVE_COLORIMETRIC or SRGB_SATURATION_PRESERVING or SRGB_ABSOLUTE_COLORIMETRIC
"icc profile name"	String	Internal ICC profile name
"icc profile"	String	Uncompressed ICC profile
"pixel calibration purpose"	String	Equation identifier
"pixel calibration x0"	Integer	Lower limit of original sample range
"pixel calibration x1"	Integer	Upper limit of original sample range
"pixel calibration type"	Integer	0: Linear mapping 1: Base-e exponential mapping 2: Arbitrary-base exponential mapping 3: Hyperbolic mapping
"pixel calibration n"	Integer	Number of parameters
"pixel calibration unit"	String	Symbol or description of unit
"pixel calibration parameters"	double[]
"gif disposal method"	Integer	See GIF89a Graphic Control Extension specification
"gif user input flag"	Integer	See GIF89a Graphic Control Extension specification
"gif delay time"	Integer	See GIF89a Graphic Control Extension specification
"transparency"	java.awt.Color	Transparent color (4)
"transparency low bytes"	java.awt.Color	The low (least significant) bytes of a 16-bit transparency color (4)
"transparency size"	Integer	The number of palette entries with transparency information (5)

⁴ Grayscale or truecolor images only
⁵ Indexed-color images only

In addition, certain common (but still optional) text chunks are available through the getProperty interface:

Name	Type	Description
"title"	TextChunk	Short (one line) title or caption for image
"author"	TextChunk	Name of image's creator
"description"	TextChunk	Description of image (possibly long)
"copyright"	TextChunk	Copyright notice
"creation time"	TextChunk	Time of original image creation
"software"	TextChunk	Software used to create the image
"disclaimer"	TextChunk	Legal disclaimer
"warning"	TextChunk	Warning of nature of content
"source"	TextChunk	Device used to create the image
"comment"	TextChunk	Miscellaneous comment

Parameters:

name - a property name

Returns:

the value of the named property.

Throws:

java.io.IOException

See Also:

getEverything(), getWidth(), getHeight(), getInterlaceType(), getColorType(), getTextChunk(java.lang.String), getBackgroundColor()

getProperties

public java.util.Enumeration getProperties()
                                    throws java.io.IOException

Returns an Enumeration of the available properties.

Throws:

java.io.IOException

See Also:

getProperty(java.lang.String)

getEverything

public void getEverything()

Ensures that the entire PNG file has been read. No exceptions are throws; errors are available by calling getErrors.

Note: The consumer/producer interface automatically reads the entire PNG file. It usually is not necessary to call getEverything unless you do not need the actual image data.

See Also:

getErrors()

hasChunk

public boolean hasChunk(java.lang.String type)

registerChunk

public static void registerChunk(ChunkHandler handler,
                                 java.lang.String type)
                          throws com.sixlegs.image.png.PngException

Register a ChunkHandler to handle a user defined chunk type.

The chunk type must be four characters, ancillary (lowercase first letter), and may not already be registered. You may register one of the supported ancillary chunk types (except tRNS) to override the standard behavior.

Parameters:

handler - object to send chunk data to

type - chunk type

Throws:

com.sixlegs.image.png.PngException

See Also:

ChunkHandler

getSuggestedPalettes

public java.util.Enumeration getSuggestedPalettes()
                                           throws java.io.IOException

Returns an Enumeration of the available suggested palette names.

Throws:

java.io.IOException

See Also:

getSuggestedPalette(java.lang.String)

getSuggestedPalette

public int[][] getSuggestedPalette(java.lang.String name)
                            throws java.io.IOException

Returns the suggested palette (sPLT chunk) specified by the palette name.

Parameters:

name - the name of the suggested palette

Returns:

[r,g,b,alpha,freq][entry], or null if not present.

Throws:

java.io.IOException

See Also:

getSuggestedPalette(java.lang.String)

getTextChunk

public TextChunk getTextChunk(java.lang.String key)
                       throws java.io.IOException

Returns the specified text chunk.

Note: Text chunks may appear anywhere in the file. This method will only read up to the beginning of the image data unless the image data has already been read, either through the consumer/producer interface or by calling getEverything.

Parameters:

key - the key of the desired chunk

Returns:

the text chunk, or null if not present.

Throws:

java.io.IOException

See Also:

getTextChunks(), getEverything(), getProperty(java.lang.String)

getTextChunks

public java.util.Enumeration getTextChunks()
                                    throws java.io.IOException

Returns the keys of all known text chunks.

Note: Text chunks may appear anywhere in the file. This method will only read up to the beginning of the image data unless the image data has already been read, either through the consumer/producer interface or by calling getEverything.

Returns:

an Enumeration of the keys of text chunks read so far.

Throws:

java.io.IOException

See Also:

getTextChunk(java.lang.String), getEverything()

getGifExtensions

public java.util.Enumeration getGifExtensions()
                                       throws java.io.IOException

Returns all known GIF Application Extensions.

Note: GIF Application Extensions may appear anywhere in the file. This method will only read up to the beginning of the image data unless the image data has already been read, either through the consumer/producer interface or by calling getEverything.

Returns:

an Enumeration of all GifExtension objects read so far.

Throws:

java.io.IOException

See Also:

getEverything(), GifExtension

setFlushAfterNextProduction

public void setFlushAfterNextProduction(boolean useFlush)

Readies this PngImage to be flushed after the next image production, to free memory (default false).

After flushing, you may only call the getErrors and hasErrors methods on this object. The pixel data will no longer be available through the consumer/producer interface.

Note: Using a PixelGrabber object on an Image produced by this PngImage object will ask for a second production of the pixel data, which will fail if the object has been flushed.

See Also:

getErrors(), hasErrors()