Add rgb gamut parameter to clampChroma(), shorter jnd bypass for toGamut(), fixes #212, #213

Author: danburzo

docs/api.md

@@ -359,7 +359,7 @@ formatCss(toRgb(crimson));
 
 <span aria-label='Source:'>☞</span> [src/clamp.js]({{codebase}}/src/clamp.js)
 
-<a id="clampChroma" href="#clampChroma">#</a> **clampChroma**(_color_ or _string_, _mode = 'lch'_) → _color_
+<a id="clampChroma" href="#clampChroma">#</a> **clampChroma**(_color_ or _string_, _mode = 'lch'_, _rgbGamut = 'rgb'_) → _color_
 
 <span aria-label='Source:'>☞</span> [src/clamp.js]({{codebase}}/src/clamp.js)
 
@@ -374,6 +374,8 @@ clampChroma('lab(50% 100 100)');
 
 By default, the color is converted to `lch` to perform the clamping, but any color space that contains a Chroma dimension can be used by sending an explicit `mode` argument.
 
+Likewise, the destination RGB gamut can be overriden with the corresponding parameter.
+
 ```js
 import { clampChroma } from 'culori';
 
@@ -414,10 +416,17 @@ toP3(color);
 // ⇒ { mode: "p3", r: 0.999…, g: 0.696…, b: 0.508… }
 ```
 
