feat(ramp): add support for arbitrary value types

BREAKING CHANGE: add support for arbitrary value types, package restructure

- add unified Ramp class, remove obsolete ARamp, LinearRamp, HermiteRamp
- add interpolation presets to be used with generic Ramp
  - LINEAR_N, LINEAR_V (numeric/vector valued)
  - HERMITE_N, HERMITE_V
- update `linear()` & `hermite()` factory fns
- update Ramp ctor to ensure min. 2 keyframes/stops are provided
- add new types
- update/extend readme
- update pkg meta

packages/ramp/README.md

@@ -18,7 +18,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 189 standalone projects, maintained as part
+> This is one of 190 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -31,12 +31,14 @@
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
 - [API](#api)
+  - [Numeric ramps](#numeric-ramps)
+  - [nD Vector ramps](#nd-vector-ramps)
 - [Authors](#authors)
 - [License](#license)
 
 ## About
 
-Parametric (non-)linearly interpolated 1D lookup tables for remapping values.
+Extensible, interpolated nD lookup tables for parameter tweening.
 
 ![screenshot](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/ramp/readme.png)
 
@@ -66,7 +68,7 @@ For Node.js REPL:
 const ramp = await import("@thi.ng/ramp");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.06 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.57 KB
 
 ## Dependencies
 
@@ -90,18 +92,17 @@ directory is using this package:
 
 [Generated API docs](https://docs.thi.ng/umbrella/ramp/)
 
-```ts
+### Numeric ramps
+
+```ts tangle:export/readme.ts
 import { linear, hermite } from "@thi.ng/ramp";
 
 const rampL = linear([[0.1, 0], [0.5, 1], [0.9, 0]]);
 const rampH = hermite([[0.1, 0], [0.5, 1], [0.9, 0]]);
 
 for(let i = 0; i <= 10; i++) {
-    console.log(
-        i / 10,
-        rampL.at(i / 10).toFixed(2),
-        rampH.at(i / 10).toFixed(2)
-    );
+    const t = i / 10;
+    console.log(t, rampL.at(t).toFixed(2), rampH.at(t).toFixed(2));
 }
 
 // 0   0.00 0.00
@@ -117,6 +118,43 @@ for(let i = 0; i <= 10; i++) {
 // 1   0.00 0.00
 ```
 
+### nD Vector ramps
+
+```ts tangle:export/readme-vector.ts
+import { HERMITE_V, ramp } from "@thi.ng/ramp";
+import { FORMATTER, VEC3 } from "@thi.ng/vectors";
+
+// use the generic `ramp()` factory function with a custom implementation
+// see: https://docs.thi.ng/umbrella/ramp/interfaces/RampImpl.html
+const rgb = ramp(
+    // use linear vector interpolation with Vec3 API
+    HERMITE_V(VEC3),
+    // keyframes
+    [
+        [0.1, [1, 0, 0]], // red
+        [0.5, [0, 1, 0]], // green
+        [0.9, [0, 0, 1]], // blue
+    ]
+);
+
+for (let i = 0; i <= 10; i++) {
+    const t = i / 10;
+    console.log(t, FORMATTER(rgb.at(t)));
+}
+
+// 0   [1.000, 0.000, 0.000]
+// 0.1 [1.000, 0.000, 0.000]
+// 0.2 [0.750, 0.250, 0.000]
+// 0.3 [0.500, 0.500, 0.000]
+// 0.4 [0.250, 0.750, 0.000]
+// 0.5 [0.000, 1.000, 0.000]
+// 0.6 [0.000, 0.750, 0.250]
+// 0.7 [0.000, 0.500, 0.500]
+// 0.8 [0.000, 0.250, 0.750]
+// 0.9 [0.000, 0.000, 1.000]
+// 1   [0.000, 0.000, 1.000]
+```
+
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)

packages/ramp/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@thi.ng/ramp",
 	"version": "2.1.103",
-	"description": "Parametric (non-)linearly interpolated 1D lookup tables for remapping values",
+	"description": "Extensible, interpolated nD lookup tables for parameter tweening",
 	"type": "module",
 	"module": "./index.js",
 	"typings": "./index.d.ts",
@@ -50,7 +50,12 @@
 	},
 	"keywords": [
 		"1d",
+		"2d",
+		"3d",
+		"4d",
+		"nd",
 		"animation",
+		"cubic",
 		"curve",
 		"datastructure",
 		"envelope",
@@ -61,7 +66,9 @@
 		"linear",
 		"lut",
 		"ramp",
+		"spline",
 		"timeline",
+		"tween",
 		"typescript"
 	],
 	"publishConfig": {
@@ -81,14 +88,14 @@
 		"./api": {
 			"default": "./api.js"
 		},
-		"./aramp": {
-			"default": "./aramp.js"
-		},
 		"./hermite": {
 			"default": "./hermite.js"
 		},
 		"./linear": {
 			"default": "./linear.js"
+		},
+		"./ramp": {
+			"default": "./ramp.js"
 		}
 	},
 	"thi.ng": {

packages/ramp/src/api.ts

@@ -1,26 +1,40 @@
-import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
+import type { Fn2 } from "@thi.ng/api";
 
-export interface IRamp {
-	stops: Vec[];
+export type Frame<T> = [number, T];
 
-	at(t: number): number;
-	bounds(): RampBounds;
-	interpolatedPoints(res?: number): Iterable<ReadonlyVec>;
-	addStopAt(t: number, y: number, eps?: number): boolean;
+export interface RampImpl<T> {
+	min: Fn2<T | null, T, T>;
+	max: Fn2<T | null, T, T>;
+	at: (stops: Frame<T>[], index: number, t: number) => T;
+	interpolate: {
+		size: number;
+		left: number;
+		right: number;
+		fn: (stops: Frame<T>[], res: number) => Iterable<Frame<T>>;
+	};
+}
+
+export interface IRamp<T> {
+	stops: Frame<T>[];
+
+	at(t: number): T;
+	bounds(): RampBounds<T>;
+	interpolatedPoints(res?: number): Iterable<Frame<T>>;
+	addStopAt(t: number, y: T, eps?: number): boolean;
 	removeStopAt(t: number, eps?: number): boolean;
 	closestIndex(t: number, eps?: number): number;
 	clampedIndexTime(i: number, t: number, eps?: number): number;
 	sort(): void;
 	uniform(): void;
 }
 
-export interface RampBounds {
-	min: number;
-	max: number;
+export interface RampBounds<T> {
+	min: T;
+	max: T;
 	minT: number;
 	maxT: number;
 }
 
-export interface RampConstructor {
-	new (stops: Vec[]): IRamp;
+export interface RampConstructor<T> {
+	new (impl: RampImpl<T>, stops: Frame<T>[]): IRamp<T>;
 }