Provides advanced functions for controlling Oklch chroma and AOkLab Lightness
to achieve specific target CIE Luminance (derived from CIELAB L*) values,
while leveraging the AOkLab model for its surround adaptation and hue uniformity.
This enables the creation of color palettes that are both perceptually harmonious
under various viewing conditions and compliant with WCAG contrast requirements.
**Key Features & Novel Approach:**
This module offers a unique combination of capabilities not commonly found together:
1. **Leverages Oklab's Excellent Hue Uniformity:**
By working with AOkLab Hue (H_aok) and Chroma (C_aok), which are based on Oklab's
structure, this module benefits from Oklab's superior hue linearity compared to
spaces like CIELAB (especially in blue regions, avoiding violet shifts).
2. **Leverages Oklab's Simplicity and Speed (as a base for AOkLab):**
AOkLab, built upon Oklab, is computationally more efficient than full
Color Appearance Models (CAMs) like CIECAM16, making these advanced
adjustments practical for dynamic applications.
3. **Integrates AOkLab's Surround Correction (New for an Oklab-based framework):**
The core AOkLab model (`AdaptiveOklab` class from `aoklab.js`) adjusts its
internal lightness mapping based on 'white', 'gray', or 'dark' surround
conditions. This module uses a configured AOkLab instance, meaning all
color transformations inherently account for the specified surround adaptation.
This is achieved by AOkLab using a derived adaptive exponent `p` and a
hue correction factor `x0^((1/3)-p)`.
4. **Enables Constant WCAG Contrast & CIE Luminance Compatibility (Novel Combination):**
- Standard Oklab/AOkLab Lightness (L_ok / L_aok) does not directly correlate
with CIE Luminance (Y) or provide straightforward WCAG contrast control.
- This module solves this by allowing users to specify a **target CIELAB L*** value.
This target L\* is converted to a target CIE Relative Luminance (Y_cie).
- An iterative search then finds the **AOkLab Lightness (L_aok)** that, for a
given AOkLab Hue, AOkLab Chroma, and AOkLab surround setting, produces an
sRGB color matching the `Y_target_cie`.
- This provides precise control over physical luminance for accessibility,
while retaining the perceptual benefits (hue uniformity, surround adaptation)
of the AOkLab color model for defining the color's chromatic characteristics.
**In essence, designers gain two powerful, previously incompatible control mechanisms:**
- Define color appearance (hue, colorfulness, adaptation to surround) using AOkLab.
- Simultaneously enforce precise luminance levels (for WCAG contrast) by targeting
a CIELAB L* value.
- Source:
Members
(inner, constant) DEFAULT_AOK_CHROMA_CONTROL_OPTIONS :Readonly.<Required.<AokChromaControlOptions>>
Default options for AOkLab chroma control functions.
Type:
- Readonly.<Required.<AokChromaControlOptions>>
- Source:
Methods
(static) adjustAokColorToLabL(inputAokLCHHint, targetLabL_forY, mode, userOptionsopt) → {AokChromaControlResult}
Adjusts an AOkLab color (defined by Hue and target Chroma) to match a target CIELAB L*
(by matching its corresponding CIE Luminance Y), respecting sRGB gamut.
The output AOkLab Lightness is found by iterative search.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
inputAokLCHHint |
||||
targetLabL_forY |
number | Target CIELAB L* [0, 100] for the output's luminance. | ||
mode |
'clip' | 'target' | How chroma is handled: - 'clip': `inputAokLCHHint.C` is target, clipped to max achievable at `targetLabL_forY`. - 'target': `userOptions.globalTargetAokChroma` is target, clipped to max achievable. | ||
userOptions |
Partial.<AdjustAokColorOptions> |
<optional> |
{} | Optional parameters. If `mode` is 'target', `userOptions.globalTargetAokChroma` is required. |
- Source:
Throws:
TypeError
|
Error
Returns:
Result object.
- Type
- AokChromaControlResult
Example
const blueHint = { C: 0.1, h: 265 };
const result = adjustAokColorToLabL(blueHint, 50, 'clip', {
adaptiveOklabOptions: { surround: 'white' }
});
if (!result.outOfGamut) {
console.log('White adapted L*50 Blue:', result.aokLCH, 'sRGB:', result.srgbColor);
}(static) findMaxAokChromaForLabL(targetAokHueInput, targetLabL_forY, userOptionsopt) → {number}
Finds the maximum AOkLab Chroma for a given AOkLab Hue that results in an sRGB color
matching a target CIELAB L* (and thus a target CIE Y), within the sRGB gamut.
AOkLab Lightness is internally adjusted by the search.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
targetAokHueInput |
number | Target AOkLab Hue in degrees [0, 360). | ||
targetLabL_forY |
number | Target CIELAB L* [0, 100], used to derive target CIE Y. | ||
userOptions |
Partial.<AokChromaControlOptions> |
<optional> |
{} | Optional parameters. |
- Source:
Throws:
TypeError
Returns:
Maximum achievable AOkLab Chroma (C_aok), or 0 if no in-gamut solution.
- Type
- number
Example
const maxC = findMaxAokChromaForLabL(265, 50, {
adaptiveOklabOptions: { surround: 'white' }
});
console.log(`Max C_aok for H_aok=265, L*_lab=50 (white surround): ${maxC}`);Type Definitions
AokChromaControlOptions
Type:
- object
Properties:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
adaptiveOklabOptions |
AdaptiveOklabOptions |
<optional> |
||
tolerance |
number |
<optional> |
1e-4 | |
maxIterations |
number |
<optional> |
50 | |
chromaStep |
number |
<optional> |
0.005 | |
maxChromaSearchLimit |
number |
<optional> |
0.4 |
- Source:
AokChromaControlResult
Type:
- object
Properties:
| Name | Type | Description |
|---|---|---|
aokLCH |
OklchColor | |
srgbColor |
SrgbColor | |
relativeLuminanceY |
number | |
outOfGamut |
boolean | |
iterations |
number |
- Source: