PngImage
Keywords: com.sixlegs.image.png.PngImage class

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sixlegs.image.png
Class PngImage

    java.lang.Object
      com.sixlegs.image.png.PngImage

All Implemented Interfaces:
  java.awt.image.ImageProducer

public final class PngImage
extends java.lang.Object
implements java.awt.image.ImageProducer

For more information visit http://www.sixlegs.com/

Version:
  1.2.3 May 14, 2002
Author:
  Chris Nokleberg <chris@sixlegs.com>
See Also:
  `ImageProducer`

Field Summary
`static int` | `COLOR_TYPE_GRAY`
`static int` | `COLOR_TYPE_GRAY_ALPHA`
`static int` | `COLOR_TYPE_PALETTE`
`static int` | `COLOR_TYPE_RGB`
`static int` | `COLOR_TYPE_RGB_ALPHA`
`static int` | `COMPRESSION_TYPE_BASE`
`static int` | `FILTER_TYPE_BASE`
`static int` | `FILTER_TYPE_INTRAPIXEL`
`static int` | `INTERLACE_TYPE_ADAM7`
`static int` | `INTERLACE_TYPE_NONE`
`static int` | `SRGB_ABSOLUTE_COLORIMETRIC`
`static int` | `SRGB_PERCEPTUAL`
`static int` | `SRGB_RELATIVE_COLORIMETRIC`
`static int` | `SRGB_SATURATION_PRESERVING`
`static int` | `UNIT_METER`
`static int` | `UNIT_MICROMETER`
`static int` | `UNIT_PIXEL`
`static int` | `UNIT_RADIAN`
`static int` | `UNIT_UNKNOWN`

Constructor Summary
`PngImage(java.io.InputStream is)` Constructs a `PngImage` object from an input stream.
`PngImage(java.lang.String filename)` Constructs a PngImage object from a local PNG file.
`PngImage(java.net.URL url)` Constructs a `PngImage` object from a URL.

Method Summary
`void` | `addConsumer(java.awt.image.ImageConsumer ic)` Adds an `ImageConsumer` to the list of consumers interested in data for this image.
`java.awt.Color` | `getBackgroundColor()` Get a suggested background color (from the bKGD chunk).
`int` | `getBitDepth()` Gets bit depth of image data.
`int` | `getColorType()` Gets the alpha and color properties of an image.
`java.util.Enumeration` | `getErrors()` Returns an `Enumeration` of all the errors that occurred during image production.
`void` | `getEverything()` Ensures that the entire PNG file has been read.
`java.util.Enumeration` | `getGifExtensions()` Returns all known GIF Application Extensions.
`int` | `getHeight()` Gets height of image in pixels.
`int` | `getInterlaceType()` Gets the interlacing method used by this image.
`java.util.Enumeration` | `getProperties()` Returns an `Enumeration` of the available properties.
`java.lang.Object` | `getProperty(java.lang.String name)` Gets a property of this image by name.
`int[][]` | `getSuggestedPalette(java.lang.String name)` Returns the suggested palette (sPLT chunk) specified by the palette name.
`java.util.Enumeration` | `getSuggestedPalettes()` Returns an `Enumeration` of the available suggested palette names.
`TextChunk` | `getTextChunk(java.lang.String key)` Returns the specified text chunk.
`java.util.Enumeration` | `getTextChunks()` Returns the keys of all known text chunks.
`int` | `getWidth()` Gets width of image in pixels.
`boolean` | `hasAlphaChannel()` Returns true if the image has an alpha channel.
`boolean` | `hasChunk(java.lang.String type)`
`boolean` | `hasErrors()` Checks if there were errors during image production.
`boolean` | `hasFatalError()`
`boolean` | `isConsumer(java.awt.image.ImageConsumer ic)` Determine if an `ImageConsumer` is on the list of consumers currently interested in data for this image.
`boolean` | `isGrayscale()` Returns true if the image is grayscale.
`boolean` | `isIndexedColor()` Returns true if the image is paletted.
`static void` | `registerChunk(ChunkHandler handler, java.lang.String type)` Register a `ChunkHandler` to handle a user defined chunk type.
`void` | `removeConsumer(java.awt.image.ImageConsumer ic)` Remove an `ImageConsumer` from the list of consumers interested in data for this image.
`void` | `requestTopDownLeftRightResend(java.awt.image.ImageConsumer ic)` Requests delivery of image data to the specified `ImageConsumer` one more time in top-down, left-right order.
`static void` | `setAllErrorsFatal(boolean allFatal)` Specifies whether all errors will abort the image production.
`static void` | `setDisplayExponent(double exponent)` Sets the default display exponent.
`void` | `setFlushAfterNextProduction(boolean useFlush)` Readies this PngImage to be flushed after the next image production, to free memory (default false).
`static void` | `setProgressiveDisplay(boolean progressive)` Interlaced images can either be displayed when completely read (default) or progressively.
`static void` | `setUserExponent(double exponent)` Sets the default desired final user exponent.
`void` | `startProduction(java.awt.image.ImageConsumer ic)` Adds an `ImageConsumer` to the list of consumers interested in data for this image, and immediately start delivery of the image data through the consumer/producer interface.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### COLOR_TYPE_GRAY

    public static final int COLOR_TYPE_GRAY