-To address the shortcomings of `clampChroma`, which can sometimes produce colors more desaturated than necessary, the test used in the binary search is replaced with "is color is roughly in gamut", by comparing the candidate to the clipped version (obtained with `clampGamut`). The test passes if the colors are not to dissimilar, judged by the `delta` color difference function and an associated `jnd` just-noticeable difference value.
+To address the shortcomings of `clampChroma`, which can sometimes produce colors more desaturated than necessary, the test used in the binary search is replaced with “is color is roughly in gamut”, by comparing the candidate to the clipped version (obtained with `clampGamut`). The test passes if the colors are not to dissimilar, judged by the `delta` color difference function and an associated `jnd` just-noticeable difference value.
 
 The default arguments for this function correspond to [the gamut mapping algorithm](https://drafts.csswg.org/css-color/#css-gamut-mapping) defined in the CSS Color Module Level 4 spec, but the algorithm itself is slightly different.
 
+The “roughly in gamut” aspect of the algorithm can be disabled by passing `null` for the `delta` color difference function:
+
+```js
+import { toGamut } from 'culori';
+const clampToP3 = toGamut('p3', 'oklch', null);
+```
+
 ## Interpolation
 
 In any color space, colors occupy positions given by their values for each channel. Interpolating colors means tracing a line through the coordinates of these colors, and figuring out what colors reside on the line at various positions.

src/clamp.js

@@ -17,6 +17,8 @@ const fixup_rgb = c => {
 	return res;
 };
 
+const to_displayable_srgb = c => fixup_rgb(rgb(c));
+
 const inrange_rgb = c => {
 	return (
 		c !== undefined &&
@@ -66,7 +68,7 @@ export function clampRgb(color) {
 	// keep track of color's original mode
 	let conv = converter(color.mode);
 
-	return conv(fixup_rgb(rgb(color)));
+	return conv(to_displayable_srgb(color));
 }
 
 /*
@@ -106,21 +108,25 @@ export function clampGamut(mode = 'rgb') {
 }
 
 /*
-	Obtain a color that's in the sRGB gamut
-	by first converting it to `mode` and then
-	finding the the greatest chroma value
-	that fits the gamut.
+	Obtain a color that’s in a RGB gamut (by default sRGB)
+	by first converting it to `mode` and then finding 
+	the greatest chroma value that fits the gamut.
 
 	By default, the CIELCh color space is used,
 	but any color that has a chroma component will do.
 
 	The result is returned in the color's original color space.
  */
-export function clampChroma(color, mode = 'lch') {
+export function clampChroma(color, mode = 'lch', rgbGamut = 'rgb') {
 	color = prepare(color);
 
+	let inDestinationGamut =
+		rgbGamut === 'rgb' ? displayable : inGamut(rgbGamut);
+	let clipToGamut =
+		rgbGamut === 'rgb' ? to_displayable_srgb : clampGamut(rgbGamut);
+
 	// if the color is undefined or displayable, return it directly
-	if (color === undefined || displayable(color)) return color;
+	if (color === undefined || inDestinationGamut(color)) return color;
 
 	// keep track of color's original mode
 	let conv = converter(color.mode);
@@ -133,8 +139,8 @@ export function clampChroma(color, mode = 'lch') {
 
 	// if not even chroma = 0 is displayable
 	// fall back to RGB clamping
-	if (!displayable(clamped)) {
-		return conv(fixup_rgb(rgb(clamped)));
+	if (!inDestinationGamut(clamped)) {
+		return conv(clipToGamut(clamped));
 	}
 
 	// By this time we know chroma = 0 is displayable and our current chroma is not.
@@ -147,7 +153,7 @@ export function clampChroma(color, mode = 'lch') {
 
 	while (end - start > resolution) {
 		clamped.c = start + (end - start) * 0.5;
-		if (displayable(clamped)) {
+		if (inDestinationGamut(clamped)) {
 			_last_good_c = clamped.c;
 			start = clamped.c;
 		} else {
@@ -156,7 +162,7 @@ export function clampChroma(color, mode = 'lch') {
 	}
 
 	return conv(
-		displayable(clamped) ? clamped : { ...clamped, c: _last_good_c }
+		inDestinationGamut(clamped) ? clamped : { ...clamped, c: _last_good_c }
 	);
 }
 
@@ -173,13 +179,16 @@ export function clampChroma(color, mode = 'lch') {
 	the test used in the binary search is replaced with
 	"is color is roughly in gamut", by comparing the candidate 
 	to the clipped version (obtained with `clampGamut`).
-	The test passes if the colors are not to dissimilar, 
+	The test passes if the colors are not too dissimilar, 
 	judged by the `delta` color difference function 
 	and an associated `jnd` just-noticeable difference value.
 
 	The default arguments for this function correspond to the
 	gamut mapping algorithm defined in CSS Color Level 4:
 	https://drafts.csswg.org/css-color/#css-gamut-mapping
+
+	To disable the “roughly in gamut” part, pass either
+	`null` for the `delta` parameter, or zero for `jnd`.
  */
 export function toGamut(
 	dest = 'rgb',
@@ -234,7 +243,7 @@ export function toGamut(
 			clipped = clipToGamut(candidate);
 			if (
 				inDestinationGamut(candidate) ||
-				(jnd > 0 && delta(candidate, clipped) <= jnd)
+				(delta && jnd > 0 && delta(candidate, clipped) <= jnd)
 			) {
 				start = candidate.c;
 			} else {

test/clamp.test.js

@@ -5,7 +5,8 @@ import {
 	inGamut,
 	clampGamut,
 	formatCss,
-	toGamut
+	toGamut,
+	lch
 } from '../src/index.js';
 
 tape('RGB', function (test) {
@@ -67,6 +68,12 @@ tape('Issue #129', function (test) {
 		clampChroma({ mode: 'oklch', l: 0.5, c: 0.16, h: 180 }, 'oklch'),
 		{ mode: 'oklch', l: 0.5, c: 0.090703125, h: 180 }
 	);
+
+	test.equal(
+		formatCss(clampChroma('lch(80% 150 60)', 'lch', 'p3')),
+		'lch(80 60.040283203125 60)',
+		'with p3 gamut'
+	);
 	test.end();
 });
 
@@ -157,5 +164,15 @@ tape('toGamut()', t => {
 		'color(display-p3 0.9999999999999994 0.6969234154991887 0.5084794582132421)',
 		'api docs example'
 	);
+
+	const likeClampChroma = toGamut('rgb', 'lch', null);
+
+	t.deepEqual(lch(likeClampChroma('lch(50% 120 5)')), {
+		mode: 'lch',
+		l: 50.00519612994975,
+		c: 77.47625128342412,
+		h: 5.006331789592595
+	});
+
 	t.end();
 });