oklch: OKLCH Perceptual Color Primitives#

The color-science toolbox behind themecode and the palette analyses: sRGB <-> OKLCH conversion (Bjoern Ottosson’s published OKLab transform), an OKLab Euclidean distance as a cheap perceptual-uniformity proxy for CIE Delta-E, WCAG relative luminance and contrast ratio, and sRGB gamut mapping (max_chroma_in_gamut, consumed by scripts/palette_analysis.py). themecode uses delta_e_ok for its nearest-swatch matching and contrast_ratio/relative_luminance for mode detection and contrast floors.

Historical note. This module previously also carried the legible_backgrounds engine, which regenerated the palette’s sheet2 swatches in OKLCH for hue legibility on the terminal-background channel. That engineering was reverted by operator decision: the palette returned to canonical Radix values and the background channel moved to the shape1 rung (see irix.colorcode.BG_SHADE). The engine survives in git history (commit ce3d47c) should it ever be warranted again.

Type Aliases#

irix.oklch.Hex = Hex#

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

irix.oklch.OKLab = OKLab#

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

irix.oklch.OKLCH = OKLCH#

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

irix.oklch.Rgb01 = Rgb01#

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

OKLCH Perceptual Color Primitives.

The color-science toolbox behind themecode and the palette analyses: sRGB <-> OKLCH conversion (Bjoern Ottosson’s published OKLab transform), an OKLab Euclidean distance as a cheap perceptual-uniformity proxy for CIE Delta-E, WCAG relative luminance and contrast ratio, and sRGB gamut mapping (max_chroma_in_gamut, consumed by scripts/palette_analysis.py). themecode uses delta_e_ok for its nearest-swatch matching and contrast_ratio/relative_luminance for mode detection and contrast floors.

Historical note. This module previously also carried the legible_backgrounds engine, which regenerated the palette’s sheet2 swatches in OKLCH for hue legibility on the terminal-background channel. That engineering was reverted by operator decision: the palette returned to canonical Radix values and the background channel moved to the shape1 rung (see irix.colorcode.BG_SHADE). The engine – hue-angle relaxation, gamut-bounded chroma maximization, and its generator script – survives in git history (commit ce3d47c) should it ever be warranted again.

irix.oklch.hex_to_rgb01(value: Hex) → Rgb01#

Parse a #rrggbb string into (r, g, b) floats in [0, 1].

Parameters:

value – A #rrggbb hex color string.

irix.oklch.rgb01_to_hex(rgb: Rgb01) → Hex#

Format (r, g, b) floats (clamped to [0, 1]) as an uppercase #rrggbb string.

Parameters:

rgb – Channel values; out-of-range values are clamped rather than raising, since this is the last step of a gamut-mapped pipeline that may still overshoot by float epsilon.

irix.oklch.rgb01_to_oklab(rgb: Rgb01) → OKLab#

Convert linear-domain-agnostic sRGB (r, g, b) ([0, 1]) to OKLab.

Coefficients are Bjoern Ottosson’s published OKLab transform (https://bottosson.github.io/posts/oklab/), verified by round-trip against the reference values (white -> L=1, sRGB red -> oklch(0.628, 0.258, 29.2deg)) in this module’s tests.

Parameters:

rgb – sRGB channel values in [0, 1].

irix.oklch.oklab_to_rgb01(oklab: OKLab) → Rgb01#

Convert OKLab back to sRGB (r, g, b) – may land outside [0, 1] (out-of-gamut).

Parameters:

oklab – An (L, a, b) OKLab triple.

irix.oklch.oklab_to_oklch(oklab: OKLab) → OKLCH#

Convert OKLab (L, a, b) to cylindrical OKLCH (L, C, H-degrees).

Parameters:

oklab – An (L, a, b) OKLab triple.

irix.oklch.oklch_to_oklab(oklch: OKLCH) → OKLab#

Convert cylindrical OKLCH (L, C, H-degrees) to OKLab (L, a, b).

Parameters:

oklch – An (L, C, H-degrees) OKLCH triple.

irix.oklch.hex_to_oklch(value: Hex) → OKLCH#

Convert a #rrggbb hex color directly to OKLCH.

Parameters:

value – A #rrggbb hex color string.

irix.oklch.oklch_to_hex(oklch: OKLCH) → Hex#

Convert OKLCH directly to a gamut-clamped #rrggbb hex color.

Parameters:

oklch – An (L, C, H-degrees) OKLCH triple. Out-of-gamut input is clamped in the final sRGB step rather than raising – callers that need a strictly in-gamut result should pass a chroma from max_chroma_in_gamut.

irix.oklch.delta_e_ok(a: Hex, b: Hex) → float#

Euclidean OKLab distance between two hex colors.

OKLab is constructed so that Euclidean distance approximates perceptual difference – this is the cheap, dependency-free stand-in for CIE Delta-E-2000 used throughout this module.

Parameters:

  • a – First #rrggbb hex color.

  • b – Second #rrggbb hex color.

irix.oklch.relative_luminance(value: Hex) → float#

WCAG relative luminance of a hex color (linear-light, Rec. 709 weights).

Parameters:

value – A #rrggbb hex color string.

irix.oklch.contrast_ratio(a: Hex, b: Hex) → float#

WCAG contrast ratio between two hex colors (always >= 1, order-independent).

Parameters:

  • a – First #rrggbb hex color.

  • b – Second #rrggbb hex color.

irix.oklch.max_chroma_in_gamut(lightness: float, hue_deg: float) → float#

Binary-search the largest in-sRGB-gamut chroma at a fixed lightness and hue.

Parameters:

  • lightness – Target OKLab L in [0, 1].

  • hue_deg – Target OKLCH hue angle in degrees.