# `Color.Temperature`

Correlated colour temperature (CCT) on the Planckian locus.

* `cct/1` — McCamy's 1992 approximation: given any colour (or an
  `{x, y}` chromaticity pair), returns the CCT in Kelvin.

* `xy/1` — Kim et al. 2002 piecewise polynomial: given a CCT in
  Kelvin, returns the `{x, y}` chromaticity of the corresponding
  blackbody radiator (accurate to ~`1e-3` over 1667–25000 K).

* `xyz/1,2` — same as `xy/1` but returns a `Color.XYZ` struct
  tagged D65/2° by default, with an optional luminance.

# `cct`

```elixir
@spec cct({number(), number()} | Color.input()) :: float() | {:error, Exception.t()}
```

Returns the correlated colour temperature of a colour, in Kelvin,
using McCamy's 1992 approximation.

Accuracy is about ±2 K from 2856 K (illuminant A) to 6500 K (D65)
and degrades smoothly outside that range. The McCamy formula is the
classical one; for more accurate results use a Planckian-locus
minimum-distance search (not provided here).

### Arguments

* `color` is any colour accepted by `Color.new/1`, or an
  `{x, y}` chromaticity tuple of floats.

### Returns

* A float — CCT in Kelvin.

### Examples

    iex> Float.round(Color.Temperature.cct({0.31271, 0.32902}), 0)
    6504.0

    iex> Float.round(Color.Temperature.cct({0.44757, 0.40745}), 0)
    2857.0

    iex> Float.round(Color.Temperature.cct("white"), 0)
    6503.0

# `daylight`

```elixir
@spec daylight(number()) :: {float(), float()}
```

Returns the `{x, y}` chromaticity on the CIE daylight locus
(CIE 15.2) at the given colour temperature. Valid over
`[4000, 25000]` K.

### Arguments

* `kelvin` is a number in `[4000, 25000]`.

### Returns

* An `{x, y}` tuple.

# `planckian`

```elixir
@spec planckian(number()) :: {float(), float()}
```

Returns the `{x, y}` chromaticity on the Planckian (blackbody)
locus at the given temperature, using the Kim et al. 2002
polynomial. Valid over `[1667, 25000]` K.

### Arguments

* `kelvin` is a number in `[1667, 25000]`.

### Returns

* An `{x, y}` tuple.

# `xy`

```elixir
@spec xy(number()) :: {float(), float()}
```

Returns the `{x, y}` chromaticity for a colour temperature in
Kelvin.

For `T < 4000 K` (incandescent range), returns the chromaticity of
the Planckian (blackbody) radiator at that temperature using the
Kim et al. 2002 piecewise polynomial.

For `T ≥ 4000 K` (daylight range), returns the chromaticity on the
CIE daylight locus (CIE 15.2), which is what the standard daylight
illuminants D50, D55, D65, D75 are built from. `xy(6500)` returns
approximately D65's chromaticity; `xy(5000)` approximately D50's.

Valid over `[1667, 25000]` K.

### Arguments

* `kelvin` is a number in `[1667, 25000]`.

### Returns

* An `{x, y}` tuple of floats.

### Examples

    iex> {x, y} = Color.Temperature.xy(6504)
    iex> {Float.round(x, 4), Float.round(y, 4)}
    {0.3127, 0.3291}

    iex> {x, y} = Color.Temperature.xy(2856)
    iex> {Float.round(x, 4), Float.round(y, 4)}
    {0.4471, 0.4075}

# `xyz`

```elixir
@spec xyz(number(), number()) :: Color.XYZ.t()
```

Returns a `Color.XYZ` struct at the given colour temperature, with
`Y` scaled to the given luminance (default `1.0`).

### Arguments

* `kelvin` is a number in `[1667, 25000]`.

* `luminance` is the `Y` value to scale to. Defaults to `1.0`.

### Returns

* A `Color.XYZ` struct tagged D65/2°.

### Examples

    iex> xyz = Color.Temperature.xyz(6504)
    iex> {Float.round(xyz.x, 4), Float.round(xyz.y, 4), Float.round(xyz.z, 4)}
    {0.9502, 1.0, 1.0883}

---

*Consult [api-reference.md](api-reference.md) for complete listing*