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 |
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 |
static
double
|
calculateLuminance(int color)
Returns the luminance of a color as a float between |
static
int
|
calculateMinimumAlpha(int foreground, int background, float minContrastRatio)
Calculates the minimum alpha value which can be applied to |
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 |
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]
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 |