Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Class java.awt.image.codec.JPEGParam

java.lang.Object
    |
    +----java.awt.image.codec.JPEGParam

public class JPEGParam
extends Object
JPEGParam encapsulates tables and options necessary to control encoding and decoding JPEG images. Parameters are either set explicitly by the application for encoding, or read from the JPEG header for decoding.

The selection of color ids for the encoded and decoded images is used to control the JPEG codec's processing of the data (e.g. chroma band subsampling and color rotation) and does not necessarily reflect the actual color space of the image data.

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 compressing or decompressing JPEG data. The JPEG codec can perform some default rotation of data into spaces that will aid in getting better compression ratios.

In order to control the "color space" behavior of the JPEG related classes, developers have the option of accepting the default codec behavior or "forcing" some types of behavior.

The default behavior is defined in the following tables.

DECODING:

JPEG (Encoded) Color ID			Image (Decoded) Color ID
=======================			========================
COLOR_ID_UNKNOWN			COLOR_ID_UNKNOWN
COLOR_ID_GRAYSCALE			COLOR_ID_GRAYSCALE
COLOR_ID_RGB				COLOR_ID_RGB
COLOR_ID_YCbCr				COLOR_ID_RGB
COLOR_ID_CMYK				COLOR_ID_CMYK
COLOR_ID_PYCC				COLOR_ID_PYCC
COLOR_ID_RGBA				COLOR_ID_RGBA
COLOR_ID_YCbCrA				COLOR_ID_RGBA
COLOR_ID_RGBA_INVERTED			COLOR_ID_RGBA_INVERTED
COLOR_ID_YCbCrA_INVERTED		COLOR_ID_RGBA_INVERTED
COLOR_ID_PYCCA				COLOR_ID_PYCCA
COLOR_ID_YCCK				COLOR_ID_YCCK


ENCODING:

Image (Decoded) Color ID		JPEG (Encoded) Color ID
========================		=======================
COLOR_ID_UNKNOWN			COLOR_ID_UNKNOWN
COLOR_ID_GRAYSCALE			COLOR_ID_GRAYSCALE
COLOR_ID_RGB				COLOR_ID_YCbCr
COLOR_ID_YCbCr				COLOR_ID_YCbCr
COLOR_ID_CMYK				COLOR_ID_CMYK
COLOR_ID_PYCC				COLOR_ID_PYCC
COLOR_ID_RGBA				COLOR_ID_YCbCrA
COLOR_ID_YCbCrA				COLOR_ID_YCbCrA
COLOR_ID_RGBA_INVERTED			COLOR_ID_YCbCrA_INVERTED
COLOR_ID_YCbCrA_INVERTED		COLOR_ID_YCbCrA_INVERTED
COLOR_ID_PYCCA				COLOR_ID_PYCCA
COLOR_ID_YCCK				COLOR_ID_YCCK

When the user wants behavior other that what is specified in the tables above the setForceColorConversion() method must be invoked passing a value of true as a parameter. When this is the case the user generally wants to avoid a default color conversion or wants to control the color id used in processing the data. If the JPEG codec cannot convert the data using the specified values of ImageColorID and EncodedColorID, an ImageFormatException will be thrown. The allowable conversions are listed in the tables below:
DECODING:

JPEG (Encoded) Color ID			Image (Decoded) Color ID
=======================			========================
COLOR_ID_UNKNOWN			COLOR_ID_UNKNOWN
COLOR_ID_GRAYSCALE			COLOR_ID_GRAYSCALE
COLOR_ID_YCbCr				COLOR_ID_GRAYSCALE
COLOR_ID_RGB				COLOR_ID_RGB
COLOR_ID_YCbCr				COLOR_ID_RGB
COLOR_ID_CMYK				COLOR_ID_CMYK
COLOR_ID_YCCK				COLOR_ID_CMYK
COLOR_ID_PYCC				COLOR_ID_PYCC
COLOR_ID_RGBA				COLOR_ID_RGBA
COLOR_ID_YCbCrA				COLOR_ID_RGBA
COLOR_ID_YCbCrA				COLOR_ID_YCbCrA
COLOR_ID_YCbCrA_INVERTED		COLOR_ID_RGBA_INVERTED
COLOR_ID_YCbCrA_INVERTED		COLOR_ID_YCbCrA_INVERTED
COLOR_ID_PYCCA				COLOR_ID_PYCCA
COLOR_ID_YCCK				COLOR_ID_YCCK