See Also:
  Constant Field Values

### COLOR_TYPE_GRAY_ALPHA

    public static final int COLOR_TYPE_GRAY_ALPHA

See Also:
  Constant Field Values

### COLOR_TYPE_PALETTE

    public static final int COLOR_TYPE_PALETTE

See Also:
  Constant Field Values

### COLOR_TYPE_RGB

    public static final int COLOR_TYPE_RGB

See Also:
  Constant Field Values

### COLOR_TYPE_RGB_ALPHA

    public static final int COLOR_TYPE_RGB_ALPHA

See Also:
  Constant Field Values

### INTERLACE_TYPE_NONE

    public static final int INTERLACE_TYPE_NONE

See Also:
  Constant Field Values

### INTERLACE_TYPE_ADAM7

    public static final int INTERLACE_TYPE_ADAM7

See Also:
  Constant Field Values

### FILTER_TYPE_BASE

    public static final int FILTER_TYPE_BASE

See Also:
  Constant Field Values

### FILTER_TYPE_INTRAPIXEL

    public static final int FILTER_TYPE_INTRAPIXEL

See Also:
  Constant Field Values

### COMPRESSION_TYPE_BASE

    public static final int COMPRESSION_TYPE_BASE

See Also:
  Constant Field Values

### UNIT_UNKNOWN

    public static final int UNIT_UNKNOWN

See Also:
  Constant Field Values

### UNIT_METER

    public static final int UNIT_METER

See Also:
  Constant Field Values

### UNIT_PIXEL

    public static final int UNIT_PIXEL

See Also:
  Constant Field Values

### UNIT_MICROMETER

    public static final int UNIT_MICROMETER

See Also:
  Constant Field Values

### UNIT_RADIAN

    public static final int UNIT_RADIAN

See Also:
  Constant Field Values

### SRGB_PERCEPTUAL

    public static final int SRGB_PERCEPTUAL

See Also:
  Constant Field Values

### SRGB_RELATIVE_COLORIMETRIC

    public static final int SRGB_RELATIVE_COLORIMETRIC

See Also:
  Constant Field Values

### SRGB_SATURATION_PRESERVING

    public static final int SRGB_SATURATION_PRESERVING

See Also:
  Constant Field Values

### SRGB_ABSOLUTE_COLORIMETRIC

    public static final int SRGB_ABSOLUTE_COLORIMETRIC

See Also:
  Constant Field Values

Constructor Detail

