@thi.ng/ramp 3.1.34 → 3.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-08-18T14:11:34Z
+- **Last updated**: 2024-09-05T12:23:14Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,21 @@ 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.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/ramp@3.3.0) (2024-09-05)
+
+#### 🚀 Features
+
+- add easing ramp implementations ([1e23b61](https://github.com/thi-ng/umbrella/commit/1e23b61))
+  - add `easing()`
+  - add `EASING_N` / `EASING_V`
+  - update pkg exports
+
+## [3.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/ramp@3.2.0) (2024-08-28)
+
+#### 🚀 Features
+
+- add IRamp.removeStopAtIndex() ([05c965f](https://github.com/thi-ng/umbrella/commit/05c965f))
+
 ### [3.1.24](https://github.com/thi-ng/umbrella/tree/@thi.ng/ramp@3.1.24) (2024-06-21)
 
 #### ♻️ Refactoring

package/README.md

@@ -34,9 +34,15 @@ 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.
+n-dimensional vectors and nested objects of the same. It provides several
+interpolation methods out of the box, but can be extended by implementing a
+simple interface to achieve other interpolation methods.
+
+Built-in interpolation modes:
+
+- [linear](https://docs.thi.ng/umbrella/ramp/functions/linear.html)
+- [cubic hermite](https://docs.thi.ng/umbrella/ramp/functions/hermite.html)
+- [arbitrary easing functions](https://docs.thi.ng/umbrella/ramp/functions/easing.html)
 
 ## Status
 
@@ -70,7 +76,7 @@ For Node.js REPL:
 const ramp = await import("@thi.ng/ramp");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.87 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.00 KB
 
 ## Dependencies
 
@@ -102,27 +108,30 @@ directory are using this package:
 ### Numeric
 
 ```ts tangle:export/readme.ts
-import { linear, hermite } from "@thi.ng/ramp";
+import { linear, hermite, easing } from "@thi.ng/ramp";
+
+const stops = [[0.1, 0], [0.5, 1], [0.9, 0]];
 
-const rampL = linear([[0.1, 0], [0.5, 1], [0.9, 0]]);
-const rampH = hermite([[0.1, 0], [0.5, 1], [0.9, 0]]);
+const rampL = linear(stops);
+const rampH = hermite(stops);
+const rampE = easing(stops);
 
 for(let i = 0; i <= 10; i++) {
     const t = i / 10;
-    console.log(t, rampL.at(t).toFixed(2), rampH.at(t).toFixed(2));
+    console.log(t, rampL.at(t).toFixed(3), rampH.at(t).toFixed(3), rampE.at(t).toFixed(3));
 }
 
-// 0   0.00 0.00
-// 0.1 0.00 0.00
-// 0.2 0.25 0.16
-// 0.3 0.50 0.50
-// 0.4 0.75 0.84
-// 0.5 1.00 1.00
-// 0.6 0.75 0.84
-// 0.7 0.50 0.50
-// 0.8 0.25 0.16
-// 0.9 0.00 0.00
-// 1   0.00 0.00
+// 0   0.000 0.000 0.000
+// 0.1 0.000 0.000 0.000
+// 0.2 0.250 0.156 0.016
+// 0.3 0.500 0.500 0.500
+// 0.4 0.750 0.844 0.984
+// 0.5 1.000 1.000 1.000
+// 0.6 0.750 0.844 0.984
+// 0.7 0.500 0.500 0.500
+// 0.8 0.250 0.156 0.016
+// 0.9 0.000 0.000 0.000
+// 1   0.000 0.000 0.000
 ```
 
 ### nD vectors

package/api.d.ts

@@ -48,6 +48,7 @@ export interface IRamp<T> extends IReadonlyRamp<T> {
     stops: Frame<T>[];
     setStopAt(t: number, y: T, eps?: number): boolean;
     removeStopAt(t: number, eps?: number): boolean;
+    removeStopAtIndex(i: number): boolean;
     closestIndex(t: number, eps?: number): number;
     clampedIndexTime(i: number, t: number, eps?: number): number;
 }

package/easing.d.ts

@@ -0,0 +1,45 @@
+import type { FnN } from "@thi.ng/api";
+import type { Vec } from "@thi.ng/vectors";
+import type { Frame, RampImpl, RampOpts, VecAPI } from "./api.js";
+import { Ramp } from "./ramp.js";
+/**
+ * Syntax sugar for creating a numeric {@link Ramp} using the {@link EASING_N}
+ * ramp interpolation impl (supporting arbitrary easing functions), given
+ * `stops` (aka keyframes, minimum 2 required) and options.
+ *
+ * @remarks
+ * Easing functions remap time values in the [0,1] range. By default uses
+ * [`easeInOut5()`](https://docs.thi.ng/umbrella/math/functions/easeInOut5.html).
+ *
+ * For vector-valued ramps, use {@link ramp} with {@link EASING_V}.
+ *
+ * @param stops
+ * @param opts
+ */
+export declare const easing: (stops: Frame<number>[], opts?: Partial<RampOpts & {
+    easing: FnN;
+}>) => Ramp<number>;
+/**
+ * Higher-order ramp interpolation implementation supporting arbitrary `easing`
+ * function to control keyframe interpolation.
+ *
+ * @remarks
+ * Easing functions remap time values in the [0,1] range. By default uses
+ * [`easeInOut5()`](https://docs.thi.ng/umbrella/math/functions/easeInOut5.html).
+ *
+ * @param easing
+ */
+export declare const EASING_N: (easing?: FnN) => RampImpl<number>;
+/**
+ * Vector version of {@link EASING_N}. Use with any of the supplied vector APIs:
+ * {@link VEC} (arbitrary size), {@link VEC2}, {@link VEC3} or {@link VEC4}.
+ *
+ * @remarks
+ * Easing functions remap time values in the [0,1] range. By default uses
+ * [`easeInOut5()`](https://docs.thi.ng/umbrella/math/functions/easeInOut5.html).
+ *
+ * @param vec
+ * @param easing
+ */
+export declare const EASING_V: <T extends Vec>(vec: VecAPI, easing?: FnN) => RampImpl<T>;
+//# sourceMappingURL=easing.d.ts.map

package/easing.js

@@ -0,0 +1,30 @@
+import { easeInOut5 } from "@thi.ng/math/easing";
+import { norm } from "@thi.ng/math/fit";
+import { mix } from "@thi.ng/math/mix";
+import { Ramp } from "./ramp.js";
+const easing = (stops, opts) => new Ramp(EASING_N(opts?.easing), stops, opts);
+const EASING_N = (easing2 = easeInOut5) => {
+  return {
+    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 mix(a[1], b[1], easing2(norm(t, a[0], b[0])));
+    }
+  };
+};
+const EASING_V = (vec, easing2 = easeInOut5) => ({
+  min: (acc, x) => vec.min(acc, acc || vec.vecOf(Infinity), x),
+  max: (acc, x) => vec.max(acc, acc || vec.vecOf(-Infinity), x),
+  at: (stops, i, t) => {
+    const a = stops[i];
+    const b = stops[i + 1];
+    return vec.mixN([], a[1], b[1], easing2(norm(t, a[0], b[0])));
+  }
+});
+export {
+  EASING_N,
+  EASING_V,
+  easing
+};

package/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./api.js";
 export * from "./domain.js";
+export * from "./easing.js";
 export * from "./group.js";
 export * from "./hermite.js";
 export * from "./linear.js";

package/index.js

@@ -1,5 +1,6 @@
 export * from "./api.js";
 export * from "./domain.js";
+export * from "./easing.js";
 export * from "./group.js";
 export * from "./hermite.js";
 export * from "./linear.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/ramp",
-  "version": "3.1.34",
+  "version": "3.3.0",
   "description": "Extensible keyframe interpolation/tweening of arbitrary, nested types",
   "type": "module",
   "module": "./index.js",
@@ -40,9 +40,9 @@
     "@thi.ng/arrays": "^2.10.0",
     "@thi.ng/compare": "^2.4.1",
     "@thi.ng/errors": "^2.5.15",
-    "@thi.ng/math": "^5.11.8",
-    "@thi.ng/transducers": "^9.2.0",
-    "@thi.ng/vectors": "^7.11.10"
+    "@thi.ng/math": "^5.11.9",
+    "@thi.ng/transducers": "^9.2.2",
+    "@thi.ng/vectors": "^7.12.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.47.5",
@@ -95,6 +95,9 @@
     "./domain": {
       "default": "./domain.js"
     },
+    "./easing": {
+      "default": "./easing.js"
+    },
     "./group": {
       "default": "./group.js"
     },
@@ -117,5 +120,5 @@
   "thi.ng": {
     "year": 2019
   },
-  "gitHead": "bfbc227cf5ca2d3c2984b3d4713eebd6225cbd54\n"
+  "gitHead": "9f71f7f82fed2a980078a96bdafd2e706f526c75\n"
 }

package/ramp.d.ts

@@ -31,6 +31,7 @@ export declare class Ramp<T> implements ICopy<IRamp<T>>, IEmpty<IRamp<T>>, IRamp
     timeBounds(): [number, number];
     setStopAt(t: number, val: T, eps?: number): boolean;
     removeStopAt(t: number, eps?: number): boolean;
+    removeStopAtIndex(i: number): boolean;
     closestIndex(t: number, eps?: number): number;
     clampedIndexTime(i: number, t: number, eps?: number): number;
     sort(): void;

package/ramp.js

@@ -78,14 +78,13 @@ class Ramp {
     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;
+    return this.stops.length > 2 ? this.removeStopAtIndex(this.closestIndex(t, eps)) : false;
+  }
+  removeStopAtIndex(i) {
+    const stops = this.stops;
+    if (i < 0 || i >= stops.length || stops.length <= 2) return false;
+    stops.splice(i, 1);
+    return true;
   }
   closestIndex(t, eps = 0.01) {
     const stops = this.stops;