FileDocCategorySizeDatePackage
ColorSpace.javaAPI DocJava SE 6 API21143Tue Jun 10 00:25:20 BST 2008java.awt.color

ColorSpace

public abstract class ColorSpace extends Object implements Serializable
This abstract class is used to serve as a color space tag to identify the specific color space of a Color object or, via a ColorModel object, of an Image, a BufferedImage, or a GraphicsDevice. It contains methods that transform colors in a specific color space to/from sRGB and to/from a well-defined CIEXYZ color space.

For purposes of the methods in this class, colors are represented as arrays of color components represented as floats in a normalized range defined by each ColorSpace. For many ColorSpaces (e.g. sRGB), this range is 0.0 to 1.0. However, some ColorSpaces have components whose values have a different range. Methods are provided to inquire per component minimum and maximum normalized values.

Several variables are defined for purposes of referring to color space types (e.g. TYPE_RGB, TYPE_XYZ, etc.) and to refer to specific color spaces (e.g. CS_sRGB and CS_CIEXYZ). sRGB is a proposed standard RGB color space. For more information, see http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html .

The purpose of the methods to transform to/from the well-defined CIEXYZ color space is to support conversions between any two color spaces at a reasonably high degree of accuracy. It is expected that particular implementations of subclasses of ColorSpace (e.g. ICC_ColorSpace) will support high performance conversion based on underlying platform color management systems.

The CS_CIEXYZ space used by the toCIEXYZ/fromCIEXYZ methods can be described as follows: 


  CIEXYZ
  viewing illuminance: 200 lux
  viewing white point: CIE D50
  media white point: "that of a perfectly reflecting diffuser" -- D50
  media black point: 0 lux or 0 Reflectance
  flare: 1 percent
  surround: 20percent of the media white point
  media description: reflection print (i.e., RLAB, Hunt viewing media)
  note: For developers creating an ICC profile for this conversion
  space, the following is applicable. Use a simple Von Kries
  white point adaptation folded into the 3X3 matrix parameters
  and fold the flare and surround effects into the three
  one-dimensional lookup tables (assuming one uses the minimal
  model for monitors).

see
ICC_ColorSpace
version
10 Feb 1997

Fields Summary
static final long
serialVersionUID
private int
type
private int
numComponents
private transient String[]
compName
private static ColorSpace
sRGBspace
private static ColorSpace
XYZspace
private static ColorSpace
PYCCspace
private static ColorSpace
GRAYspace
private static ColorSpace
LINEAR_RGBspace
public static final int
TYPE_XYZ
Any of the family of XYZ color spaces.
public static final int
TYPE_Lab
Any of the family of Lab color spaces.
public static final int
TYPE_Luv
Any of the family of Luv color spaces.
public static final int
TYPE_YCbCr
Any of the family of YCbCr color spaces.
public static final int
TYPE_Yxy
Any of the family of Yxy color spaces.
public static final int
TYPE_RGB
Any of the family of RGB color spaces.
public static final int
TYPE_GRAY
Any of the family of GRAY color spaces.
public static final int
TYPE_HSV
Any of the family of HSV color spaces.
public static final int
TYPE_HLS
Any of the family of HLS color spaces.
public static final int
TYPE_CMYK
Any of the family of CMYK color spaces.
public static final int
TYPE_CMY
Any of the family of CMY color spaces.
public static final int
TYPE_2CLR
Generic 2 component color spaces.
public static final int
TYPE_3CLR
Generic 3 component color spaces.
public static final int
TYPE_4CLR
Generic 4 component color spaces.
public static final int
TYPE_5CLR
Generic 5 component color spaces.
public static final int
TYPE_6CLR
Generic 6 component color spaces.
public static final int
TYPE_7CLR
Generic 7 component color spaces.
public static final int
TYPE_8CLR
Generic 8 component color spaces.
public static final int
TYPE_9CLR
Generic 9 component color spaces.
public static final int
TYPE_ACLR
Generic 10 component color spaces.
public static final int
TYPE_BCLR
Generic 11 component color spaces.
public static final int
TYPE_CCLR
Generic 12 component color spaces.
public static final int
TYPE_DCLR
Generic 13 component color spaces.
public static final int
TYPE_ECLR
Generic 14 component color spaces.
public static final int
TYPE_FCLR
Generic 15 component color spaces.
public static final int
CS_sRGB
The sRGB color space defined at http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html .
public static final int
CS_LINEAR_RGB
A built-in linear RGB color space. This space is based on the same RGB primaries as CS_sRGB, but has a linear tone reproduction curve.
public static final int
CS_CIEXYZ
The CIEXYZ conversion color space defined above.
public static final int
CS_PYCC
The Photo YCC conversion color space.
public static final int
CS_GRAY
The built-in linear gray scale color space.
Constructors Summary
protected ColorSpace(int type, int numcomponents)
Constructs a ColorSpace object given a color space type and the number of components.

param
type one of the ColorSpace type constants
param
numcomponents the number of components in the color space



                                         
          
        this.type = type;
        this.numComponents = numcomponents;
