Color Utilities¶

Importing dartwork_mpl registers a large catalog of named colors with matplotlib (oc.* plus Tailwind tw., Material md., Ant Design ad., Chakra cu., and Primer pr. prefixes). In addition to the named palette, a Color class provides perceptually uniform color manipulation across OKLab, OKLCH, RGB, and hex color spaces.

Example¶

import matplotlib.pyplot as plt
import dartwork_mpl as dm

# Named colors
plt.plot(x, y, color="oc.blue5", label="Series A")
lighter = dm.mix_colors("oc.blue5", "white", alpha=0.35)
muted_line = dm.pseudo_alpha("oc.blue7", alpha=0.6)

# Color class — perceptual manipulation
color = dm.oklch(0.7, 0.15, 150)
color.oklch.C *= 1.2                  # boost chroma
print(color.to_hex())                 # '#...'

# Interpolation
palette = dm.cspace('#FF6B6B', '#4ECDC4', n=5, space='oklch')
for i, c in enumerate(palette):
    ax.bar(i, 1, color=c.to_hex())

Color utilities: named colors, mix_colors, pseudo_alpha, cspace interpolation

API¶

Color Manipulation¶

Color management and conversion utilities for Matplotlib.

Provides facilities for loading, registering, and converting colors across OKLab, OKLCH, RGB, and Hex color spaces.

class dartwork_mpl.color.Color(L: float, a: float, b: float)[source]¶

Bases: object

Color class supporting OKLab, OKLCH, RGB, and Hex color spaces.

Internally stores colors in OKLab coordinates for fast conversion. Use the class methods from_oklab(), from_oklch(), from_rgb(), from_hex() to create instances.

copy() → Color[source]¶

Create a copy of the Color object.

Returns:: A new Color instance with the same OKLab coordinates.
Return type:: Color

Examples

>>> import dartwork_mpl as dm
>>> color = dm.oklab(0.7, 0.1, 0.2)
>>> new_color = color.copy()
>>>
>>> # Modify the copy without affecting the original
>>> new_color.oklab.L += 0.1
>>> print(color.oklab.L)      # 0.7 (unchanged)
>>> print(new_color.oklab.L)  # 0.8 (modified)

classmethod from_hex(hex_str: str) → Color[source]¶

Create a Color from hex color string.