### PngImage

    public PngImage(java.lang.String filename)
             throws java.io.IOException

  Constructs a PngImage object from a local PNG file.

Parameters:
  `filename` - full path to local PNG file

### PngImage

    public PngImage(java.net.URL url)
             throws java.io.IOException

  Constructs a `PngImage` object from a URL.

### PngImage

    public PngImage(java.io.InputStream is)

  Constructs a `PngImage` object from an input stream. Buffer the stream for better performance.

See Also:
  `BufferedInputStream`

Method Detail

### addConsumer

    public void addConsumer(java.awt.image.ImageConsumer ic)

  Adds an `ImageConsumer` to the list of consumers interested in data for this image.

  Specified by:
    `addConsumer` in interface `java.awt.image.ImageProducer`
  See Also:
    `ImageConsumer`

### isConsumer

    public boolean isConsumer(java.awt.image.ImageConsumer ic)

  Determine if an `ImageConsumer` is on the list of consumers currently interested in data for this image.

  Specified by:
    `isConsumer` in interface `java.awt.image.ImageProducer`
  Returns:
    true if the consumer is on the list, false otherwise.
  See Also:
    `ImageConsumer`

### removeConsumer

    public void removeConsumer(java.awt.image.ImageConsumer ic)

  Remove an `ImageConsumer` from the list of consumers interested in data for this image.

  Specified by:
    `removeConsumer` in interface `java.awt.image.ImageProducer`
  See Also:
    `ImageConsumer`

### startProduction

    public void startProduction(java.awt.image.ImageConsumer ic)

  Adds an `ImageConsumer` to the list of consumers interested in data for this image, and immediately start delivery of the image data through the consumer/producer interface.

  Specified by:
    `startProduction` in interface `java.awt.image.ImageProducer`
  See Also:
    `ImageConsumer`

### requestTopDownLeftRightResend

    public void requestTopDownLeftRightResend(java.awt.image.ImageConsumer ic)

  Requests delivery of image data to the specified `ImageConsumer` one more time in top-down, left-right order.

  Specified by:
    `requestTopDownLeftRightResend` in interface `java.awt.image.ImageProducer`
  See Also:
    `startProduction(java.awt.image.ImageConsumer)`, `ImageConsumer`

### setUserExponent

    public static void setUserExponent(double exponent)

  Sets the default desired final user exponent. Ideal setting depends on user viewing conditions. The default value is 1.0. Set greater than 1.0 to darken the mid-level tones, or less than 1.0 to lighten them.

  This method sets the user exponent for new `PngImage` objects. It is not possible to change the user exponent of an existing `PngImage`.

  Parameters:
    `exponent` - desired user exponent

### setDisplayExponent

    public static void setDisplayExponent(double exponent)

  Sets the default display exponent. Depends on monitor and gamma lookup table settings (if any). Default value is 2.2, which should work well with most PC displays. If the operating system has a gamma lookup table (Macintosh) the display exponent should be lower.

  This method sets the display exponent for new `PngImage` objects. It is not possible to change the display exponent of an existing `PngImage`.

  Parameters:
    `exponent` - desired display exponent

### hasErrors

    public boolean hasErrors()

  Checks if there were errors during image production. A good time to check this is when you implement the `ImageObserver` interface and the `ERROR` flag is set.

  See Also:
    `ImageObserver`, `getErrors()`

### hasFatalError

    public boolean hasFatalError()

### getErrors

    public java.util.Enumeration getErrors()

  Returns an `Enumeration` of all the errors that occurred during image production. This includes any non-fatal errors.

  See Also:
    `hasErrors()`

### setAllErrorsFatal

    public static void setAllErrorsFatal(boolean allFatal)

  Specifies whether all errors will abort the image production. Normally, a value error in a non-critical chunk causes the PNG loader to simply skip the offending chunk.

