@thi.ng/ramp 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-08-28T14:01:19Z
+- **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,15 @@ 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

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.89 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/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.2.0",
+  "version": "3.3.0",
   "description": "Extensible keyframe interpolation/tweening of arbitrary, nested types",
   "type": "module",
   "module": "./index.js",
@@ -41,8 +41,8 @@
     "@thi.ng/compare": "^2.4.1",
     "@thi.ng/errors": "^2.5.15",
     "@thi.ng/math": "^5.11.9",
-    "@thi.ng/transducers": "^9.2.1",
-    "@thi.ng/vectors": "^7.11.11"
+    "@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": "502a0192bae48e69290870ea8a2767f8b81adee6\n"
+  "gitHead": "9f71f7f82fed2a980078a96bdafd2e706f526c75\n"
 }