ENCODING:

Image (Decoded) Color ID		JPEG (Encoded) Color ID
========================		=======================
COLOR_ID_UNKNOWN			COLOR_ID_UNKNOWN
COLOR_ID_GRAYSCALE			COLOR_ID_GRAYSCALE
COLOR_ID_RGB				COLOR_ID_GRAYSCALE
COLOR_ID_YCbCr				COLOR_ID_GRAYSCALE
COLOR_ID_RGB				COLOR_ID_RGB
COLOR_ID_RGB				COLOR_ID_YCbCr
COLOR_ID_YCbCr				COLOR_ID_YCbCr
COLOR_ID_CMYK				COLOR_ID_CMYK
COLOR_ID_PYCC				COLOR_ID_PYCC
COLOR_ID_RGBA				COLOR_ID_RGBA
COLOR_ID_RGBA				COLOR_ID_YCbCrA
COLOR_ID_YCbCrA				COLOR_ID_YCbCrA
COLOR_ID_RGBA_INVERTED			COLOR_ID_YCbCrA_INVERTED
COLOR_ID_CMYK				COLOR_ID_YCCK
COLOR_ID_PYCCA				COLOR_ID_PYCCA
COLOR_ID_YCCK				COLOR_ID_YCCK

When encoding JPEG streams, if the image color ID is not one of COLOR_ID_UNKNOWN, COLOR_ID_GRAYSCALE, COLOR_ID_RGB, COLOR_ID_YCbCr, COLOR_ID_CMYK, or COLOR_ID_YCCK, then the value of writeJFIFHeaders should be set to false. This is due to idiosyncracies that exist between the JPEG specification and JFIF.


Field Summary
static int  AC_TABLE_TYPE
AC Huffman table types
static int  COLOR_ID_CMYK
CMYK
static int  COLOR_ID_GRAYSCALE
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  DC_TABLE_TYPE
DC Huffman table type
int  JDCT_DEFAULT
The default algorithm
static int  JDCT_FLOAT
Floating point algorithm - accurate but speed is hardware dependent
static int  JDCT_IFAST
Faster, less accurate integer algorithm
static int  JDCT_ISLOW
Slow but accurate integer algorithm
static int  NUM_HUFF_TBLS
Number of allowed HuffmanTables
 

Constructor Summary
 JPEGParam()
Constructs a JPEGParam with default options.
 

