Class PngImage
- java.lang.Object
-
- com.sixlegs.png.PngImage
-
- All Implemented Interfaces:
Transparency
public class PngImage extends Object implements Transparency
A class to decode PNG images. The simplest use is if only a decodedBufferedImage
is required:BufferedImage image = new PngImage().read(new java.io.File("test.png"));
ThePngImage
instance used to read the image also stores all of the image metadata. For customized PNG decoding, aPngConfig
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
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected BufferedImage
createImage(InputStream in, Dimension size)
A hook by which subclasses can access or manipulate the raw image data.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 ofPngConfig.getDefaultGamma()
otherwise.short[]
getGammaTable()
Returns a gamma table which can be used for custom gamma correction.int
getHeight()
Returns the image height in pixels.Map
getProperties()
Returns the map which stores all of this image's property values.Object
getProperty(String name)
Returns a per-image property by name.int
getSamples()
Returns the number of samples per pixel.TextChunk
getTextChunk(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(BufferedImage image, int pass)
A method which subclasses may override to take some action after each pass has been decoded.protected boolean
handleProgress(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 thanINTERLACE_NONE
.protected boolean
isMultipleOK(int type)
Returns whether a chunk is allowed to occur multiple times.BufferedImage
read(File file)
Reads a PNG image from the specified file.BufferedImage
read(InputStream in, boolean close)
Reads a PNG image from the specified input stream.protected void
readChunk(int type, DataInput in, long offset, int length)
Read the chunk data from the image input stream, storing properties into thisPngImage
instance.
-
-
-
Method Detail
-
getConfig
public PngConfig getConfig()
Returns the configuration used by this object.- Returns:
- the
PngConfig
instance used by this object
-
read
public BufferedImage read(File file) throws IOException
Reads a PNG image from the specified file. Image metadata will be stored in the property map of thisPngImage
instance, for retrieval via the various helper methods (getWidth()
,getHeight()
, etc.) andgetProperty(java.lang.String)
. The decoded image itself is returned by this method but not cached.If
PngConfig.getReadLimit()
is anything butPngConfig.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:
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 BufferedImage read(InputStream in, boolean close) throws IOException
Reads a PNG image from the specified input stream. Image metadata will be stored in the property map of thisPngImage
instance, for retrieval via the various helper methods (getWidth()
,getHeight()
, etc.) andgetProperty(java.lang.String)
. The decoded image itself is returned by this method but not cached.If
PngConfig.getReadLimit()
is anything butPngConfig.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 readclose
- whether to close the input stream after reading- Returns:
- the decoded image, or null if no image was decoded
- Throws:
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 BufferedImage createImage(InputStream in, Dimension size) throws IOException
A hook by which subclasses can access or manipulate the raw image data. All of the raw, compressed image data contained in theIDAT
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 callingread(java.io.File)
orread(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 datasize
- the size of the image data- Returns:
- the decoded image, or null
- Throws:
IOException
- if any error occurred while processing the image data
-
handlePass
protected boolean handlePass(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. Thepass
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 imagepass
- the index of the completed pass- Returns:
- false to abort image decoding
-
handleProgress
protected boolean handleProgress(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 imagepct
- 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 ofPngException
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:
IllegalStateException
- if an image has not been read
-
getHeight
public int getHeight()
Returns the image height in pixels.- Throws:
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:
IllegalStateException
- if an image has not been read
-
isInterlaced
public boolean isInterlaced()
Returns true if the image interlace type (PngConstants.INTERLACE
) is something other thanINTERLACE_NONE
.- Returns:
- true if the image is interlaced
- Throws:
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
,
orCOLOR_TYPE_RGB_ALPHA
- Throws:
IllegalStateException
- if an image has not been read
-
getTransparency
public int getTransparency()
Returns the type of this Transparency.- Specified by:
getTransparency
in interfaceTransparency
- Returns:
- the field type of this Transparency, which is either OPAQUE, BITMASK or TRANSLUCENT.
- Throws:
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:
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 ofPngConfig.getDefaultGamma()
otherwise.- Returns:
- the gamma exponent
- Throws:
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 andPngConfig.getReduce16()
is false, in which case the table is 65535 entries.The values in the table take into account
getGamma()
andPngConfig.getDisplayExponent()
.- Returns:
- a table of component values to be used in gamma correction
- Throws:
IllegalStateException
- if an image has not been read
-
getBackground
public 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:
IllegalStateException
- if an image has not been read
-
getProperty
public Object getProperty(String name)
Returns a per-image property by name. All common property names are defined inPngConstants
; their types are listed in the following table. The use of the various helper methods defined in this class, such asgetBackground()
, 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:
IllegalStateException
- if an image has not been read
-
getProperties
public 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 throwingIllegalStateException
orClassCastException
.- Returns:
- the mutable map of image properties
-
getTextChunk
public TextChunk getTextChunk(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 callinggetProperty(PngConstants.TEXT_CHUNKS)
- Parameters:
key
- the text chunk keyword- Returns:
- a
TextChunk
implementation, or null - Throws:
IllegalStateException
- if an image has not been read
-
readChunk
protected void readChunk(int type, DataInput in, long offset, int length) throws IOException
Read the chunk data from the image input stream, storing properties into thisPngImage
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 ifPngConfig.getReadLimit()
is set toPngConfig.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 typein
- the chunk dataoffset
- the location of the chunk data within the entire PNG datastreamlength
- the length of the chunk data- Throws:
IOException
-
-