qualpal.Color¶

class qualpal.Color(hex_color: str)[source]¶

Bases: object

A color with various representations and conversions.

Color objects are immutable.

Methods

`distance`	Calculate perceptual color difference to another color.
`from_hsl`	Create a Color from HSL values.
`from_rgb`	Create a Color from RGB values.
`hex`	Get hex representation.
`hsl`	Get HSL tuple.
`lab`	Get Lab tuple.
`lch`	Get LCH tuple.
`rgb`	Get RGB tuple in range [0.0, 1.0].
`rgb255`	Get RGB tuple in range [0, 255].
`simulate_cvd`	Simulate color vision deficiency on this color.
`xyz`	Get XYZ tuple.

distance(other: Color | str, metric: str = 'ciede2000') → float[source]¶

Calculate perceptual color difference to another color.

Parameters:

other (Color | str) – Another Color object or hex color string
metric (str) – Distance metric to use. Options: - ‘ciede2000’ (default): CIEDE2000 metric - ‘din99d’: DIN99d metric - ‘cie76’: CIE76 (Euclidean distance in Lab space)

Returns:

Perceptual color difference

Return type:

float

Raises:

ValueError – If metric is invalid or other color is not a valid color

Examples

>>> red = Color('#ff0000')
>>> green = Color('#00ff00')
>>> red.distance(green)
86.61
>>> red.distance('#00ff00', metric='din99d')
32.77

classmethod from_hsl(h: float, s: float, l: float) → Self[source]¶

Create a Color from HSL values.

Parameters:

h (float) – Hue in degrees [0.0, 360.0)
s (float) – Saturation in range [0.0, 1.0]
l (float) – Lightness in range [0.0, 1.0]

Returns:

New Color object

Return type:

Color

classmethod from_rgb(r: float, g: float, b: float) → Self[source]¶

Create a Color from RGB values.

Parameters:

r (float) – RGB values in range [0.0, 1.0]
g (float) – RGB values in range [0.0, 1.0]
b (float) – RGB values in range [0.0, 1.0]

Returns:

New Color object

Return type:

Color

hex() → str[source]¶

Get hex representation.

Returns:: Hex color string in format #rrggbb (lowercase)
Return type:: str

hsl() → tuple[float, float, float][source]¶

Get HSL tuple.

Returns:: HSL values as (h, s, l) where h is in degrees [0, 360) and s, l are in range [0.0, 1.0]
Return type:: tuple[float, float, float]

lab() → tuple[float, float, float][source]¶

Get Lab tuple.

Returns:: Lab values as (l, a, b) where l is in range [0, 100] and a, b are in range [-128, 127]
Return type:: tuple[float, float, float]

lch() → tuple[float, float, float][source]¶

Get LCH tuple.

Returns:: LCH values as (l, c, h) where l is in range [0, 100], c is chroma [0, ∞), and h is hue in degrees [0, 360)
Return type:: tuple[float, float, float]

rgb() → tuple[float, float, float][source]¶

Get RGB tuple in range [0.0, 1.0].

Returns:: RGB values as (r, g, b)
Return type:: tuple[float, float, float]

rgb255() → tuple[int, int, int][source]¶

Get RGB tuple in range [0, 255].

Returns:: RGB values as (r, g, b) integers
Return type:: tuple[int, int, int]

simulate_cvd(cvd_type: str, severity: float = 1.0) → Color[source]¶

Simulate color vision deficiency on this color.

Parameters:

cvd_type (str) – Type of color vision deficiency: - ‘protan’: Protanomaly/Protanopia (red-weak/blind) - ‘deutan’: Deuteranomaly/Deuteranopia (green-weak/blind) - ‘tritan’: Tritanomaly/Tritanopia (blue-weak/blind)
severity (float) – Severity of the deficiency in range [0, 1]: - 0.0: Normal vision (no change) - 1.0: Complete deficiency

Returns:

New Color object showing how this color appears with CVD

Return type:

Color

Raises:

ValueError – If cvd_type is invalid or severity is out of range

Examples

>>> red = Color('#ff0000')
>>> red_protan = red.simulate_cvd('protan', severity=1.0)
>>> red_deutan = red.simulate_cvd('deutan', severity=0.5)

xyz() → tuple[float, float, float][source]¶

Get XYZ tuple.

Returns:: XYZ values as (x, y, z)
Return type:: tuple[float, float, float]