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, CIELUV, CIEXYZ, HLS, HSV, RGB, hexcols, polarLAB, polarLUV, or sRGB.

Usage

compare_colors(a, b, exact=False, _all=True,
               atol=None)

Arguments

acolorobject
Object which inherits from colorobject.
bcolorobject
Object which inherits from colorobject.
exactbool
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.
_allbool
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.
atolNone or float
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.

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

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)
np.False_
compare_colors(a, b, atol = 0.1)
np.True_
compare_colors(a, b, exact = True)
np.False_
compare_colors(a, b, exact = True, _all = False)
array([ True, False])
# Same example using two sets of hexcolor objects
x = hexcols(["#ff00ff", "#003300"])
y = hexcols(["#ff00ff", "#003301"])
compare_colors(x, y)
np.False_
compare_colors(x, y, _all = False)
[True, False]
# 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
polarLUV color object (2 colors)
            H       C       L
  1:   307.73  137.40   60.32
       128.06   26.54   17.32
zz.to("hex")
zz
  • #FF00FF
  • #003301
compare_colors(z, zz)
np.True_

Raises

  • TypeError: If a or b are not objects of a class which inherits from colorobject.
  • TypeError: If a and b are not of the same class.
  • ValueError: If a and b are not of the same length, i.e., do not contain the same number of colors.
  • TypeError: If exact or _all are not bool.
  • TypeError: If atol is neither None nor float.
  • ValueError: If atol is not larger than 0.