Parameters:: hex_str (str) – Hex color string (#RGB or #RRGGBB).
Returns:: Color instance.
Return type:: Color

classmethod from_name(name: str) → Color[source]¶

Create a Color from matplotlib color name.

Supports all matplotlib color names including: - Basic colors: ‘red’, ‘blue’, ‘green’, etc. - Named colors: ‘aliceblue’, ‘antiquewhite’, etc. - Custom dartwork-mpl colors: ‘oc.red5’, ‘tw.blue500’, etc.

Parameters:: name (str) – Matplotlib color name (e.g., ‘red’, ‘oc.blue5’, ‘tw.blue500’).
Returns:: Color instance.
Return type:: Color
Raises:: ValueError – If the color name is not recognized by matplotlib.

classmethod from_oklab(L: float, a: float, b: float) → Color[source]¶

Create a Color from OKLab coordinates.

Parameters:

L (float) – OKLab coordinates (L typically in [0, 1]).
a (float) – OKLab coordinates (L typically in [0, 1]).
b (float) – OKLab coordinates (L typically in [0, 1]).

Returns:

Color instance.

Return type:

Color

classmethod from_oklch(L: float, C: float, h: float) → Color[source]¶

Create a Color from OKLCH coordinates.

Parameters:

L (float) – Lightness and Chroma (L typically in [0, 1], C >= 0).
C (float) – Lightness and Chroma (L typically in [0, 1], C >= 0).
h (float) – Hue in degrees [0, 360).

Returns:

Color instance.

Return type:

Color

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

Create a Color from RGB values.

Automatically detects if values are in [0, 1] or [0, 255] range. If all values are <= 1.0, treats as [0, 1]. Otherwise, treats as [0, 255].

Parameters:

r (float) – RGB values (auto-detected range).
g (float) – RGB values (auto-detected range).
b (float) – RGB values (auto-detected range).

Returns:

Color instance.

Return type:

Color

property oklab: OklabView¶

Get OKLab view of the color.

Returns:: View object for OKLab color space access.
Return type:: OklabView

Examples

>>> import dartwork_mpl as dm
>>> color = dm.oklab(0.7, 0.1, 0.2)
>>>
>>> # Attribute access
>>> L = color.oklab.L
>>> a = color.oklab.a
>>>
>>> # Unpacking
>>> L, a, b = color.oklab
>>>
>>> # Writing
>>> color.oklab.L += 0.1

property oklch: OklchView¶

Get OKLCH view of the color.

Returns:: View object for OKLCH color space access.
Return type:: OklchView

Examples

>>> import dartwork_mpl as dm
>>> color = dm.oklch(0.7, 0.2, 120)
>>>
>>> # Attribute access
>>> L = color.oklch.L
>>> C = color.oklch.C
>>> h = color.oklch.h
>>>
>>> # Unpacking
>>> L, C, h = color.oklch
>>>
>>> # Writing
>>> color.oklch.C *= 1.2

property rgb: RgbView¶

Get RGB view of the color.

Returns:: View object for RGB color space access.
Return type:: RgbView

Examples

>>> import dartwork_mpl as dm
>>> color = dm.rgb(0.8, 0.2, 0.3)
>>>
>>> # Attribute access
>>> r = color.rgb.r
>>> g = color.rgb.g
>>>
>>> # Unpacking
>>> r, g, b = color.rgb
>>>
>>> # Writing
>>> color.rgb.r = 0.9

to_hex() → str[source]¶

Convert to hex color string.

Returns:: Hex color string (#RRGGBB).
Return type:: str

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

Convert to OKLab coordinates.

Returns:: (L, a, b) OKLab coordinates.
Return type:: tuple[float, float, float]

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

Convert to OKLCH coordinates.

Returns:: (L, C, h) OKLCH coordinates, where h is in degrees [0, 360).
Return type:: tuple[float, float, float]

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

Convert to RGB values.

Returns:: (r, g, b) RGB values in range [0, 1].
Return type:: tuple[float, float, float]

class dartwork_mpl.color.OklabView(color: Color)[source]¶

Bases: _BaseColorView

View class for OKLab color space access.

Provides attribute-based access to OKLab coordinates (L, a, b) with support for reading, writing, unpacking, and indexing.

Parameters:: color (Color) – The Color instance to view.

Examples

>>> import dartwork_mpl as dm
>>> color = dm.oklab(0.7, 0.1, 0.2)
>>>
>>> # Attribute access
>>> L = color.oklab.L
>>> a = color.oklab.a
>>>
>>> # Unpacking
>>> L, a, b = color.oklab
>>>
>>> # Indexing
>>> a = color.oklab[1]
>>>
>>> # Writing
>>> color.oklab.L += 0.1
>>> color.oklab.a = 0.2

property L: float¶: Lightness component.

property a: float¶: Green-red component.

property b: float¶: Blue-yellow component.

dartwork_mpl.color.OklabViewIterator¶: alias of _ColorViewIterator

class dartwork_mpl.color.OklchView(color: Color)[source]¶

Bases: _BaseColorView

View class for OKLCH color space access.

Provides attribute-based access to OKLCH coordinates (L, C, h) with support for reading, writing, unpacking, and indexing.

Parameters:: color (Color) – The Color instance to view.

Examples

>>> import dartwork_mpl as dm
>>> color = dm.oklch(0.7, 0.2, 120)
>>>
>>> # Attribute access
>>> L = color.oklch.L
>>> C = color.oklch.C
>>> h = color.oklch.h
>>>
>>> # Unpacking
>>> L, C, h = color.oklch
>>>
>>> # Indexing
>>> C = color.oklch[1]
>>>
>>> # Writing
>>> color.oklch.C *= 1.2
>>> color.oklch.h = 180

property C: float¶: Chroma component.

property L: float¶: Lightness component.

property h: float¶: Hue component in degrees [0, 360).

dartwork_mpl.color.OklchViewIterator¶: alias of _ColorViewIterator

class dartwork_mpl.color.RgbView(color: Color)[source]¶

Bases: _BaseColorView

View class for RGB color space access.

Provides attribute-based access to RGB coordinates (r, g, b) with support for reading, writing, unpacking, and indexing.

Parameters:: color (Color) – The Color instance to view.

Examples

>>> import dartwork_mpl as dm
>>> color = dm.rgb(0.8, 0.2, 0.3)
>>>
>>> # Attribute access
>>> r = color.rgb.r
>>> g = color.rgb.g
>>>
>>> # Unpacking
>>> r, g, b = color.rgb
>>>
>>> # Indexing
>>> g = color.rgb[1]
>>>
>>> # Writing
>>> color.rgb.r = 0.9
>>> color.rgb.g += 0.1

property b: float¶: Blue component [0, 1].

property g: float¶: Green component [0, 1].

property r: float¶: Red component [0, 1].

dartwork_mpl.color.RgbViewIterator¶: alias of _ColorViewIterator

dartwork_mpl.color.cspace(start_color: Color | str, end_color: Color | str, n: int, space: str = 'oklch') → list[Color][source]¶

Interpolate between two colors to produce a list of evenly spaced colors.

Similar to numpy’s linspace, but operating in color space.

Parameters:

start_color (Color | str) – Starting color (Color instance or hex string).
end_color (Color | str) – Ending color (Color instance or hex string).
n (int) – Total number of colors to generate (including start and end).
space (str, optional) – Color space for interpolation: ‘oklch’ (default), ‘oklab’, or ‘rgb’. ‘oklch’ produces the most perceptually uniform results.

Returns:

List of interpolated Color objects.

Return type:

list[Color]

Raises:

TypeError – If start_color or end_color is not a Color instance or hex string.
ValueError – If an unsupported color space is specified.

dartwork_mpl.color.hex(hex_str: str) → Color[source]¶

Convenience wrapper to create a Color from a hex string.

Parameters:: hex_str (str) – Hex color code string (#RGB or #RRGGBB format).
Returns:: A new Color instance.
Return type:: Color

dartwork_mpl.color.named(color_name: str) → Color[source]¶

Create a Color from a Matplotlib named color.

Parameters:: color_name (str) – A color name recognized by Matplotlib (e.g., ‘red’, ‘oc.blue5’, ‘tw.blue500’).
Returns:: A new Color instance.
Return type:: Color

dartwork_mpl.color.oklab(L: float, a: float, b: float) → Color[source]¶

Convenience wrapper to create a Color from OKLab coordinates.

Parameters:

L (float) – OKLab color coordinates.
a (float) – OKLab color coordinates.
b (float) – OKLab color coordinates.

Returns:

A new Color instance.

Return type:

Color

dartwork_mpl.color.oklch(L: float, C: float, h: float) → Color[source]¶

Convenience wrapper to create a Color from OKLCH coordinates.

Parameters:

L (float) – Lightness and chroma values.
C (float) – Lightness and chroma values.
h (float) – Hue angle in degrees [0, 360).

Returns:

A new Color instance.

Return type:

Color

dartwork_mpl.color.rgb(r: float, g: float, b: float) → Color[source]¶

Convenience wrapper to create a Color from RGB values.

Parameters:

r (float) – RGB color values (auto-detected as [0-1] or [0-255] range).
g (float) – RGB color values (auto-detected as [0-1] or [0-255] range).
b (float) – RGB color values (auto-detected as [0-1] or [0-255] range).

Returns:

A new Color instance.

Return type:

Color

Note

mix_colors and pseudo_alpha are defined in the util module but re-exported from the top-level dartwork_mpl namespace for convenience alongside other color helpers.

dartwork_mpl.mix_colors(color1: str | tuple[float, float, float], color2: str | tuple[float, float, float], alpha: float = 0.5) → tuple[float, float, float][source]¶

Blend two colors according to a given weight (alpha).

Parameters:

color1 (str | tuple[float, float, float]) – First color to blend. Any format recognized by matplotlib.
color2 (str | tuple[float, float, float]) – Second color to blend.
alpha (float, optional) – Weight of the first color (between 0 and 1). Default is 0.5.

Returns:

RGB tuple of the blended result.

Return type:

tuple[float, float, float]

dartwork_mpl.pseudo_alpha(color: str | tuple[float, float, float], alpha: float = 1.0, background: str | tuple[float, float, float] = 'white') → tuple[float, float, float][source]¶

Return an opaque RGB that simulates alpha transparency against a background.

True alpha can cause darkening artifacts when lines overlap or cover images. This function blends the color with the background to produce a flat (opaque) color that visually mimics transparency.

Parameters:

color (str | tuple[float, float, float]) – The target foreground color.
alpha (float, optional) – Simulated opacity (0 to 1). Default is 1.0 (fully opaque).
background (str | tuple[float, float, float], optional) – Background color to blend against. Default is “white”.

Returns:

RGB tuple of the composited color.

Return type:

tuple[float, float, float]

Color Interpolation¶

dartwork_mpl.cspace(start_color: Color | str, end_color: Color | str, n: int, space: str = 'oklch') → list[Color][source]¶

Interpolate between two colors to produce a list of evenly spaced colors.

Similar to numpy’s linspace, but operating in color space.

Parameters:

start_color (Color | str) – Starting color (Color instance or hex string).
end_color (Color | str) – Ending color (Color instance or hex string).
n (int) – Total number of colors to generate (including start and end).
space (str, optional) – Color space for interpolation: ‘oklch’ (default), ‘oklab’, or ‘rgb’. ‘oklch’ produces the most perceptually uniform results.

Returns:

List of interpolated Color objects.

Return type:

list[Color]

Raises:

TypeError – If start_color or end_color is not a Color instance or hex string.
ValueError – If an unsupported color space is specified.

Palette Discovery¶

dartwork_mpl.list_palettes() → list[str][source]¶

List all available discrete color palettes.

Returns:: Sorted list of palette names (e.g., ‘dc.vivid’, ‘oc.blue’).
Return type:: list[str]

dartwork_mpl.list_colormaps(include_reversed: bool = False) → list[str][source]¶

List all registered dartwork colormaps.

Parameters:: include_reversed (bool, optional) – Whether to include reversed colormaps (names ending with ‘_r’). Default is False.
Returns:: Sorted list of registered colormap names.
Return type:: list[str]

dartwork_mpl.show_palette(palette_name: str) → None[source]¶

Visually display the colors of a specific discrete palette.

Renders all shades in the specified palette as a row of color swatches. Useful for previewing colors in Jupyter notebooks.

Parameters:: palette_name (str) – Name of the palette to visualize (e.g., ‘dc.acid’, ‘oc.gray’).
Raises:: ValueError – If the palette name does not exist or contains no numbered color entries.

Visualization Tools¶

dartwork_mpl.plot_colors(colors: dict[str, str | tuple[float, float, float]] | None = None, *, ncols: int = 4, sort_colors: bool = True, show_hex: bool = True) → list[Figure][source]¶

Plot a grid of named colors with their names and hex values.

Creates separate figures for each color library (Open Color, Tailwind, Material Design, Ant Design, Chakra UI, Primer, Other).

Parameters:

colors (dict, optional) – Dictionary mapping color names to color specifications. If None, uses all named colors from matplotlib except those starting with 'dartwork_mpl.' or 'xkcd:'.
ncols (int, optional) – Number of columns in the color grid, default is 4.
sort_colors (bool, optional) – If True, sorts colors by base color name, then by weight or HSV value.
show_hex (bool, optional) – If True, shows the hex color value beneath each color name and overlaid on the swatch. Default True.

Returns:

List of figures, one for each color library.

Return type:

list of matplotlib.figure.Figure

dartwork_mpl.plot_colormaps(cmap_list: list[str] | list[Colormap] | None = None, ncols: int = 3, group_by_type: bool = True) → list[Figure][source]¶

Plot colormaps grouped by type.

Returns a list of figures, one per category. Does not call plt.show() — the caller decides when to display.

Parameters:

cmap_list (list, optional) – List of colormap names or objects. Defaults to all registered colormaps (excluding _r reversed variants).
ncols (int, optional) – Number of columns, default 3.
group_by_type (bool, optional) – If True, group colormaps by their classified type and return one figure per category. Otherwise return a single figure.

Returns:

One figure per category (or a single-element list when group_by_type is False).

Return type:

list of matplotlib.figure.Figure

dartwork_mpl.classify_colormap(cmap: Colormap) → str[source]¶

Classify a colormap into one of the following categories.

Categories¶

Categorical
Single-Hue
Multi-Hue
Diverging
Cyclical

param cmap:: Colormap to classify.
type cmap:: matplotlib.colors.Colormap
returns:: Category of the colormap.
rtype:: str