Package com.sixlegs.png

Class PngImage

java.lang.Object

com.sixlegs.png.PngImage

All Implemented Interfaces:

java.awt.Transparency

public class PngImage
extends java.lang.Object
implements java.awt.Transparency

A class to decode PNG images. The simplest use is if only a decoded BufferedImage is required:

BufferedImage image = new PngImage().read(new java.io.File("test.png"));

The PngImage instance used to read the image also stores all of the image metadata. For customized PNG decoding, a PngConfig object may be passed to the constructor.

This class is not thread-safe. Do not share a PngImage instance among multiple threads without proper synchronization.

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

Author:

Chris Nokleberg <chris@sixlegs.com>

See Also:

PngConfig

Field Summary

Fields inherited from interface java.awt.Transparency

BITMASK, OPAQUE, TRANSLUCENT

Constructor Summary

Constructors

Constructor	Description
PngImage()	Constructor which uses a default instance of PngConfig.
PngImage(PngConfig config)	Constructor which uses the specified configuration.

Method Summary

Modifier and Type	Method	Description
protected java.awt.image.BufferedImage	createImage(java.io.InputStream in, java.awt.Dimension size)	A hook by which subclasses can access or manipulate the raw image data.
java.awt.Color	getBackground()	Returns the background color explicitly encoded in the image.
int	getBitDepth()	Returns the image bit depth.
int	getColorType()	Returns the image color type.
PngConfig	getConfig()	Returns the configuration used by this object.
float	getGamma()	Returns the gamma exponent that was explicitly encoded in the image, if there was one, or the value of PngConfig.getDefaultGamma() otherwise.
short[]	getGammaTable()	Returns a gamma table which can be used for custom gamma correction.
int	getHeight()	Returns the image height in pixels.
java.util.Map	getProperties()	Returns the map which stores all of this image's property values.
java.lang.Object	getProperty(java.lang.String name)	Returns a per-image property by name.
int	getSamples()	Returns the number of samples per pixel.
TextChunk	getTextChunk(java.lang.String key)	Returns a text chunk that uses the given keyword, if one exists.
int	getTransparency()	Returns the type of this Transparency.
int	getWidth()	Returns the image widt hin pixels.
protected boolean	handlePass(java.awt.image.BufferedImage image, int pass)	A method which subclasses may override to take some action after each pass has been decoded.
protected boolean	handleProgress(java.awt.image.BufferedImage image, float pct)	Reports the approximate degree of completion of the current read call.
protected void	handleWarning(PngException e)	Callback for customized handling of warnings.
boolean	isInterlaced()	Returns true if the image interlace type (PngConstants.INTERLACE) is something other than INTERLACE_NONE.
protected boolean	isMultipleOK(int type)	Returns whether a chunk is allowed to occur multiple times.
java.awt.image.BufferedImage	read(java.io.File file)	Reads a PNG image from the specified file.
java.awt.image.BufferedImage	read(java.io.InputStream in, boolean close)	Reads a PNG image from the specified input stream.
protected void	readChunk(int type, java.io.DataInput in, long offset, int length)	Read the chunk data from the image input stream, storing properties into this PngImage instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

PngImage

public PngImage()

Constructor which uses a default instance of PngConfig.

PngImage

public PngImage(PngConfig config)

Constructor which uses the specified configuration.

Method Detail

getConfig

public PngConfig getConfig()

Returns the configuration used by this object.

Returns:

the PngConfig instance used by this object

read

public java.awt.image.BufferedImage read(java.io.File file)
                                  throws java.io.IOException

Reads a PNG image from the specified file. Image metadata will be stored in the property map of this PngImage instance, for retrieval via the various helper methods (getWidth(), getHeight(), etc.) and getProperty(java.lang.String). The decoded image itself is returned by this method but not cached.

If PngConfig.getReadLimit() is anything but PngConfig.READ_ALL, then this method will return null instead of the decoded image.

Multiple images can be read using the same PngImage instance. The property map is cleared each time this method is called.

Parameters:

file - the file to read

Returns:

the decoded image, or null if no image was decoded

Throws:

java.io.IOException - if any error occurred while reading the image

See Also:

read(java.io.InputStream, boolean), createImage(java.io.InputStream, java.awt.Dimension), handlePass(java.awt.image.BufferedImage, int)

read

public java.awt.image.BufferedImage read(java.io.InputStream in,
                                         boolean close)
                                  throws java.io.IOException

Reads a PNG image from the specified input stream. Image metadata will be stored in the property map of this PngImage instance, for retrieval via the various helper methods (getWidth(), getHeight(), etc.) and getProperty(java.lang.String). The decoded image itself is returned by this method but not cached.