### setProgressiveDisplay

    public static void setProgressiveDisplay(boolean progressive)

  Interlaced images can either be displayed when completely read (default) or progressively. When progressive display is enabled, a `PngImage` will call the `imageComplete` method of its registered image consumers with a `SINGLEFRAMEDONE` status after each pass. This, in turn, will trigger an `imageUpdate` with the `FRAMEBITS` flag set to watching `ImageObservers`.

  Note: Images are only delivered progressively on the first production of the image data. Subsequent requests for the (cached) image data will send the image as a complete single frame.

  See Also:
    `ImageConsumer`, `ImageObserver`

### getBackgroundColor

    public java.awt.Color getBackgroundColor()
                                      throws java.io.IOException

  Get a suggested background color (from the bKGD chunk).

  Returns:
    the suggested Color, or null if no valid bKGD was found.
  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`

### getWidth

    public int getWidth()
                 throws java.io.IOException

  Gets width of image in pixels.

  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`

### getHeight

    public int getHeight()
                  throws java.io.IOException

  Gets height of image in pixels.

  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`

### getBitDepth

    public int getBitDepth()
                    throws java.io.IOException

  Gets bit depth of image data.

  Returns:
    1, 2, 4, 8, or 16.
  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`

### getInterlaceType

    public int getInterlaceType()
                         throws java.io.IOException

  Gets the interlacing method used by this image.

  Returns:
    one of the INTERLACE_TYPE_* constants.
  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`

### getColorType

    public int getColorType()
                     throws java.io.IOException

  Gets the alpha and color properties of an image. An image can either be grayscale, grayscale with alpha channel, RGB, RGB with alpha channel, or paletted.

  Returns:
    COLOR_TYPE_GRAY
    COLOR_TYPE_GRAY_ALPHA
    COLOR_TYPE_PALETTE
    COLOR_TYPE_RGB
    COLOR_TYPE_RGB_ALPHA
  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`

### hasAlphaChannel

    public boolean hasAlphaChannel()
                            throws java.io.IOException

  Returns true if the image has an alpha channel.

  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`, `getColorType()`

### isGrayscale

    public boolean isGrayscale()
                        throws java.io.IOException

  Returns true if the image is grayscale.

  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`, `getColorType()`

