Fixes #68; better handling of hue in differenceEuclidean()

Author: danburzo

CHANGELOG.md

@@ -1,5 +1,13 @@
 ## Culori Changelog
 
+### Unreleased
+
+Stop treating the _alpha_ channel specifically in the Euclidean distance formula. Instead, assume it's always the fourth channel and assign it a default weight of 0. This means that it's now possible to factor in the alpha into the distance, if needed.
+
+There's also a change of handing `NaN` differences on a channel. In this case, the distance on that particular channel is considered to be zero. (Which kind of makes sense?)
+
+Distances on the hue (`h` channel) are now computed with the _shortest hue distance_, taking into account the cyclical nature of this channel. ([#68](https://github.com/Evercoder/culori/issues/68)).
+
 ### 0.5.4
 
 Fixed typo in CMC (l:c) color difference formula. ([#66](https://github.com/Evercoder/culori/issues/66))

README.md

@@ -87,7 +87,7 @@ The object needs to have a `mode` property that identifies the color space, and
 
 ### A note on the API
 
-TODO explain Functional style and its benefits.
+> 🕳 explain choice of functional style and its benefits.
 
 ### Basic methods
 
@@ -209,6 +209,8 @@ samples(5).map(grays);
 
 #### Interpolation functions
 
+> 🕳 expand section
+
 <a name="culoriInterpolateFunctionLinear" href="#culoriInterpolateFunctionLinear">#</a> culori.**interpolateFunctionLinear** [<>](https://github.com/evercoder/culori/blob/master/src/interpolate/interpolateFunctionLinear.js 'Source')
 
 <a name="culoriInterpolateFunctionSpline" href="#culoriInterpolateFunctionSpline">#</a> culori.**interpolateFunctionSpline** [<>](https://github.com/evercoder/culori/blob/master/src/interpolate/interpolateFunctionSpline.js 'Source')
@@ -219,6 +221,8 @@ samples(5).map(grays);
 
 #### Interpolation modes
 
+> 🕳 expand section
+
 <a name="culoriInterpolateNumber" href="#culoriInterpolateNumber">#</a> culori.**interpolateNumber** [<>](https://github.com/evercoder/culori/blob/master/src/interpolate/interpolateNumber.js 'Source')
 
 <a name="culoriInterpolateHue" href="#culoriInterpolateHue">#</a> culori.**interpolateHue** [<>](https://github.com/evercoder/culori/blob/master/src/interpolate/interpolateHue.js 'Source')
@@ -229,12 +233,25 @@ samples(5).map(grays);
 
 These methods are concerned to finding the [distance between two colors](https://en.wikipedia.org/wiki/Color_difference) based on various formulas. Each of these formulas will return a _function (colorA, colorB)_ that lets you measure the distance between two colors. Also available as a separate [d3 plugin](https://github.com/evercoder/d3-color-difference).
 
-<a name="culoriDifferenceEuclidean" href="#culoriDifferenceEuclidean">#</a> culori.**differenceEuclidean**(_mode = 'rgb'_, _weights = [1, 1, 1]_) [<>](https://github.com/evercoder/culori/blob/master/src/difference.js 'Source')
+<a name="culoriDifferenceEuclidean" href="#culoriDifferenceEuclidean">#</a> culori.**differenceEuclidean**(_mode = 'rgb'_, _weights = [1, 1, 1, 0]_) [<>](https://github.com/evercoder/culori/blob/master/src/difference.js 'Source')
 
 Returns a [Euclidean distance](https://en.wikipedia.org/wiki/Color_difference#Euclidean) function in a certain color space.
 
 You can optionally assign different weights to the channels in the color space. See, for example, the [Kotsarenko/Ramos distance](#culoriDifferenceKotsarenkoRamos).
 
+The default weights `[1, 1, 1, 0]` mean that the _alpha_, which is the fourth channel in all the color spaces Culori defines, is not taken into account. Send `[1, 1, 1, 1]` as the weights to include it in the computation.
+
+For the `h` channel in the color (in any color space that has this channel), we're using a _shortest hue distance_ to compute the hue's contribution to the distance. In spaces such as HSL or HSV, where the range of this difference is `[0, 180]` — as opposed to `[0, 1]` for the other channels — consider adjusting the weights so that the hue contributes "equally" to the distance:
+
+```js
+let hsl_distance = culori.differenceEuclidean('hsl', [
+	1 / (180 * 180),
+	1,
+	1,
+	0
+]);
+```
+
 <a name="culoriDifferenceCie76" href="#culoriDifferenceCie76">#</a> culori.**differenceCie76**() [<>](https://github.com/evercoder/culori/blob/master/src/difference.js 'Source')
 
 Computes the [CIE76][cie76] ΔE\*<sub>ab</sub> color difference between the colors _a_ and _b_. The computation is done in the Lab color space and it is analogous to [culori.differenceEuclidean('lab')](#culoriDifferenceEuclidean).
@@ -275,6 +292,8 @@ Pass _n = Infinity_ to get all colors in the array with a maximum distance of _
 
 ### RGB / LRGB (Linear RGB)
 
+> 🕳 expand this section
+
 ### HSL / HSV / HSI
 
 [HSL, HSV, and HSI](https://en.wikipedia.org/wiki/HSL_and_HSV) are a family of representations of the RGB color space, created in 1970 to provide color spaces more closely aligned to how humans perceive colors.
@@ -436,7 +455,14 @@ function contrast(colorA, colorB) {
 
 ## Extending culori
 
-TODO
+### Defining a color space
+
+**Note:** The order of the items in the `channels` array matters. To keep things simple, we're making the following conventions:
+
+-   the fourth item in the array should be `alpha`
+-   any cyclical values (e.g. hue) should be identified by `h`, in the range `[0, 360)`
+
+These constrains make sure `differenceEuclidean()` works as expected.
 
 ## See also
 

src/difference.js

@@ -1,22 +1,34 @@
 import { getModeDefinition } from './modes';
 import converter from './converter';
+import normalizeHue from './util/normalizeHue';
+
+const hue_difference = (a, b) => {
+	let na = normalizeHue(a);
+	let nb = normalizeHue(b);
+	if (Math.abs(nb - na) > 180) {
+		// todo should this be normalized once again?
+		return na - (nb - 360 * Math.sign(nb - na));
+	}
+	return na - nb;
+};
 
-const differenceEuclidean = (mode = 'rgb', weights = [1, 1, 1]) => {
+const differenceEuclidean = (mode = 'rgb', weights = [1, 1, 1, 0]) => {
 	let channels = getModeDefinition(mode).channels;
 	let conv = converter(mode);
 	return (std, smp) => {
 		let ConvStd = conv(std);
 		let ConvSmp = conv(smp);
 		return Math.sqrt(
-			channels.reduce(
-				(delta, k, idx) =>
-					// ignore alpha channel in computing the euclidean distance
-					delta +
-					(k === 'alpha'
-						? 0
-						: weights[idx] * Math.pow(ConvStd[k] - ConvSmp[k], 2)),
-				0
-			)
+			channels.reduce((sum, k, idx) => {
+				let delta =
+					k === 'h'
+						? hue_difference(ConvStd[k], ConvSmp[k])
+						: ConvStd[k] - ConvSmp[k];
+				return (
+					sum +
+					(weights[idx] || 0) * Math.pow(isNaN(delta) ? 0 : delta, 2)
+				);
+			}, 0)
 		);
 	};
 };

test/difference.js

@@ -9,7 +9,8 @@ let {
 	differenceKotsarenkoRamos,
 	rgb,
 	lab,
-	round
+	round,
+	hsl
 } = culori;
 
 tape('euclidean distance in RGB', function(test) {
@@ -28,6 +29,27 @@ tape('euclidean distance in RGB', function(test) {
 	test.end();
 });
 
+tape('euclidean distance in HSL', function(test) {
+	let delta = differenceEuclidean('hsl');
+
+	test.equal(
+		delta(hsl({ h: 0, s: 1, l: 1 }), hsl({ h: 180, s: 1, l: 1 })),
+		180
+	);
+
+	test.equal(
+		delta(hsl({ h: 0, s: 1, l: 1 }), hsl({ h: 360, s: 1, l: 1 })),
+		0
+	);
+
+	test.equal(
+		delta(hsl({ h: 60, s: 1, l: 1 }), hsl({ h: -540, s: 1, l: 1 })),
+		120
+	);
+
+	test.end();
+});
+
 tape('cie76 difference', function(test) {
 	test.equal(
 		differenceCie76()(