ColorSpace

Kotlin |Java

abstract class ColorSpace

kotlin.Any
↳	android.graphics.ColorSpace

Known Direct Subclasses

ColorSpace.Rgb

An RGB color space is an additive color space using the RGB color model (a color is therefore represented by a tuple of 3 numbers).

A ColorSpace is used to identify a specific organization of colors. Each color space is characterized by a color model that defines how a color value is represented (for instance the RGB color model defines a color value as a triplet of numbers).

Each component of a color must fall within a valid range, specific to each color space, defined by getMinValue(int) and getMaxValue(int) This range is commonly \([0..1]\). While it is recommended to use values in the valid range, a color space always clamps input and output values when performing operations such as converting to a different color space.

Using color spaces

This implementation provides a pre-defined set of common color spaces described in the Named enum. To obtain an instance of one of the pre-defined color spaces, simply invoke get(android.graphics.ColorSpace.Named):

ColorSpace sRgb = ColorSpace.get(ColorSpace.Named.SRGB);

The get(android.graphics.ColorSpace.Named) method always returns the same instance for a given name. Color spaces with an RGB color model can be safely cast to Rgb. Doing so gives you access to more APIs to query various properties of RGB color models: color gamut primaries, transfer functions, conversions to and from linear space, etc. Please refer to Rgb for more information.

The documentation of Named provides a detailed description of the various characteristics of each available color space.

Color space conversions

To allow conversion between color spaces, this implementation uses the CIE XYZ profile connection space (PCS). Color values can be converted to and from this PCS using toXyz(float[]) and fromXyz(float[]).

