ColorUtils

Added in 1.1.0

class ColorUtils


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

Summary

Public functions

java-static @ColorInt Int

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

java-static @ColorInt Int
LABToColor(
    l: @FloatRange(from = 0.0, to = 100) Double,
    a: @FloatRange(from = "-128", to = 127) Double,
    b: @FloatRange(from = "-128", to = 127) Double
)

Converts a color from CIE Lab to its RGB representation.

java-static Unit
LABToXYZ(
    l: @FloatRange(from = 0.0, to = 100) Double,
    a: @FloatRange(from = "-128", to = 127) Double,
    b: @FloatRange(from = "-128", to = 127) Double,
    outXyz: DoubleArray
)

Converts a color from CIE Lab to CIE XYZ representation.

java-static @ColorInt Int
M3HCTToColor(
    hue: @FloatRange(from = 0.0, to = 360, toInclusive = false) Float,
    chroma: @FloatRange(from = 0.0, to = Double.POSITIVE_INFINITY, toInclusive = false) Float,
    tone: @FloatRange(from = 0.0, to = 100) Float
)

Generate an ARGB color using M3HCT color parameters.

java-static Unit
RGBToHSL(
    r: @IntRange(from = 0, to = 255) Int,
    g: @IntRange(from = 0, to = 255) Int,
    b: @IntRange(from = 0, to = 255) Int,
    outHsl: FloatArray
)

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

java-static Unit
RGBToLAB(
    r: @IntRange(from = 0, to = 255) Int,
    g: @IntRange(from = 0, to = 255) Int,
    b: @IntRange(from = 0, to = 255) Int,
    outLab: DoubleArray
)

Convert RGB components to its CIE Lab representative components.

java-static Unit
RGBToXYZ(
    r: @IntRange(from = 0, to = 255) Int,
    g: @IntRange(from = 0, to = 255) Int,
    b: @IntRange(from = 0, to = 255) Int,
    outXyz: DoubleArray
)

Convert RGB components to its CIE XYZ representative components.

java-static @ColorInt Int
XYZToColor(
    x: @FloatRange(from = 0.0, to = 95.047) Double,
    y: @FloatRange(from = 0.0, to = 100.0) Double,
    z: @FloatRange(from = 0.0, to = 108.883) Double
)

Converts a color from CIE XYZ to its RGB representation.

java-static Unit
XYZToLAB(
    x: @FloatRange(from = 0.0, to = 95.047) Double,
    y: @FloatRange(from = 0.0, to = 100.0) Double,
    z: @FloatRange(from = 0.0, to = 108.883) Double,
    outLab: DoubleArray
)

Converts a color from CIE XYZ to CIE Lab representation.

java-static @ColorInt Int
blendARGB(
    color1: @ColorInt Int,
    color2: @ColorInt Int,
    ratio: @FloatRange(from = 0.0, to = 1.0) Float
)

Blend between two ARGB colors using the given ratio.

java-static Unit
blendHSL(
    hsl1: FloatArray,
    hsl2: FloatArray,
    ratio: @FloatRange(from = 0.0, to = 1.0) Float,
    outResult: FloatArray
)

Blend between hsl1 and hsl2 using the given ratio.

java-static Unit
blendLAB(
    lab1: DoubleArray,
    lab2: DoubleArray,
    ratio: @FloatRange(from = 0.0, to = 1.0) Double,
    outResult: DoubleArray
)

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

java-static Double
calculateContrast(foreground: @ColorInt Int, background: @ColorInt Int)

Returns the contrast ratio between foreground and background.

java-static @FloatRange(from = 0.0, to = 1.0) Double

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

