oklab 0.1.0__py2.py3-none-any.whl

oklab-0.1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: oklab
+Version: 0.1.0
+Summary: lightweight python implementation of Björn Ottosson's oklab colour space
+Project-URL: Homepage, https://github.com/deftasparagusanaconda/oklab
+Project-URL: Repository, https://github.com/deftasparagusanaconda/oklab
+Project-URL: Issues, https://github.com/deftasparagusanaconda/oklab/issues
+Author: deftasparagusanaconda
+License-Expression: MIT
+License-File: LICENSE
+Keywords: color,colour,oklab,oklch
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Description-Content-Type: text/markdown
+
+lightweight python implementation of [Björn Ottosson](https://bottosson.github.io/)'s oklab/oklch colour space. 
+
+i like oklab but there isnt a straightforward python package for working with it. so i made it.
+
+# install
+
+install it from [PyPI](https://pypi.org/project/oklab/):
+
+```sh
+python -m pip install oklab
+```
+
+# how to use?
+
+```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)
+```
+
+# features
+
+- [x] 6 formats: `rgb`, `hex`, `lab`, `lch`, `xyz`, `lms`
+- [x] 30 conversion functions (complete graph)
+- [x] numerical accuracy + roundtrip precision
+- [x] source correctness
+- [x] zero dependencies
+- [ ] clamping (in native oklab space via chroma reduction)
+- [ ] configurable RGB primaries (P3, rec2020, …)
+- [❌] CMYK support (scope creep)
+
+# sources
+
+- function names inspired by [hsluv](https://github.com/hsluv/hsluv-python)
+- outputs sanity-checked against [oklch.com](https://oklch.com/) and [wikipedia](https://en.wikipedia.org/wiki/Oklab_color_space)
+- `M0` sourced from [Björn's CSSWG comment](https://github.com/w3c/csswg-drafts/issues/6642#issuecomment-945714988)
+- `M2_inv` sourced from [Björn's blogpost](https://bottosson.github.io/posts/oklab/)
+- `XYZ_TO_RGB`, `RGB_TO_XYZ` sourced from [colour science](https://www.colour-science.org/)
+- `M1`, `M1_inv`, `M2`, `RGB_TO_LMS`, `LMS_TO_RGB` derived numerically using [numpy](https://github.com/numpy/numpy)
+- tests sourced from [Björn's blogpost](https://bottosson.github.io/posts/oklab/)
+
+# conversion graph
+
+here is a graph of the atomic conversions:
+
+![graph of formats and conversions](https://github.com/deftasparagusanaconda/oklab/blob/main/formats.png)
+
+- lab: oklab cartesian space
+- lch: oklch cylindrical space
+- lms: intermediate lms-like space
+- xyz: CIEXYZ space
+- rgb: sRGB
+- hex: 8-bit sRGB in hexadecimal
+
+all composed conversions are derived via shortest path in this graph
+

oklab-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+oklab.py,sha256=bOveTff8-JzSqXfcqMwqtuDP0d7JuiglXN5ezqOc2gE,6871
+oklab-0.1.0.dist-info/METADATA,sha256=1VwoZX53haecoZtzkR0cfekHOYff7N5C0xEk168iWg0,2773
+oklab-0.1.0.dist-info/WHEEL,sha256=VX-VJ7c6dw9Ge3EqJIbA6W3pOUbz24SnnGGFNr55jY4,105
+oklab-0.1.0.dist-info/licenses/LICENSE,sha256=VB2xlcQdtOxvalPfPY4FykGdH2Aqqjr0NO9YeF_3cyk,1078
+oklab-0.1.0.dist-info/RECORD,,

oklab-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

oklab-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lalremruata Chongmang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oklab.py

@@ -0,0 +1,156 @@
+"lightweight python implementation of Björn Ottosson's oklab colour space"
+
+# typehinting tuple[float, float, float] everywhere is messy
+
+import math
+
+def matvec(matrix, vector):
+    'matrix × vector'
+    return tuple(math.sumprod(row, vector) for row in matrix)
+
+def root(a, b):
+    'a ** (1 / b)'
+
+    # this is proven (from daamath) to be bad
+    #return math.exp(math.log(a) / b)
+
+    return a ** (1 / b)
+
+# mysterious numbers from https://github.com/w3c/csswg-drafts/issues/6642#issuecomment-945714988
+M0     = ((+0.77849780, +0.34399940, -0.12249720),
+          (+0.03303601, +0.93076195, +0.03620204),
+          (+0.05092917, +0.27933344, +0.66973739))
+
+# source of truth: https://bottosson.github.io/posts/oklab/#converting-from-linear-srgb-to-oklab
+M2_inv = ((+1.0       , +0.3963377774, +0.2158037573),
+          (+1.0       , -0.1055613458, -0.0638541728),
+          (+1.0       , -0.0894841775, -1.2914855480))
+
+# M0 / numpy.outer(numpy.dot(M0, ((3127/3290, 1, (10000-3127-3290)/3290))), (1, 1, 1))
+M1 = ((+0.819022437996703  , +0.3619062600528904, -0.1288737815209879 ),
+      (+0.03298365393238847, +0.9292868615863434, +0.03614466635064236),
+      (+0.04817718935962421, +0.2642395317527308, +0.6335478284694309 ))
+
+# numpy.linalg.inv(M2_inv)
+M2 = ((+0.21045426827458136 , +0.7936177747300267, -0.004072043004608034),
+      (+1.9779985323885083  , -2.428592241936286 , +0.450593709547778   ),
+      (+0.025904042487658187, +0.7827717124269178, -0.808675754914576   ))
+
+# numpy.linalg.inv(M1)
+M1_inv = ((+1.2268798758459243 , -0.5578149944602171, +0.2813910456659647 ),
+          (-0.04057574521480085, +1.112286803280317 , -0.07171105806551636),
+          (-0.07637293667466007, -0.4214933324022432, +1.5869240198367816 ))
+
+def xyz_to_lms(xyz):
+    'convert (x, y, z) to (l, m, s)'
+    return matvec(M1, xyz)
+
+def lms_to_xyz(lms):
+    'convert (l, m, s) to (x, y ,z)'
+    return matvec(M1_inv, lms)
+
+def lms_to_lab(lms):
+    'convert (l, m, s) to (l, a, b)'
+    return matvec(M2, tuple(math.cbrt(cone) for cone in lms))
+
+def lab_to_lms(lab):
+    'convert (l, a, b) to (l, m, s)'
+    return tuple(cone ** 3 for cone in matvec(M2_inv, lab))
+
+# extra ------------------------------------------------------------------------
+
+# for convenience, we also want lch, rgb (srgb), hex (srgb), and p3, rec2020 in the future
+# totally we have a directed graph of 8 formats and 56 possible conversions
+
+def lch_to_lab(lch, *, degrees: bool = True):
+    'convert (l, c, h) to (l, a, b)'
+    l, c, h = lch
+    h = math.radians(h) if degrees else h
+    a = c * math.cos(h)
+    b = c * math.sin(h)
+    return l, a, b
+
+def lab_to_lch(lab, *, degrees: bool = True):
+    'convert (l, a, b) to (l, c, h)'
+    l, a, b = lab
+    c = math.hypot(a, b)
+    h = math.atan2(b, a) % math.tau
+    h = math.degrees(h) if degrees else h
+    return l, c, h
+
+def rgb_to_hex(rgb: tuple[float, float, float]) -> str:
+    "convert (r, g, b) to '#rrggbb' (rounding to 8 bits)"
+    #return '#' + ''.join(f'{round(channel * 255):02x}' for channel in rgb)
+    return f'#{round(rgb[0] * 255):02x}{round(rgb[1] * 255):02x}{round(rgb[2] * 255):02x}'
+
+def hex_to_rgb(hex: str) -> tuple[float, float, float]:
+    "convert '#rrggbb' to (r, g, b)"
+    return tuple(int(hex.lstrip('#')[i:i+2], base=16) / 255 for i in (0, 2, 4))
+
+# from colour_science: colour.RGB_COLOURSPACES['sRGB']._derived_matrix_RGB_to_XYZ
+RGB_TO_XYZ = ((+0.41239079926595934 , +0.35758433938387796, +0.1804807884018343 ),
+               (+0.2126390058715103  , +0.7151686787677559 , +0.07219231536073371),
+               (+0.019330818715591825, +0.11919477979462595, +0.9505321522496606 ))
+
+# from colour_science: colour.RGB_COLOURSPACES['sRGB']._derived_matrix_XYZ_to_RGB
+XYZ_TO_RGB = ((+3.2409699419045226  , -1.537383177570094  , -0.49861076029300344),
+               (-0.9692436362808798  , +1.8759675015077206 , +0.04155505740717563),
+               (+0.05563007969699364 , -0.20397695888897655, +1.0569715142428786 ))
+
+def eotf_srgb(x, *, A = 12.92, C = 0.055, γ = 2.4, X = 0.04045):
+    'convert gamma-encoded sRGB to linear sRGB'
+    return x / A if x <= X else ((x + C) / (1 + C)) ** γ
+
+def oetf_srgb(y, *, A = 12.92, C = 0.055, γ = 2.4, Y = 0.0031308):
+    'convert linear sRGB to gamma-encoded sRGB'
+    return y * A if y <= Y else math.fma(1 + C, root(y, γ), -C)
+
+def rgb_to_xyz(rgb):
+    'convert (r, g, b) in sRGB to (x, y, z)'
+    return matvec(RGB_TO_XYZ, tuple(map(eotf_srgb, rgb)))
+
+def xyz_to_rgb(xyz):
+    'convert (x, y, z) to (r, g, b) in sRGB'
+    return tuple(map(oetf_srgb, matvec(XYZ_TO_RGB, xyz)))
+
+# numpy.matmul(M1, _RGB_TO_XYZ)
+RGB_TO_LMS = ((+0.4121764591770371  , +0.536273974269589  , +0.05144037229550145),
+               (+0.2119091995880486  , +0.680717870982313  , +0.10739984387775395),
+               (+0.08834481407213206 , +0.28185396309857735, +0.6302808688015095 ))
+
+# numpy.matmul(_XYZ_TO_RGB, M1_inv)
+LMS_TO_RGB = ((+4.077186823717315   , -3.307622521664363  , +0.2308591954879519 ),
+               (-1.2685764914005104  , +2.609687114485009  , -0.34115574866072784),
+               (-0.004196542231656323, -0.7033996761010274 , +1.7067960338654136 ))
+
+def rgb_to_lms(rgb):
+    'convert (r, g, b) in sRGB to (l, m, s)'
+    return matvec(RGB_TO_LMS, tuple(map(eotf_srgb, rgb)))
+
+def lms_to_rgb(lms):
+    'convert (l, m, s) to (r, g, b) in sRGB'
+    return tuple(map(oetf_srgb, matvec(LMS_TO_RGB, lms)))
+
+# conveniences -----------------------------------------------------------------
+
+# with 6 formats, we now have 12 conversions out of a total of 6 * (6 - 1) = 30
+# lets derive the remaining 18
+
+def lab_to_xyz(lab): return lms_to_xyz(lab_to_lms(lab))
+def xyz_to_lab(xyz): return lms_to_lab(xyz_to_lms(xyz))
+def lch_to_lms(lch): return lab_to_lms(lch_to_lab(lch))
+def lms_to_lch(lms): return lab_to_lch(lms_to_lab(lms))
+def hex_to_lms(hex): return rgb_to_lms(hex_to_rgb(hex))
+def lms_to_hex(lms): return rgb_to_hex(lms_to_rgb(lms))
+def xyz_to_hex(xyz): return lms_to_hex(xyz_to_lms(xyz))
+def hex_to_xyz(hex): return lms_to_xyz(hex_to_lms(hex))
+def rgb_to_lab(rgb): return lms_to_lab(rgb_to_lms(rgb))
+def lab_to_rgb(lab): return lms_to_rgb(lab_to_lms(lab))
+def rgb_to_lch(rgb): return lab_to_lch(lms_to_lab(rgb_to_lms(rgb)))
+def lch_to_rgb(lch): return lms_to_rgb(lab_to_lms(lch_to_lab(lch)))
+def xyz_to_lch(xyz): return lab_to_lch(lms_to_lab(xyz_to_lms(xyz)))
+def lch_to_xyz(lch): return lms_to_xyz(lab_to_lms(lch_to_lab(lch)))
+def lab_to_hex(lab): return rgb_to_hex(lms_to_rgb(lab_to_lms(lab)))
+def hex_to_lab(hex): return lms_to_lab(rgb_to_lms(hex_to_rgb(hex)))
+def lch_to_hex(lch): return rgb_to_hex(lms_to_rgb(lab_to_lms(lch_to_lab(lch))))
+def hex_to_lch(hex): return lab_to_lch(lms_to_lab(rgb_to_lms(hex_to_rgb(hex))))