For color space with a non-RGB color model, the white point of the PCS must be the CIE standard illuminant D50. RGB color spaces use their native white point (D65 for sRGB for instance and must undergo chromatic adaptation as necessary.

Since the white point of the PCS is not defined for RGB color space, it is highly recommended to use the variants of the connect(android.graphics.ColorSpace,android.graphics.ColorSpace) method to perform conversions between color spaces. A color space can be manually adapted to a specific white point using adapt(android.graphics.ColorSpace,float[]). Please refer to the documentation of RGB color spaces for more information. Several common CIE standard illuminants are provided in this class as reference (see ILLUMINANT_D65 or ILLUMINANT_D50 for instance).

Here is an example of how to convert from a color space to another:

// Convert from DCI-P3 to Rec.2020
  ColorSpace.Connector connector = ColorSpace.connect(
          ColorSpace.get(ColorSpace.Named.DCI_P3),
          ColorSpace.get(ColorSpace.Named.BT2020));
 
  float[] bt2020 = connector.transform(p3r, p3g, p3b);

You can easily convert to sRGB by omitting the second parameter:

// Convert from DCI-P3 to sRGB
  ColorSpace.Connector connector = ColorSpace.connect(ColorSpace.get(ColorSpace.Named.DCI_P3));
 
  float[] sRGB = connector.transform(p3r, p3g, p3b);

Conversions also work between color spaces with different color models:

// Convert from CIE L*a*b* (color model Lab) to Rec.709 (color model RGB)
  ColorSpace.Connector connector = ColorSpace.connect(
          ColorSpace.get(ColorSpace.Named.CIE_LAB),
          ColorSpace.get(ColorSpace.Named.BT709));

Color spaces and multi-threading

Color spaces and other related classes (Connector for instance) are immutable and stateless. They can be safely used from multiple concurrent threads.

Public static methods provided by this class, such as get(android.graphics.ColorSpace.Named) and connect(android.graphics.ColorSpace,android.graphics.ColorSpace), are also guaranteed to be thread-safe.

Summary

Nested classes
	`Adaptation` List of adaptation matrices that can be used for chromatic adaptation using the von Kries transform.
open	`Connector` A connector transforms colors from a source color space to a destination color space.
	`Model` A color model is required by a `ColorSpace` to describe the way colors can be represented as tuples of numbers.
	`Named` List of common, named color spaces.
	`RenderIntent` A render intent determines how a `connector` maps colors from one color space to another.
open	`Rgb` An RGB color space is an additive color space using the `RGB` color model (a color is therefore represented by a tuple of 3 numbers).

Constants
static Int	`MAX_ID` The maximum ID value a color space can have.
static Int	`MIN_ID` The minimum ID value a color space can have.

Public methods
open static ColorSpace	`adapt(colorSpace: ColorSpace, whitePoint: FloatArray)` Performs the chromatic adaptation of a color space from its native white point to the specified white point.
open static ColorSpace	`adapt(colorSpace: ColorSpace, whitePoint: FloatArray, adaptation: ColorSpace.Adaptation)` Performs the chromatic adaptation of a color space from its native white point to the specified white point.
open static FloatArray	`cctToXyz(cct: Int)` Computes the chromaticity coordinates of a specified correlated color temperature (CCT) on the Planckian locus.
open static FloatArray	`chromaticAdaptation(adaptation: ColorSpace.Adaptation, srcWhitePoint: FloatArray, dstWhitePoint: FloatArray)` Computes the chromatic adaptation transform from the specified source white point to the specified destination white point.
open static ColorSpace.Connector	`connect(source: ColorSpace)` Connects the specified color spaces to sRGB.
open static ColorSpace.Connector	`connect(source: ColorSpace, destination: ColorSpace)` Connects two color spaces to allow conversion from the source color space to the destination color space.
open static ColorSpace.Connector	`connect(source: ColorSpace, destination: ColorSpace, intent: ColorSpace.RenderIntent)` Connects two color spaces to allow conversion from the source color space to the destination color space.
open static ColorSpace.Connector	`connect(source: ColorSpace, intent: ColorSpace.RenderIntent)` Connects the specified color spaces to sRGB.
open Boolean	`equals(other: Any?)`
open FloatArray	`fromXyz(x: Float, y: Float, z: Float)` Converts tristimulus values from the CIE XYZ space to this color space's color model.
abstract FloatArray	`fromXyz(v: FloatArray)` Converts tristimulus values from the CIE XYZ space to this color space's color model.
open static ColorSpace	`get(name: ColorSpace.Named)` Returns an instance of `ColorSpace` identified by the specified name.
open Int	`getComponentCount()` Returns the number of components that form a color value according to this color space's color model.
open Int	`getDataSpace()` Retrieve the `DataSpace` value from a `ColorSpace` object.
open static ColorSpace?	`getFromDataSpace(dataSpace: Int)` Create a `ColorSpace` object using a `DataSpace` value.
open Int	`getId()` Returns the ID of this color space.
abstract Float	`getMaxValue(component: Int)` Returns the maximum valid value for the specified component of this color space's color model.
abstract Float	`getMinValue(component: Int)` Returns the minimum valid value for the specified component of this color space's color model.
open ColorSpace.Model	`getModel()` Return the color model of this color space.
open String	`getName()` Returns the name of this color space.
open Int	`hashCode()`
open Boolean	`isSrgb()` Indicates whether this color space is the sRGB color space or equivalent to the sRGB color space.
abstract Boolean	`isWideGamut()` Returns whether this color space is a wide-gamut color space.
open static ColorSpace?	`match(toXYZD50: FloatArray, function: ColorSpace.Rgb.TransferParameters)` Returns a `Named` instance of `ColorSpace` that matches the specified RGB to CIE XYZ transform and transfer functions.
open String	`toString()` Returns a string representation of the object.
open FloatArray	`toXyz(r: Float, g: Float, b: Float)` Converts a color value from this color space's model to tristimulus CIE XYZ values.
abstract FloatArray	`toXyz(v: FloatArray)` Converts a color value from this color space's model to tristimulus CIE XYZ values.

Properties
static FloatArray!	`ILLUMINANT_A` Standard CIE 1931 2° illuminant A, encoded in xyY.
static FloatArray!	`ILLUMINANT_B` Standard CIE 1931 2° illuminant B, encoded in xyY.
static FloatArray!	`ILLUMINANT_C` Standard CIE 1931 2° illuminant C, encoded in xyY.
static FloatArray!	`ILLUMINANT_D50` Standard CIE 1931 2° illuminant D50, encoded in xyY.
static FloatArray!	`ILLUMINANT_D55` Standard CIE 1931 2° illuminant D55, encoded in xyY.
static FloatArray!	`ILLUMINANT_D60` Standard CIE 1931 2° illuminant D60, encoded in xyY.
static FloatArray!	`ILLUMINANT_D65` Standard CIE 1931 2° illuminant D65, encoded in xyY.
static FloatArray!	`ILLUMINANT_D75` Standard CIE 1931 2° illuminant D75, encoded in xyY.
static FloatArray!	`ILLUMINANT_E` Standard CIE 1931 2° illuminant E, encoded in xyY.

Parameters
`colorSpace`	ColorSpace: The color space to chromatically adapt This value cannot be `null`.
`whitePoint`	FloatArray: The new white point This value cannot be `null`.

Parameters
`adaptation`	ColorSpace.Adaptation: The adaptation method This value cannot be `null`.
`srcWhitePoint`	FloatArray: The white point to adapt from This value cannot be `null`.
`dstWhitePoint`	FloatArray: The white point to adapt to This value cannot be `null`.

Parameters
`source`	ColorSpace: The color space to convert colors from This value cannot be `null`.
`destination`	ColorSpace: The color space to convert colors to This value cannot be `null`.

Parameters
`source`	ColorSpace: The color space to convert colors from This value cannot be `null`.
`intent`	ColorSpace.RenderIntent: The render intent to map colors from the source to the destination This value cannot be `null`.

Parameters
`x`	Float: The X component of the color value
`y`	Float: The Y component of the color value
`z`	Float: The Z component of the color value

Parameters
`toXYZD50`	FloatArray: 3x3 column-major transform matrix from RGB to the profile connection space CIE XYZ as an array of 9 floats, cannot be null
`function`	ColorSpace.Rgb.TransferParameters: Parameters for the transfer functions This value cannot be `null`.

Parameters
`r`	Float: The first component of the value to convert from (typically R in RGB)
`g`	Float: The second component of the value to convert from (typically G in RGB)
`b`	Float: The third component of the value to convert from (typically B in RGB)

ColorSpace

Using color spaces

Color space conversions

Color spaces and multi-threading

Summary

Constants

MAX_ID

MIN_ID

Public methods

adapt

adapt

cctToXyz

chromaticAdaptation

connect

connect

connect

connect

equals

fromXyz

fromXyz

get

getComponentCount

getDataSpace

getFromDataSpace

getId

getMaxValue

getMinValue

getModel

getName

hashCode

isSrgb

isWideGamut

match

toString

toXyz

toXyz

Properties

ILLUMINANT_A

ILLUMINANT_B

ILLUMINANT_C

ILLUMINANT_D50

ILLUMINANT_D55

ILLUMINANT_D60

ILLUMINANT_D65

ILLUMINANT_D75

ILLUMINANT_E