@thi.ng/ramp 2.1.102 → 3.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-01-30T21:37:19Z
+- **Last updated**: 2024-02-12T16:09:52Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,36 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [3.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/ramp@3.0.0) (2024-02-12)
+
+#### 🛑 Breaking changes
+
+- add support for arbitrary value types ([08e12c3](https://github.com/thi-ng/umbrella/commit/08e12c3))
+- 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
+- add nested type support, simplify RampImpl ([0daa663](https://github.com/thi-ng/umbrella/commit/0daa663))
+- BREAKING CHANGE: rename interpolatedPoints() => samples()
+  - add nested() RampImpl
+  - update IRamp interface
+  - simplify RampImpl interface
+
+#### 🚀 Features
+
+- add time domain fns, grouped ramps, update API ([62c01d1](https://github.com/thi-ng/umbrella/commit/62c01d1))
+  - add time domain functions
+  - add group() ramp for nested, independent ramps
+  - add RampOpts
+  - extract IReadonlyRamp, update IRamp
+  - update/fix IRamp.addStopAt() to .setStopAt()
+
 ### [2.1.83](https://github.com/thi-ng/umbrella/tree/@thi.ng/ramp@2.1.83) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -1,5 +1,15 @@
 <!-- This file is generated - DO NOT EDIT! -->
 <!-- Please see: https://github.com/thi-ng/umbrella/blob/develop/CONTRIBUTING.md#changes-to-readme-files -->
+> [!IMPORTANT]
+> ‼️ Announcing the thi.ng user survey 2024 📋
+>
+> [Please participate in the survey here!](https://forms.gle/XacbSDEmQMPZg8197)\
+> (open until end of February)
+>
+> **To achieve a better sample size, I'd highly appreciate if you could
+> circulate the link to this survey in your own networks.**
+>
+> [Discussion](https://github.com/thi-ng/umbrella/discussions/447)
 
 # ![@thi.ng/ramp](https://media.thi.ng/umbrella/banners-20230807/thing-ramp.svg?4bf9a6f2)
 
@@ -21,15 +31,24 @@
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
 - [API](#api)
+  - [Numeric](#numeric)
+  - [nD vectors](#nd-vectors)
+  - [Nested objects](#nested-objects)
+  - [Grouped & nested ramps](#grouped--nested-ramps)
 - [Authors](#authors)
 - [License](#license)
 
 ## About
 
-Parametric (non-)linearly interpolated 1D lookup tables for remapping values.
+Extensible keyframe interpolation/tweening of arbitrary, nested types.
 
 ![screenshot](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/ramp/readme.png)
 
+This package can perform keyframe interpolation for ramps of numeric values,
+n-dimensional vectors and nested objects of the same. It provides linear and
+cubic hermite interpolation out of the box, but can be extended by implementing
+a simple interface to achieve other interpolation methods.
+
 ## Status
 
 **STABLE** - used in production
@@ -56,42 +75,44 @@ 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.67 KB
 
 ## Dependencies
 
+- [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/arrays](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays)
 - [@thi.ng/compare](https://github.com/thi-ng/umbrella/tree/develop/packages/compare)
+- [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/math](https://github.com/thi-ng/umbrella/tree/develop/packages/math)
 - [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
 - [@thi.ng/vectors](https://github.com/thi-ng/umbrella/tree/develop/packages/vectors)
 
 ## Usage examples
 
-One project in this repo's
+Several projects in this repo's
 [/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
-directory is using this package:
+directory are using this package:
 
-| Screenshot                                                                                                        | Description                                 | Live demo                                        | Source                                                                        |
-|:------------------------------------------------------------------------------------------------------------------|:--------------------------------------------|:-------------------------------------------------|:------------------------------------------------------------------------------|
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ramp-synth.png" width="240"/> | Unison wavetable synth with waveform editor | [Demo](https://demo.thi.ng/umbrella/ramp-synth/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ramp-synth) |
+| Screenshot                                                                                                              | Description                                              | Live demo                                              | Source                                                                              |
+|:------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:-------------------------------------------------------|:------------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ramp-scroll-anim.png" width="240"/> | Scroll-based, reactive, multi-param CSS animation basics | [Demo](https://demo.thi.ng/umbrella/ramp-scroll-anim/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ramp-scroll-anim) |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ramp-synth.png" width="240"/>       | Unison wavetable synth with waveform editor              | [Demo](https://demo.thi.ng/umbrella/ramp-synth/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ramp-synth)       |
 
 ## API
 
 [Generated API docs](https://docs.thi.ng/umbrella/ramp/)
 
-```ts
+### Numeric
+
+```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
@@ -107,6 +128,120 @@ for(let i = 0; i <= 10; i++) {
 // 1   0.00 0.00
 ```
 
+### nD vectors
+
+```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 a vector interpolation preset with the VEC3 API
+    HERMITE_V(VEC3),
+    // keyframes
+    [
+        [0.0, [1, 0, 0]], // red
+        [0.5, [0, 1, 0]], // green
+        [1.0, [0, 0, 1]], // blue
+    ]
+);
+
+for (let i = 0; i <= 20; i++) {
+    const t = i / 20;
+    console.log(t, FORMATTER(rgb.at(t)));
+}
+
+// 0    [1.000, 0.000, 0.000]
+// 0.05 [0.972, 0.028, 0.000]
+// 0.1  [0.896, 0.104, 0.000]
+// 0.15 [0.784, 0.216, 0.000]
+// 0.2  [0.648, 0.352, 0.000]
+// 0.25 [0.500, 0.500, 0.000]
+// 0.3  [0.352, 0.648, 0.000]
+// 0.35 [0.216, 0.784, 0.000]
+// 0.4  [0.104, 0.896, 0.000]
+// 0.45 [0.028, 0.972, 0.000]
+// 0.5  [0.000, 1.000, 0.000]
+// 0.55 [0.000, 0.972, 0.028]
+// 0.6  [0.000, 0.896, 0.104]
+// 0.65 [0.000, 0.784, 0.216]
+// 0.7  [0.000, 0.648, 0.352]
+// 0.75 [0.000, 0.500, 0.500]
+// 0.8  [0.000, 0.352, 0.648]
+// 0.85 [0.000, 0.216, 0.784]
+// 0.9  [0.000, 0.104, 0.896]
+// 0.95 [0.000, 0.028, 0.972]
+// 1    [0.000, 0.000, 1.000]
+```
+
+### Nested objects
+
+```ts tangle:export/readme-nested.ts
+import { HERMITE_V, LINEAR_N, nested, ramp } from "@thi.ng/ramp";
+import { VEC2 } from "@thi.ng/vectors";
+
+const r = ramp(
+    nested({
+        a: LINEAR_N,
+        b: nested({
+            c: HERMITE_V(VEC2),
+        }),
+    }),
+    [
+        [0, { a: 0, b: { c: [100, 100] } }],
+        [0.5, { a: 10, b: { c: [300, 50] } }],
+        [1, { a: -10, b: { c: [200, 120] } }],
+    ]
+);
+
+// produce an iterator of N uniformly spaced sample points
+// across the full range of the ramp
+console.log([...r.samples(10)]);
+
+// [
+// 	[0, { a: 0, b: { c: [100, 100] } }],
+// 	[0.1, { a: 2, b: { c: [120.8, 94.8] } }],
+// 	[0.2, { a: 4, b: { c: [170.4, 82.4] } }],
+// 	[0.3, { a: 6, b: { c: [229.6, 67.6] } }],
+// 	[0.4, { a: 8, b: { c: [279.2, 55.2] } }],
+// 	[0.5, { a: 10, b: { c: [300, 50] } }],
+// 	[0.6, { a: 6, b: { c: [289.6, 57.28] } }],
+// 	[0.7, { a: 2, b: { c: [264.8, 74.64] } }],
+// 	[0.8, { a: -2, b: { c: [235.2, 95.36] } }],
+// 	[0.9, { a: -6, b: { c: [210.4, 112.72] } }],
+// 	[1, { a: -10, b: { c: [200, 120] } }]
+// ]
+```
+
+### Grouped & nested ramps
+
+```ts tangle:export/readme-group.ts
+import { group, linear, wrap } from "@thi.ng/ramp";
+
+const example = group({
+    // child timeline with looping behavior
+    a: linear([[0, 0], [20, 100]], { domain: wrap }),
+    // another child timeline
+    b: linear([[10, 100], [90, 200]]),
+});
+
+console.log(JSON.stringify([...example.samples(10, 0, 100)]));
+// [
+// 	[0, { a: 0, b: 100 }],
+// 	[10, { a: 50, b: 100 }],
+// 	[20, { a: 100, b: 112.5 }],
+// 	[30, { a: 50, b: 125 }],
+// 	[40, { a: 100, b: 137.5 }],
+// 	[50, { a: 50, b: 150 }],
+// 	[60, { a: 0, b: 162.5 }],
+// 	[70, { a: 50, b: 175 }],
+// 	[80, { a: 0, b: 187.5 }],
+// 	[90, { a: 50, b: 200 }],
+// 	[100, { a: 50, b: 200 }]
+// ]
+```
+
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)

package/api.d.ts

@@ -1,23 +1,73 @@
-import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
-export interface IRamp {
-    stops: Vec[];
-    at(t: number): number;
-    bounds(): RampBounds;
-    interpolatedPoints(res?: number): Iterable<ReadonlyVec>;
-    addStopAt(t: number, y: number, eps?: number): boolean;
+import type { Fn2 } from "@thi.ng/api";
+export type Frame<T> = [number, T];
+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;
+}
+export interface IReadonlyRamp<T> {
+    /**
+     * Computes interpolated value at time `t`. Depending on implementation, `t`
+     * might first be processed using the ramp's time domain function.
+     *
+     * @remarks
+     * Also see {@link RampOpts.domain}.
+     *
+     * @param t
+     */
+    at(t: number): T;
+    /**
+     * Returns an iterator of `n` uniformly spaced samples of the time domain
+     * between the first and last keyframe. Each returned sample is a tuple of
+     * `[time, interpolatedValue]`.
+     *
+     * @param n
+     * @param start
+     * @param end
+     */
+    samples(n?: number, start?: number, end?: number): Iterable<Frame<T>>;
+    /**
+     * Computes the ramp's min/max time domain and value bounds.
+     *
+     * @remarks
+     * Also see {@link IReadonlyRamp.timeBounds}.
+     */
+    bounds(): RampBounds<T>;
+    /**
+     * Computes the ramp's min/max time bounds (i.e. the positions of the first
+     * & last keyframes/stops).
+     *
+     * @remarks
+     * Also see {@link IReadonlyRamp.bounds}.
+     */
+    timeBounds(): [number, number];
+}
+export interface IRamp<T> extends IReadonlyRamp<T> {
+    impl: RampImpl<T>;
+    stops: Frame<T>[];
+    setStopAt(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 RampOpts {
+    /**
+     * Time domain mapping function, e.g. to achieve looping. See {@link clamp},
+     * {@link wrap}, {@link wrapInterval}.
+     *
+     * @remarks
+     * The domain function can be changed dynamically by setting the
+     * {@link Ramp.domain} property.
+     *
+     * @defaultValue {@link unconstrained}
+     */
+    domain: RampDomain;
+}
+export interface RampBounds<T> {
+    min: T;
+    max: T;
     minT: number;
     maxT: number;
 }
-export interface RampConstructor {
-    new (stops: Vec[]): IRamp;
-}
+export type RampDomain = (t: number, min: number, max: number) => number;
 //# sourceMappingURL=api.d.ts.map

package/domain.d.ts

@@ -0,0 +1,26 @@
+import type { RampDomain } from "./api.js";
+/**
+ * Identity time domain function. Default for {@link RampOpts.domain}.
+ * Passthrough, no-op.
+ *
+ * @param t
+ */
+export declare const unconstrained: RampDomain;
+/**
+ * Time domain function. Clamps given lookup time `t` to the parent
+ * ramp's first & last keyframe times.
+ */
+export declare const clamp: RampDomain;
+/**
+ * Time domain function. Wraps given lookup time `t` into the interval defined
+ * by parent ramp's first & last keyframe times, thereby creating a looping
+ * effect.
+ */
+export declare const wrap: RampDomain;
+/**
+ * Higher-order time domain function and version of {@link wrap} to create a
+ * looping effect using the given `min` & `max` keyframe times (instead of the
+ * parent ramp's first/last keyframe times).
+ */
+export declare const wrapInterval: (min: number, max: number) => RampDomain;
+//# sourceMappingURL=domain.d.ts.map

package/domain.js

@@ -0,0 +1,11 @@
+import { clamp as $clamp, wrap as $wrap } from "@thi.ng/math/interval";
+const unconstrained = (t) => t;
+const clamp = $clamp;
+const wrap = $wrap;
+const wrapInterval = (min, max) => (t) => $wrap(t, min, max);
+export {
+  clamp,
+  unconstrained,
+  wrap,
+  wrapInterval
+};

package/group.d.ts

@@ -0,0 +1,50 @@
+import type { Frame, IRamp, IReadonlyRamp, RampBounds, RampDomain, RampOpts } from "./api.js";
+export type GroupImpl<T extends Record<string, any>> = {
+    [P in keyof T]: IRamp<T[P]>;
+};
+/**
+ * Creates a new nested ramp from given object of otherwise independent child
+ * ramps (which can be groups themselves).
+ *
+ * @remarks
+ * Similar to {@link nested}, but different in that groups are merely views of
+ * independent timelines, each with their own set of keyframes, interpolation
+ * logic, time domain functions.
+ *
+ * Groups can have their own time domain function (given via `opts`, default:
+ * {@link unconstrained}), which will be applied _prior_ to evaluating any child ramps.
+ *
+ * @example
+ * ```ts
+ * const example = group({
+ *   // named, independent child ramps/timelines
+ *   a: linear([[0.1, 0], [0.5, -10]]),
+ *   b: hermite([[0, 100], [1, 200]]),
+ * });
+ *
+ * example.at(0.2)
+ * // { a: -2.5, b: 110.4 }
+ *
+ * // set new keyframe for `b` ramp
+ * // (in TS need to cast to proper type first)
+ * (<Ramp<number>>example.children.b).setStopAt(0.5, 200);
+ *
+ * example.at(0.2)
+ * // { a: -2.5, b: 135.2 }
+ * ```
+ *
+ * @param children
+ * @param opts
+ */
+export declare const group: <T extends Record<string, any>>(children: GroupImpl<T>, opts?: Partial<RampOpts>) => Group<T>;
+export declare class Group<T extends Record<string, any>> implements IReadonlyRamp<T> {
+    children: GroupImpl<T>;
+    domain: RampDomain;
+    protected childEntries: [keyof T, IReadonlyRamp<any>][];
+    constructor(children: GroupImpl<T>, opts?: Partial<RampOpts>);
+    at(t: number): T;
+    samples(n?: number, start?: number, end?: number): Iterable<Frame<T>>;
+    bounds(): RampBounds<T>;
+    timeBounds(): [number, number];
+}
+//# sourceMappingURL=group.d.ts.map

package/group.js

@@ -0,0 +1,60 @@
+import { mix } from "@thi.ng/math/mix";
+import { map } from "@thi.ng/transducers/map";
+import { normRange } from "@thi.ng/transducers/norm-range";
+import { unconstrained } from "./domain.js";
+const group = (children, opts) => new Group(children, opts);
+class Group {
+  constructor(children, opts) {
+    this.children = children;
+    this.childEntries = Object.entries(this.children);
+    this.domain = opts?.domain || unconstrained;
+  }
+  domain;
+  childEntries;
+  at(t) {
+    t = this.domain(t, ...this.timeBounds());
+    return this.childEntries.reduce((acc, [id, ramp]) => {
+      acc[id] = ramp.at(t);
+      return acc;
+    }, {});
+  }
+  samples(n = 100, start, end) {
+    if (start == void 0 || end == void 0) {
+      const bounds = this.timeBounds();
+      start = start ?? bounds[0];
+      end = end ?? bounds[1];
+    }
+    return map((t) => {
+      t = mix(start, end, t);
+      return [t, this.at(t)];
+    }, normRange(n));
+  }
+  bounds() {
+    return this.childEntries.reduce(
+      (acc, [id, ramp]) => {
+        const bounds = ramp.bounds();
+        acc.minT = Math.min(acc.minT, bounds.minT);
+        acc.maxT = Math.max(acc.maxT, bounds.maxT);
+        acc.min[id] = bounds.min;
+        acc.max[id] = bounds.max;
+        return acc;
+      },
+      { minT: Infinity, maxT: -Infinity, min: {}, max: {} }
+    );
+  }
+  timeBounds() {
+    return this.childEntries.reduce(
+      (acc, [_, ramp]) => {
+        const bounds = ramp.timeBounds();
+        acc[0] = Math.min(acc[0], bounds[0]);
+        acc[1] = Math.max(acc[1], bounds[1]);
+        return acc;
+      },
+      [Infinity, -Infinity]
+    );
+  }
+}
+export {
+  Group,
+  group
+};

package/hermite.d.ts

@@ -1,8 +1,25 @@
-import type { Vec } from "@thi.ng/vectors";
-import { ARamp } from "./aramp.js";
-export declare const hermite: (stops?: Vec[]) => HermiteRamp;
-export declare class HermiteRamp extends ARamp {
-    at(t: number): number;
-    interpolatedPoints(res?: number): IterableIterator<number[]>;
-}
+import type { Vec, VecAPI } from "@thi.ng/vectors";
+import type { Frame, RampImpl, RampOpts } from "./api.js";
+import { Ramp } from "./ramp.js";
+/**
+ * Syntax sugar for creating a numeric {@link Ramp} using the {@link HERMITE_N}
+ * ramp hermite spline interpolation impl and given stops (aka keyframes,
+ * minimum 2 required).
+ *
+ * @remarks
+ * For vector-valued hermite ramps, use {@link ramp} with {@link HERMITE_V}.
+ *
+ * References:
+ * - https://en.wikipedia.org/wiki/Cubic_Hermite_spline
+ *
+ * Also see:
+ * - https://docs.thi.ng/umbrella/math/functions/mixCubicHermite.html
+ * - https://docs.thi.ng/umbrella/math/functions/tangentCardinal.html
+ *
+ * @param stops
+ * @param opts
+ */
+export declare const hermite: (stops: Frame<number>[], opts?: Partial<RampOpts>) => Ramp<number>;
+export declare const HERMITE_N: RampImpl<number>;
+export declare const HERMITE_V: <T extends Vec>(vec: VecAPI) => RampImpl<T>;
 //# sourceMappingURL=hermite.d.ts.map

package/hermite.js

@@ -1,54 +1,36 @@
 import { norm } from "@thi.ng/math/fit";
-import { mix, mixCubicHermite, tangentCardinal } from "@thi.ng/math/mix";
-import { comp } from "@thi.ng/transducers/comp";
-import { extendSides } from "@thi.ng/transducers/extend-sides";
-import { iterator } from "@thi.ng/transducers/iterator";
-import { map } from "@thi.ng/transducers/map";
-import { mapcat } from "@thi.ng/transducers/mapcat";
-import { normRange } from "@thi.ng/transducers/norm-range";
-import { partition } from "@thi.ng/transducers/partition";
-import { ARamp } from "./aramp.js";
-const hermite = (stops) => new HermiteRamp(stops);
-class HermiteRamp extends ARamp {
-  at(t) {
-    const stops = this.stops;
+import { mixCubicHermite, tangentCardinal } from "@thi.ng/math/mix";
+import { mixHermiteCardinal } from "@thi.ng/vectors/mix-hermite";
+import { Ramp } from "./ramp.js";
+const hermite = (stops, opts) => new Ramp(HERMITE_N, stops, opts);
+const HERMITE_N = {
+  min: (acc, x) => Math.min(acc ?? Infinity, x),
+  max: (acc, x) => Math.max(acc ?? -Infinity, x),
+  at: (stops, i, t) => {
     const n = stops.length - 1;
-    const i = this.timeIndex(t);
-    if (i < 0) {
-      return stops[0][1];
-    } else if (i >= n) {
-      return stops[n][1];
-    } else {
-      const a = stops[Math.max(i - 1, 0)];
-      const [bx, by] = stops[Math.max(i, 0)];
-      const [cx, cy] = stops[Math.min(i + 1, n)];
-      const d = stops[Math.min(i + 2, n)];
-      const t1 = tangentCardinal(a[1], cy, 0, a[0], cx);
-      const t2 = tangentCardinal(by, d[1], 0, bx, d[0]);
-      return mixCubicHermite(by, t1, cy, t2, norm(t, bx, cx));
-    }
+    const a = stops[Math.max(i - 1, 0)];
+    const [bx, by] = stops[Math.max(i, 0)];
+    const [cx, cy] = stops[Math.min(i + 1, n)];
+    const d = stops[Math.min(i + 2, n)];
+    const t1 = tangentCardinal(a[1], cy, 0, a[0], cx);
+    const t2 = tangentCardinal(by, d[1], 0, bx, d[0]);
+    return mixCubicHermite(by, t1, cy, t2, norm(t, bx, cx));
   }
-  interpolatedPoints(res = 20) {
-    return iterator(
-      comp(
-        partition(4, 1),
-        mapcat(([a, [bx, by], [cx, cy], d]) => {
-          const t1 = tangentCardinal(a[1], cy, 0, a[0], cx);
-          const t2 = tangentCardinal(by, d[1], 0, bx, d[0]);
-          return map(
-            (t) => [
-              mix(bx, cx, t),
-              mixCubicHermite(by, t1, cy, t2, t)
-            ],
-            normRange(res, false)
-          );
-        })
-      ),
-      extendSides(this.stops, 1, 2)
-    );
+};
+const HERMITE_V = (vec) => ({
+  min: (acc, x) => vec.min(acc, acc || vec.setN([], Infinity), x),
+  max: (acc, x) => vec.max(acc, acc || vec.setN([], -Infinity), x),
+  at: (stops, i, t) => {
+    const n = stops.length - 1;
+    const [, a] = stops[Math.max(i - 1, 0)];
+    const [bt, b] = stops[Math.max(i, 0)];
+    const [ct, c] = stops[Math.min(i + 1, n)];
+    const [, d] = stops[Math.min(i + 2, n)];
+    return mixHermiteCardinal([], a, b, c, d, norm(t, bt, ct), 0);
   }
-}
+});
 export {
-  HermiteRamp,
+  HERMITE_N,
+  HERMITE_V,
   hermite
 };

package/index.d.ts

@@ -1,5 +1,8 @@
 export * from "./api.js";
-export * from "./aramp.js";
+export * from "./domain.js";
+export * from "./group.js";
 export * from "./hermite.js";
 export * from "./linear.js";
+export * from "./nested.js";
+export * from "./ramp.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,4 +1,7 @@
 export * from "./api.js";
-export * from "./aramp.js";
+export * from "./domain.js";
+export * from "./group.js";
 export * from "./hermite.js";
 export * from "./linear.js";
+export * from "./nested.js";
+export * from "./ramp.js";

package/linear.d.ts

@@ -1,8 +1,18 @@
-import type { Vec } from "@thi.ng/vectors";
-import { ARamp } from "./aramp.js";
-export declare const linear: (stops?: Vec[]) => LinearRamp;
-export declare class LinearRamp extends ARamp {
-    at(t: number): number;
-    interpolatedPoints(): Vec[];
-}
+import type { Vec, VecAPI } from "@thi.ng/vectors";
+import type { Frame, RampImpl, RampOpts } from "./api.js";
+import { Ramp } from "./ramp.js";
+/**
+ * Syntax sugar for creating a numeric {@link Ramp} using the {@link LINEAR_N}
+ * ramp linear interpolation impl and given stops (aka keyframes, minimum 2
+ * required).
+ *
+ * @remarks
+ * For vector-valued linear ramps, use {@link ramp} with {@link LINEAR_V}.
+ *
+ * @param stops
+ * @param opts
+ */
+export declare const linear: (stops: Frame<number>[], opts?: Partial<RampOpts>) => Ramp<number>;
+export declare const LINEAR_N: RampImpl<number>;
+export declare const LINEAR_V: <T extends Vec>(vec: VecAPI) => RampImpl<T>;
 //# sourceMappingURL=linear.d.ts.map

package/linear.js

@@ -1,26 +1,26 @@
-import { fit } from "@thi.ng/math/fit";
-import { ARamp } from "./aramp.js";
-const linear = (stops) => new LinearRamp(stops);
-class LinearRamp extends ARamp {
-  at(t) {
-    const stops = this.stops;
-    const n = stops.length - 1;
-    const i = this.timeIndex(t);
-    if (i < 0) {
-      return stops[0][1];
-    } else if (i >= n) {
-      return stops[n][1];
-    } else {
-      const a = stops[i];
-      const b = stops[i + 1];
-      return fit(t, a[0], b[0], a[1], b[1]);
-    }
+import { fit, norm } from "@thi.ng/math/fit";
+import { Ramp } from "./ramp.js";
+const linear = (stops, opts) => new Ramp(LINEAR_N, stops, opts);
+const LINEAR_N = {
+  min: (acc, x) => Math.min(acc ?? Infinity, x),
+  max: (acc, x) => Math.max(acc ?? -Infinity, x),
+  at: (stops, i, t) => {
+    const a = stops[i];
+    const b = stops[i + 1];
+    return fit(t, a[0], b[0], a[1], b[1]);
   }
-  interpolatedPoints() {
-    return this.stops;
+};
+const LINEAR_V = (vec) => ({
+  min: (acc, x) => vec.min(acc, acc || vec.setN([], Infinity), x),
+  max: (acc, x) => vec.max(acc, acc || vec.setN([], -Infinity), x),
+  at: (stops, i, t) => {
+    const a = stops[i];
+    const b = stops[i + 1];
+    return vec.mixN([], a[1], b[1], norm(t, a[0], b[0]));
   }
-}
+});
 export {
-  LinearRamp,
+  LINEAR_N,
+  LINEAR_V,
   linear
 };

package/nested.d.ts

@@ -0,0 +1,35 @@
+import type { RampImpl } from "./api.js";
+export type NestedImpl<T extends Record<string, any>> = {
+    [P in keyof T]: RampImpl<T[P]>;
+};
+/**
+ * Higher order ramp implementation for nested (object based) values. The given
+ * `children` object must specify a {@link RampImpl} for each key in the object.
+ *
+ * @remarks
+ * Since this is only a {@link RampImpl}, all keys in the to-be-interpolated
+ * objects will share the same keyframe times (specified in the parent
+ * {@link ramp}). If a nested ramp is desired where each child can have its own
+ * set of keyframes, please use {@link group} instead. Both of these concepts
+ * are somewhat similar but satisfy different use cases.
+ *
+ * @example
+ * ```ts
+ * const example = ramp(
+ *   // nested ramp spec w/ interpolation modes for each key
+ *   nested({a: LINEAR_N, b: HERMITE_N }),
+ *   // keyframes
+ *   [
+ *     [0, { a: 0, b: 1000 }],
+ *     [100, { a: -10, b: 2000 }],
+ *   ]
+ * )
+ *
+ * example.at(25)
+ * // { a: -2.5, b: 1156.25 }
+ * ```
+ *
+ * @param children
+ */
+export declare const nested: <T extends Record<string, any>>(children: NestedImpl<T>) => RampImpl<T>;
+//# sourceMappingURL=nested.d.ts.map

package/nested.js

@@ -0,0 +1,24 @@
+const nested = (children) => {
+  const pairs = Object.entries(children);
+  return {
+    min: (acc, x) => pairs.reduce((acc2, [id, impl]) => {
+      acc2[id] = impl.min(acc2[id], x[id]);
+      return acc2;
+    }, acc || {}),
+    max: (acc, x) => pairs.reduce((acc2, [id, impl]) => {
+      acc2[id] = impl.max(acc2[id], x[id]);
+      return acc2;
+    }, acc || {}),
+    at: (stops, index, t) => pairs.reduce((acc, [id, impl]) => {
+      acc[id] = impl.at(
+        stops.map((x) => [x[0], x[1][id]]),
+        index,
+        t
+      );
+      return acc;
+    }, {})
+  };
+};
+export {
+  nested
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/ramp",
-  "version": "2.1.102",
-  "description": "Parametric (non-)linearly interpolated 1D lookup tables for remapping values",
+  "version": "3.0.0",
+  "description": "Extensible keyframe interpolation/tweening of arbitrary, nested types",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -35,22 +35,29 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@thi.ng/arrays": "^2.7.19",
-    "@thi.ng/compare": "^2.2.18",
-    "@thi.ng/math": "^5.9.0",
-    "@thi.ng/transducers": "^8.9.0",
-    "@thi.ng/vectors": "^7.10.5"
+    "@thi.ng/api": "^8.9.23",
+    "@thi.ng/arrays": "^2.7.20",
+    "@thi.ng/compare": "^2.2.19",
+    "@thi.ng/errors": "^2.4.16",
+    "@thi.ng/math": "^5.9.1",
+    "@thi.ng/transducers": "^8.9.1",
+    "@thi.ng/vectors": "^7.10.6"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.39.0",
-    "esbuild": "^0.19.10",
+    "@microsoft/api-extractor": "^7.40.1",
+    "esbuild": "^0.20.0",
     "rimraf": "^5.0.5",
-    "typedoc": "^0.25.4",
+    "typedoc": "^0.25.7",
     "typescript": "^5.3.3"
   },
   "keywords": [
     "1d",
+    "2d",
+    "3d",
+    "4d",
+    "nd",
     "animation",
+    "cubic",
     "curve",
     "datastructure",
     "envelope",
@@ -60,8 +67,12 @@
     "keyframe",
     "linear",
     "lut",
+    "nested",
+    "object",
     "ramp",
+    "spline",
     "timeline",
+    "tween",
     "typescript"
   ],
   "publishConfig": {
@@ -81,18 +92,21 @@
     "./api": {
       "default": "./api.js"
     },
-    "./aramp": {
-      "default": "./aramp.js"
-    },
     "./hermite": {
       "default": "./hermite.js"
     },
     "./linear": {
       "default": "./linear.js"
+    },
+    "./nested": {
+      "default": "./nested.js"
+    },
+    "./ramp": {
+      "default": "./ramp.js"
     }
   },
   "thi.ng": {
     "year": 2019
   },
-  "gitHead": "ce8202c237a367c4038d41919a8acf75e1122507\n"
+  "gitHead": "e304d8e10f3446a22666ba75aaa2fb1d32752ae0\n"
 }

package/ramp.d.ts

@@ -0,0 +1,40 @@
+import type { ICopy, IEmpty } from "@thi.ng/api";
+import type { Frame, IRamp, RampBounds, RampDomain, RampImpl, RampOpts } from "./api.js";
+/**
+ * Syntax sugar for {@link Ramp} constructor using the given ramp interpolation
+ * `impl`, keyframes `stops` (minimum 2) and options.
+ *
+ * @param impl
+ * @param stops
+ * @param opts
+ */
+export declare const ramp: <T>(impl: RampImpl<T>, stops: Frame<T>[], opts?: Partial<RampOpts>) => Ramp<T>;
+export declare class Ramp<T> implements ICopy<IRamp<T>>, IEmpty<IRamp<T>>, IRamp<T> {
+    impl: RampImpl<T>;
+    stops: Frame<T>[];
+    domain: RampDomain;
+    constructor(impl: RampImpl<T>, stops: Frame<T>[], opts?: Partial<RampOpts>);
+    copy(): Ramp<T>;
+    empty(): Ramp<T>;
+    /**
+     * Samples the ramp at given time `t` and returns interpolated value.
+     *
+     * @remarks
+     * The given `t` is first processed by the configured time
+     * {@link Ramp.domain} function.
+     *
+     * @param t
+     */
+    at(t: number): T;
+    samples(n?: number, start?: number, end?: number): IterableIterator<Frame<T>>;
+    bounds(): RampBounds<T>;
+    timeBounds(): [number, number];
+    setStopAt(t: number, val: 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;
+    protected timeIndex(t: number): number;
+}
+//# sourceMappingURL=ramp.d.ts.map

package/ramp.js

@@ -0,0 +1,141 @@
+import { binarySearch } from "@thi.ng/arrays/binary-search";
+import { peek } from "@thi.ng/arrays/peek";
+import { compareNumAsc } from "@thi.ng/compare/numeric";
+import { assert } from "@thi.ng/errors/assert";
+import { absDiff } from "@thi.ng/math/abs";
+import { clamp } from "@thi.ng/math/interval";
+import { mix } from "@thi.ng/math/mix";
+import { map } from "@thi.ng/transducers/map";
+import { normRange } from "@thi.ng/transducers/norm-range";
+import { unconstrained } from "./domain.js";
+const ramp = (impl, stops, opts) => new Ramp(impl, stops, opts);
+class Ramp {
+  constructor(impl, stops, opts) {
+    this.impl = impl;
+    this.stops = stops;
+    assert(stops.length >= 2, `require at least 2 keyframes/stops`);
+    const $opts = { domain: unconstrained, ...opts };
+    this.domain = $opts.domain;
+    this.sort();
+  }
+  domain;
+  copy() {
+    return new Ramp(
+      this.impl,
+      this.stops.map((x) => x.slice())
+    );
+  }
+  empty() {
+    return new Ramp(this.impl, []);
+  }
+  /**
+   * Samples the ramp at given time `t` and returns interpolated value.
+   *
+   * @remarks
+   * The given `t` is first processed by the configured time
+   * {@link Ramp.domain} function.
+   *
+   * @param t
+   */
+  at(t) {
+    const { domain, impl, stops } = this;
+    const n = stops.length - 1;
+    const first = stops[0];
+    const last = stops[n];
+    t = domain(t, first[0], last[0]);
+    const i = this.timeIndex(t);
+    return i < 0 ? first[1] : i >= n ? last[1] : impl.at(stops, i, t);
+  }
+  samples(n = 100, start, end) {
+    if (start == void 0 || end == void 0) {
+      const bounds = this.timeBounds();
+      start = start ?? bounds[0];
+      end = end ?? bounds[1];
+    }
+    return map((t) => {
+      t = mix(start, end, t);
+      return [t, this.at(t)];
+    }, normRange(n));
+  }
+  bounds() {
+    const { impl, stops } = this;
+    const n = stops.length;
+    let min = null;
+    let max = null;
+    for (let i = n; i-- > 0; ) {
+      const val = stops[i][1];
+      min = impl.min(min, val);
+      max = impl.max(max, val);
+    }
+    return {
+      min,
+      max,
+      minT: stops[0][0],
+      maxT: stops[n - 1][0]
+    };
+  }
+  timeBounds() {
+    return [this.stops[0][0], peek(this.stops)[0]];
+  }
+  setStopAt(t, val, eps = 0.01) {
+    const idx = this.closestIndex(t, eps);
+    if (idx < 0) {
+      this.stops.push([t, val]);
+      this.sort();
+      return true;
+    }
+    this.stops[idx][1] = val;
+    return false;
+  }
+  removeStopAt(t, eps = 0.01) {
+    if (this.stops.length > 2) {
+      const i = this.closestIndex(t, eps);
+      if (i !== -1) {
+        this.stops.splice(i, 1);
+        return true;
+      }
+    }
+    return false;
+  }
+  closestIndex(t, eps = 0.01) {
+    const stops = this.stops;
+    for (let i = stops.length; i-- > 0; ) {
+      if (absDiff(t, stops[i][0]) < eps)
+        return i;
+    }
+    return -1;
+  }
+  clampedIndexTime(i, t, eps = 0.01) {
+    const stops = this.stops;
+    const n = stops.length - 1;
+    return i == 0 ? Math.min(t, stops[1][0] - eps) : i === n ? Math.max(t, stops[n - 1][0] + eps) : clamp(t, stops[i - 1][0] + eps, stops[i + 1][0] - eps);
+  }
+  sort() {
+    this.stops.sort((a, b) => a[0] - b[0]);
+  }
+  uniform() {
+    const n = this.stops.length - 1;
+    this.stops.forEach((p, i) => p[0] = i / n);
+  }
+  timeIndex(t) {
+    const stops = this.stops;
+    const n = stops.length;
+    if (n < 256) {
+      for (let i = n; i-- > 0; ) {
+        if (t >= stops[i][0])
+          return i;
+      }
+      return -1;
+    }
+    return binarySearch(
+      stops,
+      [t, null],
+      (x) => x[0],
+      compareNumAsc
+    );
+  }
+}
+export {
+  Ramp,
+  ramp
+};

package/aramp.d.ts

@@ -1,17 +0,0 @@
-import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
-import type { IRamp, RampBounds } from "./api.js";
-export declare abstract class ARamp implements IRamp {
-    stops: Vec[];
-    constructor(stops?: Vec[]);
-    abstract at(t: number): number;
-    abstract interpolatedPoints(): Iterable<ReadonlyVec>;
-    bounds(): RampBounds;
-    addStopAt(t: number, y: number, 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;
-    protected timeIndex(t: number): number;
-}
-//# sourceMappingURL=aramp.d.ts.map

package/aramp.js

@@ -1,80 +0,0 @@
-import { binarySearch } from "@thi.ng/arrays/binary-search";
-import { compareNumAsc } from "@thi.ng/compare/numeric";
-import { absDiff } from "@thi.ng/math/abs";
-import { clamp } from "@thi.ng/math/interval";
-class ARamp {
-  stops;
-  constructor(stops = [
-    [0, 0],
-    [1, 1]
-  ]) {
-    this.stops = stops;
-  }
-  bounds() {
-    const stops = this.stops;
-    const n = stops.length;
-    if (!n)
-      return { min: 0, max: 0, minT: 0, maxT: 0 };
-    let min = Infinity;
-    let max = -Infinity;
-    for (let i = n; i-- > 0; ) {
-      const y = stops[i][1];
-      min = Math.min(min, y);
-      max = Math.max(max, y);
-    }
-    return { min, max, minT: stops[0][0], maxT: stops[n - 1][0] };
-  }
-  addStopAt(t, y, eps = 0.01) {
-    if (this.closestIndex(t, eps) !== -1) {
-      this.stops.push([t, y]);
-      this.sort();
-      return true;
-    }
-    return false;
-  }
-  removeStopAt(t, eps = 0.01) {
-    if (this.stops.length > 2) {
-      const i = this.closestIndex(t, eps);
-      if (i !== -1) {
-        this.stops.splice(i, 1);
-        return true;
-      }
-    }
-    return false;
-  }
-  closestIndex(t, eps = 0.01) {
-    const stops = this.stops;
-    for (let i = stops.length; i-- > 0; ) {
-      if (absDiff(t, stops[i][0]) < eps)
-        return i;
-    }
-    return -1;
-  }
-  clampedIndexTime(i, t, eps = 0.01) {
-    const stops = this.stops;
-    const n = stops.length - 1;
-    return i == 0 ? Math.min(t, stops[1][0] - eps) : i === n ? Math.max(t, stops[n - 1][0] + eps) : clamp(t, stops[i - 1][0] + eps, stops[i + 1][0] - eps);
-  }
-  sort() {
-    this.stops.sort((a, b) => a[0] - b[0]);
-  }
-  uniform() {
-    const n = this.stops.length - 1;
-    this.stops.forEach((p, i) => p[0] = i / n);
-  }
-  timeIndex(t) {
-    const stops = this.stops;
-    const n = stops.length;
-    if (n < 256) {
-      for (let i = n; i-- > 0; ) {
-        if (t >= stops[i][0])
-          return i;
-      }
-      return -1;
-    }
-    return binarySearch(stops, [t], (x) => x[0], compareNumAsc);
-  }
-}
-export {
-  ARamp
-};