Re: #207, add blerp() and trilerp() functions for bilinear and trilinear interpolation

Author: danburzo

docs/api.md

@@ -13,6 +13,7 @@ codebase: 'https://github.com/evercoder/culori/blob/main'
 <li><a href='#averageAngle'>averageAngle</a></li>
 <li><a href='#averageNumber'>averageNumber</a></li>
 <li><a href='#blend'>blend</a></li>
+<li><a href='#blerp'>blerp</a></li>
 <li><a href='#clampChroma'>clampChroma</a></li>
 <li><a href='#clampRgb'>clampRgb</a></li>
 <li><a href='#colorsNamed'>colorsNamed</a></li>
@@ -102,6 +103,7 @@ codebase: 'https://github.com/evercoder/culori/blob/main'
 <li><a href='#round'>round</a></li>
 <li><a href='#samples'>samples</a></li>
 <li><a href='#toGamut'>toGamut</a></li>
+<li><a href='#trilerp'>trilerp</a></li>
 <li><a href='#unlerp'>unlerp</a></li>
 <li><a href='#useMode'>useMode</a></li>
 <li><a href='#wcagContrast'>wcagContrast</a></li>
@@ -912,6 +914,18 @@ lerp(5, 10, 0.5);
 
 Returns the point `t` at which the value `v` is located between the values `a` and `b`. The inverse of `lerp`.
 
