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

    All Methods Instance Methods Concrete Methods
    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