Methods Summary
public abstract float[]fromCIEXYZ(float[] colorvalue)
Transforms a color value assumed to be in the CS_CIEXYZ conversion color space into this ColorSpace.

This method transforms color values using relative colorimetry, as defined by the International Color Consortium standard. This means that the XYZ argument values taken by this method are represented relative to the D50 white point of the CS_CIEXYZ color space. This representation is useful in a two-step color conversion process in which colors are transformed from an input color space to CS_CIEXYZ and then to an output color space. The color values returned by this method are not those that would produce the XYZ value passed to the method when measured by a colorimeter. If you have XYZ values corresponding to measurements made using current CIE recommended practices, they must be converted to D50 relative values before being passed to this method. See the {@link ICC_ColorSpace#fromCIEXYZ(float[]) fromCIEXYZ} method of ICC_ColorSpace for further information.

param
colorvalue a float array with length of at least 3
return
a float array with length equal to the number of components in this ColorSpace
throws
ArrayIndexOutOfBoundsException if array length is not at least 3

public abstract float[]fromRGB(float[] rgbvalue)
Transforms a color value assumed to be in the default CS_sRGB
color space into this ColorSpace.


This method transforms color values using algorithms designed
to produce the best perceptual match between input and output
colors. In order to do colorimetric conversion of color values,
you should use the toCIEXYZ
method of the CS_sRGB color space to first convert from the input
color space to the CS_CIEXYZ color space, and then use the
fromCIEXYZ method of this color space to
convert from CS_CIEXYZ to the output color space.
See {@link #toCIEXYZ(float[]) toCIEXYZ} and
{@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information.

param
rgbvalue a float array with length of at least 3
return
a float array with length equal to the number of
components in this ColorSpace
throws
ArrayIndexOutOfBoundsException if array length is not
at least 3
public static java.awt.color.ColorSpacegetInstance(int colorspace)
Returns a ColorSpace representing one of the specific
predefined color spaces.
param
colorspace a specific color space identified by one of
the predefined class constants (e.g. CS_sRGB, CS_LINEAR_RGB,
CS_CIEXYZ, CS_GRAY, or CS_PYCC)
return
the requested ColorSpace object
    ColorSpace    theColorSpace;

        switch (colorspace) {
        case CS_sRGB:
            synchronized(ColorSpace.class) {
                if (sRGBspace == null) {
                    ICC_Profile theProfile = ICC_Profile.getInstance (CS_sRGB);
                    sRGBspace = new ICC_ColorSpace (theProfile);
                }

                theColorSpace = sRGBspace;
            }
            break;
        
        case CS_CIEXYZ:
            synchronized(ColorSpace.class) {
                if (XYZspace == null) {
                    ICC_Profile theProfile = 
                        ICC_Profile.getInstance (CS_CIEXYZ);
                    XYZspace = new ICC_ColorSpace (theProfile);
                }

                theColorSpace = XYZspace;
            }
            break;
        
        case CS_PYCC:
            synchronized(ColorSpace.class) {
                if (PYCCspace == null) {
                    ICC_Profile theProfile = ICC_Profile.getInstance (CS_PYCC);
                    PYCCspace = new ICC_ColorSpace (theProfile);
                }

                theColorSpace = PYCCspace;
            }
            break;
        

        case CS_GRAY:
            synchronized(ColorSpace.class) {
                if (GRAYspace == null) {
                    ICC_Profile theProfile = ICC_Profile.getInstance (CS_GRAY);
                    GRAYspace = new ICC_ColorSpace (theProfile);
                    /* to allow access from java.awt.ColorModel */
                    CMM.GRAYspace = GRAYspace;
                }

                theColorSpace = GRAYspace;
            }
            break;
        

        case CS_LINEAR_RGB:
            synchronized(ColorSpace.class) {
                if (LINEAR_RGBspace == null) {
                    ICC_Profile theProfile = 
                        ICC_Profile.getInstance(CS_LINEAR_RGB);
                    LINEAR_RGBspace = new ICC_ColorSpace (theProfile);
                    /* to allow access from java.awt.ColorModel */
                    CMM.LINEAR_RGBspace = LINEAR_RGBspace;
                }

                theColorSpace = LINEAR_RGBspace;
            }
            break;
        

        default:
            throw new IllegalArgumentException ("Unknown color space");
        }
        
        return theColorSpace;
    
public floatgetMaxValue(int component)
Returns the maximum normalized color component value for the
specified component. The default implementation in this abstract
class returns 1.0 for all components. Subclasses should override
this method if necessary.
param
component the component index
return
the maximum normalized component value
throws
IllegalArgumentException if component is less than 0 or
greater than numComponents - 1
since
1.4
        if ((component < 0) || (component > numComponents - 1)) {
            throw new IllegalArgumentException(
                "Component index out of range: " + component);
        }
        return 1.0f;
    
public floatgetMinValue(int component)
Returns the minimum normalized color component value for the
specified component. The default implementation in this abstract
class returns 0.0 for all components. Subclasses should override
this method if necessary.
param
component the component index
return
the minimum normalized component value
throws
IllegalArgumentException if component is less than 0 or
greater than numComponents - 1
since
1.4
        if ((component < 0) || (component > numComponents - 1)) {
            throw new IllegalArgumentException(
                "Component index out of range: " + component);
        }
        return 0.0f;
    
public java.lang.StringgetName(int idx)
Returns the name of the component given the component index.
param
idx the component index
return
the name of the component at the specified index
throws
IllegalArgumentException if idx is
less than 0 or greater than numComponents - 1
        /* REMIND - handle common cases here */
        if ((idx < 0) || (idx > numComponents - 1)) {
            throw new IllegalArgumentException(
                "Component index out of range: " + idx);
        }

        if (compName == null) {
            switch (type) {
                case ColorSpace.TYPE_XYZ:
                    compName = new String[] {"X", "Y", "Z"};
                    break;
                case ColorSpace.TYPE_Lab:
                    compName = new String[] {"L", "a", "b"};
                    break;
                case ColorSpace.TYPE_Luv:
                    compName = new String[] {"L", "u", "v"};
                    break;
                case ColorSpace.TYPE_YCbCr:
                    compName = new String[] {"Y", "Cb", "Cr"};
                    break;
                case ColorSpace.TYPE_Yxy:
                    compName = new String[] {"Y", "x", "y"};
                    break;
                case ColorSpace.TYPE_RGB:
                    compName = new String[] {"Red", "Green", "Blue"};
                    break;
                case ColorSpace.TYPE_GRAY:
                    compName = new String[] {"Gray"};
                    break;
                case ColorSpace.TYPE_HSV:
                    compName = new String[] {"Hue", "Saturation", "Value"};
                    break;
                case ColorSpace.TYPE_HLS:
                    compName = new String[] {"Hue", "Lightness", 
                                             "Saturation"};
                    break;
                case ColorSpace.TYPE_CMYK:
                    compName = new String[] {"Cyan", "Magenta", "Yellow",
                                             "Black"};
                    break;
                case ColorSpace.TYPE_CMY:
                    compName = new String[] {"Cyan", "Magenta", "Yellow"};
                    break;
                default:
                    String [] tmp = new String[numComponents]; 
                    for (int i = 0; i < tmp.length; i++) {
                        tmp[i] = "Unnamed color component(" + i + ")";
                    }
                    compName = tmp;
            }
        }
        return compName[idx];
    
public intgetNumComponents()
Returns the number of components of this ColorSpace.
return
The number of components in this ColorSpace.
        return numComponents;
    
public intgetType()
Returns the color space type of this ColorSpace (for example
TYPE_RGB, TYPE_XYZ, ...). The type defines the
number of components of the color space and the interpretation,
e.g. TYPE_RGB identifies a color space with three components - red,
green, and blue. It does not define the particular color
characteristics of the space, e.g. the chromaticities of the
primaries.
return
the type constant that represents the type of this
ColorSpace
        return type;
    
static booleanisCS_CIEXYZ(java.awt.color.ColorSpace cspace)
        return (cspace == XYZspace);
    
public booleanisCS_sRGB()
Returns true if the ColorSpace is CS_sRGB.
return
true if this is a CS_sRGB color
space, false if it is not
        /* REMIND - make sure we know sRGBspace exists already */
        return (this == sRGBspace);
    
public abstract float[]toCIEXYZ(float[] colorvalue)
Transforms a color value assumed to be in this ColorSpace
into the CS_CIEXYZ conversion color space.


This method transforms color values using relative colorimetry,
as defined by the International Color Consortium standard. This
means that the XYZ values returned by this method are represented
relative to the D50 white point of the CS_CIEXYZ color space.
This representation is useful in a two-step color conversion
process in which colors are transformed from an input color
space to CS_CIEXYZ and then to an output color space. This
representation is not the same as the XYZ values that would
be measured from the given color value by a colorimeter.
A further transformation is necessary to compute the XYZ values
that would be measured using current CIE recommended practices.
See the {@link ICC_ColorSpace#toCIEXYZ(float[]) toCIEXYZ} method of
ICC_ColorSpace for further information.

param
colorvalue a float array with length of at least the number
of components in this ColorSpace
return
a float array of length 3
throws
ArrayIndexOutOfBoundsException if array length is not
at least the number of components in this ColorSpace.
public abstract float[]toRGB(float[] colorvalue)
Transforms a color value assumed to be in this ColorSpace
into a value in the default CS_sRGB color space.


This method transforms color values using algorithms designed
to produce the best perceptual match between input and output
colors. In order to do colorimetric conversion of color values,
you should use the toCIEXYZ
method of this color space to first convert from the input
color space to the CS_CIEXYZ color space, and then use the
fromCIEXYZ method of the CS_sRGB color space to
convert from CS_CIEXYZ to the output color space.
See {@link #toCIEXYZ(float[]) toCIEXYZ} and
{@link #fromCIEXYZ(float[]) fromCIEXYZ} for further information.

param
colorvalue a float array with length of at least the number
of components in this ColorSpace
return
a float array of length 3
throws
ArrayIndexOutOfBoundsException if array length is not
at least the number of components in this ColorSpace