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="dc.ocean2", label="Series A")
lighter = dm.mix_colors("dc.ocean2", "white", alpha=0.35)
muted_line = dm.pseudo_alpha("dc.ocean3", 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.colors.Color(value: Color | str)[source]¶

Bases: object

Color in OKLab/OKLCH/RGB/Hex color spaces.

A wrapper over a single canonical store (OKLab coordinates) with per-space property views (color.oklab / color.oklch / color.rgb). The constructor takes a string (or pass-through Color) — bare numerics are rejected because three floats give no way to tell OKLab apart from OKLCH or RGB. For already-typed numeric input, use from_oklab() / from_oklch() / from_rgb() / from_hex() / from_name() (or the top-level wrappers oklab() / oklch() / rgb() / hex()).

Equality and hashing are by value — two colors with the same OKLab coordinates compare equal (__eq__()) and hash equal (__hash__()).

Note

Unlike Length, Color is currently mutable: the oklab / oklch / rgb views write back to the underlying store in place (hence copy()). Because it is both mutable and value-hashable, do not mutate a Color after using it as a dict / set key. A future release will make Color immutable (view setters returning a new instance); see issue #233.

Parameters:: value (Color or str) – Either another Color (returned as a fresh copy with the same OKLab coordinates) or a string parseable by Color.parse() — hex ("#ff0000"), functional ("rgb(1, 0, 0)" / "oklch(0.7, 0.15, 30)" / "oklab(...)"), or a palette/matplotlib color name ("oc.red5", "red").

Examples

>>> import dartwork_mpl as dm
>>> dm.Color("#ff0000")
>>> dm.Color("oklch(0.7, 0.15, 30)")
>>> dm.Color("oc.red5")
>>> dm.Color(dm.oklab(0.7, 0.1, 0.2))   # pass-through copy

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

in_gamut(tol: float = 1e-06) → bool[source]¶

Whether this color is representable inside the sRGB gamut.

Returns True when every linear-sRGB channel falls within [0, 1] (within tol), i.e. to_rgb() returns the color directly. Returns False for out-of-gamut colors, which to_rgb() gamut-maps by reducing chroma while holding lightness and hue (so the rendered color stays close in L/h).

Parameters:: tol (float, optional) – Numerical tolerance on the [0, 1] bounds, to absorb floating-point error at the gamut boundary. Default 1e-6.
Return type:: bool

Examples

>>> import dartwork_mpl as dm
>>> dm.Color.from_oklch(0.7, 0.05, 30).in_gamut()
True
>>> dm.Color.from_oklch(0.7, 0.40, 30).in_gamut()
False

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

classmethod parse(value: str) → Color[source]¶

Parse a string in any supported form into a Color.

Routes by the leading character / token of value:

"#rgb" / "#rrggbb" → from_hex().
"rgb(r, g, b)" (auto 0-1 / 0-255 detection), "oklch(L, C, h)" (h in degrees), "oklab(L, a, b)" → corresponding factory. Function name is case-insensitive; arguments are comma-separated and tolerant of internal whitespace.
Anything else falls through to from_name() (matplotlib named colors, oc., tw., md., ad., cu., pr., dc.).

Parameters:

value (str) – The color string to parse. Surrounding whitespace is stripped.

Return type:

Color

Raises:

TypeError – If value is not a str.
ValueError – If a functional form has the wrong number of arguments, non-numeric arguments, or the underlying factory rejects the value.

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) sRGB values in range [0, 1].
Return type:: tuple[float, float, float]

Notes

Colors inside the sRGB gamut convert exactly. Out-of-gamut colors are gamut-mapped by reducing chroma while holding lightness (L) and hue (h) fixed — a binary search to the sRGB gamut boundary along the requested OKLCH hue line (CSS Color 4 style) — so the rendered color keeps the requested L and h instead of the per-channel clamp’s L/h drift. A final per-channel clamp absorbs sub-tolerance boundary residual and clips an achromatic L outside [0, 1] (which chroma reduction alone cannot represent). Use in_gamut() to detect whether a color required mapping.

class dartwork_mpl.colors.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.colors.OklabViewIterator¶: alias of _ColorViewIterator

class dartwork_mpl.colors.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.colors.OklchViewIterator¶: alias of _ColorViewIterator

class dartwork_mpl.colors.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.colors.RgbViewIterator¶: alias of _ColorViewIterator

dartwork_mpl.colors.color(value: Color | str) → Color[source]¶

Parse a string (or pass through a Color) into a Color.

String-parser counterpart to hex(), rgb(), oklch(), oklab(), and palette-name lookup. Mirrors dartwork_mpl.length() for unit strings.

Examples

>>> import dartwork_mpl as dm
>>> dm.color("#ff0000")            # hex
>>> dm.color("rgb(1, 0, 0)")       # functional
>>> dm.color("oklch(0.7, 0.15, 30)")
>>> dm.color("oc.red5")            # palette name

Parameters:: value (Color or str) – A Color instance is returned as a fresh copy with the same OKLab coordinates. A string is dispatched through Color.parse().
Return type:: Color

dartwork_mpl.colors.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.colors.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

Notes

This is the public dm.hex constructor and intentionally shares the name of the builtin hex. The shadow is scoped to this module / the dartwork_mpl namespace; use builtins.hex if you need the integer-to-hex builtin alongside it.

dartwork_mpl.colors.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.colors.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.colors.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 in OKLab space (perceptually uniform blend).

Blends in OKLab rather than gamma-encoded sRGB, so midpoints avoid the “muddy” saturation dip that naive RGB mixing produces for saturated hues (e.g. red + blue → purple, not a dark desaturated grey).

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. Any format recognized by matplotlib.
alpha (float, optional) – Weight of color1 (0 → color2, 1 → color1). Default is 0.5.

Returns:

sRGB tuple of the blended result, compatible with any matplotlib color= argument.

Return type:

tuple[float, float, float]

Notes

The result will differ subtly from previous versions for non-grayscale blends — gradients now look smoother and less desaturated through saturated midpoints. dm.pseudo_alpha (which delegates to this function) inherits the same improvement.

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