# `Color.Distance`

Color difference (ΔE) metrics between two colors.

Each function accepts two colors in any supported color space; inputs
that are not already in `L*a*b*` are converted via `Color.convert/2`,
chromatically adapting to D65 as necessary.

The supported metrics are:

* `delta_e_76/2` — CIE76, the original simple Euclidean distance in
  `L*a*b*`. Fast but known to be perceptually non-uniform, especially
  in saturated blue-purple regions.

* `delta_e_94/3` — CIE94, a weighted distance that corrects the
  saturation/hue issues of CIE76. Parametric factors default to the
  graphic-arts application (`kL = 1, K1 = 0.045, K2 = 0.015`).

* `delta_e_2000/3` — CIEDE2000, the modern standard. Much more
  complex but handles perceptual non-uniformity well.

* `delta_e_cmc/3` — CMC l:c, developed by the Colour Measurement
  Committee of the Society of Dyers and Colourists. Common in the
  textile industry.

For most use cases prefer `delta_e_2000/3`.

# `delta_e_76`

```elixir
@spec delta_e_76(Color.input(), Color.input()) :: float()
```

CIE76 color difference — Euclidean distance in `L*a*b*`.

### Arguments

* `a` is any supported color.

* `b` is any supported color.

### Returns

* A non-negative float.

### Examples

    iex> Color.Distance.delta_e_76(%Color.Lab{l: 50.0, a: 0.0, b: 0.0}, %Color.Lab{l: 50.0, a: 0.0, b: 0.0})
    0.0

    iex> Float.round(Color.Distance.delta_e_76(%Color.Lab{l: 50.0, a: 2.6772, b: -79.7751}, %Color.Lab{l: 50.0, a: 0.0, b: -82.7485}), 4)
    4.0011

# `delta_e_94`

```elixir
@spec delta_e_94(Color.input(), Color.input(), keyword()) :: float()
```

CIE94 color difference.

### Arguments

* `a` is any supported color.

* `b` is any supported color.

* `options` is a keyword list.

### Options

* `:application` is `:graphic_arts` (default) or `:textiles` and
  picks the CIE94 `kL`, `K1`, `K2` constants.

* `:kL`, `:kC`, `:kH` are parametric weighting factors (defaults
  `1.0, 1.0, 1.0`).

### Returns

* A non-negative float.

### Examples

    iex> Float.round(Color.Distance.delta_e_94(%Color.Lab{l: 50.0, a: 2.6772, b: -79.7751}, %Color.Lab{l: 50.0, a: 0.0, b: -82.7485}), 4)
    1.3950

# `delta_e_2000`

```elixir
@spec delta_e_2000(Color.input(), Color.input(), keyword()) :: float()
```

CIEDE2000 color difference.

Reference: Sharma, Wu & Dalal, "The CIEDE2000 Color-Difference
Formula: Implementation Notes, Supplementary Test Data, and
Mathematical Observations" (2005).

### Arguments

* `a` is any supported color.

* `b` is any supported color.

* `options` is a keyword list.

### Options

* `:kL`, `:kC`, `:kH` are parametric weighting factors (defaults
  `1.0, 1.0, 1.0`).

### Returns

* A non-negative float.

### Examples

    iex> Float.round(Color.Distance.delta_e_2000(%Color.Lab{l: 50.0, a: 2.6772, b: -79.7751}, %Color.Lab{l: 50.0, a: 0.0, b: -82.7485}), 4)
    2.0425

    iex> Float.round(Color.Distance.delta_e_2000(%Color.Lab{l: 50.0, a: 2.5, b: 0.0}, %Color.Lab{l: 73.0, a: 25.0, b: -18.0}), 4)
    27.1492

# `delta_e_cmc`

```elixir
@spec delta_e_cmc(Color.input(), Color.input(), keyword()) :: float()
```

CMC l:c color difference.

### Arguments

* `a` is any supported color.

* `b` is any supported color.

* `options` is a keyword list.

### Options

* `:l` is the lightness weighting factor. Defaults to `2.0`
  (acceptability). Use `1.0` for perceptibility.

* `:c` is the chroma weighting factor. Defaults to `1.0`.

### Returns

* A non-negative float.

### Examples

    iex> Float.round(Color.Distance.delta_e_cmc(%Color.Lab{l: 50.0, a: 2.6772, b: -79.7751}, %Color.Lab{l: 50.0, a: 0.0, b: -82.7485}), 4)
    1.7387

---

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