Color.LED.RGBW (Color v0.4.0)

Copy Markdown

A four-channel RGBW LED pixel — red, green, blue plus one fixed-temperature white channel.

This is the pixel format used by the WS2814 family (warm, neutral, cool variants) and the SK6812-RGBW family, among others. Each addressable pixel has three coloured LEDs plus a single white LED whose colour temperature is fixed by the chip variant.

All four channels — :r, :g, :b, :w — are linear drive values in [0.0, 1.0]. 0.0 means the LED is off, 1.0 means at full drive. They are not sRGB-companded values; companding is applied when converting from / to Color.SRGB.

Fields

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

  • :w — linear drive for the white LED.

  • :white_temperature — the correlated colour temperature (in Kelvin) of the white LED. Stored on the struct so the pixel is self-describing and round-trippable.

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

Converting sRGB → RGBW

iex> {:ok, target} = Color.new("#ffa500")
iex> pixel = Color.LED.RGBW.from_srgb(target, white_temperature: 4500)
iex> match?(%Color.LED.RGBW{white_temperature: 4500}, pixel)
true

The extraction picks the largest white drive that keeps every R/G/B channel non-negative. See Color.LED for the algorithm.

Converting RGBW → sRGB

Use to_srgb/1 to simulate what the pixel actually emits, for preview or gamut-checking. This applies the white LED's spectral output on top of the coloured LEDs and companded-clamps the result to the sRGB display space.

Summary

Types

t()

Functions

from_srgb(srgb, options \\ [])

Builds an RGBW pixel from an sRGB colour for a fixture whose white LED has the given colour temperature.

to_srgb(rgbw)

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

to_xyz(pixel)

Converts an RGBW pixel to Color.XYZ by simulating its emitted light and running the standard sRGB → XYZ path.

Types

t()

@type t() :: %Color.LED.RGBW{
  alpha: Color.Types.alpha() | nil,
  b: float(),
  g: float(),
  r: float(),
  w: float(),
  white_temperature: number()
}

Functions

from_srgb(srgb, options \\ [])

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

Builds an RGBW pixel from an sRGB colour for a fixture whose white LED has the given colour temperature.

The algorithm picks the largest w that keeps r, g, b non-negative and w ≤ 1, maximising how much light comes from the (usually more efficient) white LED.

Arguments

  • srgb is any value accepted by Color.new/1 — a Color.SRGB struct, a hex string, a CSS named colour, etc.

Options

  • :white_temperature is the correlated colour temperature of the white LED, in Kelvin. Required.

  • :chip is an alternative to :white_temperature: pass a chip atom from Color.LED.chips/0 and the temperature is looked up from Color.LED.chip_options/1. Only RGBW chips are accepted.

Returns

Examples

iex> {:ok, white} = Color.new("#ffffff")
iex> pixel = Color.LED.RGBW.from_srgb(white, white_temperature: 6500)
iex> Float.round(pixel.w, 3)
1.0

iex> {:ok, red} = Color.new("#ff0000")
iex> pixel = Color.LED.RGBW.from_srgb(red, chip: :ws2814_nw)
iex> Float.round(pixel.r, 3) > 0.9
true

to_srgb(rgbw)

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

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

The result is clamped to the sRGB cube — pixels that over-drive any display channel will saturate. Use this for preview, gamut checking, or to round-trip back to any other colour space.

Arguments

Returns

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

Examples

iex> {:ok, target} = Color.new("#ffa500")
iex> pixel = Color.LED.RGBW.from_srgb(target, white_temperature: 4500)
iex> {:ok, srgb} = Color.LED.RGBW.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 RGBW pixel to Color.XYZ by simulating its emitted light and running the standard sRGB → XYZ path.

Arguments

Returns

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

Examples

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