Implements average() function, fixes #78

Author: danburzo

docs/api.md

@@ -709,6 +709,22 @@ culori.blend(['red', 'green'], function average(b, s) {
 
 The non-separable blend modes — `color`, `hue`, `saturation`, and `lightness` — are not available. The effect which they mean to produce is better obtained with simple formulas on a cylindrical color space (e.g. HSL).
 
+## Average color
+
+<a name="average" href="#average">#</a> culori.**average**(_colors_, _mode = 'rgb'_, _overrides_) &middot; [Source](https://github.com/evercoder/culori/blob/master/src/average.js)
+
+Returns the average color of the _colors_ array, in the color space specified by the _mode_ argument. The color is obtained by the arithmetic average of values on each individual channel.
+
+Colors with undefined values on a channel don't participate in the average for that channel.
+
+<a name="averageNumber" href="#averageNumber">#</a> culori.**averageNumber**(_values_) &middot; [Source](https://github.com/evercoder/culori/blob/master/src/average.js)
+
+The arithmetic mean of values in the _values_ array.
+
+<a name="averageAngle" href="#averageAngle">#</a> culori.**averageAngle**(_values_) &middot; [Source](https://github.com/evercoder/culori/blob/master/src/average.js)
+
+The function used by default to average hue values in all built-in color spaces, using the formula for [the mean of circular quantities](https://en.wikipedia.org/wiki/Mean_of_circular_quantities).
+
 ## Random colors
 
 <a name="random" href="#random">#</a> culori.**random**(_mode = 'rgb'_, _constraints = {}_) &middot; [Source](https://github.com/evercoder/culori/blob/master/src/random.js)

src/average.js

@@ -0,0 +1,52 @@
+import converter from './converter';
+import { getModeDefinition } from './modes';
+
+const averageAngle = val => {
+	// See: https://en.wikipedia.org/wiki/Mean_of_circular_quantities
+	let sum = val.reduce(
+		(sum, val) => {
+			if (val !== undefined) {
+				let rad = (val * Math.PI) / 180;
+				sum.sin += Math.sin(rad);
+				sum.cos += Math.cos(rad);
+			}
+			return sum;
+		},
+		{ sin: 0, cos: 0 }
+	);
+	return (Math.atan2(sum.sin, sum.cos) * 180) / Math.PI;
+};
+
+const averageNumber = val => {
+	let a = val.filter(v => v !== undefined);
+	return a.length ? a.reduce((sum, v) => sum + v, 0) / a.length : undefined;
+};
+
+const isfn = o => typeof o === 'function';
+
+function average(colors, mode = 'rgb', overrides) {
+	let def = getModeDefinition(mode);
+	let cc = colors.map(converter(mode));
+	return def.channels.reduce(
+		(res, ch) => {
+			let arr = cc.map(c => c[ch]).filter(val => val !== undefined);
+			if (arr.length) {
+				let fn;
+				if (isfn(overrides)) {
+					fn = overrides;
+				} else if (overrides && isfn(overrides[ch])) {
+					fn = overrides[ch];
+				} else if (def.average && isfn(def.average[ch])) {
+					fn = def.average[ch];
+				} else {
+					fn = averageNumber;
+				}
+				res[ch] = fn(arr, ch);
+			}
+			return res;
+		},
+		{ mode }
+	);
+}
+
+export { average, averageAngle, averageNumber };

src/cubehelix/definition.js

@@ -37,6 +37,7 @@ import { interpolatorLinear } from '../interpolate/linear';
 import convertRgbToCubehelix from './convertRgbToCubehelix';
 import convertCubehelixToRgb from './convertCubehelixToRgb';
 import { differenceHueSaturation } from '../difference';
+import { averageAngle } from '../average';
 
 export default {
 	mode: 'cubehelix',
@@ -65,5 +66,8 @@ export default {
 	},
 	difference: {
 		h: differenceHueSaturation
+	},
+	average: {
+		h: averageAngle
 	}
 };

src/dlch/definition.js

@@ -10,6 +10,7 @@ import { fixupHueShorter } from '../fixup/hue';
 import { fixupAlpha } from '../fixup/alpha';
 import { interpolatorLinear } from '../interpolate/linear';
 import { differenceHueChroma } from '../difference';
+import { averageAngle } from '../average';
 
 export default {
 	mode: 'dlch',
@@ -43,5 +44,8 @@ export default {
 	},
 	difference: {
 		h: differenceHueChroma
+	},
+	average: {
+		h: averageAngle
 	}
 };

src/hsi/definition.js

@@ -4,6 +4,7 @@ import { fixupHueShorter } from '../fixup/hue';
 import { fixupAlpha } from '../fixup/alpha';
 import { interpolatorLinear } from '../interpolate/linear';
 import { differenceHueSaturation } from '../difference';
+import { averageAngle } from '../average';
 
 export default {
 	mode: 'hsi',
@@ -25,5 +26,8 @@ export default {
 	},
 	difference: {
 		h: differenceHueSaturation
+	},
+	average: {
+		h: averageAngle
 	}
 };

src/hsl/definition.js

@@ -5,6 +5,7 @@ import { fixupHueShorter } from '../fixup/hue';
 import { fixupAlpha } from '../fixup/alpha';
 import { interpolatorLinear } from '../interpolate/linear';
 import { differenceHueSaturation } from '../difference';
+import { averageAngle } from '../average';
 
 export default {
 	mode: 'hsl',
@@ -27,5 +28,8 @@ export default {
 	},
 	difference: {
 		h: differenceHueSaturation
+	},
+	average: {
+		h: averageAngle
 	}
 };

src/hsv/definition.js

@@ -4,6 +4,7 @@ import { fixupHueShorter } from '../fixup/hue';
 import { fixupAlpha } from '../fixup/alpha';
 import { interpolatorLinear } from '../interpolate/linear';
 import { differenceHueSaturation } from '../difference';
+import { averageAngle } from '../average';
 
 export default {
 	mode: 'hsv',
@@ -25,5 +26,8 @@ export default {
 	},
 	difference: {
 		h: differenceHueSaturation
+	},
+	average: {
+		h: averageAngle
 	}
 };

src/hwb/definition.js

@@ -5,6 +5,7 @@ import { fixupHueShorter } from '../fixup/hue';
 import { fixupAlpha } from '../fixup/alpha';
 import { interpolatorLinear } from '../interpolate/linear';
 import { differenceHueNaive } from '../difference';
+import { averageAngle } from '../average';
 
 export default {
 	mode: 'hwb',
@@ -27,5 +28,8 @@ export default {
 	},
 	difference: {
 		h: differenceHueNaive
+	},
+	average: {
+		h: averageAngle
 	}
 };

src/index.js

@@ -180,3 +180,5 @@ export {
 	filterGrayscale,
 	filterHueRotate
 } from './filter';
+
+export { average, averageAngle, averageNumber } from './average';

src/lch/definition.js

@@ -7,6 +7,7 @@ import { fixupHueShorter } from '../fixup/hue';
 import { fixupAlpha } from '../fixup/alpha';
 import { interpolatorLinear } from '../interpolate/linear';
 import { differenceHueChroma } from '../difference';
+import { averageAngle } from '../average';
 
 export default {
 	mode: 'lch',
@@ -33,5 +34,8 @@ export default {
 	},
 	difference: {
 		h: differenceHueChroma
+	},
+	average: {
+		h: averageAngle
 	}
 };