@thi.ng/math 5.11.34 → 5.12.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-08-04T08:45:04Z
+- **Last updated**: 2025-09-01T16:38:35Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,17 @@ 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.
 
+## [5.12.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/math@5.12.0) (2025-09-01)
+
+#### 🚀 Features
+
+- add `mixTrilinear()` ([5914ced](https://github.com/thi-ng/umbrella/commit/5914ced))
+- add/update interpolation fns ([91e8fbd](https://github.com/thi-ng/umbrella/commit/91e8fbd))
+  - add defLanczos(), defMitchell()
+  - add mixKernel4()
+  - add interactive Desmos graphs
+  - update docs
+
 ## [5.11.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/math@5.11.0) (2024-06-21)
 
 #### 🚀 Features

package/README.md

@@ -77,7 +77,7 @@ For Node.js REPL:
 const math = await import("@thi.ng/math");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.80 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.01 KB
 
 ## Dependencies
 

package/mix.d.ts

@@ -27,8 +27,43 @@ export declare const mix: FnN3;
  * @param v - 2nd interpolation factor
  */
 export declare const mixBilinear: FnN6;
+/**
+ * Trilinear interpolation of given values (`a`..`h`) with interpolation factors
+ * `u`,`v`,`w` (in `[0,1]` range).
+ *
+ * @example
+ * ```text
+ * c +-------+ d
+ *   |\      :\
+ *   | \     : \
+ *   |g +-------+ h
+ *   |  |    :  |
+ * a +··|····+ b|
+ *    \ |     \ |
+ *     \|      \|
+ *    e +-------+ f
+ * ```
+ *
+ * @param a
+ * @param b
+ * @param c
+ * @param d
+ * @param e
+ * @param f
+ * @param g
+ * @param h
+ * @param u
+ * @param v
+ * @param w
+ */
+export declare const mixTrilinear: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, u: number, v: number, w: number) => number;
 /**
  * Computes quadratic bezier interpolation for normalized value `t`.
+ * Interpolated result is between end points `a` and `c` with `b` a control
+ * point.
+ *
+ * @remarks
+ * [Interactive graph](https://www.desmos.com/calculator/s3cvphot1o)
  *
  * @param a
  * @param b
@@ -37,7 +72,11 @@ export declare const mixBilinear: FnN6;
  */
 export declare const mixQuadratic: FnN4;
 /**
- * Computes cubic bezier interpolation for normalized value `t`.
+ * Computes cubic bezier interpolation for normalized value `t`. Interpolated
+ * result is between end points `a` and `d` with `b` and `c` control points.
+ *
+ * @remarks
+ * [Interactive graph](https://www.desmos.com/calculator/dfc6twzlmk)
  *
  * @param a
  * @param b
@@ -52,6 +91,7 @@ export declare const mixCubic: FnN5;
  * inform the tangent of the interpolation curve. The interpolated result is
  * that of `b` and `c`.
  *
+ * @remarks
  * Assumes all inputs are uniformly spaced. If that's not the case, use
  * {@link mixCubicHermite} with one of the tangent generators supporting
  * non-uniform spacing of points.
@@ -129,6 +169,27 @@ export declare const mixCubicHermiteFromPoints: FnN5;
  * @param v -
  */
 export declare const mixBicubic: (s00: number, s01: number, s02: number, s03: number, s10: number, s11: number, s12: number, s13: number, s20: number, s21: number, s22: number, s23: number, s30: number, s31: number, s32: number, s33: number, u: number, v: number) => number;
+/**
+ * Parametric interpolation function for 4 samples `a`...`d` and interpolation
+ * `kernel` and factor `t`. The interpolation is assumed to be between `b` and
+ * `c`, using `a` and `d` as neighbors. Interpolation factor `t` is in the [0,1]
+ * range.
+ *
+ * @remarks
+ * The `kernel` is avaluated for 4 different `t`s @ `t-1`, `t`, `t+1`, `t+2`
+ * (corresponding to samples `a`..`d`).
+ *
+ * This function can be used with e.g. {@link defLanczos} (filter radius=2) or
+ * {@link defMitchell}.
+ *
+ * @param kernel
+ * @param a
+ * @param b
+ * @param c
+ * @param d
+ * @param t
+ */
+export declare const mixKernel4: (kernel: FnN, a: number, b: number, c: number, d: number, t: number) => number;
 /**
  * Helper function for {@link mixCubicHermite}. Computes cardinal tangents based
  * on point neighbors of a point B (not given), i.e. `a` (predecessor) and `c`
@@ -318,12 +379,39 @@ export declare const sincNormalized: FnN2;
  * returns 0.
  *
  * @remarks
- * [Interactive graph](https://www.desmos.com/calculator/pmypqgefle)
+ * References:
+ *
+ * - [Interactive graph](https://www.desmos.com/calculator/ccpog9yol8)
+ * - https://en.wikipedia.org/wiki/Lanczos_resampling
  *
  * @param a -
  * @param t -
  */
 export declare const lanczos: FnN2;
+/**
+ * Higher-order version of {@link lanczos} for filter size `a` (should be 1, 2
+ * or 3). Returns function which takes single param `t` and computes its Lanczos
+ * filter coefficient.
+ *
+ * @param a
+ */
+export declare const defLanczos: (a: number) => FnN;
+/**
+ * Higher-order Mitchell-Netravali filter kernel for params `b` and `c`. Returns
+ * function which takes single param `t` and computes its filter coefficient.
+ *
+ * @remarks
+ * Default `b` and `c` values are: b=1/3, c=1/3. The returned function can be
+ * used with {@link mixKernel4}.
+ *
+ * References:
+ *
+ * - https://en.wikipedia.org/wiki/Mitchell%E2%80%93Netravali_filters
+ *
+ * @param b
+ * @param c
+ */
+export declare const defMitchell: (b?: number, c?: number) => (t: number) => number;
 /**
  * Sigmoid function for inputs arounds center bias.
  *

package/mix.js

@@ -5,6 +5,16 @@ const mixBilinear = (a, b, c, d, u, v) => {
   const iv = 1 - v;
   return a * iu * iv + b * u * iv + c * iu * v + d * u * v;
 };
+const mixTrilinear = (a, b, c, d, e, f, g, h, u, v, w) => {
+  const iu = 1 - u;
+  const iv = 1 - v;
+  const iw = 1 - w;
+  const uv = u * v;
+  const u_iv = u * iv;
+  const iu_v = iu * v;
+  const iuv = iu * iv;
+  return a * iuv * iw + b * u_iv * iw + c * iu_v * iw + d * uv * iw + e * iuv * w + f * u_iv * w + g * iu_v * w + h * uv * w;
+};
 const mixQuadratic = (a, b, c, t) => {
   const s = 1 - t;
   return a * s * s + b * 2 * s * t + c * t * t;
@@ -46,6 +56,7 @@ const mixBicubic = (s00, s01, s02, s03, s10, s11, s12, s13, s20, s21, s22, s23,
   mixCubicHermiteFromPoints(s30, s31, s32, s33, u),
   v
 );
+const mixKernel4 = (kernel, a, b, c, d, t) => a * kernel(t + 1) + b * kernel(t) + c * kernel(t - 1) + d * kernel(t - 2);
 const tangentCardinal = (prev, next, scale = 0.5, ta = 0, tc = 2) => scale * ((next - prev) / (tc - ta));
 const tangentDiff3 = (prev, curr, next, ta = 0, tb = 1, tc = 2) => 0.5 * ((next - curr) / (tc - tb) + (curr - prev) / (tb - ta));
 const tween = (f, from, to) => (t) => mix(from, to, f(t));
@@ -79,7 +90,24 @@ const cubicPulse = (w, c, t) => {
 };
 const sinc = (t) => t !== 0 ? Math.sin(t) / t : 1;
 const sincNormalized = (k, t) => sinc(PI * k * t);
-const lanczos = (a, t) => t !== 0 ? -a < t && t < a ? sinc(PI * t) * sinc(PI * t / a) : 0 : 1;
+const lanczos = (a, t) => t !== 0 ? -a < t && t < a ? (t *= PI, a * Math.sin(t) * Math.sin(t / a) / (t * t)) : 0 : 1;
+const defLanczos = (a) => (t) => lanczos(a, t);
+const defMitchell = (b = 1 / 3, c = 1 / 3) => {
+  const b12 = 12 * b;
+  const c6 = 6 * c;
+  const k1 = 12 - 9 * b - c6;
+  const k2 = -18 + b12 + c6;
+  const k3 = 6 - 2 * b;
+  const k4 = -b - c6;
+  const k5 = 6 * b + 30 * c;
+  const k6 = -b12 - 48 * c;
+  const k7 = 8 * b + 24 * c;
+  return (t) => {
+    if (t < 0) t = -t;
+    const t2 = t * t;
+    return t < 1 ? (k1 * t2 * t + k2 * t2 + k3) / 6 : t < 2 ? (k4 * t2 * t + k5 * t2 + k6 * t + k7) / 6 : 0;
+  };
+};
 const sigmoid = (bias, k, t) => t != bias ? 1 / (1 + Math.exp(-k * (t - bias))) : 0.5;
 const sigmoid01 = (k, t) => sigmoid(0.5, k, t);
 const sigmoid11 = (k, t) => sigmoid(0, k, t);
@@ -92,6 +120,8 @@ export {
   cosine,
   cubicPulse,
   decimated,
+  defLanczos,
+  defMitchell,
   ease,
   expFactor,
   gain,
@@ -107,7 +137,9 @@ export {
   mixCubicHermite,
   mixCubicHermiteFromPoints,
   mixHermite,
+  mixKernel4,
   mixQuadratic,
+  mixTrilinear,
   parabola,
   schlick,
   sigmoid,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/math",
-  "version": "5.11.34",
+  "version": "5.12.0",
   "description": "Assorted common math functions & utilities",
   "type": "module",
   "module": "./index.js",
@@ -42,11 +42,11 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.12.0"
+    "@thi.ng/api": "^8.12.2"
   },
   "devDependencies": {
-    "esbuild": "^0.25.8",
-    "typedoc": "^0.28.9",
+    "esbuild": "^0.25.9",
+    "typedoc": "^0.28.12",
     "typescript": "^5.9.2"
   },
   "keywords": [
@@ -144,5 +144,5 @@
   "thi.ng": {
     "year": 2013
   },
-  "gitHead": "d4e2e72dcdadf26da3400900f04f9eb0ebeb0a5b\n"
+  "gitHead": "e215a3e8de3809736ba0042c93bd8703a5a1a337\n"
 }