### isIndexedColor

    public boolean isIndexedColor()
                           throws java.io.IOException

  Returns true if the image is paletted.

  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`, `getColorType()`

### getProperty

    public java.lang.Object getProperty(java.lang.String name)
                                 throws java.io.IOException

  Gets a property of this image by name. If a property is not defined for a particular image, this method returns `null`.

  Note: This method will only read up to the beginning of the image data unless the image data has already been read, either through the consumer/producer interface or by calling `getEverything`.

  The following properties are guaranteed to be defined:

  Name | Type | Description
  "width" | `Integer` | Image width in pixels
  "height" | `Integer` | Image height in pixels
  "interlace type" | `Integer` | See getInterlaceType
  "compression type" | `Integer` | `COMPRESSION_TYPE_BASE`
  "filter type" | `Integer` | `FILTER_TYPE_BASE`
  "color type" | `Integer` | See getColorType
  "bit depth" | `Integer` | 1, 2, 4, 8, or 16 (1)
  "gamma" | `Long` | File gamma * 100000 (2)
  "significant bits" | `byte[]` | Significant bits per component: `[r,g,b]` or `[r,g,b,alpha]` (3)

  1 16-bit pixel components are reduced to 8 bits 2 Uses value from `sRGB` or `gAMA` chunks, or default (`45455`) 3 For grayscale images, `r == g == b`

  The following properties are optional:

  Name | Type | Description
  "palette" | `int[][]` | Palette or suggested palette (PLTE chunk): `[r,g,b][entry]` or `[r,g,b][entry]`
  "palette size" | `Integer` | Size of palette, 1 - 256
  "histogram" | `int[]` | Palette entry usage frequency
  "background" | `java.awt.Color` | Suggested background color
  "background low bytes" | `java.awt.Color` | The low (least significant) bytes of a 16-bit background color
  "background index" | `Integer` | The palette index of the suggested background color
  "time" | `java.util.Date` | Time of last image modification
  "pixel dimensions x" | `Long` | Pixels per unit, X axis
  "pixel dimensions y" | `Long` | Pixels per unit, Y axis
  "pixel dimensions unit" | `Integer` | `UNIT_UNKNOWN` or `UNIT_METER`
  "image position x" | `Integer` | Horizontal offset from left of page
  "image position y" | `Integer` | Vertical offset from top of page
  "image position unit" | `Integer` | `UNIT_PIXEL` or `UNIT_MICROMETER`
  "pixel scale x" | `Double` | Pixel width, physical scale of subject
  "pixel scale y" | `Double` | Pixel height, physical scale of subject
  "pixel scale unit" | `Integer` | `UNIT_METER` or `UNIT_RADIAN`
  "chromaticity xy" | `long[][]` | CIE x,y chromaticities * 100000: `[white,r,g,b][x,y]`
  "chromaticity xyz" | `double[][]` | CIE XYZ chromaticities: `[white,r,g,b][X,Y,Z]`
  "srgb rendering intent" | `Integer` | `SRGB_PERCEPTUAL` or `SRGB_RELATIVE_COLORIMETRIC` or `SRGB_SATURATION_PRESERVING` or `SRGB_ABSOLUTE_COLORIMETRIC`
  "icc profile name" | `String` | Internal ICC profile name
  "icc profile" | `String` | Uncompressed ICC profile
  "pixel calibration purpose" | `String` | Equation identifier
  "pixel calibration x0" | `Integer` | Lower limit of original sample range
  "pixel calibration x1" | `Integer` | Upper limit of original sample range
  "pixel calibration type" | `Integer` | `0`: Linear mapping `1`: Base-e exponential mapping `2`: Arbitrary-base exponential mapping `3`: Hyperbolic mapping
  "pixel calibration n" | `Integer` | Number of parameters
  "pixel calibration unit" | `String` | Symbol or description of unit
  "pixel calibration parameters" | `double[]` |
  "gif disposal method" | `Integer` | See GIF89a Graphic Control Extension specification
  "gif user input flag" | `Integer` | See GIF89a Graphic Control Extension specification
  "gif delay time" | `Integer` | See GIF89a Graphic Control Extension specification
  "transparency" | `java.awt.Color` | Transparent color (4)
  "transparency low bytes" | `java.awt.Color` | The low (least significant) bytes of a 16-bit transparency color (4)
  "transparency size" | `Integer` | The number of palette entries with transparency information (5)

  4 Grayscale or truecolor images only 5 Indexed-color images only

  In addition, certain common (but still optional) text chunks are available through the `getProperty` interface:

  Name | Type | Description
  "title" | `TextChunk` | Short (one line) title or caption for image
  "author" | `TextChunk` | Name of image's creator
  "description" | `TextChunk` | Description of image (possibly long)
  "copyright" | `TextChunk` | Copyright notice
  "creation time" | `TextChunk` | Time of original image creation
  "software" | `TextChunk` | Software used to create the image
  "disclaimer" | `TextChunk` | Legal disclaimer
  "warning" | `TextChunk` | Warning of nature of content
  "source" | `TextChunk` | Device used to create the image
  "comment" | `TextChunk` | Miscellaneous comment

  Parameters:
    `name` - a property name
  Returns:
    the value of the named property.
  Throws:
    `java.io.IOException`
  See Also:
    `getEverything()`, `getWidth()`, `getHeight()`, `getInterlaceType()`, `getColorType()`, `getTextChunk(java.lang.String)`, `getBackgroundColor()`

### getProperties

    public java.util.Enumeration getProperties()
                                        throws java.io.IOException

  Returns an `Enumeration` of the available properties.

  Throws:
    `java.io.IOException`
  See Also:
    `getProperty(java.lang.String)`

### getEverything

    public void getEverything()

  Ensures that the entire PNG file has been read. No exceptions are throws; errors are available by calling `getErrors`.

  Note: The consumer/producer interface automatically reads the entire PNG file. It usually is not necessary to call `getEverything` unless you do not need the actual image data.

  See Also:
    `getErrors()`

### hasChunk

    public boolean hasChunk(java.lang.String type)

### registerChunk

    public static void registerChunk(ChunkHandler handler,
                                     java.lang.String type)
                              throws com.sixlegs.image.png.PngException

  Register a `ChunkHandler` to handle a user defined chunk type.

  The chunk type must be four characters, ancillary (lowercase first letter), and may not already be registered. You may register one of the supported ancillary chunk types (except `tRNS`) to override the standard behavior.

  Parameters:
    `handler` - object to send chunk data to
    `type` - chunk type
  Throws:
    `com.sixlegs.image.png.PngException`
  See Also:
    `ChunkHandler`

### getSuggestedPalettes

    public java.util.Enumeration getSuggestedPalettes()
                                               throws java.io.IOException

  Returns an `Enumeration` of the available suggested palette names.

  Throws:
    `java.io.IOException`
  See Also:
    `getSuggestedPalette(java.lang.String)`

### getSuggestedPalette

    public int[][] getSuggestedPalette(java.lang.String name)
                                throws java.io.IOException

  Returns the suggested palette (sPLT chunk) specified by the palette name.

  Parameters:
    `name` - the name of the suggested palette
  Returns:
    `[r,g,b,alpha,freq][entry]`, or null if not present.
  Throws:
    `java.io.IOException`
  See Also:
    `getSuggestedPalette(java.lang.String)`

### getTextChunk

    public TextChunk getTextChunk(java.lang.String key)
                           throws java.io.IOException

  Returns the specified text chunk.

  Note: Text chunks may appear anywhere in the file. This method will only read up to the beginning of the image data unless the image data has already been read, either through the consumer/producer interface or by calling `getEverything`.

  Parameters:
    `key` - the key of the desired chunk
  Returns:
    the text chunk, or null if not present.
  Throws:
    `java.io.IOException`
  See Also:
    `getTextChunks()`, `getEverything()`, `getProperty(java.lang.String)`

### getTextChunks

    public java.util.Enumeration getTextChunks()
                                        throws java.io.IOException

  Returns the keys of all known text chunks.

  Note: Text chunks may appear anywhere in the file. This method will only read up to the beginning of the image data unless the image data has already been read, either through the consumer/producer interface or by calling `getEverything`.

  Returns:
    an `Enumeration` of the keys of text chunks read so far.
  Throws:
    `java.io.IOException`
  See Also:
    `getTextChunk(java.lang.String)`, `getEverything()`

### getGifExtensions

    public java.util.Enumeration getGifExtensions()
                                           throws java.io.IOException

  Returns all known GIF Application Extensions.

  Note: GIF Application Extensions may appear anywhere in the file. This method will only read up to the beginning of the image data unless the image data has already been read, either through the consumer/producer interface or by calling `getEverything`.

  Returns:
    an `Enumeration` of all GifExtension objects read so far.
  Throws:
    `java.io.IOException`
  See Also:
    `getEverything()`, `GifExtension`

### setFlushAfterNextProduction

    public void setFlushAfterNextProduction(boolean useFlush)

  Readies this PngImage to be flushed after the next image production, to free memory (default false).

  After flushing, you may only call the `getErrors` and `hasErrors` methods on this object. The pixel data will no longer be available through the consumer/producer interface.

  Note: Using a PixelGrabber object on an Image produced by this PngImage object will ask for a second production of the pixel data, which will fail if the object has been flushed.

  See Also:
    `getErrors()`, `hasErrors()`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD