Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

ColorUtils

class ColorUtils
kotlin.Any
   ↳ androidx.core.graphics.ColorUtils

A set of color-related utility methods, building upon those available in Color.

Summary

Public methods

static Int
HSLToColor(@NonNull hsl: FloatArray)

Convert HSL (hue-saturation-lightness) components to a RGB color.

static Int

Converts a color from CIE Lab to its RGB representation.

static Unit
LABToXYZ(l: Double, a: Double, b: Double, @NonNull outXyz: DoubleArray)

Converts a color from CIE Lab to CIE XYZ representation.

static Unit
RGBToHSL(r: Int, g: Int, b: Int, @NonNull outHsl: FloatArray)

Convert RGB components to HSL (hue-saturation-lightness).

static Unit
RGBToLAB(r: Int, g: Int, b: Int, @NonNull outLab: DoubleArray)

Convert RGB components to its CIE Lab representative components.

static Unit
RGBToXYZ(r: Int, g: Int, b: Int, @NonNull outXyz: DoubleArray)

Convert RGB components to its CIE XYZ representative components.

static Int

Converts a color from CIE XYZ to its RGB representation.

static Unit
XYZToLAB(x: Double, y: Double, z: Double, @NonNull outLab: DoubleArray)

Converts a color from CIE XYZ to CIE Lab representation.

static Int
blendARGB(color1: Int, color2: Int, ratio: Float)

Blend between two ARGB colors using the given ratio.

static Unit
blendHSL(@NonNull hsl1: FloatArray, @NonNull hsl2: FloatArray, ratio: Float, @NonNull outResult: FloatArray)

Blend between hsl1 and hsl2 using the given ratio.

static Unit
blendLAB(@NonNull lab1: DoubleArray, @NonNull lab2: DoubleArray, ratio: Double, @NonNull outResult: DoubleArray)

Blend between two CIE-LAB colors using the given ratio.

static Double
calculateContrast(foreground: Int, background: Int)

Returns the contrast ratio between foreground and background.

static Double

Returns the luminance of a color as a float between 0.0 and 1.0.

static Int
calculateMinimumAlpha(foreground: Int, background: Int, minContrastRatio: Float)

Calculates the minimum alpha value which can be applied to foreground so that would have a contrast value of at least minContrastRatio when compared to background.

static Unit
colorToHSL(color: Int, @NonNull outHsl: FloatArray)

Convert the ARGB color to its HSL (hue-saturation-lightness) components.

static Unit
colorToLAB(color: Int, @NonNull outLab: DoubleArray)

Convert the ARGB color to its CIE Lab representative components.

static Unit
colorToXYZ(color: Int, @NonNull outXyz: DoubleArray)

Convert the ARGB color to its CIE XYZ representative components.

static Int
compositeColors(foreground: Int, background: Int)

Composite two potentially translucent colors over each other and returns the result.

static Color
compositeColors(@NonNull foreground: Color, @NonNull background: Color)

Composites two translucent colors together.

static Double
distanceEuclidean(@NonNull labX: DoubleArray, @NonNull labY: DoubleArray)

Returns the euclidean distance between two LAB colors.

static Int
setAlphaComponent(color: Int, alpha: Int)

Set the alpha component of color to be alpha.

Public methods

HSLToColor

static fun HSLToColor(@NonNull hsl: FloatArray): Int

Convert HSL (hue-saturation-lightness) components to a RGB color.

  • hsl[0] is Hue [0 .. 360)
  • hsl[1] is Saturation [0...1]
  • hsl[2] is Lightness [0...1]
If hsv values are out of range, they are pinned.

Parameters
hsl FloatArray: 3-element array which holds the input HSL components
Return
Int: the resulting RGB color

LABToColor

static fun LABToColor(l: Double, a: Double, b: Double): Int

Converts a color from CIE Lab to its RGB representation.

Parameters
l Double: L component value [0...100]
a Double: A component value [-128...127]
b Double: B component value [-128...127]
Return
Int: int containing the RGB representation

LABToXYZ

static fun LABToXYZ(l: Double, a: Double, b: Double, @NonNull outXyz: DoubleArray): Unit

Converts a color from CIE Lab to CIE XYZ representation.

The resulting XYZ representation will use the D65 illuminant and the CIE 2° Standard Observer (1931).

  • outXyz[0] is X [0 ...95.047)
  • outXyz[1] is Y [0...100)
  • outXyz[2] is Z [0...108.883)
Parameters
l Double: L component value [0...100)
a Double: A component value [-128...127)
b Double: B component value [-128...127)
outXyz Double: 3-element array which holds the resulting XYZ components

RGBToHSL

static fun RGBToHSL(r: Int, g: Int, b: Int, @NonNull outHsl: FloatArray): Unit

Convert RGB components to HSL (hue-saturation-lightness).

  • outHsl[0] is Hue [0 .. 360)
  • outHsl[1] is Saturation [0...1]
  • outHsl[2] is Lightness [0...1]

Parameters
r Int: red component value [0..255]
g Int: green component value [0..255]
b Int: blue component value [0..255]
outHsl Int: 3-element array which holds the resulting HSL components

RGBToLAB

static fun RGBToLAB(r: Int, g: Int, b: Int, @NonNull outLab: DoubleArray): Unit

Convert RGB components to its CIE Lab representative components.

  • outLab[0] is L [0 ...1)
  • outLab[1] is a [-128...127)
  • outLab[2] is b [-128...127)

Parameters
r Int: red component value [0..255]
g Int: green component value [0..255]
b Int: blue component value [0..255]
outLab Int: 3-element array which holds the resulting LAB components

RGBToXYZ

static fun RGBToXYZ(r: Int, g: Int, b: Int, @NonNull outXyz: DoubleArray): Unit

Convert RGB components to its CIE XYZ representative components.

The resulting XYZ representation will use the D65 illuminant and the CIE 2° Standard Observer (1931).

  • outXyz[0] is X [0 ...95.047)
  • outXyz[1] is Y [0...100)
  • outXyz[2] is Z [0...108.883)
Parameters
r Int: red component value [0..255]
g Int: green component value [0..255]
b Int: blue component value [0..255]
outXyz Int: 3-element array which holds the resulting XYZ components

XYZToColor

static fun XYZToColor(x: Double, y: Double, z: Double): Int

Converts a color from CIE XYZ to its RGB representation.

This method expects the XYZ representation to use the D65 illuminant and the CIE 2° Standard Observer (1931).

Parameters
x Double: X component value [0...95.047)
y Double: Y component value [0...100)
z Double: Z component value [0...108.883)
Return
Int: int containing the RGB representation

XYZToLAB

static fun XYZToLAB(x: Double, y: Double, z: Double, @NonNull outLab: DoubleArray): Unit

Converts a color from CIE XYZ to CIE Lab representation.

This method expects the XYZ representation to use the D65 illuminant and the CIE 2° Standard Observer (1931).

  • outLab[0] is L [0 ...1)
  • outLab[1] is a [-128...127)
  • outLab[2] is b [-128...127)
Parameters
x Double: X component value [0...95.047)
y Double: Y component value [0...100)
z Double: Z component value [0...108.883)
outLab Double: 3-element array which holds the resulting Lab components

blendARGB

static fun blendARGB(color1: Int, color2: Int, ratio: Float): Int

Blend between two ARGB colors using the given ratio.

A blend ratio of 0.0 will result in color1, 0.5 will give an even blend, 1.0 will result in color2.

Parameters
color1 Int: the first ARGB color
color2 Int: the second ARGB color
ratio Int: the blend ratio of color1 to color2

blendHSL

static fun blendHSL(@NonNull hsl1: FloatArray, @NonNull hsl2: FloatArray, ratio: Float, @NonNull outResult: FloatArray): Unit

Blend between hsl1 and hsl2 using the given ratio. This will interpolate the hue using the shortest angle.

A blend ratio of 0.0 will result in hsl1, 0.5 will give an even blend, 1.0 will result in hsl2.

Parameters
hsl1 FloatArray: 3-element array which holds the first HSL color
hsl2 FloatArray: 3-element array which holds the second HSL color
ratio FloatArray: the blend ratio of hsl1 to hsl2
outResult FloatArray: 3-element array which holds the resulting HSL components

blendLAB

static fun blendLAB(@NonNull lab1: DoubleArray, @NonNull lab2: DoubleArray, ratio: Double, @NonNull outResult: DoubleArray): Unit

Blend between two CIE-LAB colors using the given ratio.

A blend ratio of 0.0 will result in lab1, 0.5 will give an even blend, 1.0 will result in lab2.

Parameters
lab1 DoubleArray: 3-element array which holds the first LAB color
lab2 DoubleArray: 3-element array which holds the second LAB color
ratio DoubleArray: the blend ratio of lab1 to lab2
outResult DoubleArray: 3-element array which holds the resulting LAB components

calculateContrast

static fun calculateContrast(foreground: Int, background: Int): Double

Returns the contrast ratio between foreground and background. background must be opaque.

Formula defined here.

calculateLuminance

static fun calculateLuminance(color: Int): Double

Returns the luminance of a color as a float between 0.0 and 1.0.

Defined as the Y component in the XYZ representation of color.

calculateMinimumAlpha

static fun calculateMinimumAlpha(foreground: Int, background: Int, minContrastRatio: Float): Int

Calculates the minimum alpha value which can be applied to foreground so that would have a contrast value of at least minContrastRatio when compared to background.

Parameters
foreground Int: the foreground color
background Int: the opaque background color
minContrastRatio Int: the minimum contrast ratio
Return
Int: the alpha value in the range 0-255, or -1 if no value could be calculated

colorToHSL

static fun colorToHSL(color: Int, @NonNull outHsl: FloatArray): Unit

Convert the ARGB color to its HSL (hue-saturation-lightness) components.

  • outHsl[0] is Hue [0 .. 360)
  • outHsl[1] is Saturation [0...1]
  • outHsl[2] is Lightness [0...1]

Parameters
color Int: the ARGB color to convert. The alpha component is ignored
outHsl Int: 3-element array which holds the resulting HSL components

colorToLAB

static fun colorToLAB(color: Int, @NonNull outLab: DoubleArray): Unit

Convert the ARGB color to its CIE Lab representative components.

Parameters
color Int: the ARGB color to convert. The alpha component is ignored
outLab Int: 3-element array which holds the resulting LAB components

colorToXYZ

static fun colorToXYZ(color: Int, @NonNull outXyz: DoubleArray): Unit

Convert the ARGB color to its CIE XYZ representative components.

The resulting XYZ representation will use the D65 illuminant and the CIE 2° Standard Observer (1931).

  • outXyz[0] is X [0 ...95.047)
  • outXyz[1] is Y [0...100)
  • outXyz[2] is Z [0...108.883)
Parameters
color Int: the ARGB color to convert. The alpha component is ignored
outXyz Int: 3-element array which holds the resulting LAB components

compositeColors

static fun compositeColors(foreground: Int, background: Int): Int

Composite two potentially translucent colors over each other and returns the result.

compositeColors

@NonNull static fun compositeColors(@NonNull foreground: Color, @NonNull background: Color): Color

Composites two translucent colors together. More specifically, adds two colors using the source over blending mode. The colors must not be pre-multiplied and the result is a non pre-multiplied color.

If the two colors have different color spaces, the foreground color is converted to the color space of the background color.

The following example creates a purple color by blending opaque blue with semi-translucent red:

<code>Color purple = ColorUtils.compositeColors(
              Color.valueOf(1f, 0f, 0f, 0.5f),
              Color.valueOf(0f, 0f, 1f));
      </code>
Note: This method requires API 26 or newer.
Exceptions
IllegalArgumentException if the models of the colors do not match

distanceEuclidean

static fun distanceEuclidean(@NonNull labX: DoubleArray, @NonNull labY: DoubleArray): Double

Returns the euclidean distance between two LAB colors.

setAlphaComponent

static fun setAlphaComponent(color: Int, alpha: Int): Int

Set the alpha component of color to be alpha.