If PngConfig.getReadLimit() is anything but PngConfig.READ_ALL, then this method will return null instead of the decoded image.

Multiple images can be read using the same PngImage instance. A new property map is created each time this method is called.

Parameters:

in - the input stream to read

close - whether to close the input stream after reading

Returns:

the decoded image, or null if no image was decoded

Throws:

java.io.IOException - if any error occurred while reading the image

See Also:

read(java.io.File), createImage(java.io.InputStream, java.awt.Dimension), handlePass(java.awt.image.BufferedImage, int)

createImage

protected java.awt.image.BufferedImage createImage(java.io.InputStream in,
                                                   java.awt.Dimension size)
                                            throws java.io.IOException

A hook by which subclasses can access or manipulate the raw image data. All of the raw, compressed image data contained in the IDAT chunks of the PNG image being read is concatenated and passed to this method as a single input stream. The returned image will become the return value of the calling read(java.io.File) or read(java.io.InputStream, boolean) method.

Unlike readChunk(int, java.io.DataInput, long, int) implementations, subclasses may read less than the correct amount from this stream; the remainder will be skipped.

Parameters:

in - the input stream of raw, compressed image data

size - the size of the image data

Returns:

the decoded image, or null

Throws:

java.io.IOException - if any error occurred while processing the image data

handlePass

protected boolean handlePass(java.awt.image.BufferedImage image,
                             int pass)

A method which subclasses may override to take some action after each pass has been decoded. An interlaced image has seven passes, and non-interlaced image only one. The pass arguments indicates the index of the completed pass, starting with zero.

For interlaced images, the state of the image data before the last pass is affected by the value of PngConfig.getProgressive().

Image decoding can be aborted by returning false. The default implementation always returns true.

Parameters:

image - the partially or fully decoded image

pass - the index of the completed pass

Returns:

false to abort image decoding

handleProgress

protected boolean handleProgress(java.awt.image.BufferedImage image,
                                 float pct)

Reports the approximate degree of completion of the current read call. This method is called periodically during image decoding. The degree of completion is expressed as a percentage varying from 0.0F to 100.0F, and is calculated using the number of pixels decoded.

Image decoding can be aborted by returning false. The default implementation returns true.

Parameters:

image - the partially or fully decoded image

pct - the approximate percentage of decoding that has been completed

Returns:

false to abort image decoding

handleWarning

protected void handleWarning(PngException e)
                      throws PngException

Callback for customized handling of warnings. Whenever a non-fatal error is found, an instance of PngException is created and passed to this method. To signal that the exception should be treated as a fatal exception (and abort image processing), an implementation should re-throw the exception.

By default, this method will re-throw the warning if the warningsFatal property is true.

Throws:

PngException - if the warning should be treated as fatal

getWidth

public int getWidth()

Returns the image widt hin pixels.

Throws:

java.lang.IllegalStateException - if an image has not been read

getHeight

public int getHeight()

Returns the image height in pixels.

Throws:

java.lang.IllegalStateException - if an image has not been read

getBitDepth

public int getBitDepth()

Returns the image bit depth.

Returns:

1, 2, 4, 8, or 16

Throws:

java.lang.IllegalStateException - if an image has not been read

isInterlaced

public boolean isInterlaced()

Returns true if the image interlace type (PngConstants.INTERLACE) is something other than INTERLACE_NONE.

Returns:

true if the image is interlaced

Throws:

java.lang.IllegalStateException - if an image has not been read

getColorType

public int getColorType()

Returns the image color type.

Returns:

COLOR_TYPE_GRAY,
COLOR_TYPE_GRAY_ALPHA,
COLOR_TYPE_PALETTE,
COLOR_TYPE_RGB,
or COLOR_TYPE_RGB_ALPHA

Throws:

java.lang.IllegalStateException - if an image has not been read

getTransparency

public int getTransparency()

Returns the type of this Transparency.

Specified by:

getTransparency in interface java.awt.Transparency

Returns:

the field type of this Transparency, which is either OPAQUE, BITMASK or TRANSLUCENT.

Throws:

java.lang.IllegalStateException - if an image has not been read

getSamples

public int getSamples()

Returns the number of samples per pixel. Gray and paletted images use one sample, gray+alpha uses two, RGB uses three, and RGB+alpha uses four.

Returns:

1, 2, 3 or 4

Throws:

java.lang.IllegalStateException - if an image has not been read

getGamma

public float getGamma()

Returns the gamma exponent that was explicitly encoded in the image, if there was one, or the value of PngConfig.getDefaultGamma() otherwise.

Returns:

