ColorUtils

Added in 1.1.0

public final class ColorUtils

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

Summary

Public methods
static @ColorInt int
HSLToColor(@NonNull float[] hsl)

Convert HSL (hue-saturation-lightness) components to a RGB color.
static @ColorInt int
LABToColor(
    @FloatRange(from = 0.0, to = 100) double l,
    @FloatRange(from = "-128", to = 127) double a,
    @FloatRange(from = "-128", to = 127) double b
)

Converts a color from CIE Lab to its RGB representation.
static void
LABToXYZ(
    @FloatRange(from = 0.0, to = 100) double l,
    @FloatRange(from = "-128", to = 127) double a,
    @FloatRange(from = "-128", to = 127) double b,
    @NonNull double[] outXyz
)

Converts a color from CIE Lab to CIE XYZ representation.
static @ColorInt int
M3HCTToColor(
    @FloatRange(from = 0.0, to = 360, toInclusive = false) float hue,
    @FloatRange(from = 0.0, to = Double.POSITIVE_INFINITY, toInclusive = false) float chroma,
    @FloatRange(from = 0.0, to = 100) float tone
)

Generate an ARGB color using M3HCT color parameters.
static void
RGBToHSL(
    @IntRange(from = 0, to = 255) int r,
    @IntRange(from = 0, to = 255) int g,
    @IntRange(from = 0, to = 255) int b,
    @NonNull float[] outHsl
)

Convert RGB components to HSL (hue-saturation-lightness).
static void
RGBToLAB(
    @IntRange(from = 0, to = 255) int r,
    @IntRange(from = 0, to = 255) int g,
    @IntRange(from = 0, to = 255) int b,
    @NonNull double[] outLab
)

Convert RGB components to its CIE Lab representative components.
static void
RGBToXYZ(
    @IntRange(from = 0, to = 255) int r,
    @IntRange(from = 0, to = 255) int g,
    @IntRange(from = 0, to = 255) int b,
    @NonNull double[] outXyz
)

Convert RGB components to its CIE XYZ representative components.
static @ColorInt int
XYZToColor(
    @FloatRange(from = 0.0, to = 95.047) double x,
    @FloatRange(from = 0.0, to = 100.0) double y,
    @FloatRange(from = 0.0, to = 108.883) double z
)

Converts a color from CIE XYZ to its RGB representation.
static void
XYZToLAB(
    @FloatRange(from = 0.0, to = 95.047) double x,
    @FloatRange(from = 0.0, to = 100.0) double y,
    @FloatRange(from = 0.0, to = 108.883) double z,
    @NonNull double[] outLab
)

Converts a color from CIE XYZ to CIE Lab representation.
static @ColorInt int
blendARGB(
    @ColorInt int color1,
    @ColorInt int color2,
    @FloatRange(from = 0.0, to = 1.0) float ratio
)

Blend between two ARGB colors using the given ratio.
static void
blendHSL(
    @NonNull float[] hsl1,
    @NonNull float[] hsl2,
    @FloatRange(from = 0.0, to = 1.0) float ratio,
    @NonNull float[] outResult
)

Blend between hsl1 and hsl2 using the given ratio.
static void
blendLAB(
    @NonNull double[] lab1,
    @NonNull double[] lab2,
    @FloatRange(from = 0.0, to = 1.0) double ratio,
    @NonNull double[] outResult
)

Blend between two CIE-LAB colors using the given ratio.
static double
calculateContrast(@ColorInt int foreground, @ColorInt int background)

Returns the contrast ratio between foreground and background.
static @FloatRange(from = 0.0, to = 1.0) double

