com.sun.image.codec.jpeg

com.sun.image.codec.jpeg
Interface JPEGDecodeParam

All Known Subinterfaces:
JPEGEncodeParam
public abstract interface JPEGDecodeParam
extends Cloneable

JPEGDecodeParam encapsulates tables and options necessary to control decoding JPEG datastreams. Parameters are either set explicitly by the application for encoding, or read from the JPEG header for decoding. In the case of decoding abbreviated data streams the application may need to set some/all of the values it's self.

When working with BufferedImages (@see JPEGImageDecoder.decodeBufferedImage), the codec will attempt to generate an appropriate ColorModel for the JPEG COLOR_ID. This is not always possible (example mappings are listed below) . In cases where unsupported conversions are required, or unknown encoded COLOR_ID's are in use, the user must request the data as a Raster and perform the transformations themselves. When decoding into a raster (@see JPEGImageDecoder.decodeRaster) no ColorSpace adjustments are made. Note: The color ids described herein are simply enumerated values that influence data processing by the JPEG codec. JPEG compression is by definition color blind. These values are used as hints when decompressing JPEG data. Of particular interest is the default conversion from YCbCr to sRGB when decoding buffered Images.

Note: because JPEG is mostly color-blind color fidelity can not be garunteed. This will hopefully be rectified in the near future by the wide spread inclusion of ICC-profiles in the JPEG data stream (as a special marker). The following is an example of the conversions that take place. This is only a guide to the types of conversions that are allowed. This list is likely to change in the future so it is strongly recommended that you check for thrown ImageFormatExceptions and check the actual ColorModel associated with the BufferedImage returned rather than make assumtions. 

DECODING:

JPEG (Encoded) Color ID         BufferedImage ColorSpace
=======================         ========================
COLOR_ID_UNKNOWN                ** Invalid **
COLOR_ID_GRAY                   CS_GRAY
COLOR_ID_RGB                    CS_sRGB
COLOR_ID_YCbCr                  CS_sRGB
COLOR_ID_CMYK                   ** Invalid **
COLOR_ID_PYCC                   CS_PYCC
COLOR_ID_RGBA                   CS_sRGB (w/ alpha)
COLOR_ID_YCbCrA                 CS_sRGB (w/ alpha)
COLOR_ID_RGBA_INVERTED          ** Invalid **
COLOR_ID_YCbCrA_INVERTED        ** Invalid **
COLOR_ID_PYCCA                  CS_PYCC (w/ alpha)
COLOR_ID_YCCK                   ** Invalid **
If the user needs better control over conversion, the user must request the data as a Raster and handle the conversion of the image data themselves.

When decoding JFIF files the encoded COLOR_ID will always be one of: COLOR_ID_UNKNOWN, COLOR_ID_GRAY, COLOR_ID_RGB, COLOR_ID_YCbCr, COLOR_ID_CMYK, or COLOR_ID_YCCK

Note that the classes in the com.sun.image.codec.jpeg package are not part of the core Java APIs. They are a part of Sun's JDK and JRE distributions. Although other licensees may choose to distribute these classes, developers cannot depend on their availability in non-Sun implementations. We expect that equivalent functionality will eventually be available in a core API or standard extension.

Field Summary
static int APP0_MARKER
          APP0 marker - JFIF info
static int APP1_MARKER
          APP1 marker
static int APP2_MARKER
          APP2 marker
static int APP3_MARKER
          APP3 marker
static int APP4_MARKER
          APP4 marker
static int APP5_MARKER
          APP5 marker
static int APP6_MARKER
          APP6 marker
static int APP7_MARKER
          APP7 marker
static int APP8_MARKER
          APP8 marker
static int APP9_MARKER
          APP9 marker
static int APPA_MARKER
          APPA marker
static int APPB_MARKER
          APPB marker
static int APPC_MARKER
          APPC marker
static int APPD_MARKER
          APPD marker
static int APPE_MARKER
          APPE marker - Adobe info
static int APPF_MARKER
          APPF marker
static int COLOR_ID_CMYK
          CMYK
static int COLOR_ID_GRAY
          Monochrome
static int COLOR_ID_PYCC
          PhotoYCC
static int COLOR_ID_PYCCA
          PhotoYCC-Alpha