Method Summary
int  getDCTMethod()
Retrievs the DCT algorithm
byte  getdensityUnit()
Get the JFIF code for pixel size units This value is copied into the JFIF APP0 marker.
int  getEncodedColorID()
Returns the JPEG Encoded color id
boolean  getForceColorConversion()
Returns the value of the forceColorConversion data member.
int  getHeight()
Get the image height
JPEGHuffmanTable  getHuffmanTable(int tableNum, int type)
Returns the Huffman coding table or NULL if not defined
int  getImageColorID()
Returns the JPEG Image color id
double  getinputGamma()
Get the gamma of the input image
int  getNumComponents(int id)
Returns the number of components for the color id passed as a parameter.
boolean  getoptimizeCoding()
Get flag indicating whether to optimize entropy encoding tables
double  getoutputGamma()
Get the image gamma wanted in the output
JPEGQTable  getQTable(int tableNum)
Returns the coefficient quantization tables or NULL if not defined
int  getrestartInRows()
Get MCU rows per restart interval
int  getrestartInterval()
Get the MCUs per restart
int  getsmoothingFactor()
Get the input smoothing factor
int  getWidth()
Get the image width
boolean  getwriteAdobeMarker()
Get flag indicating whether to write the Adobe marker when encoding
boolean  getwriteImage()
Get flag indicating whether to write the image data when encoding
boolean  getwriteJFIFHeader()
Get flag indicating whether to write the JFIF header when encoding
boolean  getwriteTables()
Get flag indicating whether to write the tables when encoding.
int  getxDensity()
Get the horizontal pixel density This value is copied into the JFIF APP0 marker.
int  getyDensity()
Get the vertical pixel density This value is copied into the JFIF APP0 marker.
void  setDCTMethod(int dctAlg)
Selects the DCT algorithm
void  setDefaults()
Sets all parameters to reasonable defaults.
void  setdensityUnit(byte unit)
Set the JFIF code for pixel size units This value is copied into the JFIF APP0 marker.
void  setEncodedColorID(int id)
Sets the value of the Encoded color id
void  setForceColorConversion(boolean flag)
Sets the value of the forceColorConversion data member.
void  setHeight(int h)
Set the image height
void  setHuffmanTable(JPEGHuffmanTable hufftable, int tableNum, int type)
Sets the Huffman coding table at index passed.
void  setImageColorID(int id)
Sets the value of the decoded color id.
void  setinputGamma(double gamma)
Set the gamma of the input image
void  setoptimizeCoding(boolean flag)
Set flag indicating whether to optimize entropy encoding tables
void  setoutputGamma(double gamma)
Set the image gamma wanted in output
void  setQTable(JPEGQTable qtable, int tableNum)
Sets the coefficient quantization tables at index passed.
void  setQuality(int quality, boolean force_baseline)
Constructs JPEG quantization tables appropriate for the indicated quality setting (0..100).
void  setrestartInRows(int restartRows)
Set MCU rows per restart interval
void  setrestartInterval(int restartMCUs)
Set the MCUs per restart, or 0 for no restart
void  setsmoothingFactor(int factor)
Set the input smoothing factor parameter applied when encoding.
void  setWidth(int w)
Set the image width
void  setwriteAdobeMarker(boolean flag)
Set flag indicating whether to write the Adobe marker (when encoding)
void  setwriteImage(boolean flag)
Set flag indicating whether to write the image data when encoding jpeg data streams.
void  setwriteJFIFHeader(boolean flag)
Set flag indicating whether to write the JFIF header (when encoding)
void  setwriteTables(boolean flag)
Set flag indicating whether to write the tables when encoding
void  setxDensity(int density)
Set the horizontal pixel density This value is copied into the JFIF APP0 marker.
void  setyDensity(int density)
Set the vertical pixel density.
void  stdHuffmanTables()
Sets the Huffman encoding tables to those in JPEG standard section K.3 These are only valid for 8-bit data precision.
 
Methods inherited from class java.lang.Object
 clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COLOR_ID_UNKNOWN

public static final int COLOR_ID_UNKNOWN
Unknown or Undefined Color ID

COLOR_ID_GRAYSCALE

public static final int COLOR_ID_GRAYSCALE
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

JDCT_ISLOW

public static final int JDCT_ISLOW
Slow but accurate integer algorithm

JDCT_IFAST

public static final int JDCT_IFAST
Faster, less accurate integer algorithm

JDCT_FLOAT

public static final int JDCT_FLOAT
Floating point algorithm - accurate but speed is hardware dependent

JDCT_DEFAULT

protected int JDCT_DEFAULT
The default algorithm

NUM_HUFF_TBLS

public static final int NUM_HUFF_TBLS
Number of allowed HuffmanTables

DC_TABLE_TYPE

public static final int DC_TABLE_TYPE
DC Huffman table type

AC_TABLE_TYPE

public static final int AC_TABLE_TYPE
AC Huffman table types
Constructor Detail

JPEGParam

public JPEGParam()
Constructs a JPEGParam with default options. The compression tables are set to the standard quantization and encoding tables for 8 bit data with a linear quality level of 75.
Method Detail

stdHuffmanTables

protected void stdHuffmanTables()
Sets the Huffman encoding tables to those in JPEG standard section K.3 These are only valid for 8-bit data precision.

setQuality

public void setQuality(int quality,
                       boolean force_baseline)
Constructs JPEG quantization tables appropriate for the indicated quality setting (0..100). If force_baseline is TRUE, the quantization table entries are constrained to the range 1..255 for full JPEG baseline compatibility. The base quantization table is the sample given in the JPEG spec section K.1
Parameters:
quality - - the quality setting ranging from 0 - 100
force_baseline - - boolean value that force baseline quantization. see JPEG spec for details

setDefaults

protected void setDefaults()
Sets all parameters to reasonable defaults. Equivalent to the jpeg_set_defaults() helper routine in the IJG library, with the exception that the encoded and decoded color id is set to COLOR_ID_RGB instead of being read from the JFIF header.

getQTable

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

setQTable

public void setQTable(JPEGQTable qtable,
                      int tableNum)
Sets the coefficient quantization tables at index passed.
Parameters:
JPEGQTable - - QTable that will be assigned to index tableNum.
int - tableNum - the index of the table to be set.
Returns:
void.