the gamma exponent

Throws:

java.lang.IllegalStateException - if an image has not been read

getGammaTable

public short[] getGammaTable()

Returns a gamma table which can be used for custom gamma correction. The table is 256 entries unless the bit depth is 16 and PngConfig.getReduce16() is false, in which case the table is 65535 entries.

The values in the table take into account getGamma() and PngConfig.getDisplayExponent().

Returns:

a table of component values to be used in gamma correction

Throws:

java.lang.IllegalStateException - if an image has not been read

getBackground

public java.awt.Color getBackground()

Returns the background color explicitly encoded in the image. For 16-bit images the components are reduced to 8-bit by shifting.

Returns:

the background color, or null

Throws:

java.lang.IllegalStateException - if an image has not been read

getProperty

public java.lang.Object getProperty(java.lang.String name)

Returns a per-image property by name. All common property names are defined in PngConstants; their types are listed in the following table. The use of the various helper methods defined in this class, such as getBackground(), is normally preferrable to working with the raw property values.

Property	Type	Description
BIT_DEPTH	Integer	Bit depth
COLOR_TYPE	Integer	Color type
COMPRESSION	Integer	Compression method
FILTER	Integer	Filter method
GAMMA	Float	Gamma
WIDTH	Integer	Width
HEIGHT	Integer	Height
INTERLACE	Integer	Interlace method
PALETTE	byte[]	Palette entries
PALETTE_ALPHA	byte[]	Palette alpha
TRANSPARENCY	int[]	Transparency samples
BACKGROUND	int[]	Background samples
PIXELS_PER_UNIT_X	Integer	Pixels per unit, X axis
PIXELS_PER_UNIT_Y	Integer	Pixels per unit, Y axis
UNIT	Integer	Unit specifier
RENDERING_INTENT	Integer	Rendering intent
SIGNIFICANT_BITS	byte[]	Significant bits
TEXT_CHUNKS	List	List of text chunks
TIME	Date	Image last-modification time
CHROMATICITY	float[]	Chromaticity
ICC_PROFILE	byte[]	ICC profile
ICC_PROFILE_NAME	String	ICC profile name
HISTOGRAM	int[]	Palette histogram
SUGGESTED_PALETTES	List	List of suggested palettes
GIF_DISPOSAL_METHOD	Integer	GIF disposal method
GIF_USER_INPUT_FLAG	Integer	GIF user input flag
GIF_DELAY_TIME	Integer	GIF delay time (hundredths of a second)
SCALE_UNIT	Integer	Unit for physical scale of image subject
PIXEL_WIDTH	Double	Physical width of pixel
PIXEL_HEIGHT	Double	Physical height of pixel
POSITION_UNIT	Integer	Unit for image offset
STEREO_MODE	Integer	Indicator of stereo image

Parameters:

name - a property name

Returns:

the property value, or null if no such property exists

Throws:

java.lang.IllegalStateException - if an image has not been read

getProperties

public java.util.Map getProperties()

Returns the map which stores all of this image's property values. The map is mutable, and storing a value with the wrong type may result in other methods in this class throwing IllegalStateException or ClassCastException.

Returns:

the mutable map of image properties

getTextChunk

public TextChunk getTextChunk(java.lang.String key)

Returns a text chunk that uses the given keyword, if one exists. If multiple text chunks share the same keyword, this method will return the first one that was read. The full list of text chunks may be accessed by calling

getProperty(PngConstants.TEXT_CHUNKS)

Parameters:

key - the text chunk keyword

Returns:

a TextChunk implementation, or null

Throws:

java.lang.IllegalStateException - if an image has not been read

readChunk

protected void readChunk(int type,
                         java.io.DataInput in,
                         long offset,
                         int length)
                  throws java.io.IOException

Read the chunk data from the image input stream, storing properties into this PngImage instance.

By default this method will handle all of the chunk types defined in Version 1.2 of the PNG Specification, and most of the registered extension chunks. IDAT chunks will be processed through this method only if PngConfig.getReadLimit() is set to PngConfig.READ_EXCEPT_DATA.

Attempting to read past the end of the chunk data will result in an EOFException. Unread data will be skipped.

Parameters:

type - the chunk type

in - the chunk data

offset - the location of the chunk data within the entire PNG datastream

length - the length of the chunk data

Throws:

java.io.IOException

isMultipleOK

protected boolean isMultipleOK(int type)

Returns whether a chunk is allowed to occur multiple times.

By default this method returns true only for sPLT, iTXt, tEXt, zTXt, and IDAT.

Parameters:

type - the chunk type

Returns:

whether multiple chunks of the given type are allowed