static int COLOR_ID_RGB
          Red, Green, and Blue
static int COLOR_ID_RGBA
          RGB-Alpha
static int COLOR_ID_RGBA_INVERTED
          RGB-Alpha with R, G, and B inverted.
static int COLOR_ID_UNKNOWN
          Unknown or Undefined Color ID
static int COLOR_ID_YCbCr
          YCbCr
static int COLOR_ID_YCbCrA
          YCbCr-Alpha
static int COLOR_ID_YCbCrA_INVERTED
          YCbCr-Alpha with Y, Cb, and Cr inverted.
static int COLOR_ID_YCCK
          YCbCrK
static int COMMENT_MARKER
          Adobe marker indicates presence/need for Adobe marker.
static int DENSITY_UNIT_ASPECT_RATIO
          The X and Y units simply indicate the aspect ratio of the pixels.
static int DENSITY_UNIT_DOTS_CM
          Pixel density is in pixels per centemeter.
static int DENSITY_UNIT_DOTS_INCH
          Pixel density is in pixels per inch.
static int NUM_COLOR_ID
          Number of color ids defined.
static int NUM_DENSITY_UNIT
          The max known value for DENSITY_UNIT
static int NUM_TABLES
          Number of allowed Huffman and Quantization Tables
 
Method Summary
 Object clone()
           
 int getACHuffmanComponentMapping(int component)
          Get the number of the AC Huffman table that will be used for a particular component.
 JPEGHuffmanTable getACHuffmanTable(int tableNum)
          Returns the AC Huffman coding table requested or null if not defined
 JPEGHuffmanTable getACHuffmanTableForComponent(int component)
          Returns the AC Huffman coding table for the requested component.
 int getDCHuffmanComponentMapping(int component)
          Get the number of the DC Huffman table that will be used for a particular component.
 JPEGHuffmanTable getDCHuffmanTable(int tableNum)
          Returns the DC Huffman coding table requested or null if not defined
 JPEGHuffmanTable getDCHuffmanTableForComponent(int component)
          Returns the DC Huffman coding table for the requested component.
 int getDensityUnit()
          Get the code for pixel size units This value is copied from the APP0 marker.
 int getEncodedColorID()
          Returns the JPEG Encoded color id.
 int getHeight()
          Get the image height
 int getHorizontalSubsampling(int component)
          Return the Horizontal subsampling factor for requested Component.
 boolean getMarker(int marker)
          Returns true if at least one instance of the marker is present in the Parameter object.
 byte[][] getMarkerData(int marker)
          Returns a 'byte[][]' associated with the requested marker in the parameter object.
 int getNumComponents()
          Returns the number of components for the current encoding COLOR_ID.
 JPEGQTable getQTable(int tableNum)
          Returns the coefficient quantization tables or NULL if not defined.
 int getQTableComponentMapping(int component)
          Get the number of the quantization table that will be used for a particular component.
 JPEGQTable getQTableForComponent(int component)
          Returns the Quantization table for the requested component.
 int getRestartInterval()
          Get the MCUs per restart marker.
 int getVerticalSubsampling(int component)
          Return the Vertical subsampling factor for requested Component.
 int getWidth()
          Get the image width
 int getXDensity()
          Get the horizontal pixel density This value is copied from the APP0 marker.
 int getYDensity()
          Get the vertical pixel density This value is copied into the APP0 marker.
 boolean isImageInfoValid()
          Returns true if the image information in the ParamBlock is currently valid.
 boolean isTableInfoValid()
          Returns true if the tables in the ParamBlock are currently valid.
 

Field Detail

COLOR_ID_UNKNOWN

public static final int COLOR_ID_UNKNOWN
Unknown or Undefined Color ID

COLOR_ID_GRAY

public static final int COLOR_ID_GRAY
Monochrome

COLOR_ID_RGB

public static final int COLOR_ID_RGB
Red, Green, and Blue

COLOR_ID_YCbCr

public static final int COLOR_ID_YCbCr
YCbCr

COLOR_ID_CMYK

public static final int COLOR_ID_CMYK
CMYK

COLOR_ID_PYCC

public static final int COLOR_ID_PYCC
PhotoYCC

COLOR_ID_RGBA

public static final int COLOR_ID_RGBA
RGB-Alpha