getHuffmanTable

public JPEGHuffmanTable getHuffmanTable(int tableNum,
                                        int type)
Returns the Huffman coding table or NULL if not defined
Parameters:
int - tableNum - the index of the table to be returned.
int - type 0=DC table, 1=AC table
Returns:
JPEGHuffmanTable - Huffman table stored at index tableNum.

setHuffmanTable

public void setHuffmanTable(JPEGHuffmanTable hufftable,
                            int tableNum,
                            int type)
Sets the Huffman coding table at index passed.
Parameters:
JPEGHuffmanTable - - JPEGHuffmanTable that will be assigned to index tableNum.
int - tableNum - the index of the table to be set.
Returns:
void.

setDCTMethod

public void setDCTMethod(int dctAlg)
Selects the DCT algorithm
Parameters:
dctAlg - - algorithm type. Must be one of the following values JDCT_ISLOW, JDCT_IFAST, JDCT_IFLOAT. The default value is JDCT_ISLOW.

getDCTMethod

public int getDCTMethod()
Retrievs the DCT algorithm
Returns:
int - current setting for the DCT algorithm type.

setoptimizeCoding

public void setoptimizeCoding(boolean flag)
Set flag indicating whether to optimize entropy encoding tables
Parameters:
boolean - flag - indicates whether to set this option in the jpeg codec. the default value is false.

getoptimizeCoding

public boolean getoptimizeCoding()
Get flag indicating whether to optimize entropy encoding tables
Returns:
boolean - indicating wheter the optimize coding flag was set in the codec. Applies to encoding only.

setwriteJFIFHeader

public void setwriteJFIFHeader(boolean flag)
Set flag indicating whether to write the JFIF header (when encoding)
Parameters:
boolean - flag - tells the jpeg compressor whether to write the JFIF header into the data stream. The default value is true. Applies to encoding only.

getwriteJFIFHeader

public boolean getwriteJFIFHeader()
Get flag indicating whether to write the JFIF header when encoding
Returns:
boolean - indicating the current state of the writeJFIFHeader flag that will be applied to any data streams that are written.

setwriteAdobeMarker

public void setwriteAdobeMarker(boolean flag)
Set flag indicating whether to write the Adobe marker (when encoding)
Parameters:
boolean - flag - tells the jpeg compressor whether to write the Adobe markers into the data stream.

getwriteAdobeMarker

public boolean getwriteAdobeMarker()
Get flag indicating whether to write the Adobe marker when encoding
Returns:
boolean - a value indicating whether Adobe markers will be written the the jpeg data stream.

setwriteTables

public void setwriteTables(boolean flag)
Set flag indicating whether to write the tables when encoding
Parameters:
boolean - - a value directing the JPEG compressor to write the JPEG tables into the jpeg data stream.

getwriteTables

public boolean getwriteTables()
Get flag indicating whether to write the tables when encoding.
Returns:
boolean - returns the current jpeg compressor setting that indicates whether the tables will be written to the jpeg data stream.

setwriteImage

public void setwriteImage(boolean flag)
Set flag indicating whether to write the image data when encoding jpeg data streams.
Parameters:
boolean - - directs the jpeg compressor to include the image data into subsequent data streams.

getwriteImage

public boolean getwriteImage()
Get flag indicating whether to write the image data when encoding
Returns:
boolean - value indicatine the current disposition of this parameter in the codec.

setsmoothingFactor

public void setsmoothingFactor(int factor)
Set the input smoothing factor parameter applied when encoding.
Parameters:
int - factor 1..100, or 0 for no input smoothing

getsmoothingFactor

public int getsmoothingFactor()
Get the input smoothing factor
Returns:
int - returns the value of the smoothing factor currently set in the jpeg codec for encoding.

setrestartInterval

public void setrestartInterval(int restartMCUs)
Set the MCUs per restart, or 0 for no restart
Parameters:
int - - returns the restart MCU setting for the jpeg codec.

getrestartInterval

public int getrestartInterval()
Get the MCUs per restart
Returns:
int - the number of MCUs applied to the jpeg codec when restarting.

setrestartInRows

public void setrestartInRows(int restartRows)
Set MCU rows per restart interval
Parameters:
int - - restart rows that are applied when the jpeg codec restarts.

getrestartInRows

