|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sixlegs.png.PngImage
public class PngImage
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/
PngConfig
Field Summary |
---|
Fields inherited from interface java.awt.Transparency |
---|
BITMASK, OPAQUE, TRANSLUCENT |
Constructor Summary | |
---|---|
PngImage()
Constructor which uses a default instance of PngConfig . |
|
PngImage(PngConfig config)
Constructor which uses the specified configuration. |
Method Summary | |
---|---|
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 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. |
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 than INTERLACE_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 this PngImage instance. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public PngImage()
PngConfig
.
public PngImage(PngConfig config)
Method Detail |
---|
public PngConfig getConfig()
PngConfig
instance used by this objectpublic BufferedImage read(File file) throws 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 read
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 BufferedImage read(InputStream in, boolean close) throws 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 reading
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 BufferedImage createImage(InputStream in, Dimension size) throws 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 data
IOException
- if any error occurred while processing the image dataprotected boolean handlePass(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 pass
protected boolean handleProgress(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 completed
protected 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()
IllegalStateException
- if an image has not been readpublic int getHeight()
IllegalStateException
- if an image has not been readpublic int getBitDepth()
IllegalStateException
- if an image has not been readpublic boolean isInterlaced()
PngConstants.INTERLACE
)
is something other than INTERLACE_NONE
.
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
IllegalStateException
- if an image has not been readpublic int getTransparency()
getTransparency
in interface Transparency
IllegalStateException
- if an image has not been readpublic int getSamples()
IllegalStateException
- if an image has not been readpublic float getGamma()
PngConfig.getDefaultGamma()
otherwise.
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()
.
IllegalStateException
- if an image has not been readpublic Color getBackground()
IllegalStateException
- if an image has not been readpublic Object getProperty(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 name
IllegalStateException
- if an image has not been readpublic Map getProperties()
IllegalStateException
or
ClassCastException
.
public TextChunk getTextChunk(String key)
getProperty(PngConstants.TEXT_CHUNKS)
key
- the text chunk keyword
TextChunk
implementation, or null
IllegalStateException
- if an image has not been readprotected void readChunk(int type, DataInput in, long offset, int length) throws 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 data
IOException
protected boolean isMultipleOK(int type)
By default this method returns true
only for sPLT
,
iTXt
, tEXt
,
zTXt
, and IDAT
.
type
- the chunk type
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |