qualpal.Palette

class qualpal.Palette(colors: Sequence[Color | str])

Bases: object

A collection of colors that behaves like a list.

Palette objects are immutable.

Methods

distance_matrix	Calculate pairwise distance matrix for all colors in the palette.
hex	Get list of hex color strings.
min_distance	Get the minimum pairwise distance between any two colors.
min_distances	Get minimum distance for each color to its nearest neighbor.
rgb	Get RGB values as list of tuples.
show	Display palette as color swatches (requires matplotlib).
to_css	Export palette as CSS custom properties (CSS variables).
to_json	Export palette as JSON array of hex colors.

distance_matrix(metric: str = 'ciede2000') → list[list[float]]

Calculate pairwise distance matrix for all colors in the palette.

Parameters:

metric (str) – Distance metric to use. Options: - ‘ciede2000’ (default): CIEDE2000 metric - ‘din99d’: DIN99d metric - ‘cie76’: CIE76 (Euclidean distance in Lab space)

Returns:

Symmetric distance matrix where element [i][j] is the distance between colors i and j. Diagonal elements are 0.0.

Return type:

list[list[float]]

Examples

>>> from qualpal import Palette
>>> pal = Palette(['#ff0000', '#00ff00', '#0000ff'])
>>> matrix = pal.distance_matrix()
>>> len(matrix)
3
>>> matrix[0][0]  # Distance to self
0.0

hex() → list[str]

Get list of hex color strings.

Returns:

List of hex strings in format #rrggbb (lowercase)

Return type:

list[str]

min_distance(metric: str = 'ciede2000') → float

Get the minimum pairwise distance between any two colors.

Parameters:

metric (str) – Distance metric to use (default: ‘ciede2000’)

Returns:

Minimum distance between any pair of distinct colors

Return type:

float

Examples

>>> from qualpal import Palette
>>> pal = Palette(['#ff0000', '#00ff00', '#0000ff'])
>>> min_dist = pal.min_distance()
>>> min_dist > 0
True

min_distances(metric: str = 'ciede2000') → list[float]

Get minimum distance for each color to its nearest neighbor.

Parameters:

metric (str) – Distance metric to use (default: ‘ciede2000’)

Returns:

List where element i is the minimum distance from color i to any other color in the palette

Return type:

list[float]

Examples

>>> from qualpal import Palette
>>> pal = Palette(['#ff0000', '#00ff00', '#0000ff'])
>>> min_dists = pal.min_distances()
>>> len(min_dists)
3
>>> all(d > 0 for d in min_dists)
True

rgb() → list[tuple[float, float, float]]

Get RGB values as list of tuples.

Returns:

List of RGB tuples in range [0.0, 1.0]

Return type:

list[tuple[float, float, float]]

show(labels: bool | list[str] | None = None) → object

Display palette as color swatches (requires matplotlib).

Parameters:

labels (bool | list[str] | None) –

• None (default): No labels

• True: Show hex codes as labels

• list[str]: Custom labels for each color

Returns:

Matplotlib Figure object that can be saved or further customized

Return type:

matplotlib.figure.Figure

Raises:

ImportError – If matplotlib is not installed

Examples

>>> from qualpal import Palette
>>> pal = Palette(['#ff0000', '#00ff00', '#0000ff'])
>>> fig = pal.show()  # Display swatches
>>> fig = pal.show(labels=True)  # With hex codes
>>> fig = pal.show(labels=['Red', 'Green', 'Blue'])  # Custom labels
>>> fig.savefig('palette.png')  # Save to file

to_css(prefix: str = 'color') → list[str]

Export palette as CSS custom properties (CSS variables).

Parameters:

prefix (str) – Prefix for CSS variable names (default: ‘color’)

Returns:

List of CSS custom property declarations

Return type:

list[str]

Examples

>>> from qualpal import Palette
>>> pal = Palette(['#ff0000', '#00ff00', '#0000ff'])
>>> pal.to_css()
['--color-1: #ff0000;', '--color-2: #00ff00;', '--color-3: #0000ff;']
>>> pal.to_css(prefix='theme')
['--theme-1: #ff0000;', '--theme-2: #00ff00;', '--theme-3: #0000ff;']

to_json() → str

Export palette as JSON array of hex colors.

Returns:

JSON string containing array of hex color strings

Return type:

str

Examples

>>> from qualpal import Palette
>>> pal = Palette(['#ff0000', '#00ff00', '#0000ff'])
>>> pal.to_json()
'["#ff0000", "#00ff00", "#0000ff"]'