public int getrestartInRows()
Get MCU rows per restart interval
Returns:
int - the current jpeg codec setting for the value of restart in rows.

setinputGamma

public void setinputGamma(double gamma)
Set the gamma of the input image
Parameters:
double - - the gamma value of the input image.

getinputGamma

public double getinputGamma()
Get the gamma of the input image
Returns:
double - the gamma value of the input image.

setoutputGamma

public void setoutputGamma(double gamma)
Set the image gamma wanted in output
Parameters:
double - - gamma of the output image

getoutputGamma

public double getoutputGamma()
Get the image gamma wanted in the output
Returns:
double - the image gamma desired in the output.

setdensityUnit

public void setdensityUnit(byte unit)
Set the JFIF code for pixel size units This value is copied into the JFIF APP0 marker. It isn't used by the JPEG code.
Parameters:
byte - 0=unknown, 1=dots/inch, 2=dots/cm.

getdensityUnit

public byte getdensityUnit()
Get the JFIF code for pixel size units This value is copied into the JFIF APP0 marker. It isn't used by the JPEG code.
Returns:
byte - value indicating the density unit 0=unknown, 1=dots/inch, 2=dots/cm.

setxDensity

public void setxDensity(int density)
Set the horizontal pixel density This value is copied into the JFIF APP0 marker. It isn't used by the JPEG code.
Parameters:
int - - horizontal pixel density.

getxDensity

public int getxDensity()
Get the horizontal pixel density This value is copied into the JFIF APP0 marker. It isn't used by the JPEG code.
Returns:
int - the horizontal pixel density.

setyDensity

public void setyDensity(int density)
Set the vertical pixel density. This value is copied into the JFIF APP0 marker. It isn't used by the JPEG code.
Parameters:
int - - the verticle pixel density

getyDensity

public int getyDensity()
Get the vertical pixel density This value is copied into the JFIF APP0 marker. It isn't used by the JPEG code.
Returns:
int - the verticle pixel density.

getWidth

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

setWidth

public void setWidth(int w)
Set the image width
Parameters:
int - - the width of the image data that is to be encoded.

getHeight

public int getHeight()
Get the image height
Returns:
int - height of the image data passed throught the codec in pixels.

setHeight

public void setHeight(int h)
Set the image height
Parameters:
int - - the height of the image data being encoded in pixels.

setImageColorID

public void setImageColorID(int id)
Sets the value of the decoded color id.
Parameters:
int - - integer value of the decoded color id. When encoding image data this must correspond to the color id of the image data. When decompressing image data this corresponds to the color id of the data being returned.
Throws:
IllegalArgumentException - - thrown when the value of the of the color id that is passed is not a valid value as described in the publicly defined color id values.

setEncodedColorID

public void setEncodedColorID(int id)
Sets the value of the Encoded color id
Parameters:
int - - the integer value of the color id of the data after it has been encoded. This is used as a hint to the JPEG codec. There are no guarantees that that color conversion as part of data compression will be performed.
Throws:
IllegalArgumentException - - thrown when the value of the of the color id that is passed is not a valid value as described in the publicly defined color id values.

getImageColorID

public int getImageColorID()
Returns the JPEG Image color id
Returns:
int - returns the current value of the decoded color id.

getEncodedColorID

public int getEncodedColorID()
Returns the JPEG Encoded color id
Returns:
int - returns the value of the JPEG encoded color id.

getNumComponents

public int getNumComponents(int id)
Returns the number of components for the color id passed as a parameter.
Parameters:
id - - a color id.
Returns:
int - the number of components
Throws:
IllegalArgumentException - - thrown when the value of the of the color id that is passed is not a valid value as described in the publicly defined color id values.

getForceColorConversion

public boolean getForceColorConversion()
Returns the value of the forceColorConversion data member.
Returns:
boolean - if false the default coversions will happen as defined in the class header comments. If true, JPEG lib will be instructed to decode the image data into the DecodedColorID. If there is no conversion routine available an ImageFormatException will be thrown indicating an invalid color conversion.

setForceColorConversion

public void setForceColorConversion(boolean flag)
Sets the value of the forceColorConversion data member.
Parameters:
boolean - - if false the default coversions will happen as defined in the class header comments. If true, JPEG lib will be instructed to decode the image data into the DecodedColorID. If there is no conversion routine available an ImageFormatException will be thrown indicating an invalid color conversion.

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
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.