COLOR_ID_YCbCrA

public static final int COLOR_ID_YCbCrA
YCbCr-Alpha

COLOR_ID_RGBA_INVERTED

public static final int COLOR_ID_RGBA_INVERTED
RGB-Alpha with R, G, and B inverted.

COLOR_ID_YCbCrA_INVERTED

public static final int COLOR_ID_YCbCrA_INVERTED
YCbCr-Alpha with Y, Cb, and Cr inverted.

COLOR_ID_PYCCA

public static final int COLOR_ID_PYCCA
PhotoYCC-Alpha

COLOR_ID_YCCK

public static final int COLOR_ID_YCCK
YCbCrK

NUM_COLOR_ID

public static final int NUM_COLOR_ID
Number of color ids defined.

NUM_TABLES

public static final int NUM_TABLES
Number of allowed Huffman and Quantization Tables

DENSITY_UNIT_ASPECT_RATIO

public static final int DENSITY_UNIT_ASPECT_RATIO
The X and Y units simply indicate the aspect ratio of the pixels.

DENSITY_UNIT_DOTS_INCH

public static final int DENSITY_UNIT_DOTS_INCH
Pixel density is in pixels per inch.

DENSITY_UNIT_DOTS_CM

public static final int DENSITY_UNIT_DOTS_CM
Pixel density is in pixels per centemeter.

NUM_DENSITY_UNIT

public static final int NUM_DENSITY_UNIT
The max known value for DENSITY_UNIT

APP0_MARKER

public static final int APP0_MARKER
APP0 marker - JFIF info

APP1_MARKER

public static final int APP1_MARKER
APP1 marker

APP2_MARKER

public static final int APP2_MARKER
APP2 marker

APP3_MARKER

public static final int APP3_MARKER
APP3 marker

APP4_MARKER

public static final int APP4_MARKER
APP4 marker

APP5_MARKER

public static final int APP5_MARKER
APP5 marker

APP6_MARKER

public static final int APP6_MARKER
APP6 marker

APP7_MARKER

public static final int APP7_MARKER
APP7 marker

APP8_MARKER

public static final int APP8_MARKER
APP8 marker

APP9_MARKER

public static final int APP9_MARKER
APP9 marker

APPA_MARKER

public static final int APPA_MARKER
APPA marker

APPB_MARKER

public static final int APPB_MARKER
APPB marker

APPC_MARKER

public static final int APPC_MARKER
APPC marker

APPD_MARKER

public static final int APPD_MARKER
APPD marker

APPE_MARKER

public static final int APPE_MARKER
APPE marker - Adobe info

APPF_MARKER

public static final int APPF_MARKER
APPF marker

COMMENT_MARKER

public static final int COMMENT_MARKER
Adobe marker indicates presence/need for Adobe marker.
Method Detail

clone

public Object clone()
Overrides:
clone in class Object

getWidth

public int getWidth()
Get the image width
Returns:
int the width of the image data in pixels.

getHeight

public int getHeight()
Get the image height
Returns:
The height of the image data in pixels.

getHorizontalSubsampling

public int getHorizontalSubsampling(int component)
Return the Horizontal subsampling factor for requested Component. The Subsample factor is the number of input pixels that contribute to each output pixel. This is distinct from the way the JPEG to each output pixel. This is distinct from the way the JPEG standard defines this quantity, because fractional subsampling factors are not allowed, and it was felt
Parameters:
component - The component of the encoded image to return the subsampling factor for.
Returns:
The subsample factor.

getVerticalSubsampling

public int getVerticalSubsampling(int component)
Return the Vertical subsampling factor for requested Component. The Subsample factor is the number of input pixels that contribute to each output pixel. This is distinct from the way the JPEG to each output pixel. This is distinct from the way the JPEG standard defines this quantity, because fractional subsampling factors are not allowed, and it was felt
Parameters:
component - The component of the encoded image to return the subsampling factor for.
Returns:
The subsample factor.

getQTable

public JPEGQTable getQTable(int tableNum)
Returns the coefficient quantization tables or NULL if not defined. tableNum must range in value from 0 - 3.
Parameters:
tableNum - the index of the table to be returned.
Returns:
Quantization table stored at index tableNum.

getQTableForComponent

