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). These helpers expose the color mixing routines used across the package and let you classify colormaps before plotting. Each helper lists its parameters and return value before jumping into examples.

mix_colors(color1, color2, alpha=0.5)

Parameters: - color1: matplotlib-compatible color (name or RGB tuple). - color2: second color to blend toward. - alpha: weight for color1 between 0 (all color2) and 1 (all color1).
Returns: - blended RGB tuple.

pseudo_alpha(color, alpha=1.0, background="white")

Parameters: - color: foreground color to soften. - alpha: perceived transparency level. - background: color to mix toward when true transparency is unavailable (e.g., PDF export).
Returns: - RGB tuple mixed against background.

classify_colormap(cmap)

Parameters: - cmap: colormap instance or name.
Returns: string label — one of "Categorical", "Sequential Single-Hue", "Sequential Multi-Hue", "Diverging", or "Cyclical".

Example

import matplotlib.pyplot as plt
import dartwork_mpl as dm

plt.plot(x, y, color="oc.blue5", label="Series A")
lighter = dm.mix_colors("oc.blue5", "white", alpha=0.35)
plt.fill_between(x, y, color=lighter)
dm.classify_colormap(plt.colormaps["viridis"])  # -> "Sequential Multi-Hue"
muted_line = dm.pseudo_alpha("oc.blue7", alpha=0.6, background="white")
plt.plot(x, z, color=muted_line, label="Muted series")

Color management and conversion utilities for matplotlib.

This module provides color loading, registration, and conversion functionality including support for OKLab, OKLCH, RGB, and hex color spaces.

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

Bases: object

A color class that supports OKLab, OKLCH, RGB, and hex color spaces.

Colors are stored internally as OKLab coordinates for efficient conversion. Use classmethods to create Color instances: from_oklab(), from_oklch(), from_rgb(), from_hex().

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: object

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.

Returns:: Lightness value.
Return type:: float

property a: float¶

Green-red component.

Returns:: Green-red value.
Return type:: float

property b: float¶

Blue-yellow component.

Returns:: Blue-yellow value.
Return type:: float

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

Bases: object

Iterator for OklabView unpacking.

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

Bases: object

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.

Returns:: Chroma value.
Return type:: float

property L: float¶

Lightness component.

Returns:: Lightness value.
Return type:: float

property h: float¶

Hue component in degrees.

Returns:: Hue value in degrees [0, 360).
Return type:: float

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

Bases: object

Iterator for OklchView unpacking.

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

Bases: object

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.

Returns:: Blue value in range [0, 1].
Return type:: float

property g: float¶

Green component.

Returns:: Green value in range [0, 1].
Return type:: float

property r: float¶

Red component.

Returns:: Red value in range [0, 1].
Return type:: float

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

Bases: object

Iterator for RgbView unpacking.

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

Generate a list of colors by interpolating between two colors.

Inspired by np.linspace, but for colors.

Parameters:

start_color (Color or str) – Starting color (Color instance or hex string).
end_color (Color or str) – Ending color (Color instance or hex string).
n (int) – Number of colors to generate (including start and end).
space (str, optional) – Color space for interpolation: ‘oklch’ (default), ‘oklab’, or ‘rgb’. Default is ‘oklch’.

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 space is not one of the supported color spaces.

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

Convenience function to create a Color from hex color string.

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

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

Convenience function to create a Color from matplotlib color name.

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

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

Convenience function to create a Color from OKLab coordinates.

Parameters:

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

Returns:

Color instance.

Return type:

Color

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

Convenience function to create a Color from OKLCH coordinates.

Parameters:

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

Returns:

Color instance.

Return type:

Color

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

Convenience function to create a Color from RGB values.

Parameters:

r (float) – RGB values (auto-detected range: 0-1 or 0-255).
g (float) – RGB values (auto-detected range: 0-1 or 0-255).
b (float) – RGB values (auto-detected range: 0-1 or 0-255).

Returns:

Color instance.

Return type:

Color

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]¶

Mix two colors.

Parameters:

color1 (color) – First color (any format accepted by matplotlib).
color2 (color) – Second color (any format accepted by matplotlib).
alpha (float, optional) – Weight of the first color, between 0 and 1.

Returns:

RGB tuple of the mixed color.

Return type:

tuple

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 a color with pseudo alpha.

Parameters:

color (color) – Color to apply pseudo-transparency to.
alpha (float, optional) – Alpha value between 0 and 1.
background (color, optional) – Background color to mix with.

Returns:

RGB tuple of the resulting color.

Return type:

tuple

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

Classify a colormap into one of the following categories: - Categorical - Sequential Single-Hue - Sequential Multi-Hue - Diverging - Cyclical

Parameters:: cmap (matplotlib.colors.Colormap) – Colormap to classify.
Returns:: Category of the colormap.
Return type:: str