---
title: "Compare Sets of Colors"
---

### Description

Compares two sets of colors based on two color objects. The objects
provided on argument `a` and `b` must inherit from `colorobject`.
This can be any of the following classes: [CIELAB](colorspace.colorlib.CIELAB.qmd),
[CIELUV](colorspace.colorlib.CIELUV.qmd), [CIEXYZ](colorspace.colorlib.CIEXYZ.qmd), [HLS](colorspace.colorlib.HLS.qmd), [HSV](colorspace.colorlib.HSV.qmd),
[RGB](colorspace.colorlib.RGB.qmd), [hexcols](colorspace.colorlib.hexcols.qmd), [polarLAB](colorspace.colorlib.polarLAB.qmd),
[polarLUV](colorspace.colorlib.polarLUV.qmd), or [sRGB](colorspace.colorlib.sRGB.qmd).

### Usage

<pre><code class='language-python'>compare_colors(a, b, exact=False, _all=True,<br/>               atol=None)</code></pre>

### Arguments

<dl class="pyp-list param-list">
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.colorlib.compare_colors:a">a</code><code class="argument-class">colorobject</code>
  </dt>
 <dd>Object which inherits from `colorobject`.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.colorlib.compare_colors:b">b</code><code class="argument-class">colorobject</code>
  </dt>
 <dd>Object which inherits from `colorobject`.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.colorlib.compare_colors:exact">exact</code><code class="argument-class">bool</code>
  </dt>
 <dd>Default `False`, check for colors being nearly equal
(see `atol`). If set to `True` the coordinates must be identical.
Note: in case `a` and `b` are hex colors
(colorspace.colorlib.hexcols) strings will always be matched exactly.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.colorlib.compare_colors:_all">_all</code><code class="argument-class">bool</code>
  </dt>
 <dd>Default `True`; the function will return `True` if
all colors are identical/nearly equal. If set to `False` the return
will be a list of bool containing `True` and `False` for each
pair of colors.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.colorlib.compare_colors:atol">atol</code><code class="argument-class">None or float</code>
  </dt>
 <dd>Absolute tolerance for the distance measure
between two colors to be considered as nearly equal (must be > 0 if set).
Only used if `exact = False`, else `atol = 1e-6` is used.  If set
to `None` the tolerance will automatically be set depending on the
type of the objects. Defaults to None.</dd>
</dl>

### Return

bool, list: Returns `True` if all colors of `a` are exactly equal or
nearly equal (see arguments) to the colors in object `b`. If `_all =
False`, a list of bool is returned indicating pair-wise comparison
of all colors in `a` and `b`.

### Examples

```{python}
#| echo: true
#| warning: true
#| error: true
from colorspace import RGB, hexcols, compare_colors
# Three RGB colors
a = RGB([0.5, 0.5], [0.1, 0.1], [0.9, 0.9])
b = RGB([0.5, 0.5], [0.1, 0.1], [0.9, 0.91])

compare_colors(a, b)
```

```{python}
#| echo: true
#| warning: true
#| error: true
compare_colors(a, b, atol = 0.1)
```

```{python}
#| echo: true
#| warning: true
#| error: true
compare_colors(a, b, exact = True)
```

```{python}
#| echo: true
#| warning: true
#| error: true
compare_colors(a, b, exact = True, _all = False)
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Same example using two sets of hexcolor objects
x = hexcols(["#ff00ff", "#003300"])
y = hexcols(["#ff00ff", "#003301"])
compare_colors(x, y)
```

```{python}
#| echo: true
#| warning: true
#| error: true
compare_colors(x, y, _all = False)
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Convert HEX to HCL (polarLUV) and back, compare the
# resulting colors to the original ones; should be identical
from copy import deepcopy
z  = hexcols(["#ff00ff", "#003301"])
zz = deepcopy(z)
zz.to("HCL")
zz
```

```{python}
#| echo: true
#| warning: true
#| error: true
zz.to("hex")
zz
```

```{python}
#| echo: true
#| warning: true
#| error: true
compare_colors(z, zz)
```




### Raises

<ul class="python-raises">
<li><code class="text-warning">TypeError</code>: If `a` or `b` are not objects of a class which inherits from
`colorobject`.
<li><code class="text-warning">TypeError</code>: If `a` and `b` are not of the same class.
<li><code class="text-warning">ValueError</code>: If `a` and `b` are not of the same length, i.e., do not contain
the same number of colors.
<li><code class="text-warning">TypeError</code>: If `exact` or `_all` are not bool.
<li><code class="text-warning">TypeError</code>: If `atol` is neither `None` nor float.
<li><code class="text-warning">ValueError</code>: If `atol` is not larger than 0.
</ul>

