lightweight python implementation of Björn Ottosson's oklab/oklch colour space

i like oklab but there isnt a straightforward python package for it, so i made it

install

install it from PyPI:

python -m pip install oklab

how to use?

use it in python:

import oklab

oklab.lch_to_hex((0.75, 0.125, 310.0))
# '#c697e9'

oklab.hex_to_lch('#ff0000')
# (0.6279536182521783, 0.25762679148825324, 29.227131291763712)

oklab.lab_to_xyz((1.0, 0.0, 0.0))
# (0.9504559270516719, 0.9999999999999998, 1.0890577507598782)

or use it in the terminal:

> oklab -i lch -o hex 0.75 0.125 310
#c697e9

> oklch ff0000
(0.6279536182521783 0.25762679148825324 29.227131291763712)

> oklab -i lab -o xyz 1.0 0.0 0.0
(0.9504559270516719, 0.9999999999999998, 1.0890577507598782)

try this fancy demo!

import os, oklab
C, R = os.get_terminal_size()
for row in range(R - 1, -1, -1):
    string = []
    for col in range(C):
        l = row / (R - 1) * 0.85 + 0.15
        c = 0.125
        h = col / (C - 1) * 360
        colour = oklab.lch_to_rgb((l, c, h))
        if not all(0 < c < 1 for c in colour):
			# out of gamut
            string.append(f' ')
            continue
        r, g, b = tuple(round(c * 255) for c in colour)
        string.append(f'\x1b[38;2;{r};{g};{b}m█')
    print(''.join(string))

features

• ✅ 8 formats: lab, lch, hex, rgb, dp3, rec, xyz, lms

• ✅ 26 conversion functions

• ✅ high numerical stability

• ✅ zero dependencies

• ✅ sRGB, Display P3, ITU-R BT.2020 (Rec. 2020) support

• ✅ clamping: chroma reduction (default), point projection

• 🚧 python ≥3.11 compatibility

• 🚧 CLI convenience tools (still being polished)

• 🚧 reference-grade correctness (not yet verified by Björn & CSSWG)

• 🚧 clamping: MINDE, CSS-style JND approximation

• ❌ CMYK support (non-RGB spaces and ICC profiles cause scope creep)

sources

• function names inspired by hsluv
• outputs sanity-checked against oklch.com and wikipedia
• M0 sourced from Björn's CSSWG comment
• M2_inv sourced from Björn's blogpost
• matrices sourced from colour science
• M1, M1_inv, M2, … derived numerically using numpy
• test_oklab.test_xyz sourced from Björn's blogpost

conversions

the following conversions are maintained:

trivial non-oklab-related conversions such as rgb_to_xyz are not included