+<a id="blerp" href="#blerp">#</a> **blerp**(_a00_, _a01_, _a10_, _a11_, _tx_, _ty_) → _value_
+
+<span aria-label='Source:'>☞</span> [src/interpolate/lerp.js]({{codebase}}/src/interpolate/lerp.js)
+
+Perform the [bilinear interpolation](https://en.wikipedia.org/wiki/Bilinear_interpolation) of the four values `a00`, `a01`, `a10`, and `a11` at the point `(tx, ty)`, with `tx, ty ∈ [0, 1]`. This is the extension of `lerp` to two dimensions.
+
+<a id="trilerp" href="#trilerp">#</a> **trilerp**(_a000_, _a010_, _a100_, _a110_, _a001_, _a011_, _a101_, _a111_, _tx_, _ty_, _tz_) → _value_
+
+<span aria-label='Source:'>☞</span> [src/interpolate/lerp.js]({{codebase}}/src/interpolate/lerp.js)
+
+Perform the [trilinear interpolation](https://en.wikipedia.org/wiki/Trilinear_interpolation) of the eight values `a000`, `a010`, `a100`, `a110`, `a001`, `a011`, `a101`, and `a111` at the point `(tx, ty, tz)`, with `tx, ty, tz ∈ [0, 1]`. This is the extension of `lerp` to three dimensions.
+
 ### Mappings
 
 <a id="mapper" href="#mapper">#</a> **mapper**(_fn_, _mode = "rgb"_) → _function (color | string)_

src/index-fn.js

@@ -93,7 +93,7 @@ export {
 	interpolatorSplineMonotoneClosed
 } from './interpolate/splineMonotone.js';
 
-export { lerp, unlerp } from './interpolate/lerp.js';
+export { lerp, unlerp, blerp, trilerp } from './interpolate/lerp.js';
 export { default as samples } from './samples.js';
 export {
 	displayable,

src/index.js

@@ -94,7 +94,7 @@ export {
 	interpolatorSplineMonotoneClosed
 } from './interpolate/splineMonotone.js';
 
-export { lerp, unlerp } from './interpolate/lerp.js';
+export { lerp, unlerp, blerp, trilerp } from './interpolate/lerp.js';
 export { default as samples } from './samples.js';
 export {
 	displayable,

src/interpolate/lerp.js

@@ -1,4 +1,28 @@
 const lerp = (a, b, t) => a + t * (b - a);
 const unlerp = (a, b, v) => (v - a) / (b - a);
 
-export { lerp, unlerp };
+const blerp = (a00, a01, a10, a11, tx, ty) => {
+	return lerp(lerp(a00, a01, tx), lerp(a10, a11, tx), ty);
+};
+
+const trilerp = (
+	a000,
+	a010,
+	a100,
+	a110,
+	a001,
+	a011,
+	a101,
+	a111,
+	tx,
+	ty,
+	tz
+) => {
+	return lerp(
+		blerp(a000, a010, a100, a110, tx, ty),
+		blerp(a001, a011, a101, a111, tx, ty),
+		tz
+	);
+};
+
+export { lerp, blerp, trilerp, unlerp };

test/api.test.js

@@ -14,6 +14,7 @@ const API_FULL = [
 	'averageAngle',
 	'averageNumber',
 	'blend',
+	'blerp',
 	'clampChroma',
 	'clampGamut',
 	'clampRgb',
@@ -211,6 +212,7 @@ const API_FULL = [
 	'serializeHsl',
 	'serializeRgb',
 	'toGamut',
+	'trilerp',
 	'unlerp',
 	'useMode',
 	'useParser',
@@ -278,6 +280,7 @@ const API_FN = [
 	'averageAngle',
 	'averageNumber',
 	'blend',
+	'blerp',
 	'clampChroma',
 	'clampGamut',
 	'clampRgb',
@@ -451,6 +454,7 @@ const API_FN = [
 	'serializeHsl',
 	'serializeRgb',
 	'toGamut',
+	'trilerp',
 	'unlerp',
 	'useMode',
 	'useParser',

test/lerp.test.js

@@ -1,5 +1,5 @@
 import tape from 'tape';
-import { lerp, unlerp } from '../src/index.js';
+import { lerp, unlerp, blerp, trilerp } from '../src/index.js';
 
 tape('lerp()', t => {
 	t.equal(lerp(10, 2, 0.5), 6);
@@ -10,3 +10,47 @@ tape('unlerp()', t => {
 	t.equal(unlerp(5, 10, 2.5), -0.5);
 	t.end();
 });
+
+const RYB_CUBE = [
+	{ mode: 'rgb', r: 1, g: 1, b: 1 }, // white
+	{ mode: 'rgb', r: 1, g: 0, b: 0 }, // red
+	{ mode: 'rgb', r: 1, g: 1, b: 0 }, // yellow
+	{ mode: 'rgb', r: 1, g: 0.5, b: 0 }, // orange
+	{ mode: 'rgb', r: 0.163, g: 0.373, b: 0.6 }, // blue
+	{ mode: 'rgb', r: 0.5, g: 0, b: 0.5 }, // violet
+	{ mode: 'rgb', r: 0, g: 0.66, b: 0.2 }, // green
+	{ mode: 'rgb', r: 0.2, g: 0.094, b: 0 } // black
+];
+
+tape('trilerp()', t => {
+	const RYB_COLOR = [1, 0.5, 0.25];
+	const EXPECTED_LINEAR = {
+		mode: 'rgb',
+		r: 0.8375,
+		g: 0.19924999999999998,
+		b: 0.0625
+	};
+	const EXPECTED_BIASED = {
+		mode: 'rgb',
+		r: 0.8984375,
+		g: 0.21828124999999998,
+		b: 0.0390625
+	};
+
+	function ryb2rgb(coords, bias = true) {
+		const biased_coords = bias
+			? coords.map(t => t * t * (3 - 2 * t))
+			: coords;
+		return {
+			mode: 'rgb',
+			r: trilerp(...RYB_CUBE.map(it => it.r), ...biased_coords),
+			g: trilerp(...RYB_CUBE.map(it => it.g), ...biased_coords),
+			b: trilerp(...RYB_CUBE.map(it => it.b), ...biased_coords)
+		};
+	}
+
+	t.deepEqual(ryb2rgb(RYB_COLOR, false), EXPECTED_LINEAR, 'ryb: linear');
+	t.deepEqual(ryb2rgb(RYB_COLOR), EXPECTED_BIASED, 'ryb: biased');
+
+	t.end();
+});