Class 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 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
    • 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
      • 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 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:
        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. 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​(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:
        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
      • getTransparency

        public int getTransparency()
        Returns the type of this Transparency.
        Specified by:
        getTransparency in interface Transparency
        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 of PngConfig.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 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:
        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
      • 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 throwing IllegalStateException or ClassCastException.
        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 calling
        getProperty(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 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:
        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