ColorUtils

public final class ColorUtils
extends Object

java.lang.Object
   ↳ androidx.core.graphics.ColorUtils

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

Summary

Public methods

static int HSLToColor(float[] hsl)

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

static int LABToColor(double l, double a, double b)

Converts a color from CIE Lab to its RGB representation.

static void LABToXYZ(double l, double a, double b, double[] outXyz)

Converts a color from CIE Lab to CIE XYZ representation.

static void RGBToHSL(int r, int g, int b, float[] outHsl)

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

static void RGBToLAB(int r, int g, int b, double[] outLab)

Convert RGB components to its CIE Lab representative components.

static void RGBToXYZ(int r, int g, int b, double[] outXyz)

Convert RGB components to its CIE XYZ representative components.

static int XYZToColor(double x, double y, double z)

Converts a color from CIE XYZ to its RGB representation.

static void XYZToLAB(double x, double y, double z, double[] outLab)

Converts a color from CIE XYZ to CIE Lab representation.

static int blendARGB(int color1, int color2, float ratio)

Blend between two ARGB colors using the given ratio.

static void blendHSL(float[] hsl1, float[] hsl2, float ratio, float[] outResult)

Blend between hsl1 and hsl2 using the given ratio.

static void blendLAB(double[] lab1, double[] lab2, double ratio, double[] outResult)

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

static double calculateContrast(int foreground, int background)

Returns the contrast ratio between foreground and background.

static double calculateLuminance(int color)

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

static int calculateMinimumAlpha(int foreground, int background, float minContrastRatio)

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 void colorToHSL(int color, float[] outHsl)

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

static void colorToLAB(int color, double[] outLab)

Convert the ARGB color to its CIE Lab representative components.

static void colorToXYZ(int color, double[] outXyz)

Convert the ARGB color to its CIE XYZ representative components.

static Color compositeColors(Color foreground, Color background)

Composites two translucent colors together.

static int compositeColors(int foreground, int background)

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

static double distanceEuclidean(double[] labX, double[] labY)

Returns the euclidean distance between two LAB colors.

static int setAlphaComponent(int color, int alpha)

Set the alpha component of color to be alpha.

Inherited methods

Public methods

HSLToColor

public static int HSLToColor (float[] hsl)

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 float: 3-element array which holds the input HSL components
Returns
int the resulting RGB color

LABToColor

public static int LABToColor (double l, 
                double a, 
                double b)

Converts a color from CIE Lab to its RGB representation.

Parameters
l double: L component value [0...100]

Value is between 0.0 and 100.0 inclusive.
a double: A component value [-128...127]

Value is between -128.0 and 127.0 inclusive.
b double: B component value [-128...127]

Value is between -128.0 and 127.0 inclusive.
Returns
int int containing the RGB representation

LABToXYZ

public static void LABToXYZ (double l, 
                double a, 
                double b, 
                double[] outXyz)

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)

Value is between 0.0 and 100.0 inclusive.
a double: A component value [-128...127)

Value is between -128.0 and 127.0 inclusive.
b double: B component value [-128...127)

Value is between -128.0 and 127.0 inclusive.
outXyz double: 3-element array which holds the resulting XYZ components

RGBToHSL

public static void RGBToHSL (int r, 
                int g, 
                int b, 
                float[] outHsl)

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]

Value is 255 or less.
g int: green component value [0..255]

Value is 255 or less.
b int: blue component value [0..255]

Value is 255 or less.
outHsl float: 3-element array which holds the resulting HSL components

RGBToLAB

public static void RGBToLAB (int r, 
                int g, 
                int b, 
                double[] outLab)

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]

Value is 255 or less.
g int: green component value [0..255]

Value is 255 or less.
b int: blue component value [0..255]

Value is 255 or less.
outLab double: 3-element array which holds the resulting LAB components

RGBToXYZ

public static void RGBToXYZ (int r, 
                int g, 
                int b, 
                double[] outXyz)

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]

Value is 255 or less.
g int: green component value [0..255]

Value is 255 or less.
b int: blue component value [0..255]

Value is 255 or less.
outXyz double: 3-element array which holds the resulting XYZ components

XYZToColor

public static int XYZToColor (double x, 
                double y, 
                double z)

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)

Value is between 0.0 and 95.047 inclusive.
y double: Y component value [0...100)

Value is between 0.0 and 100.0 inclusive.
z double: Z component value [0...108.883)

Value is between 0.0 and 108.883 inclusive.
Returns
int int containing the RGB representation

XYZToLAB

public static void XYZToLAB (double x, 
                double y, 
                double z, 
                double[] outLab)

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)

Value is between 0.0 and 95.047 inclusive.
y double: Y component value [0...100)

Value is between 0.0 and 100.0 inclusive.
z double: Z component value [0...108.883)

Value is between 0.0 and 108.883 inclusive.
outLab double: 3-element array which holds the resulting Lab components

blendARGB

public static int blendARGB (int color1, 
                int color2, 
                float ratio)

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 float: the blend ratio of color1 to color2

Value is between 0.0 and 1.0 inclusive.
Returns
int

blendHSL

public static void blendHSL (float[] hsl1, 
                float[] hsl2, 
                float ratio, 
                float[] outResult)

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 float: 3-element array which holds the first HSL color
hsl2 float: 3-element array which holds the second HSL color
ratio float: the blend ratio of hsl1 to hsl2

Value is between 0.0 and 1.0 inclusive.
outResult float: 3-element array which holds the resulting HSL components

blendLAB

public static void blendLAB (double[] lab1, 
                double[] lab2, 
                double ratio, 
                double[] outResult)

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 double: 3-element array which holds the first LAB color
lab2 double: 3-element array which holds the second LAB color
ratio double: the blend ratio of lab1 to lab2

Value is between 0.0 and 1.0 inclusive.
outResult double: 3-element array which holds the resulting LAB components

calculateContrast

public static double calculateContrast (int foreground, 
                int background)

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

Formula defined here.

Parameters
foreground int

background int

Returns
double

calculateLuminance

public static double calculateLuminance (int color)

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.

Parameters
color int

Returns
double

Value is between 0.0 and 1.0 inclusive.

calculateMinimumAlpha

public static int calculateMinimumAlpha (int foreground, 
                int background, 
                float minContrastRatio)

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 float: the minimum contrast ratio
Returns
int the alpha value in the range 0-255, or -1 if no value could be calculated

colorToHSL

public static void colorToHSL (int color, 
                float[] outHsl)

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 float: 3-element array which holds the resulting HSL components

colorToLAB

public static void colorToLAB (int color, 
                double[] outLab)

Convert the ARGB color to its CIE Lab representative components.

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

colorToXYZ

public static void colorToXYZ (int color, 
                double[] outXyz)

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 double: 3-element array which holds the resulting LAB components

compositeColors

public static Color compositeColors (Color foreground, 
                Color background)

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.

Parameters
foreground Color

background Color

Returns
Color

Throws
IllegalArgumentException if the models of the colors do not match

compositeColors

public static int compositeColors (int foreground, 
                int background)

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

Parameters
foreground int

background int

Returns
int

distanceEuclidean

public static double distanceEuclidean (double[] labX, 
                double[] labY)

Returns the euclidean distance between two LAB colors.

Parameters
labX double

labY double

Returns
double

setAlphaComponent

public static int setAlphaComponent (int color, 
                int alpha)

Set the alpha component of color to be alpha.

Parameters
color int

alpha int

Value is 255 or less.
Returns
int