Module: gamut

Gamut validation and management functions following industry standards. DESIGN PRINCIPLES: ================== - Core conversions process out-of-range values - Validation is opt-in via these utility functions - Multiple strategies for different use cases - No automatic clamping in mathematical operations
Source:
See:
  • RANGE_STANDARDS.md for detailed conventions

Methods

(static) clamp(value, min, max) → {number}

Clamps a numeric value to a range. Helper function for custom clamping operations.
Parameters:
Name Type Description
value number Value to clamp
min number Minimum value
max number Maximum value
Source:
Returns:
Clamped value
Type
number

(static) clampSrgb(srgb) → {SrgbColor}

Simple clamping of sRGB values to [0,1] range. Fast but can shift hue for out-of-gamut colors.
Parameters:
Name Type Description
srgb SrgbColor sRGB color to clamp
Source:
Returns:
Clamped color with all components in [0,1]
Type
SrgbColor
Example
clampSrgb({r: 1.2, g: 0.5, b: -0.1}) // {r: 1, g: 0.5, b: 0}

(static) getMaxChroma(L, h, spaceopt, precisionopt) → {number}

Gets the maximum displayable chroma for a given lightness and hue. Uses binary search to find the gamut boundary.
Parameters:
Name Type Attributes Default Description
L number Lightness (0-100 for Lab, 0-1 for Oklab)
h number Hue angle in degrees [0, 360)
space string <optional>
 'oklch' Color space to use ('lch' or 'oklch')
precision number <optional>
 0.001 Search precision
Source:
Returns:
Maximum chroma that stays in sRGB gamut
Type
number

(static) getSrgbGamutInfo(srgb) → {GamutInfo}

Detailed gamut check with information about how far out of gamut.
Parameters:
Name Type Description
srgb SrgbColor sRGB color to check
Source:
Returns:
Detailed gamut information
Type
GamutInfo
Example
const info = getSrgbGamutInfo({r: 1.2, g: 0.5, b: -0.1});
// { inGamut: false, channels: [1.2, 0.5, -0.1], maxExcess: 0.2, minDeficit: 0.1 }

(static) isLabInTypicalRange(lab) → {boolean}

Checks if a CIELAB color is within typical display gamut. Note: Lab space can represent colors outside any display gamut.
Parameters:
Name Type Description
lab LabColor CIELAB color to check
Source:
Returns:
True if within typical ranges Typical ranges: - L*: [0, 100] - a*: [-128, 127] - b*: [-128, 127]
Type
boolean

(static) isOklabInTypicalRange(oklab) → {boolean}

Checks if an Oklab color is within typical display gamut.
Parameters:
Name Type Description
oklab OklabColor Oklab color to check
Source:
Returns:
True if within typical ranges Typical ranges: - L: [0, 1] - a: [-0.4, 0.4] - b: [-0.4, 0.4]
Type
boolean

(static) isSrgbInGamut(srgb, epsilonopt) → {boolean}

Checks if an sRGB color is within the standard [0,1] gamut.
Parameters:
Name Type Attributes Default Description
srgb SrgbColor sRGB color to check
epsilon number <optional>
 1e-10 Tolerance for floating point comparison
Source:
Returns:
True if all components are within [0,1]
Type
boolean
Example
isSrgbInGamut({r: 0.5, g: 0.3, b: 0.8}) // true
isSrgbInGamut({r: 1.1, g: 0.5, b: -0.1}) // false
isSrgbInGamut({r: 1.0000000001, g: 0.5, b: 0.5}, 1e-9) // true (within tolerance)

(static) isValidLabObject(obj) → {boolean}

Validates that an object has the required Lab properties. Does NOT validate ranges, only structure.
Parameters:
Name Type Description
obj any Object to validate
Source:
Returns:
True if object has numeric L, a, b properties
Type
boolean

(static) isValidSrgbObject(obj) → {boolean}

Validates that an object has the required sRGB properties. Does NOT validate ranges, only structure.
Parameters:
Name Type Description
obj any Object to validate
Source:
Returns:
True if object has numeric r, g, b properties
Type
boolean

(static) scaleToSrgbGamut(srgb) → {SrgbColor}

Scales an sRGB color uniformly until it fits within gamut. Preserves hue better than channel clamping but reduces saturation.
Parameters:
Name Type Description
srgb SrgbColor sRGB color to scale
Source:
Returns:
Scaled color within [0,1] gamut
Type
SrgbColor
Example
scaleToSrgbGamut({r: 1.2, g: 0.6, b: 0.3}) // Scales all channels by 1/1.2

Type Definitions

GamutInfo

Information about gamut check results.
Type:
  • Object
Properties:
Name Type Description
inGamut boolean Whether color is in gamut
channels Array.<number> Array of channel values
maxExcess number Maximum amount any channel exceeds bounds
minDeficit number Maximum amount any channel is below bounds
Source: