Other API Bundled with the Java 2 SDK: Interface JPEGDecodeParam

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.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2001 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.

com.sun.image.codec.jpeg Interface JPEGDecodeParam