Merge remote-tracking branch 'origin/master'

danburzo · danburzo · commit 71c87cd30b68 · 2019-05-05T19:24:29.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 ## Culori Changelog
 
+### 0.8.2
+
+Adds `culori.random()` for generating random colors.
+
 ### 0.8.0
 
 Adds `culori.blend()` ([#59](https://github.com/Evercoder/culori/issues/59)).
diff --git a/README.md b/README.md
@@ -86,6 +86,7 @@ To import culori as a `<script>` tag to use in a web page, you can load it from
 -   [Interpolation](#interpolation)
 -   [Difference](#difference)
 -   [Blending](#blending)
+-   [Random colors](#random-colors)
 -   [Extending culori](#extending-culori)
 
 ### Color representation
@@ -452,6 +453,32 @@ culori.blend(['red', 'green'], function average(b, s) {
 });
 ```
 
+### Random colors
+
+<a name="culoriRandom" href="#culoriRandom">#</a> culori.**random**(_mode = 'rgb'_, _constraints = {}_) [<>](https://github.com/evercoder/culori/blob/master/src/random.js 'Source')
+
+Obtain a random color from a particular color space, with optional constraints. The resulting color will be in the color space from where it has been picked.
+
+Basic usage:
+
+```js
+culori.random();
+// => { mode: 'rgb', r: 0.75, g: 0.12, b: 0.99 }
+```
+
+You can specify constraints for each individual channel in the color space, as either a _fixed number_ or an _interval_:
+
+```js
+culori.random('hsv', {
+	h: 120 // number,
+	s: [0.25, 0.75] // interval
+});
+```
+
+The resulting color will not include an _alpha_ value, unless you include it in the list of constraints.
+
+The value for any channel in the color space for which there are no constraints will be picked from the entire range of that channel. However, some color spaces, such as LAB or LCH, don't have explicit ranges for certain channels; for these, some approximate ranges [have been pre-computed](https://github.com/evercoder/culori/blob/master/tools/ranges.js) as the limits of the displayable sRGB gamut. Even with these ranges in place, a combination of channel values may not be displayable. You can use [`culori.displayable()`](#culoriDisplayable) to check this, and [`culori.clamp()`](#culoriClamp) to obtain a displayable version.
+
 ### Extending culori
 
 <a name="culoriDefineMode" href="#culoriDefineMode">#</a> culori.**defineMode**(_definition_) [<>](https://github.com/evercoder/culori/blob/master/src/modes.js 'Source')
@@ -468,6 +495,9 @@ Defines a new color space through a _definition_ object. By way of example, here
 		rgb: convertRgbToHsl
 	},
 	channels: ['h', 's', 'l', 'alpha'],
+	ranges: {
+		h: [0, 360]
+	},
 	parsers: [parseHsl],
 	interpolate: {
 		h: interpolateLinear(interpolateHue),
@@ -484,6 +514,7 @@ The properties a definition needs are the following:
 -   `output`: a set of functions to convert from the color space we're defining to other color spaces. At least `rgb` needs to be included; in case a specific conversion pair between two color spaces is missing, RGB is used as the "buffer" for the conversion.
 -   `input`: opposite of `output`; a set of function to convert from various color spaces to the color space we're defining. At least `rgb` needs to be included.
 -   `channels`: a list of channels for the color space.
+-   `ranges`: the ranges for values in specific channels; if left unspecified, defaults to `[0, 1]`.
 -   `parsers`: any parsers for the color space that can transform strings into colors
 -   `interpolate`: the default interpolations for the color space.
 
@@ -564,19 +595,19 @@ The figure below shows a slice of the HSI color space for a particular hue:
 
 #### `lab`
 
-| Channel | Range                  | Description           |
-| ------- | ---------------------- | --------------------- |
-| `l`     | `[0 — 100]`            | Lightness             |
-| `a`     | `[-79.2872, 93.55]`    | Green–red component   |
-| `b`     | `[-112.0294, 93.3884]` | Blue–yellow component |
+| Channel | Range                | Description           |
+| ------- | -------------------- | --------------------- |
+| `l`     | `[0, 100]`           | Lightness             |
+| `a`     | `[-79.167, 93.408]`  | Green–red component   |
+| `b`     | `[-111.859, 93.246]` | Blue–yellow component |
 
 #### `lch`
 
-| Channel | Range           | Description |
-| ------- | --------------- | ----------- |
-| `l`     | `[0 - 100]`     | Lightness   |
-| `c`     | `[0 - 131.207]` | Chroma      |
-| `h`     | `[0 - 360]`     | Hue         |
+| Channel | Range          | Description |
+| ------- | -------------- | ----------- |
+| `l`     | `[0, 100]`     | Lightness   |
+| `c`     | `[0, 131.008]` | Chroma      |
+| `h`     | `[0, 360)`     | Hue         |
 
 > 💡 The range for the `a` and `b` channels in Lab, and the `c` channel in LCh, depend on the specific implementation. I've obtained the ranges from the tables above by converting all sRGB colors defined by `r, g, b ∈ ℕ ⋂ [0, 255]` into Lab and LCh respectively.
 
@@ -586,19 +617,19 @@ The [DIN99][din99o] color space "squishes" the CIE Lab color space to obtain an
 
 #### `dlab`
 
-| Channel | Range | Description |
-| ------- | ----- | ----------- |
-| `l`     | ?     | Lightness   |
-| `a`     | ?     |
-| `b`     | ?     |
+| Channel | Range               | Description |
+| ------- | ------------------- | ----------- |
+| `l`     | `[0, 100]`          | Lightness   |
+| `a`     | `[-39.229, 45.166]` |
+| `b`     | `[-43.002, 44.424]` |
 
 #### `dlch`
 
-| Channel | Range | Description |
-| ------- | ----- | ----------- |
-| `l`     | ?     | Lightness   |
-| `c`     | ?     | Chroma      |
-| `h`     | ?     | Hue         |
+| Channel | Range         | Description |
+| ------- | ------------- | ----------- |
+| `l`     | `[0, 100]`    | Lightness   |
+| `c`     | `[0, 50.944]` | Chroma      |
+| `h`     | `[0, 360)`    | Hue         |
 
 **References:**
 
@@ -608,11 +639,11 @@ The [DIN99][din99o] color space "squishes" the CIE Lab color space to obtain an
 
 [YIQ](yiq) is the color space used by the NTSC color TV system. It contains the following channels:
 
-| Channel | Range               | Description                    |
-| ------- | ------------------- | ------------------------------ |
-| Y       | `[0,1]`             | Luma                           |
-| I       | `[-0.5957, 0.5957]` | In-phase (orange-blue axis)    |
-| Q       | `[-0.5226, 0.5226]` | Quadrature (green-purple axis) |
+| Channel | Range             | Description                    |
+| ------- | ----------------- | ------------------------------ |
+| Y       | `[0, 1]`          | Luma                           |
+| I       | `[-0.593, 0.593]` | In-phase (orange-blue axis)    |
+| Q       | `[-0.520, 0.520]` | Quadrature (green-purple axis) |
 
 ### Cubehelix
 
diff --git a/src/cubehelix/definition.js b/src/cubehelix/definition.js
@@ -40,6 +40,10 @@ import convertCubehelixToRgb from './convertCubehelixToRgb';
 export default {
 	mode: 'cubehelix',
 	channels: ['h', 's', 'l', 'alpha'],
+	ranges: {
+		h: [0, 360],
+		s: [0, 4.6143]
+	},
 	input: {
 		rgb: convertRgbToCubehelix
 	},
diff --git a/src/dlab/definition.js b/src/dlab/definition.js
@@ -16,6 +16,11 @@ export default {
 		rgb: convertRgbToDlab
 	},
 	channels: ['l', 'a', 'b', 'alpha'],
+	ranges: {
+		l: [0, 100],
+		a: [-39.229, 45.166],
+		b: [-43.002, 44.424]
+	},
 	interpolate: {
 		l: interpolateLinear(),
 		a: interpolateLinear(),
diff --git a/src/dlch/definition.js b/src/dlch/definition.js
@@ -23,6 +23,11 @@ export default {
 		rgb: convertRgbToDlch
 	},
 	channels: ['l', 'c', 'h', 'alpha'],
+	ranges: {
+		l: [0, 100],
+		c: [0, 50.944],
+		h: [0, 360]
+	},
 	interpolate: {
 		l: interpolateLinear(),
 		c: interpolateLinear(),
diff --git a/src/hsi/definition.js b/src/hsi/definition.js
@@ -13,6 +13,9 @@ export default {
 		rgb: convertRgbToHsi
 	},
 	channels: ['h', 's', 'i', 'alpha'],
+	ranges: {
+		h: [0, 360]
+	},
 	interpolate: {
 		h: interpolateLinear(interpolateHue),
 		s: interpolateLinear(),
diff --git a/src/hsl/definition.js b/src/hsl/definition.js
@@ -14,6 +14,9 @@ export default {
 		rgb: convertRgbToHsl
 	},
 	channels: ['h', 's', 'l', 'alpha'],
+	ranges: {
+		h: [0, 360]
+	},
 	parsers: [parseHsl],
 	interpolate: {
 		h: interpolateLinear(interpolateHue),
diff --git a/src/hsv/definition.js b/src/hsv/definition.js
@@ -13,6 +13,9 @@ export default {
 		rgb: convertRgbToHsv
 	},
 	channels: ['h', 's', 'v', 'alpha'],
+	ranges: {
+		h: [0, 360]
+	},
 	interpolate: {
 		h: interpolateLinear(interpolateHue),
 		s: interpolateLinear(),
diff --git a/src/hwb/definition.js b/src/hwb/definition.js
@@ -14,6 +14,9 @@ export default {
 		rgb: convertRgbToHwb
 	},
 	channels: ['h', 'w', 'b', 'alpha'],
+	ranges: {
+		h: [0, 360]
+	},
 	parsers: [parseHwb],
 	interpolate: {
 		h: interpolateLinear(interpolateHue),
diff --git a/src/index.js b/src/index.js
@@ -90,3 +90,4 @@ export {
 } from './difference';
 export { default as colorsNamed } from './colors/named';
 export { default as blend } from './blend';
+export { default as random } from './random';
diff --git a/src/lab/definition.js b/src/lab/definition.js
@@ -13,6 +13,11 @@ export default {
 		rgb: convertRgbToLab
 	},
 	channels: ['l', 'a', 'b', 'alpha'],
+	ranges: {
+		l: [0, 100],
+		a: [-79.167, 93.408],
+		b: [-111.859, 93.246]
+	},
 	parsers: [parseLab],
 	interpolate: {
 		l: interpolateLinear(),
diff --git a/src/lch/definition.js b/src/lch/definition.js
@@ -18,6 +18,11 @@ export default {
 		lch: convertLabToLch
 	},
 	channels: ['l', 'c', 'h', 'alpha'],
+	ranges: {
+		l: [0, 100],
+		c: [0, 131.008],
+		h: [0, 360]
+	},
 	parsers: [parseLch],
 	interpolate: {
 		h: interpolateLinear(interpolateHue),
diff --git a/src/modes.js b/src/modes.js
@@ -13,6 +13,19 @@ const defineMode = definition => {
 		}
 		converters[k][definition.mode] = definition.input[k];
 	});
+
+	// Color space channel ranges
+	if (!definition.ranges) {
+		definition.ranges = {};
+	}
+
+	definition.channels.forEach(channel => {
+		// undefined channel ranges default to the [0, 1] interval
+		if (definition.ranges[channel] === undefined) {
+			definition.ranges[channel] = [0, 1];
+		}
+	});
+
 	modes[definition.mode] = definition;
 	(definition.parsers || []).forEach(parser => parsers.push(parser));
 };
diff --git a/src/random.js b/src/random.js
@@ -0,0 +1,34 @@
+import { getModeDefinition } from './modes';
+
+/*
+	Generate a random number between `min` and `max`
+ */
+const rand = ([min, max]) => min + Math.random() * (max - min);
+
+/*
+	Convert a constraints object to intervals.
+ */
+const to_intervals = constraints =>
+	Object.keys(constraints).reduce((o, k) => {
+		let v = constraints[k];
+		o[k] = Array.isArray(v) ? v : [v, v];
+		return o;
+	}, {});
+
+/*
+	Generate a random color.
+ */
+export default (mode = 'rgb', constraints = {}) => {
+	let def = getModeDefinition(mode);
+	let limits = to_intervals(constraints);
+	return def.channels.reduce(
+		(res, ch) => {
+			// ignore alpha if not present in constraints
+			if (limits.alpha || ch !== 'alpha') {
+				res[ch] = rand(limits[ch] || def.ranges[ch]);
+			}
+			return res;
+		},
+		{ mode }
+	);
+};
diff --git a/src/yiq/definition.js b/src/yiq/definition.js
@@ -32,6 +32,10 @@ export default {
 		rgb: convertRgbToYiq
 	},
 	channels: ['y', 'i', 'q', 'alpha'],
+	ranges: {
+		i: [-0.593, 0.593],
+		q: [-0.52, 0.52]
+	},
 	interpolate: {
 		y: interpolateLinear(),
 		i: interpolateLinear(),
diff --git a/test/random.test.js b/test/random.test.js
@@ -0,0 +1,26 @@
+let tape = require('tape');
+let culori = require('..');
+
+let { random } = culori;
+
+tape('random (rgb)', test => {
+	let c1 = random();
+	let c2 = random('rgb', { r: 0.1 });
+	let c3 = random('rgb', { r: [0.4, 0.6] });
+
+	test.equal(c1.mode, 'rgb');
+	test.ok(c1.r >= 0);
+	test.ok(c1.r <= 1);
+
+	test.equal(c2.r, 0.1);
+	test.ok(c3.r >= 0.4);
+	test.ok(c3.r <= 0.6);
+
+	test.end();
+});
+
+tape('random (lch)', test => {
+	let c = random('lch');
+	test.equal(c.mode, 'lch');
+	test.end();
+});
diff --git a/tools/ranges.js b/tools/ranges.js
@@ -0,0 +1,34 @@
+let culori = require('..');
+
+/*
+	Find the channel value ranges (minimum & maximum)
+	for a particular color space, by converting lots of
+	RGB colors to that space.
+ */
+let ranges = (mode, step = 0.01) => {
+	let conv = culori.converter(mode);
+	let chs = culori.getModeDefinition(mode).channels;
+	let res = chs.reduce(
+		(acc, ch) => ((acc[ch] = [Infinity, -Infinity]), acc),
+		{}
+	);
+	let r, g, b, c;
+	for (r = 0; r <= 1; r += step) {
+		for (g = 0; g <= 1; g += step) {
+			for (b = 0; b <= 1; b += step) {
+				c = conv({ mode: 'rgb', r, g, b });
+				chs.forEach(ch => {
+					if (c[ch] < res[ch][0]) {
+						res[ch][0] = c[ch];
+					}
+					if (c[ch] > res[ch][1]) {
+						res[ch][1] = c[ch];
+					}
+				});
+			}
+		}
+	}
+	return res;
+};
+
+console.log(ranges('yiq', 0.002));