java-static Int
calculateMinimumAlpha(
    foreground: @ColorInt Int,
    background: @ColorInt 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.

java-static Unit
colorToHSL(color: @ColorInt Int, outHsl: FloatArray)

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

java-static Unit
colorToLAB(color: @ColorInt Int, outLab: DoubleArray)

Convert the ARGB color to its CIE Lab representative components.

java-static Unit
colorToM3HCT(color: @ColorInt Int, outM3HCT: @Size(value = 3) FloatArray)

Generate a M3HCT color from an ARGB color.

java-static Unit
colorToXYZ(color: @ColorInt Int, outXyz: DoubleArray)

Convert the ARGB color to its CIE XYZ representative components.

java-static Color
@RequiresApi(value = 26)
compositeColors(foreground: Color, background: Color)

Composites two translucent colors together.

java-static Int
compositeColors(foreground: @ColorInt Int, background: @ColorInt Int)

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

java-static Double

Returns the euclidean distance between two LAB colors.

java-static @ColorInt Int
setAlphaComponent(color: @ColorInt Int, alpha: @IntRange(from = 0, to = 255) Int)

Set the alpha component of color to be alpha.

Public functions

HSLToColor

Added in 1.1.0
java-static fun HSLToColor(hsl: FloatArray): @ColorInt 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

Returns
@ColorInt Int

the resulting RGB color

LABToColor

Added in 1.1.0
java-static fun LABToColor(
    l: @FloatRange(from = 0.0, to = 100) Double,
    a: @FloatRange(from = "-128", to = 127) Double,
    b: @FloatRange(from = "-128", to = 127) Double
): @ColorInt Int

Converts a color from CIE Lab to its RGB representation.

Parameters
l: @FloatRange(from = 0.0, to = 100) Double

L component value [0, 100]

a: @FloatRange(from = "-128", to = 127) Double

A component value [-128, 127]

b: @FloatRange(from = "-128", to = 127) Double

B component value [-128, 127]

Returns
@ColorInt Int

int containing the RGB representation

LABToXYZ

Added in 1.1.0
java-static fun LABToXYZ(
    l: @FloatRange(from = 0.0, to = 100) Double,
    a: @FloatRange(from = "-128", to = 127) Double,
    b: @FloatRange(from = "-128", to = 127) Double,
    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: @FloatRange(from = 0.0, to = 100) Double

L component value [0, 100]

a: @FloatRange(from = "-128", to = 127) Double

A component value [-128, 127)

b: @FloatRange(from = "-128", to = 127) Double

B component value [-128, 127)

outXyz: DoubleArray

3-element array which holds the resulting XYZ components

M3HCTToColor

Added in 1.11.0
java-static fun M3HCTToColor(
    hue: @FloatRange(from = 0.0, to = 360, toInclusive = false) Float,
    chroma: @FloatRange(from = 0.0, to = Double.POSITIVE_INFINITY, toInclusive = false) Float,
    tone: @FloatRange(from = 0.0, to = 100) Float
): @ColorInt Int

Generate an ARGB color using M3HCT color parameters. HCT color space is a new color space proposed in Material Design 3

Parameters
hue: @FloatRange(from = 0.0, to = 360, toInclusive = false) Float

is Hue in M3HCT [0, 360); invalid values are corrected.

chroma: @FloatRange(from = 0.0, to = Double.POSITIVE_INFINITY, toInclusive = false) Float

is Chroma in M3HCT [0, ?); Chroma may decrease because chroma has a different maximum for any given hue and tone.

tone: @FloatRange(from = 0.0, to = 100) Float

is Tone in M3HCT [0, 100]; invalid values are corrected.

See also

RGBToHSL

Added in 1.1.0
java-static fun RGBToHSL(
    r: @IntRange(from = 0, to = 255) Int,
    g: @IntRange(from = 0, to = 255) Int,
    b: @IntRange(from = 0, to = 255) Int,
    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: @IntRange(from = 0, to = 255) Int

red component value [0, 255]

g: @IntRange(from = 0, to = 255) Int

green component value [0, 255]

b: @IntRange(from = 0, to = 255) Int

blue component value [0, 255]

outHsl: FloatArray

3-element array which holds the resulting HSL components

RGBToLAB

Added in 1.1.0
java-static fun RGBToLAB(
    r: @IntRange(from = 0, to = 255) Int,
    g: @IntRange(from = 0, to = 255) Int,
    b: @IntRange(from = 0, to = 255) Int,
    outLab: DoubleArray
): Unit

Convert RGB components to its CIE Lab representative components.

  • outLab[0] is L [0, 100]
  • outLab[1] is a [-128, 127)
  • outLab[2] is b [-128, 127)
Parameters
r: @IntRange(from = 0, to = 255) Int

red component value [0, 255]

g: @IntRange(from = 0, to = 255) Int

green component value [0, 255]

b: @IntRange(from = 0, to = 255) Int

blue component value [0, 255]

outLab: DoubleArray

3-element array which holds the resulting LAB components

RGBToXYZ

Added in 1.1.0
java-static fun RGBToXYZ(
    r: @IntRange(from = 0, to = 255) Int,
    g: @IntRange(from = 0, to = 255) Int,
    b: @IntRange(from = 0, to = 255) Int,
    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: @IntRange(from = 0, to = 255) Int

red component value [0, 255]

g: @IntRange(from = 0, to = 255) Int

green component value [0, 255]

b: @IntRange(from = 0, to = 255) Int

blue component value [0, 255]

outXyz: DoubleArray

3-element array which holds the resulting XYZ components

XYZToColor

Added in 1.1.0
java-static fun XYZToColor(
    x: @FloatRange(from = 0.0, to = 95.047) Double,
    y: @FloatRange(from = 0.0, to = 100.0) Double,
    z: @FloatRange(from = 0.0, to = 108.883) Double
): @ColorInt 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: @FloatRange(from = 0.0, to = 95.047) Double

X component value [0, 95.047)

y: @FloatRange(from = 0.0, to = 100.0) Double

Y component value [0, 100)

z: @FloatRange(from = 0.0, to = 108.883) Double

Z component value [0, 108.883)

Returns
@ColorInt Int

int containing the RGB representation

XYZToLAB

Added in 1.1.0
java-static fun XYZToLAB(
    x: @FloatRange(from = 0.0, to = 95.047) Double,
    y: @FloatRange(from = 0.0, to = 100.0) Double,
    z: @FloatRange(from = 0.0, to = 108.883) Double,
    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, 100]
  • outLab[1] is a [-128, 127)
  • outLab[2] is b [-128, 127)
Parameters
x: @FloatRange(from = 0.0, to = 95.047) Double

X component value [0, 95.047)

y: @FloatRange(from = 0.0, to = 100.0) Double

Y component value [0, 100)

z: @FloatRange(from = 0.0, to = 108.883) Double

Z component value [0, 108.883)

outLab: DoubleArray

3-element array which holds the resulting Lab components

blendARGB

Added in 1.1.0
java-static fun blendARGB(
    color1: @ColorInt Int,
    color2: @ColorInt Int,
    ratio: @FloatRange(from = 0.0, to = 1.0) Float
): @ColorInt 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: @ColorInt Int

the first ARGB color

color2: @ColorInt Int

the second ARGB color

ratio: @FloatRange(from = 0.0, to = 1.0) Float

the blend ratio of color1 to color2

blendHSL

Added in 1.1.0
java-static fun blendHSL(
    hsl1: FloatArray,
    hsl2: FloatArray,
    ratio: @FloatRange(from = 0.0, to = 1.0) Float,
    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: @FloatRange(from = 0.0, to = 1.0) Float

the blend ratio of hsl1 to hsl2

outResult: FloatArray

3-element array which holds the resulting HSL components

blendLAB

Added in 1.1.0
java-static fun blendLAB(
    lab1: DoubleArray,
    lab2: DoubleArray,
    ratio: @FloatRange(from = 0.0, to = 1.0) Double,
    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: @FloatRange(from = 0.0, to = 1.0) Double

the blend ratio of lab1 to lab2

outResult: DoubleArray

3-element array which holds the resulting LAB components

calculateContrast

Added in 1.1.0
java-static fun calculateContrast(foreground: @ColorInt Int, background: @ColorInt Int): Double

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

Formula defined here.

calculateLuminance

Added in 1.1.0
java-static fun calculateLuminance(color: @ColorInt Int): @FloatRange(from = 0.0, to = 1.0) 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

Added in 1.1.0
java-static fun calculateMinimumAlpha(
    foreground: @ColorInt Int,
    background: @ColorInt 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: @ColorInt Int

the foreground color

background: @ColorInt Int

the opaque background color

minContrastRatio: Float

the minimum contrast ratio

Returns
Int

the alpha value in the range [0, 255] or -1 if no value could be calculated

colorToHSL

Added in 1.1.0
java-static fun colorToHSL(color: @ColorInt Int, 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: @ColorInt Int

the ARGB color to convert. The alpha component is ignored

outHsl: FloatArray

3-element array which holds the resulting HSL components

colorToLAB

Added in 1.1.0
java-static fun colorToLAB(color: @ColorInt Int, outLab: DoubleArray): Unit

Convert the ARGB color to its CIE Lab representative components.

Parameters
color: @ColorInt Int

the ARGB color to convert. The alpha component is ignored

outLab: DoubleArray

3-element array which holds the resulting LAB components

colorToM3HCT

Added in 1.11.0
java-static fun colorToM3HCT(color: @ColorInt Int, outM3HCT: @Size(value = 3) FloatArray): Unit

Generate a M3HCT color from an ARGB color. HCT color space is a new color space proposed in Material Design 3

Parameters
color: @ColorInt Int

is the ARGB color value we use to get its respective M3HCT values.

outM3HCT: @Size(value = 3) FloatArray

3-element array which holds the resulting M3HCT components (Hue, Chroma, Tone).

See also
  • outM3HCT[0] is Hue in M3HCT [0, 360); invalid values are corrected.
  • outM3HCT[1] is Chroma in M3HCT [0, ?); Chroma may decrease because chroma has a different maximum for any given hue and tone.
  • outM3HCT[2] is Tone in M3HCT [0, 100]; invalid values are corrected.

colorToXYZ

Added in 1.1.0
java-static fun colorToXYZ(color: @ColorInt Int, 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: @ColorInt Int

the ARGB color to convert. The alpha component is ignored

outXyz: DoubleArray

3-element array which holds the resulting LAB components

compositeColors

Added in 1.1.0
@RequiresApi(value = 26)
java-static fun compositeColors(foreground: Color, 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:

Color purple = ColorUtils.compositeColors(
        Color.valueOf(1f, 0f, 0f, 0.5f),
        Color.valueOf(0f, 0f, 1f));
Note: This method requires API 26 or newer.
Throws
java.lang.IllegalArgumentException

if the models of the colors do not match

compositeColors

Added in 1.1.0
java-static fun compositeColors(foreground: @ColorInt Int, background: @ColorInt Int): Int

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

distanceEuclidean

Added in 1.1.0
java-static fun distanceEuclidean(labX: DoubleArray, labY: DoubleArray): Double

Returns the euclidean distance between two LAB colors.

setAlphaComponent

Added in 1.1.0
java-static fun setAlphaComponent(color: @ColorInt Int, alpha: @IntRange(from = 0, to = 255) Int): @ColorInt Int

Set the alpha component of color to be alpha.