java.lang.Object

org.openhab.core.util.ColorUtil

@NonNullByDefault public class ColorUtil extends Object

The ColorUtil is responsible for converting different color formats. The implementation of HSB/CIE conversion is based work from Erik Baauw for the Homebridge project.

Author:: Jan N. Klug - Initial contribution, Holger Friedrich - Transfer RGB color conversion from HSBType, improve RGB conversion, restructuring, Chris Jackson - Added fromRGB (moved from HSBType), Andrew Fiddian-Green - Extensive revamp to fix bugs and improve accuracy, Cody Cutrer - Added xyToDuv

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static final record

ColorUtil.Gamut

Color gamut

static class

ColorUtil.Point

Class for points in the CIE xy color space
Field Summary

Fields

Modifier and Type

Field

Description

static final ColorUtil.Gamut

DEFAULT_GAMUT
Method Summary

Modifier and Type

Method

Description

static int[]

hsbToRgb(HSBType hsb)

Transform HSV based HSBType to sRGB.

static PercentType[]

hsbToRgbPercent(HSBType hsb)

Transform HSV based HSBType to sRGB.

static int[]

hsbToRgbw(HSBType hsb)

Transform HSV based HSBType to sRGB.

static PercentType[]

hsbToRgbwPercent(HSBType hsb)

Transform HSV based HSBType to RGBW.

static int

hsbTosRgb(HSBType hsb)

Transform HSV based HSBType to the RGB value representing the color in the default sRGB color model.

static double[]

hsbToXY(HSBType hsb)

Transform HSV based HSBType to CIE 1931 xy format.

static double[]

hsbToXY(HSBType hsb, ColorUtil.Gamut gamut)

Transform HSV based HSBType to CIE 1931 xy format.

static double[]

kelvinToXY(double kelvin)

Convert a colour temperature in Kelvin to a point in the CIE XY colour space.

static HSBType

rgbToHsb(int[] rgbw)

Transform sRGB color format to HSV based HSBType.

static HSBType

rgbToHsb(PercentType[] rgbw)

Transform sRGB color format to HSV based HSBType.

static double

xyToDuv(double[] xy)

Calculate the Duv (Delta u,v) metric from a CIE 1931 xy format color.

static HSBType

xyToHsb(double[] xy)

Transform CIE 1931 xy format to HSV based HSBType.

static HSBType

xyToHsb(double[] xyY, ColorUtil.Gamut gamut)

Transform CIE 1931 xy format to HSV based HSBType.

static double

xyToKelvin(double[] xy)

Convert a point in the CIE XY colour space to a colour temperature in Kelvin.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- DEFAULT_GAMUT
  
  public static final ColorUtil.Gamut DEFAULT_GAMUT
Method Details
- hsbToRgb
  
  public static int[] hsbToRgb(HSBType hsb)
  
  Transform HSV based HSBType to sRGB. This function does rounding to integer valued components. It is the preferred way of doing HSB to RGB conversion. See also: hsbToRgbPercent(HSBType), hsbToRgbw(HSBType), hsbTosRgb(HSBType)
  
  Parameters:
  
  hsb - an HSBType value.
  
  Returns:
  
  array of three int with the RGB values in the range 0 to 255.
- hsbToRgbw
  
  public static int[] hsbToRgbw(HSBType hsb)
  
  Transform HSV based HSBType to sRGB. This function does rounding to integer valued components. It is the preferred way of doing HSB to RGBW conversion. See also: hsbToRgbPercent(HSBType), hsbToRgbwPercent(HSBType), hsbTosRgb(HSBType)
  
  Parameters:
  
  hsb - an HSBType value.
  
  Returns:
  
  array of four int with the RGBW values in the range 0 to 255.
- hsbToRgbPercent
  
  public static PercentType[] hsbToRgbPercent(HSBType hsb)
  
  Transform HSV based HSBType to sRGB. This function does not round the components. For conversion to integer values in the range 0 to 255 use hsbToRgb(HSBType). See also: hsbToRgb(HSBType), hsbTosRgb(HSBType), hsbToRgbwPercent(HSBType)
  
  Parameters:
  
  hsb - an HSBType value.
  
  Returns:
  
  array of three PercentType with the RGB values in the range 0 to 100 percent.
- hsbToRgbwPercent
  
  public static PercentType[] hsbToRgbwPercent(HSBType hsb)
  
  Transform HSV based HSBType to RGBW. See Converting RGB to RGBW. This function does not round the components. For conversion to integer values in the range 0 to 255 use hsbToRgb(HSBType). See also: hsbToRgb(HSBType), hsbTosRgb(HSBType), hsbToRgbPercent(HSBType)
  
  Parameters:
  
  hsb - an HSBType value.
  
  Returns:
  
  array of four PercentType with the RGBW values in the range 0 to 100 percent.
- hsbTosRgb
  
  public static int hsbTosRgb(HSBType hsb)
  
  Transform HSV based HSBType to the RGB value representing the color in the default sRGB color model. (Bits 24-31 are alpha, 16-23 are red, 8-15 are green, 0-7 are blue). See also: hsbToRgb(HSBType), hsbToRgbPercent(HSBType)
  
  Parameters:
  
  hsb - an HSBType value.
  
  Returns:
  
  the RGB value of the color in the default sRGB color model.
- hsbToXY
  
  public static double[] hsbToXY(HSBType hsb)
  
  Transform HSV based HSBType to CIE 1931 xy format. See Hue developerportal.
  
  Parameters:
  
  hsb - an HSBType value.
  
  Returns:
  
  array of three double with the closest matching CIE 1931 x,y,Y in the range 0.0000 to 1.0000
- hsbToXY
  
  public static double[] hsbToXY(HSBType hsb, ColorUtil.Gamut gamut)
  
  Transform HSV based HSBType to CIE 1931 xy format. See Hue developer portal.
  
  Parameters:
  
  hsb - an HSBType value.
  
  gamut - the color Gamut supported by the light.
  
  Returns:
  
  array of three or four double with the closest matching CIE 1931 x,y,Y in the range 0.0000 to 1.0000 - plus an optional extra empty element to flag if the xyY result has been forced inside the given Gamut.
- rgbToHsb
  
  public static HSBType rgbToHsb(int[] rgbw) throws IllegalArgumentException
  
  Transform sRGB color format to HSV based HSBType.
  
  Parameters:
  
  rgbw - array of three or four int with the RGB(W) values in the range 0 to 255.
  
  Returns:
  
  the corresponding HSBType.
  
  Throws:
  
  IllegalArgumentException - when input array has wrong size or exceeds allowed value range.
- rgbToHsb
  
  public static HSBType rgbToHsb(PercentType[] rgbw) throws IllegalArgumentException
  
  Transform sRGB color format to HSV based HSBType.
  
  Parameters:
  
  rgbw - array of three or four PercentType with the RGB(W) values in the range 0 to 100 percent.
  
  Returns:
  
  the corresponding HSBType.
  
  Throws:
  
  IllegalArgumentException - when input array has wrong size or exceeds allowed value range.
- xyToHsb
  
  public static HSBType xyToHsb(double[] xy) throws IllegalArgumentException
  
  Transform CIE 1931 xy format to HSV based HSBType. See Hue developer portal.
  
  Parameters:
  
  xy - array of double with CIE 1931 x,y[,Y] in the range 0.0000 to 1.0000 Y value is optional.
  
  Returns:
  
  the corresponding HSBType.
  
  Throws:
  
  IllegalArgumentException - when input array has wrong size or exceeds allowed value range.
- xyToHsb
  
  public static HSBType xyToHsb(double[] xyY, ColorUtil.Gamut gamut) throws IllegalArgumentException
  
  Transform CIE 1931 xy format to HSV based HSBType. See Hue developer portal.
  
  Parameters:
  
  xyY - array of double with CIE 1931 x,y[,Y] in the range 0.0000 to 1.0000 Y value is optional.
  
  gamut - the color Gamut supported by the light.
  
  Returns:
  
  the corresponding HSBType.
  
  Throws:
  
  IllegalArgumentException - when input array has wrong size or exceeds allowed value range
- xyToDuv
  
  public static double xyToDuv(double[] xy) throws IllegalArgumentException
  
  Calculate the Duv (Delta u,v) metric from a CIE 1931 xy format color. Duv describes the distance of a color point from the black body curve. It's useful for calculating if a color is near to "white", at any color temperature.
  
  Parameters:
  
  xy - array of double with CIE 1931 x,y in the range 0.0000 to 1.0000
  
  Returns:
  
  the calculated Duv metric
  
  Throws:
  
  IllegalArgumentException - when input array has wrong size or exceeds allowed value range.
- kelvinToXY
  
  public static double[] kelvinToXY(double kelvin) throws IndexOutOfBoundsException
  
  Convert a colour temperature in Kelvin to a point in the CIE XY colour space. Uses a lookup table as described here.
  
  Parameters:
  
  kelvin - the colour temperature in K to be converted
  
  Returns:
  
  an array with the found CIE colour XY values
  
  Throws:
  
  IndexOutOfBoundsException - if the colour temperature is out of range 2000K .. 6500K
- xyToKelvin
  
  public static double xyToKelvin(double[] xy) throws IllegalArgumentException
  
  Convert a point in the CIE XY colour space to a colour temperature in Kelvin. Uses McCamy's approximation as described here.
  Note that McCamy's approximation is accurate to better than 1% from 2000 K to 10000 K but below 2000 K the approximation error increases rapidly and exponentially.
  
  Parameters:
  
  xy - an array with the CIE colour XY values to be converted
  
  Returns:
  
  the colour temperature in K
  
  Throws:
  
  IllegalArgumentException - if the wrong number of arguments is provided

Class ColorUtil

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

DEFAULT_GAMUT

Method Details

hsbToRgb

hsbToRgbw

hsbToRgbPercent

hsbToRgbwPercent

hsbTosRgb

hsbToXY

hsbToXY

rgbToHsb

rgbToHsb

xyToHsb

xyToHsb

xyToDuv

kelvinToXY

xyToKelvin