ColorSpace

Artifact: androidx.compose.ui:ui-graphics

Added in 1.0.0

Cmn
```
abstract class ColorSpace
```

Known direct subclasses

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 and getMaxValue 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 ColorSpaces object.

The documentation of ColorSpaces 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 and fromXyz.

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 connect method to perform conversions between color spaces. A color space can be manually adapted to a specific white point using adapt. 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
val connector = ColorSpaces.DciP3.connect(ColorSpaces.BT2020)
val bt2020Values = connector.transform(p3r, p3g, p3b);

You can easily convert to sRGB by omitting the color space parameter:

// Convert from DCI-P3 to sRGB
val connector = ColorSpaces.DciP3.connect()
val sRGBValues = 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)
val connector = ColorSpaces.CieLab.connect(ColorSpaces.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.

See also
`ColorSpaces`
`ColorModel`
`Connector`
`Adaptation`

Summary

Public constructors
`ColorSpace(name: String, model: ColorModel)`	Cmn

Public functions
`open operator Boolean`	`equals(other: Any?)`	Cmn
`abstract @Size(min = 3) FloatArray`	`fromXyz(v: @Size(min = 3) FloatArray)` Converts tristimulus values from the CIE XYZ space to this color space's color model.	Cmn
`@Size(min = 3) FloatArray`	`fromXyz(x: Float, y: Float, z: Float)` Converts tristimulus values from the CIE XYZ space to this color space's color model.	Cmn
`abstract Float`	`getMaxValue(component: @IntRange(from = 0, to = 3) Int)` Returns the maximum valid value for the specified component of this color space's color model.	Cmn
`abstract Float`	`getMinValue(component: @IntRange(from = 0, to = 3) Int)` Returns the minimum valid value for the specified component of this color space's color model.	Cmn
`open Int`	`hashCode()`	Cmn
`open String`	`toString()` Returns a string representation of the object.	Cmn
`abstract @Size(min = 3) FloatArray`	`toXyz(v: @Size(min = 3) FloatArray)` Converts a color value from this color space's model to tristimulus CIE XYZ values.	Cmn
`@Size(value = 3) FloatArray`	`toXyz(r: Float, g: Float, b: Float)` Converts a color value from this color space's model to tristimulus CIE XYZ values.	Cmn

Public properties
`Int`	`componentCount` Returns the number of components that form a color value according to this color space's color model.	Cmn
`open Boolean`	`isSrgb` Indicates whether this color space is the sRGB color space or equivalent to the sRGB color space.	Cmn
`abstract Boolean`	`isWideGamut` Returns whether this color space is a wide-gamut color space.	Cmn
`ColorModel`	`model` The color model of this color space.	Cmn
`String`	`name` Returns the name of this color space.	Cmn

Extension functions
`ColorSpace`	`@RequiresApi(value = 26) ColorSpace.toAndroidColorSpace()` Convert the Compose `ColorSpace` into an Android framework `android.graphics.ColorSpace`	android
`ColorSpace`	`ColorSpace.adapt(whitePoint: WhitePoint, adaptation: Adaptation)` Performs the chromatic adaptation of a color space from its native white point to the specified white point.	Cmn
`Connector`	`ColorSpace.connect(destination: ColorSpace, intent: RenderIntent)` Connects two color spaces to allow conversion from the source color space to the destination color space.	Cmn

Public constructors

ColorSpace

Cmn

ColorSpace(name: String, model: ColorModel)

Public functions

equals

Cmn

open operator fun equals(other: Any?): Boolean

fromXyz

Cmn

Added in 1.0.0

abstract fun fromXyz(v: @Size(min = 3) FloatArray): @Size(min = 3) FloatArray

Converts tristimulus values from the CIE XYZ space to this color space's color model. The resulting value is passed back in the specified array.

The specified array's length must be at least equal to to the number of color components as returned by ColorModel.componentCount, and its first 3 values must be the XYZ components to convert from.

Parameters
`v: @Size(min = 3) FloatArray`	An array of color components containing the XYZ values to convert from, and large enough to hold the number of components of this color space's model. The minimum size is 3, but most color spaces have 4 components.

Returns
`@Size(min = 3) FloatArray`	The array passed in parameter `v`.

See also
`fromXyz`
`toXyz`

fromXyz

Cmn

Added in 1.0.0

fun fromXyz(x: Float, y: Float, z: Float): @Size(min = 3) FloatArray

Converts tristimulus values from the CIE XYZ space to this color space's color model.

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

Returns
`@Size(min = 3) FloatArray`	A new array whose size is equal to the number of color components as returned by `ColorModel.componentCount`.

See also
`fromXyz`
`toXyz`

getMaxValue

Cmn

Added in 1.0.0

abstract fun getMaxValue(component: @IntRange(from = 0, to = 3) Int): Float

Returns the maximum valid value for the specified component of this color space's color model.

Parameters
`component: @IntRange(from = 0, to = 3) Int`	The index of the component, from `0` to `3`, inclusive

Returns
`Float`	A floating point value greater than `getMinValue`

See also
`getMinValue`
`componentCount`

getMinValue

Cmn

Added in 1.0.0

abstract fun getMinValue(component: @IntRange(from = 0, to = 3) Int): Float

Returns the minimum valid value for the specified component of this color space's color model.

Parameters
`component: @IntRange(from = 0, to = 3) Int`	The index of the component, from `0` to `3`, inclusive.

Returns
`Float`	A floating point value less than `getMaxValue`

See also
`getMaxValue`
`componentCount`

hashCode

Cmn

open fun hashCode(): Int

toString

Cmn

open fun toString(): String

Returns a string representation of the object. This method returns a string equal to the value of:

"$name "(id=$id, model=$model)"

For instance, the string representation of the sRGB color space is equal to the following value:

sRGB IEC61966-2.1 (id=0, model=RGB)

Returns
`String`	A string representation of the object

toXyz

Cmn

Added in 1.0.0

abstract fun toXyz(v: @Size(min = 3) FloatArray): @Size(min = 3) FloatArray

Converts a color value from this color space's model to tristimulus CIE XYZ values. If the color model of this color space is not RGB, it is assumed that the target CIE XYZ space uses a D50 standard illuminant.

The specified array's length must be at least equal to to the number of color components as returned by ColorModel.componentCount.

Parameters
`v: @Size(min = 3) FloatArray`	An array of color components containing the color space's color value to convert to XYZ, and large enough to hold the resulting tristimulus XYZ values, at least 3 values.

Returns
`@Size(min = 3) FloatArray`	The array passed in parameter `v`.

See also
`toXyz`
`fromXyz`

toXyz

Cmn

Added in 1.0.0

fun toXyz(r: Float, g: Float, b: Float): @Size(value = 3) FloatArray

This method is a convenience for color spaces with a model of 3 components (RGB or ColorModel.Lab for instance). With color spaces using fewer or more components, use toXyz instead.

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)

Returns
`@Size(value = 3) FloatArray`	A new array of 3 floats, containing tristimulus XYZ values

See also
`toXyz`
`fromXyz`

Public properties

componentCount

Cmn

Added in 1.0.0

val componentCount: Int

Returns the number of components that form a color value according to this color space's color model.

Returns
`Int`	An integer between 1 and 4

See also
`ColorModel`
`model`

isSrgb

Cmn

Added in 1.0.0

open val isSrgb: Boolean

Indicates whether this color space is the sRGB color space or equivalent to the sRGB color space.

A color space is considered sRGB if it meets all the following conditions:

Its color model is ColorModel.Rgb. * Its primaries are within 1e-3 of the true sRGB primaries.

Its white point is within 1e-3 of the CIE standard illuminant D65.

Its opto-electronic transfer function is not linear.
Its electro-optical transfer function is not linear.
Its transfer functions yield values within 1e-3 of ColorSpaces.Srgb.
Its range is [0..1].

This method always returns true for ColorSpaces.Srgb.

Returns
`Boolean`	True if this color space is the sRGB color space (or a close approximation), false otherwise

isWideGamut

Cmn

Added in 1.0.0

abstract val isWideGamut: Boolean

Returns whether this color space is a wide-gamut color space. An RGB color space is wide-gamut if its gamut entirely contains the sRGB gamut and if the area of its gamut is 90% of greater than the area of the NTSC gamut.

Returns
`Boolean`	True if this color space is a wide-gamut color space, false otherwise

model

Cmn

Added in 1.0.0

val model: ColorModel

The color model of this color space.

See also
`ColorModel`
`componentCount`

name

Cmn

Added in 1.0.0

val name: String

Returns the name of this color space. The name is never null and contains always at least 1 character.

Color space names are recommended to be unique but are not guaranteed to be. There is no defined format but the name usually falls in one of the following categories:

Generic names used to identify color spaces in non-RGB color models. For instance: Generic Lab*.
Names tied to a particular specification. For instance: sRGB IEC61966-2.1 or SMPTE ST 2065-1:2012 ACES.
Ad-hoc names, often generated procedurally or by the user during a calibration workflow. These names often contain the make and model of the display.

Because the format of color space names is not defined, it is not recommended to programmatically identify a color space by its name alone. Names can be used as a first approximation.

It is however perfectly acceptable to display color space names to users in a UI, or in debuggers and logs. When displaying a color space name to the user, it is recommended to add extra information to avoid ambiguities: color model, a representation of the color space's gamut, white point, etc.

Returns
`String`	A non-null String of length >= 1

Extension functions

toAndroidColorSpace

android

Artifact: androidx.compose.ui:ui-graphics

View Source

@RequiresApi(value = 26)
fun ColorSpace.toAndroidColorSpace(): ColorSpace

Convert the Compose ColorSpace into an Android framework android.graphics.ColorSpace

adapt

Cmn

Artifact: androidx.compose.ui:ui-graphics

View Source

fun ColorSpace.adapt(
    whitePoint: WhitePoint,
    adaptation: Adaptation = Adaptation.Bradford
): ColorSpace

Performs the chromatic adaptation of a color space from its native white point to the specified white point. If the specified color space does not have an RGB color model, or if the color space already has the target white point, the color space is returned unmodified.

The chromatic adaptation is performed using the von Kries method described in the documentation of Adaptation.

Parameters
`whitePoint: WhitePoint`	The new white point
`adaptation: Adaptation = Adaptation.Bradford`	The adaptation matrix

Returns
`ColorSpace`	A new color space if the specified color space has an RGB model and a white point different from the specified white point; the specified color space otherwise

See also
`Adaptation`

connect

Cmn

Artifact: androidx.compose.ui:ui-graphics

View Source

fun ColorSpace.connect(
    destination: ColorSpace = ColorSpaces.Srgb,
    intent: RenderIntent = RenderIntent.Perceptual
): Connector

Connects two color spaces to allow conversion from the source color space to the destination color space. If the source and destination color spaces do not have the same profile connection space (CIE XYZ with the same white point), they are chromatically adapted to use the CIE standard illuminant D50 as needed.

If the source and destination are the same, an optimized connector is returned to avoid unnecessary computations and loss of precision.

Parameters
`destination: ColorSpace = ColorSpaces.Srgb`	The color space to convert colors to
`intent: RenderIntent = RenderIntent.Perceptual`	The render intent to map colors from the source to the destination

Returns
`Connector`	A non-null connector between the two specified color spaces