OpenJDK 27 · java.awt.color.ColorSpace · APIdia, the JavaDoc alternative

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).

Modifier and Type	Class and Description
private static interface	ColorSpace.BuiltInSpace The lazy cache of singletons for the predefined built-in color spaces.

Field Summary

Modifier and Type	Field and Description
private transient volatile String[]	compName Lazy-initialized names of components in the color space.
public static final int	CS_CIEXYZ The built-in CIEXYZ conversion color space defined above.
public static final int	CS_GRAY The built-in linear gray scale color space.
public static final int	CS_LINEAR_RGB The built-in linear RGB color space.
public static final int	CS_PYCC The built-in Photo YCC conversion color space.
public static final int	CS_sRGB The built-in sRGB color space defined at http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html.
private final int	numComponents
private static final long	serialVersionUID Use serialVersionUID from JDK 1.2 for interoperability.
private final int	type
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_CMY Any of the family of CMY color spaces.
public static final int	TYPE_CMYK Any of the family of CMYK 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	TYPE_GRAY Any of the family of GRAY color spaces.
public static final int	TYPE_HLS Any of the family of HLS color spaces.
public static final int	TYPE_HSV Any of the family of HSV 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_RGB Any of the family of RGB color spaces.
public static final int	TYPE_XYZ Any of the family of XYZ 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.

Access	Constructor and Description
protected	ColorSpace(int one of the `ColorSpace` type constants type, int the number of components in the color space numComponents) Constructs a `ColorSpace` object given a color space type and the number of components.

Method Summary