Returns the luminance of a color as a float between 0.0 and 1.0.
static int
calculateMinimumAlpha(
    @ColorInt int foreground,
    @ColorInt 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(@ColorInt int color, @NonNull float[] outHsl)

Convert the ARGB color to its HSL (hue-saturation-lightness) components.
static void
colorToLAB(@ColorInt int color, @NonNull double[] outLab)

Convert the ARGB color to its CIE Lab representative components.
static void
colorToM3HCT(@ColorInt int color, @NonNull @Size(value = 3) float[] outM3HCT)

Generate a M3HCT color from an ARGB color.
static void
colorToXYZ(@ColorInt int color, @NonNull double[] outXyz)

Convert the ARGB color to its CIE XYZ representative components.
static @NonNull Color
@RequiresApi(value = 26)
compositeColors(@NonNull Color foreground, @NonNull Color background)

Composites two translucent colors together.
static int
compositeColors(@ColorInt int foreground, @ColorInt int background)

Composite two potentially translucent colors over each other and returns the result.
static double
distanceEuclidean(@NonNull double[] labX, @NonNull double[] labY)

Returns the euclidean distance between two LAB colors.
static @ColorInt int
setAlphaComponent(@ColorInt int color, @IntRange(from = 0, to = 255) int alpha)

Set the alpha component of color to be alpha.

Public methods

HSLToColor

Added in 1.1.0
public static @ColorInt int HSLToColor(@NonNull 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
@NonNull float[] hsl

3-element array which holds the input HSL components
Returns
@ColorInt int

the resulting RGB color

LABToColor

Added in 1.1.0
public static @ColorInt int LABToColor(
    @FloatRange(from = 0.0, to = 100) double l,
    @FloatRange(from = "-128", to = 127) double a,
    @FloatRange(from = "-128", to = 127) double b
)

Converts a color from CIE Lab to its RGB representation.

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

L component value [0, 100]
@FloatRange(from = "-128", to = 127) double a

A component value [-128, 127]
@FloatRange(from = "-128", to = 127) double b

B component value [-128, 127]
Returns
@ColorInt int

int containing the RGB representation

LABToXYZ

Added in 1.1.0
public static void LABToXYZ(
    @FloatRange(from = 0.0, to = 100) double l,
    @FloatRange(from = "-128", to = 127) double a,
    @FloatRange(from = "-128", to = 127) double b,
    @NonNull 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
@FloatRange(from = 0.0, to = 100) double l

L component value [0, 100]
@FloatRange(from = "-128", to = 127) double a

A component value [-128, 127)
@FloatRange(from = "-128", to = 127) double b

B component value [-128, 127)
@NonNull double[] outXyz

3-element array which holds the resulting XYZ components

M3HCTToColor

Added in 1.11.0
public static @ColorInt int M3HCTToColor(
    @FloatRange(from = 0.0, to = 360, toInclusive = false) float hue,
    @FloatRange(from = 0.0, to = Double.POSITIVE_INFINITY, toInclusive = false) float chroma,
    @FloatRange(from = 0.0, to = 100) float tone
)

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

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

is Hue in M3HCT [0, 360); invalid values are corrected.
@FloatRange(from = 0.0, to = Double.POSITIVE_INFINITY, toInclusive = false) float chroma

is Chroma in M3HCT [0, ?); Chroma may decrease because chroma has a different maximum for any given hue and tone.
@FloatRange(from = 0.0, to = 100) float tone

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

RGBToHSL

Added in 1.1.0
public static void RGBToHSL(
    @IntRange(from = 0, to = 255) int r,
    @IntRange(from = 0, to = 255) int g,
    @IntRange(from = 0, to = 255) int b,
    @NonNull 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
@IntRange(from = 0, to = 255) int r

red component value [0, 255]
@IntRange(from = 0, to = 255) int g

green component value [0, 255]
@IntRange(from = 0, to = 255) int b

blue component value [0, 255]
@NonNull float[] outHsl

3-element array which holds the resulting HSL components

RGBToLAB

Added in 1.1.0
public static void RGBToLAB(
    @IntRange(from = 0, to = 255) int r,
    @IntRange(from = 0, to = 255) int g,
    @IntRange(from = 0, to = 255) int b,
    @NonNull double[] outLab
)

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
@IntRange(from = 0, to = 255) int r

red component value [0, 255]
@IntRange(from = 0, to = 255) int g

green component value [0, 255]
@IntRange(from = 0, to = 255) int b

blue component value [0, 255]
@NonNull double[] outLab

3-element array which holds the resulting LAB components

RGBToXYZ

Added in 1.1.0
public static void RGBToXYZ(
    @IntRange(from = 0, to = 255) int r,
    @IntRange(from = 0, to = 255) int g,
    @IntRange(from = 0, to = 255) int b,
    @NonNull 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
@IntRange(from = 0, to = 255) int r

red component value [0, 255]
@IntRange(from = 0, to = 255) int g

green component value [0, 255]
@IntRange(from = 0, to = 255) int b

blue component value [0, 255]
@NonNull double[] outXyz

3-element array which holds the resulting XYZ components

XYZToColor

Added in 1.1.0
public static @ColorInt int XYZToColor(
    @FloatRange(from = 0.0, to = 95.047) double x,
    @FloatRange(from = 0.0, to = 100.0) double y,
    @FloatRange(from = 0.0, to = 108.883) 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
@FloatRange(from = 0.0, to = 95.047) double x

X component value [0, 95.047)
@FloatRange(from = 0.0, to = 100.0) double y

Y component value [0, 100)
@FloatRange(from = 0.0, to = 108.883) double z

Z component value [0, 108.883)
Returns
@ColorInt int

int containing the RGB representation

XYZToLAB

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

X component value [0, 95.047)
@FloatRange(from = 0.0, to = 100.0) double y

Y component value [0, 100)
@FloatRange(from = 0.0, to = 108.883) double z

Z component value [0, 108.883)
@NonNull double[] outLab

3-element array which holds the resulting Lab components

blendARGB

Added in 1.1.0
public static @ColorInt int blendARGB(
    @ColorInt int color1,
    @ColorInt int color2,
    @FloatRange(from = 0.0, to = 1.0) 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
@ColorInt int color1

the first ARGB color
@ColorInt int color2

the second ARGB color
@FloatRange(from = 0.0, to = 1.0) float ratio

the blend ratio of color1 to color2

blendHSL

Added in 1.1.0
public static void blendHSL(
    @NonNull float[] hsl1,
    @NonNull float[] hsl2,
    @FloatRange(from = 0.0, to = 1.0) float ratio,
    @NonNull 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
@NonNull float[] hsl1

3-element array which holds the first HSL color
@NonNull float[] hsl2

3-element array which holds the second HSL color
@FloatRange(from = 0.0, to = 1.0) float ratio

the blend ratio of hsl1 to hsl2
@NonNull float[] outResult

3-element array which holds the resulting HSL components

blendLAB

Added in 1.1.0
public static void blendLAB(
    @NonNull double[] lab1,
    @NonNull double[] lab2,
    @FloatRange(from = 0.0, to = 1.0) double ratio,
    @NonNull 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
@NonNull double[] lab1

3-element array which holds the first LAB color
@NonNull double[] lab2

3-element array which holds the second LAB color
@FloatRange(from = 0.0, to = 1.0) double ratio

the blend ratio of lab1 to lab2
@NonNull double[] outResult

3-element array which holds the resulting LAB components

calculateContrast

Added in 1.1.0
public static double calculateContrast(@ColorInt int foreground, @ColorInt int background)

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

Formula defined here.

calculateLuminance

Added in 1.1.0
public static @FloatRange(from = 0.0, to = 1.0) double calculateLuminance(@ColorInt 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.

calculateMinimumAlpha

Added in 1.1.0
public static int calculateMinimumAlpha(
    @ColorInt int foreground,
    @ColorInt 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
@ColorInt int foreground

the foreground color
@ColorInt int background

the opaque background color
float minContrastRatio

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
public static void colorToHSL(@ColorInt int color, @NonNull 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
@ColorInt int color

the ARGB color to convert. The alpha component is ignored
@NonNull float[] outHsl

3-element array which holds the resulting HSL components

colorToLAB

Added in 1.1.0
public static void colorToLAB(@ColorInt int color, @NonNull double[] outLab)

Convert the ARGB color to its CIE Lab representative components.

Parameters
@ColorInt int color

the ARGB color to convert. The alpha component is ignored
@NonNull double[] outLab

3-element array which holds the resulting LAB components

colorToM3HCT

Added in 1.11.0
public static void colorToM3HCT(@ColorInt int color, @NonNull @Size(value = 3) float[] outM3HCT)

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

Parameters
@ColorInt int color

is the ARGB color value we use to get its respective M3HCT values.
@NonNull @Size(value = 3) float[] outM3HCT

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
public static void colorToXYZ(@ColorInt int color, @NonNull 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
@ColorInt int color

the ARGB color to convert. The alpha component is ignored
@NonNull double[] outXyz

3-element array which holds the resulting LAB components

compositeColors

Added in 1.1.0
@RequiresApi(value = 26)
public static @NonNull Color compositeColors(@NonNull Color foreground, @NonNull 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.
Throws
java.lang.IllegalArgumentException

if the models of the colors do not match

compositeColors

Added in 1.1.0
public static int compositeColors(@ColorInt int foreground, @ColorInt int background)

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

distanceEuclidean

Added in 1.1.0
public static double distanceEuclidean(@NonNull double[] labX, @NonNull double[] labY)

Returns the euclidean distance between two LAB colors.

setAlphaComponent

Added in 1.1.0
public static @ColorInt int setAlphaComponent(@ColorInt int color, @IntRange(from = 0, to = 255) int alpha)

Set the alpha component of color to be alpha.