Google は、黒人コミュニティに対する人種平等の促進に取り組んでいます。取り組みを見る

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
LABToColor(@FloatRange(0.0, 100) l: Double, @FloatRange(-128, 127) a: Double, @FloatRange(-128, 127) b: Double)

Converts a color from CIE Lab to its RGB representation.

static Unit
LABToXYZ(@FloatRange(0.0, 100) l: Double, @FloatRange(-128, 127) a: Double, @FloatRange(-128, 127) b: Double, @NonNull outXyz: DoubleArray)

Converts a color from CIE Lab to CIE XYZ representation.

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

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

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

Convert RGB components to its CIE Lab representative components.

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

Convert RGB components to its CIE XYZ representative components.

static Int
XYZToColor(@FloatRange(0.0, 95.047) x: Double, @FloatRange(0.0, 100.0) y: Double, @FloatRange(0.0, 108.883) z: Double)

Converts a color from CIE XYZ to its RGB representation.

static Unit
XYZToLAB(@FloatRange(0.0, 95.047) x: Double, @FloatRange(0.0, 100.0) y: Double, @FloatRange(0.0, 108.883) z: Double, @NonNull outLab: DoubleArray)

Converts a color from CIE XYZ to CIE Lab representation.

static Int
blendARGB(@ColorInt color1: Int, @ColorInt color2: Int, @FloatRange(0.0, 1.0) ratio: Float)

Blend between two ARGB colors using the given ratio.

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

Blend between hsl1 and hsl2 using the given ratio.

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

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

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

Returns the contrast ratio between foreground and background.

static Double
calculateLuminance(@ColorInt color: Int)

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

static Int
calculateMinimumAlpha(@ColorInt foreground: Int, @ColorInt 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(@ColorInt color: Int, @NonNull outHsl: FloatArray)

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

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

Convert the ARGB color to its CIE Lab representative components.

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

Convert the ARGB color to its CIE XYZ representative components.

static Int
compositeColors(@ColorInt foreground: Int, @ColorInt 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(@ColorInt color: Int, @IntRange(0, 255) alpha: Int)

Set the alpha component of color to be alpha.

Public methods

HSLToColor

@ColorInt 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

@ColorInt static fun LABToColor(
    @FloatRange(0.0, 100) l: Double,
    @FloatRange(-128, 127) a: Double,
    @FloatRange(-128, 127) 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(
    @FloatRange(0.0, 100) l: Double,
    @FloatRange(-128, 127) a: Double,
    @FloatRange(-128, 127) 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 DoubleArray: 3-element array which holds the resulting XYZ components

RGBToHSL

static fun RGBToHSL(
    @IntRange(0, 255) r: Int,
    @IntRange(0, 255) g: Int,
    @IntRange(0, 255) 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 FloatArray: 3-element array which holds the resulting HSL components

RGBToLAB

static fun RGBToLAB(
    @IntRange(0, 255) r: Int,
    @IntRange(0, 255) g: Int,
    @IntRange(0, 255) 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 DoubleArray: 3-element array which holds the resulting LAB components

RGBToXYZ

static fun RGBToXYZ(
    @IntRange(0, 255) r: Int,
    @IntRange(0, 255) g: Int,
    @IntRange(0, 255) 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 DoubleArray: 3-element array which holds the resulting XYZ components

XYZToColor

@ColorInt static fun XYZToColor(
    @FloatRange(0.0, 95.047) x: Double,
    @FloatRange(0.0, 100.0) y: Double,
    @FloatRange(0.0, 108.883) 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(
    @FloatRange(0.0, 95.047) x: Double,
    @FloatRange(0.0, 100.0) y: Double,
    @FloatRange(0.0, 108.883) 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 DoubleArray: 3-element array which holds the resulting Lab components

blendARGB

@ColorInt static fun blendARGB(
    @ColorInt color1: Int,
    @ColorInt color2: Int,
    @FloatRange(0.0, 1.0) 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 Float: the blend ratio of color1 to color2

blendHSL

static fun blendHSL(
    @NonNull hsl1: FloatArray,
    @NonNull hsl2: FloatArray,
    @FloatRange(0.0, 1.0) 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 Float: 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,
    @FloatRange(0.0, 1.0) 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 Double: the blend ratio of lab1 to lab2
outResult DoubleArray: 3-element array which holds the resulting LAB components

calculateContrast

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

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

Formula defined here.

calculateLuminance

@FloatRange(0.0, 1.0) static fun calculateLuminance(@ColorInt 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(
    @ColorInt foreground: Int,
    @ColorInt 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 Float: 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(
    @ColorInt 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 FloatArray: 3-element array which holds the resulting HSL components

colorToLAB

static fun colorToLAB(
    @ColorInt 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 DoubleArray: 3-element array which holds the resulting LAB components

colorToXYZ

static fun colorToXYZ(
    @ColorInt 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 DoubleArray: 3-element array which holds the resulting LAB components

compositeColors

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

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

compositeColors

@RequiresApi(26) @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

@ColorInt static fun setAlphaComponent(
    @ColorInt color: Int,
    @IntRange(0, 255) alpha: Int
): Int

Set the alpha component of color to be alpha.