Modifier and Type	Method and Description
public abstract float[]	Returns: a float array with length equal to the number of components in this `ColorSpace` fromCIEXYZ(float[] a float array with length of at least 3 colorvalue) Transforms a color value assumed to be in the `CS_CIEXYZ` conversion color space into this `ColorSpace`.
public abstract float[]	Returns: a float array with length equal to the number of components in this `ColorSpace` fromRGB(float[] a float array with length of at least 3 rgbvalue) Transforms a color value assumed to be in the default `CS_sRGB` color space into this `ColorSpace`.
public static ColorSpace	Returns: the requested `ColorSpace` object getInstance(int 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`) cspace) Returns a `ColorSpace` representing one of the specific predefined color spaces.
public float	Returns: the maximum normalized component value getMaxValue(int the component index component) Returns the maximum normalized color component value for the specified component.
public float	Returns: the minimum normalized component value getMinValue(int the component index component) Returns the minimum normalized color component value for the specified component.
public String	Returns: the name of the component at the specified index getName(int the component index component) Returns the name of the component given the component index.
public int	Returns: the number of components in this `ColorSpace` getNumComponents() Returns the number of components of this ColorSpace.
public int	Returns: the type constant that represents the type of this `ColorSpace` getType() Returns the color space type of this `ColorSpace` (for example `TYPE_RGB`, `TYPE_XYZ`, ...).
public boolean	Returns: `true` if this is a `CS_sRGB` color space, `false` if it is not isCS_sRGB() Returns true if the `ColorSpace` is `CS_sRGB`.
pack-priv final void	rangeCheck(int the component index component) Checks that `component` is in range of the number of components.
public abstract float[]	Returns: a float array of length 3 toCIEXYZ(float[] a float array with length of at least the number of components in this `ColorSpace` colorvalue) Transforms a color value assumed to be in this `ColorSpace` into the `CS_CIEXYZ` conversion color space.
public abstract float[]	Returns: a float array of length 3 toRGB(float[] a float array with length of at least the number of components in this `ColorSpace` colorvalue) Transforms a color value assumed to be in this `ColorSpace` into a value in the default `CS_sRGB` color space.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

compName	back to summary
private transient volatile String[] compName Lazy-initialized names of components in the color space.

CS_CIEXYZ	back to summary
public static final int CS_CIEXYZ The built-in CIEXYZ conversion color space defined above. Annotations @Native

CS_GRAY	back to summary
public static final int CS_GRAY The built-in linear gray scale color space. Annotations @Native

CS_LINEAR_RGB	back to summary
public static final int CS_LINEAR_RGB The 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. Annotations @Native

CS_PYCC	back to summary
public static final int CS_PYCC The built-in Photo YCC conversion color space. Annotations @Native

CS_sRGB	back to summary
public static final int CS_sRGB The built-in sRGB color space defined at http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html. Annotations @Native

numComponents	back to summary
private final int numComponents

serialVersionUID	back to summary
private static final long serialVersionUID Use serialVersionUID from JDK 1.2 for interoperability. Annotations @Serial

type	back to summary
private final int type

TYPE_2CLR	back to summary
public static final int TYPE_2CLR Generic 2 component color spaces. Annotations @Native

TYPE_3CLR	back to summary
public static final int TYPE_3CLR Generic 3 component color spaces. Annotations @Native

TYPE_4CLR	back to summary
public static final int TYPE_4CLR Generic 4 component color spaces. Annotations @Native

TYPE_5CLR	back to summary
public static final int TYPE_5CLR Generic 5 component color spaces. Annotations @Native

TYPE_6CLR	back to summary
public static final int TYPE_6CLR Generic 6 component color spaces. Annotations @Native

TYPE_7CLR	back to summary
public static final int TYPE_7CLR Generic 7 component color spaces. Annotations @Native

TYPE_8CLR	back to summary
public static final int TYPE_8CLR Generic 8 component color spaces. Annotations @Native

TYPE_9CLR	back to summary
public static final int TYPE_9CLR Generic 9 component color spaces. Annotations @Native

TYPE_ACLR	back to summary
public static final int TYPE_ACLR Generic 10 component color spaces. Annotations @Native

TYPE_BCLR	back to summary
public static final int TYPE_BCLR Generic 11 component color spaces. Annotations @Native

TYPE_CCLR	back to summary
public static final int TYPE_CCLR Generic 12 component color spaces. Annotations @Native

TYPE_CMY	back to summary
public static final int TYPE_CMY Any of the family of CMY color spaces. Annotations @Native

TYPE_CMYK	back to summary
public static final int TYPE_CMYK Any of the family of CMYK color spaces. Annotations @Native

TYPE_DCLR	back to summary
public static final int TYPE_DCLR Generic 13 component color spaces. Annotations @Native

TYPE_ECLR	back to summary
public static final int TYPE_ECLR Generic 14 component color spaces. Annotations @Native

TYPE_FCLR	back to summary
public static final int TYPE_FCLR Generic 15 component color spaces. Annotations @Native

TYPE_GRAY	back to summary
public static final int TYPE_GRAY Any of the family of GRAY color spaces. Annotations @Native

TYPE_HLS	back to summary
public static final int TYPE_HLS Any of the family of HLS color spaces. Annotations @Native

TYPE_HSV	back to summary
public static final int TYPE_HSV Any of the family of HSV color spaces. Annotations @Native

TYPE_Lab	back to summary
public static final int TYPE_Lab Any of the family of Lab color spaces. Annotations @Native

TYPE_Luv	back to summary
public static final int TYPE_Luv Any of the family of Luv color spaces. Annotations @Native

TYPE_RGB	back to summary
public static final int TYPE_RGB Any of the family of RGB color spaces. Annotations @Native

TYPE_XYZ	back to summary
public static final int TYPE_XYZ Any of the family of XYZ color spaces. Annotations @Native

TYPE_YCbCr	back to summary
public static final int TYPE_YCbCr Any of the family of YCbCr color spaces. Annotations @Native

TYPE_Yxy	back to summary
public static final int TYPE_Yxy Any of the family of Yxy color spaces. Annotations @Native

Constructor Detail

ColorSpace back to summary

ColorSpace	back to summary
protected ColorSpace(int type, int numComponents) Constructs a `ColorSpace` object given a color space type and the number of components. Parameters type:int one of the `ColorSpace` type constants numComponents:int the number of components in the color space

protected ColorSpace(int type, int numComponents)

Constructs a ColorSpace object given a color space type and the number of components.

Parameters

type:int: one of the ColorSpace type constants
numComponents:int: the number of components in the color space

Method Detail

fromCIEXYZ back to summary

fromCIEXYZ	back to 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 `fromCIEXYZ` method of `ICC_ColorSpace` for further information. Parameters colorvalue:float[] a float array with length of at least 3 Returns:float[] a float array with length equal to the number of components in this `ColorSpace` Exceptions ArrayIndexOutOfBoundsException: if array length is not at least 3 NullPointerException: if `colorvalue` is `null`

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 fromCIEXYZ method of ICC_ColorSpace for further information.

Parameters

colorvalue:float[]: a float array with length of at least 3

Returns:float[]

a float array with length equal to the number of components in this ColorSpace

Exceptions

ArrayIndexOutOfBoundsException:: if array length is not at least 3
NullPointerException:: if colorvalue is null

fromRGB back to summary

fromRGB	back to summary
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 `toCIEXYZ` and `fromCIEXYZ` for further information. Parameters rgbvalue:float[] a float array with length of at least 3 Returns:float[] a float array with length equal to the number of components in this `ColorSpace` Exceptions ArrayIndexOutOfBoundsException: if array length is not at least 3 NullPointerException: if `rgbvalue` is `null`

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 toCIEXYZ and fromCIEXYZ for further information.

Parameters

rgbvalue:float[]: a float array with length of at least 3

Returns:float[]

a float array with length equal to the number of components in this ColorSpace

Exceptions

ArrayIndexOutOfBoundsException:: if array length is not at least 3
NullPointerException:: if rgbvalue is null

getInstance back to summary

getInstance	back to summary
public static ColorSpace getInstance(int cspace) Returns a `ColorSpace` representing one of the specific predefined color spaces. Parameters cspace:int 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`) Returns:ColorSpace the requested `ColorSpace` object Exceptions IllegalArgumentException: if `cspace` is not one of the predefined color space types

