public class PngImage
extends java.lang.Object
implements java.awt.Transparency
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/
PngConfig
Constructor and Description |
---|
PngImage()
Constructor which uses a default instance of
PngConfig . |
PngImage(PngConfig config)
Constructor which uses the specified configuration.
|
Modifier and Type | Method and 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. |
public PngImage()
PngConfig
.public PngImage(PngConfig config)
public PngConfig getConfig()
PngConfig
instance used by this objectpublic java.awt.image.BufferedImage read(java.io.File file) throws java.io.IOException
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.
file
- the file to readjava.io.IOException
- if any error occurred while reading the imageread(java.io.InputStream, boolean)
,
createImage(java.io.InputStream, java.awt.Dimension)
,
handlePass(java.awt.image.BufferedImage, int)
public java.awt.image.BufferedImage read(java.io.InputStream in, boolean close) throws java.io.IOException
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.
in
- the input stream to readclose
- whether to close the input stream after readingjava.io.IOException
- if any error occurred while reading the imageread(java.io.File)
,
createImage(java.io.InputStream, java.awt.Dimension)
,
handlePass(java.awt.image.BufferedImage, int)
protected java.awt.image.BufferedImage createImage(java.io.InputStream in, java.awt.Dimension size) throws java.io.IOException
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.
in
- the input stream of raw, compressed image datasize
- the size of the image datajava.io.IOException
- if any error occurred while processing the image dataprotected boolean handlePass(java.awt.image.BufferedImage image, int pass)
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.
image
- the partially or fully decoded imagepass
- the index of the completed passprotected boolean handleProgress(java.awt.image.BufferedImage image, float pct)
Image decoding can be aborted by returning false. The default implementation returns true.
image
- the partially or fully decoded imagepct
- the approximate percentage of decoding that has been completedprotected void handleWarning(PngException e) throws PngException
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.
PngException
- if the warning should be treated as fatalpublic int getWidth()
java.lang.IllegalStateException
- if an image has not been readpublic int getHeight()
java.lang.IllegalStateException
- if an image has not been readpublic int getBitDepth()
java.lang.IllegalStateException
- if an image has not been readpublic boolean isInterlaced()
PngConstants.INTERLACE
)
is something other than INTERLACE_NONE
.java.lang.IllegalStateException
- if an image has not been readpublic int getColorType()
COLOR_TYPE_GRAY
,COLOR_TYPE_GRAY_ALPHA
,COLOR_TYPE_PALETTE
,COLOR_TYPE_RGB
,COLOR_TYPE_RGB_ALPHA
java.lang.IllegalStateException
- if an image has not been readpublic int getTransparency()
getTransparency
in interface java.awt.Transparency
java.lang.IllegalStateException
- if an image has not been readpublic int getSamples()
java.lang.IllegalStateException
- if an image has not been readpublic float getGamma()
PngConfig.getDefaultGamma()
otherwise.java.lang.IllegalStateException
- if an image has not been readpublic short[] getGammaTable()
PngConfig.getReduce16()
is false, in which
case the table is 65535 entries.
The values in the table take into account getGamma()
and
PngConfig.getDisplayExponent()
.
java.lang.IllegalStateException
- if an image has not been readpublic java.awt.Color getBackground()
java.lang.IllegalStateException
- if an image has not been readpublic java.lang.Object getProperty(java.lang.String name)
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 |
name
- a property namejava.lang.IllegalStateException
- if an image has not been readpublic java.util.Map getProperties()
IllegalStateException
or
ClassCastException
.public TextChunk getTextChunk(java.lang.String key)
getProperty(PngConstants.TEXT_CHUNKS)
key
- the text chunk keywordTextChunk
implementation, or nulljava.lang.IllegalStateException
- if an image has not been readprotected void readChunk(int type, java.io.DataInput in, long offset, int length) throws java.io.IOException
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.
type
- the chunk typein
- the chunk dataoffset
- the location of the chunk data within the entire PNG datastreamlength
- the length of the chunk datajava.io.IOException