dymokomi/luce-color
Color science in Luce Base: XYZ and Bradford adaptation, sRGB/P3/Adobe/Rec.2020/ACES/ProPhoto, sRGB/gamma/PQ/HLG curves, CIELAB/CIEDE2000, Oklab, CAM16, HSV/HSL, OCIO-style conversion, ICC profiles and transforms (skcms port).
A library written in luce-base. Latest release 0.8.2.
Install#
luc add dymokomi/luce-colorDocumentation#
luce-color
Color science for Luce, written in Luce Base. Everything that turns numbers into colors and colors into what the eye sees lives here, so an editor, a UI theme and a file codec agree about what a color is:
| module | what it holds |
|---|---|
color | Color (linear sRGB, the GPU model), Oklab, and the surface derivations luce-ui themes use (elevate, blend) |
transfer | transfer functions: sRGB, gamma 1.8/2.2/2.4, PQ (ST 2084), HLG; encode/decode by Transfer; for per-pixel CPU loops srgb_byte and SrgbTable (the decoding interpolated from 4097 samples) |
xyz | CIE XYZ, chromaticities and whites (D65, D50, ACES), Primaries for sRGB, Display P3, Adobe RGB, Rec. 2020, ACES AP0/AP1, ProPhoto; matrices derived from chromaticities; Bradford adaptation; convert between primaries |
lab | CIELAB and LCh against any white, ΔE76 and CIEDE2000, OkLCh |
cam16 | CAM16 viewing conditions, appearance (J, Q, C, M, s, h), the inverse from JCh, CAM16-UCS and its ΔE |
oklab | Oklab from XYZ, ΔEok, sRGB max_chroma(l, h), CSS-style gamut mapping by chroma reduction (to_srgb), gamut-relative chroma for pickers |
hsl | HSV (Photoshop's HSB) and HSL over encoded RGB, for pickers |
space | ColorSpace = name + primaries + transfer, as OpenColorIO models one; a catalogue (space.all, space.named); convert(color, from, to) — decode, matrix, adapt, matrix, encode — plus to_lab, to_oklab_in, to_appearance, in_gamut, clamp |
temperature | correlated color temperature and tint (Robertson, with the DNG SDK's tint scale): white(kelvin, tint) and of(chromaticity) |
spectral | spectra at 5 nm over 380–780 nm, the CIE 1931 observer, black-body and CIE daylight light, a white balance's light as a spectrum, and spectral upsampling (Jakob & Hanika's sigmoid spectra): fit one color, Upsampler a grid over xy |
camera | cameras' spectral sensitivities: 52 measured (rawtoaces-data), or estimated from a raw's color matrix; 190 training reflectances |
aces | the ACES 2.0 Output Transform: Hellwig 2022 JMh, the Daniele tonescale, chroma compression and gamut compression into a display's limiting gamut, for SDR and HDR peaks, and its inverse; matches OpenColorIO's builtin transforms within 1e-4 of the peak |
icc | ICC profiles, a port of skcms (Skia's ICC library): parse (v2 and v4, matrix/TRC, A2B/B2A lookup tables, cicp), transfer functions and curve fitting, transform between profiles and pixel formats; Skia's ColorSpace (from a profile, CICP code points or named primaries and curves) and the Steps between two of them |
from luce_color import space, lab, cam16
# Display P3's red, as sRGB sees it: out of gamut, so clamp for a preview.
let red = space.convert(color.Color(1.0, 0.0, 0.0), space.display_p3, space.srgb)
let shown = space.clamp(red)
# How different are two paints? CIEDE2000 about 1 is a just-noticeable step.
let difference = lab.delta_e2000(space.to_lab(a, space.srgb), space.to_lab(b, space.srgb))
# What a color looks like on this display: CAM16 lightness, chroma and hue.
let look = space.to_appearance(a, space.srgb, space.display_viewing(space.srgb))
The sRGB curve for GLSL shaders is shaders/srgb.glsl: luce-painting's and luce-image's shaders include it (embed_shaders.py -I ../luce-color/shaders), so there is one copy.
Numbers are checked against the published references in each module's tests: the sRGB matrix, ST 2084's luminance anchors, Sharma's CIEDE2000 pairs, CAM16's white and inverse. An OCIO config reader is not here yet; space.convert is the processor chain one would produce for a pair of its color spaces.
ACES 2.0 (aces)
from luce_color import aces, xyz
# SDR: a 100-nit display limited to Rec.709/sRGB primaries.
let sdr = try aces.OutputTransform.create(100.0, xyz.srgb)
let shown = sdr.apply_ap1([0.18, 0.18, 0.18]) # ACEScg in; display-linear sRGB-primary RGB out, ~0.1
let scene = sdr.invert_ap1([1.0, 1.0, 1.0]) # display white back to the scene light that shows as white
OutputTransform.create(peak_nits, limiting) builds the transform's hue tables once, in a few milliseconds. apply(ap0) and apply_ap1(ap1) give display-linear RGB in the limiting primaries, where 1.0 is 100 cd/m² (an SDR display's white is 1.0, a 1000-nit display's is 10.0), clamped to the peak. to_xyz() converts that RGB to CIE XYZ. Encoding for the display is the caller's job, through space and transfer. The transform follows the Academy's aces-output and OpenColorIO's ACES2 implementation (reference only), in f64. tests/aces compares it with OpenColorIO 2.6's builtins (SDR Rec.709, SDR P3-D65, 1000-nit P3-D65 and Rec.2020) on 447 colors each. The largest difference is 1.5e-5 of the peak. tests/make_aces_fixtures.py regenerates the reference from OpenColorIO.
invert(display) and invert_ap1(display) run the transform backward, as OpenColorIO's inverse ACES2 output transform does: display-linear RGB to the scene light the forward transform shows as it. That is how display-referred pictures (JPEGs, textures, screen captures) enter a scene and still look as they did: put through the plain sRGB decode instead, their white would sit at scene 1.0 and show grey. Shown again, the inverse lands on the display color within 2e-4 of the peak across a grid of SDR colors. Against OpenColorIO's inverse on the same 447 colors, scene light under ten times reference white agrees within 0.05%. Nearer the peak the inverse is very steep (display 0.99 is scene 30 to 140). There the two implementations, shown again, agree within 6e-4 of the peak, and each lands about that close to the display color.
ICC profiles (icc)
icc is a faithful port of skcms, the ICC library Skia (and so Chrome, Android and Ladybird) uses, with the parts of Skia that make a profile into the color space an image is drawn in. It computes in f32 in skcms's order without fused multiply-adds, so its results are skcms's built portable without contraction, to the bit: tests/icc_oracle holds every profile of tests/fixtures/icc against skcms's own dump of it, and against Skia's color spaces.
from luce_color import icc
# A PNG's iCCP profile: what does it make of a pixel, in sRGB?
let profile = icc.parse(profile_bytes) else return
let srgb = icc.Profile.srgb()
_ = icc.transform(pixels, .rgba_8888, .unpremul, &profile, out, .rgba_8888, .unpremul, &srgb, count)
# As Skia draws an image tagged with it: the color space, then the steps to sRGB.
if let space = icc.ColorSpace.from_profile(&profile):
let destination = icc.ColorSpace.srgb()
let steps = icc.Steps.make(&space, .premul, &destination, .premul)
let shown = steps.apply([0.6, 0.0, 0.0, 1.0])
# CICP code points (ITU-T H.273), as a PNG's cICP chunk gives them: Display P3.
let p3 = icc.ColorSpace.cicp(12, 13)
| Function | Purpose |
|---|---|
parse(bytes), parse_with_a2b_priority | A profile, or none when malformed or unusable (skcms_Parse). |
transform(src, format, alpha, profile, dst, ...) | Pixels between profiles and formats (skcms_Transform). |
TransferFunction.kind/eval/invert | skcms's transfer functions: sRGB-ish, PQ(-ish), HLG(-ish). |
Curve.eval/approximate | A tone curve; a table fitted with a transfer function (skcms_ApproximateCurve). |
Profile.make_usable_as_destination | Tabulated curves replaced by fitted ones. |
approximately_equal_profiles(a, b) | Profiles that move colors alike (skcms_ApproximatelyEqualProfiles). |
ColorSpace.from_profile/cicp/rgb | Skia's SkColorSpace::Make, MakeCICP, MakeRGB. |
Steps.make(src, alpha, dst, alpha) | SkColorSpaceXformSteps; apply on one color. |
transfer_function(t), primaries_matrix(p), ColorSpace.from_space(s) | This library's transfer, xyz and space types in skcms's terms. |
skcms and Skia are BSD-3-Clause (LICENSE-skia); the port keeps their notices.
Spectra (spectral)
Something with its own spectral response, a film emulsion or a camera, needs a spectrum for a color, not three numbers. spectral samples spectra every 5 nm from 380 to 780 nm, turns them into XYZ with the CIE 1931 2° observer, and makes black-body light (planck, scaled to Y = 1). A color's spectrum comes from Jakob & Hanika's model ("A Low-Dimensional Function Space for Efficient Spectral Upsampling", 2019): a sigmoid of a quadratic in wavelength, three coefficients fitted by Gauss–Newton in CIELAB. fit(target, light) fits a surface for one color under a light; upsampler(light, size) fits a grid over CIE xy, from the white outward, each cell's spectrum lit and scaled to Y = 1, so any color's spectrum is its cell's times its luminance. Chromaticities beyond the spectral locus take the nearest color toward the white a surface can show. A 48 × 48 grid fits in about 0.1 s.
Light: planck(kelvin), daylight(kelvin) (CIE's D series from S0, S1, S2, 4000–25000 K) and illuminant(kelvin, tint), the light a white balance names as a spectrum: a black body below 4000 K, daylight above 5000 K, a blend between, then nudged onto the white temperature.white(kelvin, tint) gives exactly.
from luce_color import spectral
let tungsten = spectral.planck(3200.0)
var grid = try spectral.upsampler(tungsten, 48)
defer grid.release()
let skin = grid.spectrum(30, 22) # light at that cell's chromaticity, Y = 1
let exposure = skin.dot(response) # through a sensor's f64[81] response
Cameras (camera)
A camera records three numbers per pixel, each the scene's spectrum weighted by one of its channels' spectral sensitivities. camera.Response holds those curves; of(spectrum) gives the camera's values. measured(make, model) finds the 52 cameras the Academy's rawtoaces-data measured (Canon, Nikon, Sony, Fujifilm, Panasonic, Hasselblad and others; names compared the way raw files give them). For any other camera, estimate(to_camera, kelvins) fits curves to its color matrices (XYZ to raw values under each light) in a prior over the measured ones, each channel's mean shape and three principal components, gains free, after Solomatov and Akkaynak (ICCP 2023): about a tenth of the peak off the measured curves. observer() is the CIE observer as a camera, whose values are XYZ. training(at) gives the 190 reflectances rawtoaces fits its matrices to.
from luce_color import camera
let sony = camera.measured("SONY", "ILCE-7M3") # Response?
let guess = camera.estimate(xyz_to_raw_d65, [6504.0]) # from a raw's matrix
The measured curves and the training reflectances are the Academy Software Foundation's rawtoaces-data (https://github.com/AcademySoftwareFoundation/rawtoaces-data), Apache License 2.0; tools/cameras.py generates src/camera_data.lucb from it.
Theme derivations (color)
Color is a linear-light sRGB triple — the same model as gpu.Color — so a caller bridges with a field-wise copy and no gamma handling of its own. Oklab is the perceptual space: lightness l with opponent axes a and b, both zero for a neutral gray.
from luce_color import color
# A hovered surface: lift a base color toward the foreground in perceptual
# lightness, keeping its hue. amount 0 is the base, 1 the reference lightness.
let hover = color.elevate(color.Color(0.02, 0.03, 0.05), color.Color(0.7, 0.75, 0.82), 0.1)
# A midpoint state, such as a hovered border between resting and focused:
let edge = color.blend(color.Color(0.06, 0.09, 0.12), color.Color(0.10, 0.22, 0.32), 0.5)
Reference
| Function | Purpose |
|---|---|
to_oklab(color) | Linear sRGB to Oklab. |
to_color(lab) | Oklab to linear sRGB, clamped to the displayable cube. |
elevate(base, reference, amount) | Shift base toward reference in lightness only, keeping hue and chroma. |
blend(a, b, amount) | Interpolate two colors in Oklab, so midpoints stay saturated. |
Build and test
Keep luce-color, luce, and luce-base as sibling checkouts. The tested compiler revisions are recorded in bootstrap/. Build the native compilers, then run the module's test blocks in every compiled mode:
(cd ../luce-base && ./build.sh)
(cd ../luce && LUCE_BASE_COMPILER=../luce-base/build/luce-base ./build.sh)
luc test
Licensed under either of Apache-2.0 or MIT at your option.
Dependencies#
| Package | Version |
|---|---|
| dymokomi/luce-std | newest |
Versions#
0.8.2
Browse source · pack · commit e5f1a38c42e3
SHA-256 6c6f93f2c3eba4dcf2abec3bb1a8ffdca3b50dde700b1323aeddf1bc8c129537
luce-color 0.8.2: batch release
0.8.1
Browse source · pack · commit c9c0640cfabe
SHA-256 aed332dad85946cc9ed9a213f6a8b882319e62a12d7baeb1ff255b2289835503
luce-color 0.8.1: batch release
0.8.0
Browse source · pack · commit ffa8fb24ce30
SHA-256 7174e5a79ccae8f9fba3141791b6bafb0c435258266933dc08595166c53be952
ACES 2.0 Output Transform; ICC v4 display profile writer; dependencies name no version