public static ColorSpace getInstance(int cspace)

Returns a ColorSpace representing one of the specific predefined color spaces.

Parameters

cspace:int: 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)

Returns:ColorSpace

the requested ColorSpace object

Exceptions

IllegalArgumentException:: if cspace is not one of the predefined color space types

getMaxValue back to summary

getMaxValue	back to summary
public float getMaxValue(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. Parameters component:int the component index Returns:float the maximum normalized component value Exceptions IllegalArgumentException: if component is less than 0 or greater than `numComponents - 1` Since 1.4

public float getMaxValue(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.

Parameters

component:int: the component index

Returns:float

the maximum normalized component value

Exceptions

IllegalArgumentException:: if component is less than 0 or greater than numComponents - 1

Since

1.4

getMinValue back to summary

getMinValue	back to summary
public float getMinValue(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. Parameters component:int the component index Returns:float the minimum normalized component value Exceptions IllegalArgumentException: if component is less than 0 or greater than `numComponents - 1` Since 1.4

public float getMinValue(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.

Parameters

component:int: the component index

Returns:float

the minimum normalized component value

Exceptions

IllegalArgumentException:: if component is less than 0 or greater than numComponents - 1

Since

1.4

getName back to summary

getName	back to summary
public String getName(int component) Returns the name of the component given the component index. Parameters component:int the component index Returns:String the name of the component at the specified index Exceptions IllegalArgumentException: if `component` is less than 0 or greater than `numComponents - 1`

public String getName(int component)

Returns the name of the component given the component index.

Parameters

component:int: the component index

Returns:String

the name of the component at the specified index

Exceptions

IllegalArgumentException:: if component is less than 0 or greater than numComponents - 1

getNumComponents back to summary

getNumComponents	back to summary
public int getNumComponents() Returns the number of components of this ColorSpace. Returns:int the number of components in this `ColorSpace`

public int getNumComponents()

Returns the number of components of this ColorSpace.

Returns:int: the number of components in this ColorSpace

getType back to summary

getType	back to summary
public int getType() 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. Returns:int the type constant that represents the type of this `ColorSpace`

public int getType()

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.

Returns:int: the type constant that represents the type of this ColorSpace

isCS_sRGB back to summary

isCS_sRGB	back to summary
public boolean isCS_sRGB() Returns true if the `ColorSpace` is `CS_sRGB`. Returns:boolean `true` if this is a `CS_sRGB` color space, `false` if it is not

public boolean isCS_sRGB()

Returns true if the ColorSpace is CS_sRGB.

Returns:boolean: true if this is a CS_sRGB color space, false if it is not

rangeCheck back to summary

rangeCheck	back to summary
pack-priv final void rangeCheck(int component) Checks that `component` is in range of the number of components. Parameters component:int the component index Exceptions IllegalArgumentException: if component is less than 0 or greater than `numComponents - 1`

pack-priv final void rangeCheck(int component)

Checks that component is in range of the number of components.

Parameters

component:int: the component index

Exceptions

IllegalArgumentException:: if component is less than 0 or greater than numComponents - 1

toCIEXYZ back to summary

toCIEXYZ	back to summary
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 `toCIEXYZ` method of `ICC_ColorSpace` for further information. Parameters colorvalue:float[] a float array with length of at least the number of components in this `ColorSpace` Returns:float[] a float array of length 3 Exceptions ArrayIndexOutOfBoundsException: if array length is not at least the number of components in this `ColorSpace` NullPointerException: if `colorvalue` is `null`

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 toCIEXYZ method of ICC_ColorSpace for further information.

Parameters

colorvalue:float[]: a float array with length of at least the number of components in this ColorSpace

Returns:float[]

a float array of length 3

Exceptions

ArrayIndexOutOfBoundsException:: if array length is not at least the number of components in this ColorSpace
NullPointerException:: if colorvalue is null

toRGB back to summary

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 toCIEXYZ and fromCIEXYZ for further information.

Parameters

colorvalue:float[]: a float array with length of at least the number of components in this ColorSpace

Returns:float[]

a float array of length 3

Exceptions

ArrayIndexOutOfBoundsException:: if array length is not at least the number of components in this ColorSpace
NullPointerException:: if colorvalue is null

Modifier and Type	Field and Description
public static final ColorSpace	GRAY
public static final ColorSpace	LRGB
public static final ColorSpace	PYCC
public static final ColorSpace	SRGB
public static final ColorSpace	XYZ

public abstract Class ColorSpace

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Interface ColorSpace.BuiltInSpace

Field Summary

Field Detail