public JPEGQTable getQTableForComponent(int component)
Returns the Quantization table for the requested component.
Parameters:
component - the image component of interest.
Returns:
Quantization table associated with component

getDCHuffmanTable

public JPEGHuffmanTable getDCHuffmanTable(int tableNum)
Returns the DC Huffman coding table requested or null if not defined
Parameters:
tableNum - the index of the table to be returned.
Returns:
Huffman table stored at index tableNum.

getDCHuffmanTableForComponent

public JPEGHuffmanTable getDCHuffmanTableForComponent(int component)
Returns the DC Huffman coding table for the requested component.
Parameters:
component - the image component of interest.
Returns:
Huffman table associated with component

getACHuffmanTable

public JPEGHuffmanTable getACHuffmanTable(int tableNum)
Returns the AC Huffman coding table requested or null if not defined
Parameters:
tableNum - the index of the table to be returned.
Returns:
Huffman table stored at index tableNum.

getACHuffmanTableForComponent

public JPEGHuffmanTable getACHuffmanTableForComponent(int component)
Returns the AC Huffman coding table for the requested component.
Parameters:
component - the image component of interest.
Returns:
Huffman table associated with component

getDCHuffmanComponentMapping

public int getDCHuffmanComponentMapping(int component)
Get the number of the DC Huffman table that will be used for a particular component.
Parameters:
component - The Component of interest.
Returns:
The table number of the DC Huffman table for component.

getACHuffmanComponentMapping

public int getACHuffmanComponentMapping(int component)
Get the number of the AC Huffman table that will be used for a particular component.
Parameters:
component - The Component of interest.
Returns:
The table number of the AC Huffman table for component.

getQTableComponentMapping

public int getQTableComponentMapping(int component)
Get the number of the quantization table that will be used for a particular component.
Parameters:
component - The Component of interest.
Returns:
The table number of the Quantization table for component.

isImageInfoValid

public boolean isImageInfoValid()
Returns true if the image information in the ParamBlock is currently valid. This indicates if image data was read from the stream for decoding and weather image data should be written when encoding.

isTableInfoValid

public boolean isTableInfoValid()
Returns true if the tables in the ParamBlock are currently valid. This indicates that tables were read from the stream for decoding. When encoding this indicates wether tables should be written to the stream.

getMarker

public boolean getMarker(int marker)
Returns true if at least one instance of the marker is present in the Parameter object. For encoding returns true if there is at least one instance of the marker to be written.
Parameters:
marker - The marker of interest.

getMarkerData

public byte[][] getMarkerData(int marker)
Returns a 'byte[][]' associated with the requested marker in the parameter object. Each entry in the 'byte[][]' is the data associated with one instance of the marker (each marker can theoretically appear any number of times in a stream).
Parameters:
marker - The marker of interest.
Returns:
The 'byte[][]' for this marker or null if none available.

getEncodedColorID

public int getEncodedColorID()
Returns the JPEG Encoded color id. This is generally speaking only used if you are decoding into Rasters. Note that when decoding into a Raster no color conversion is performed.
Returns:
The value of the JPEG encoded data's color id.

getNumComponents

public int getNumComponents()
Returns the number of components for the current encoding COLOR_ID.
Returns:
the number of Components

getRestartInterval

public int getRestartInterval()
Get the MCUs per restart marker.
Returns:
The number of MCUs between restart markers.

getDensityUnit

public int getDensityUnit()
Get the code for pixel size units This value is copied from the APP0 marker. It isn't used by the JPEG codec. If the APP0 marker wasn't present then you can not rely on this value.
Returns:
Value indicating the density unit one of the DENSITY_UNIT_* constants.

getXDensity

public int getXDensity()
Get the horizontal pixel density This value is copied from the APP0 marker. It isn't used by the JPEG code. If the APP0 marker wasn't present then you can not rely on this value.
Returns:
The horizontal pixel density, in units described by
See Also:
JPEGDecodeParam.getDensityUnit.

getYDensity

public int getYDensity()
Get the vertical pixel density This value is copied into the APP0 marker. It isn't used by the JPEG code. If the APP0 marker wasn't present then you can not rely on this value.
Returns:
The verticle pixel density, in units described by
See Also:
JPEGDecodeParam.getDensityUnit.
com.sun.image.codec.jpeg
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.