Suggestion to specify target gamut for clampChroma()

[dokozero]

Hello @danburzo,

I use Culori for the OkColor Figma plugin and it's quite useful, however, regarding gamut clipping by the chroma only, when I saw clampGamut() for the first time, I thought that it has an option to specify the target gamut to clamp.

As it was not the case, I ended up making a local modified version that uses inGamut() instead of displayable(), as I read from doc that it was equivalent to inGamut('rgb'). However, I had to duplicate culori's main js file into my project.

With this update, I'm able to easily clamp to sRGB or P3 gamut. I don't use toGamut() as I need to keep the same hue and lightness.

I saw previous issue regarding this topic and my suggestion would be to add a new optional target gamut param to clampChroma(), default to 'rgb' for retro-compatibility:

function clampChroma(color, mode = 'lch', targetGamut = 'rgb') {
  const isInTargetGamut = inGamut(targetGamut)

  color = prepare_default(color)
  if (color === void 0 || isInTargetGamut(color)) return color
  let conv = converter_default(color.mode)
  color = converter_default(mode)(color)
  let clamped = { ...color, c: 0 }
  if (!isInTargetGamut(clamped)) {
    return conv(fixup_rgb(rgb(clamped)))
  }
  let start = 0
  let end = color.c
  let range = getMode(mode).ranges.c
  let resolution = (range[1] - range[0]) / Math.pow(2, 13)
  let _last_good_c
  while (end - start > resolution) {
    clamped.c = start + (end - start) * 0.5
    if (isInTargetGamut(clamped)) {
      _last_good_c = clamped.c
      start = clamped.c
    } else {
      end = clamped.c
    }
  }
  return conv(isInTargetGamut(clamped) ? clamped : { ...clamped, c: _last_good_c })
}

For comparison, current code:

function clampChroma(color, mode = 'lch') {
  color = prepare_default(color)
  if (color === void 0 || displayable(color)) return color
  let conv = converter_default(color.mode)
  color = converter_default(mode)(color)
  let clamped = { ...color, c: 0 }
  if (!displayable(clamped)) {
    return conv(fixup_rgb(rgb(clamped)))
  }
  let start = 0
  let end = color.c
  let range = getMode(mode).ranges.c
  let resolution = (range[1] - range[0]) / Math.pow(2, 13)
  let _last_good_c
  while (end - start > resolution) {
    clamped.c = start + (end - start) * 0.5
    if (displayable(clamped)) {
      _last_good_c = clamped.c
      start = clamped.c
    } else {
      end = clamped.c
    }
  }
  return conv(displayable(clamped) ? clamped : { ...clamped, c: _last_good_c })
}

I saw your answer from #211, with:

oklch(toGamut('p3', 'oklch', differenceEuclidean('oklch'), 0)("oklch(70% 0.4 200)")) 

But personally, I think the new param on clampChroma() would be nice.

Thanks for your time.

[danburzo]

Hi @dokozero, thank you for your suggestion.

Culori has a bit too many gamut mapping functions because in the beginning they were sRGB oriented. We had displayable to check that a color is in gamut, and clampRgb and clampChroma to implement gamut mapping strategies: clipping and chroma reduction, respectively.

This set of sRGB-based functions got upgraded to more generic methods:

• displayable -> inGamut()
• clampRgb -> clampGamut()
• clampChroma -> toGamut()

The move from first-order function to higher-order function, that is from a function that you can invoke for a color to a function that returns a function, was intentional. This allows us to do the prep work for the destination gamut once, upfront, which makes the actual gamut mapping functions closer in performance to the originals.

The difference between clampChroma and toGamut is that the latter includes the tweaks from the CSS Color Level 4 algorithm that can choose a color of slightly different lightness or hue. This aspect of the algorithm can be disabled by passing JND = 0, which due to Culori’s usage of positional parameters, means you need to declare the defaults to all parameters up to jnd, resulting in:

const clampToP3 = toGamut('p3', 'oklch', differenceEuclidean('oklch'), 0);

It’s improbable that we will add new features to the old functions, but I think we can make the toGamut version shorter with:

const clampToP3 = toGamut('p3', 'oklch', null);

Later edit: Updated to replace clampGamut with the correct toGamut.

[danburzo]

Fixed in [email protected]

[dokozero]

Thanks for your quick reply and even a new release, wow 🙏

Indeed, I better understand now the timeline history and role of these functions. I will then see to use toGamut() with the shorter version you just released, as I get from your message that it is more future-proof.

Thanks again for your work on the lib.

[danburzo]

After writing the short version of toGamut() for the release I figured we might as well have this for clampChroma(), so feel free to use whichever suits you best.