Color.LED.RGBWW (Color v0.4.0)

Copy Markdown

A five-channel RGBWW / RGB+CCT LED pixel — red, green, blue plus a warm white and a cool white channel.

This is the pixel format used by the WS2805 family and several SK6812 variants. The warm and cool white LEDs can be blended to reach any correlated colour temperature along the line between them, giving much better white rendering than a plain RGB pixel and more flexibility than single-temperature RGBW.

All five channels — :r, :g, :b, :ww, :cw — are linear drive values in [0.0, 1.0], not sRGB-companded.

Fields

  • :r, :g, :b — linear drive for the red, green, blue LEDs.

  • :ww — linear drive for the warm white LED.

  • :cw — linear drive for the cool white LED.

  • :warm_temperature — CCT (Kelvin) of the warm white LED.

  • :cool_temperature — CCT (Kelvin) of the cool white LED.

  • :alpha — optional alpha in [0.0, 1.0], or nil.

Extraction

from_srgb/2 finds the target's CCT, clamps it to [warm_temperature, cool_temperature], picks a blend ratio between the two whites that matches that CCT, synthesises a single "mixed white" at that blend, runs the RGBW extraction against it, and splits the resulting total white drive back into :ww and :cw by the same ratio.

Example

iex> options = Color.LED.chip_options(:ws2805)
iex> {:ok, target} = Color.new("#ffa500")
iex> pixel = Color.LED.RGBWW.from_srgb(target, options)
iex> match?(%Color.LED.RGBWW{warm_temperature: 3000, cool_temperature: 6500}, pixel)
true

Summary

Types

t()

Functions

from_srgb(srgb, options \\ [])

Builds an RGBWW pixel from an sRGB colour for a fixture whose warm and cool white LEDs have the given colour temperatures.

to_srgb(rgbww)

Simulates what an RGBWW pixel actually emits, as a companded Color.SRGB struct.

to_xyz(pixel)

Converts an RGBWW pixel to Color.XYZ by simulating its emitted light.

Types

t()

@type t() :: %Color.LED.RGBWW{
  alpha: Color.Types.alpha() | nil,
  b: float(),
  cool_temperature: number(),
  cw: float(),
  g: float(),
  r: float(),
  warm_temperature: number(),
  ww: float()
}

Functions

from_srgb(srgb, options \\ [])

@spec from_srgb(
  Color.input(),
  keyword()
) :: t()

Builds an RGBWW pixel from an sRGB colour for a fixture whose warm and cool white LEDs have the given colour temperatures.

Arguments

Options

  • :warm_temperature is the warm white LED's CCT in Kelvin.

  • :cool_temperature is the cool white LED's CCT in Kelvin.

  • :chip is an alternative to supplying the two temperatures explicitly: pass a chip atom from Color.LED.chips/0 and the temperatures are looked up from Color.LED.chip_options/1. Only RGBWW chips are accepted.

Returns

Examples

iex> {:ok, white} = Color.new("#ffffff")
iex> pixel = Color.LED.RGBWW.from_srgb(white, chip: :ws2805)
iex> Float.round(pixel.ww + pixel.cw, 3) > 0.9
true

to_srgb(rgbww)

@spec to_srgb(t()) :: {:ok, Color.SRGB.t()}

Simulates what an RGBWW pixel actually emits, as a companded Color.SRGB struct.

Arguments

Returns

  • {:ok, %Color.SRGB{}}.

Examples

iex> {:ok, target} = Color.new("#ffa500")
iex> pixel = Color.LED.RGBWW.from_srgb(target, chip: :ws2805)
iex> {:ok, srgb} = Color.LED.RGBWW.to_srgb(pixel)
iex> match?(%Color.SRGB{}, srgb)
true

to_xyz(pixel)

@spec to_xyz(t()) :: {:ok, Color.XYZ.t()} | {:error, Exception.t()}

Converts an RGBWW pixel to Color.XYZ by simulating its emitted light.

Arguments

Returns

  • {:ok, %Color.XYZ{}} on success, {:error, exception} on failure.

Examples

iex> {:ok, target} = Color.new("#336699")
iex> pixel = Color.LED.RGBWW.from_srgb(target, chip: :ws2805)
iex> {:ok, xyz} = Color.LED.RGBWW.to_xyz(pixel)
iex> match?(%Color.XYZ{}, xyz)
true