@thi.ng/tensors 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-08-16T18:12:02Z
+- **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,19 @@ 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.
 
+## [0.10.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.10.0) (2025-09-01)
+
+#### 🚀 Features
+
+- add 1D/2D/3D samplers and resampling fns ([2130067](https://github.com/thi-ng/umbrella/commit/2130067))
+  - add `defSampler1/2/3/4()` and supporting helpers
+  - add sampling kernel presets:
+    - `SAMPLE_NEAREST`
+    - `SAMPLE_LINEAR`
+    - `SAMPLE_CUBIC`
+    - `SAMPLE_LANCZOS` (higher order)
+  - add `resample1/2/3()` fns
+
 ## [0.9.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.9.0) (2025-08-16)
 
 #### 🚀 Features

package/README.md

@@ -250,7 +250,7 @@ For Node.js REPL:
 const ten = await import("@thi.ng/tensors");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 10.06 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 11.49 KB
 
 ## Dependencies
 

package/index.d.ts

@@ -50,6 +50,7 @@ export * from "./rand-distrib.js";
 export * from "./range.js";
 export * from "./relu.js";
 export * from "./relun.js";
+export * from "./sample.js";
 export * from "./select.js";
 export * from "./set.js";
 export * from "./setn.js";

package/index.js

@@ -50,6 +50,7 @@ export * from "./rand-distrib.js";
 export * from "./range.js";
 export * from "./relu.js";
 export * from "./relun.js";
+export * from "./sample.js";
 export * from "./select.js";
 export * from "./set.js";
 export * from "./setn.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/tensors",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "0D/1D/2D/3D/4D tensors with extensible polymorphic operations and customizable storage",
   "type": "module",
   "module": "./index.js",
@@ -39,19 +39,19 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.12.1",
-    "@thi.ng/arrays": "^2.13.10",
-    "@thi.ng/checks": "^3.7.17",
-    "@thi.ng/equiv": "^2.1.91",
-    "@thi.ng/errors": "^2.5.41",
-    "@thi.ng/math": "^5.11.35",
-    "@thi.ng/random": "^4.1.26",
-    "@thi.ng/strings": "^3.9.21",
-    "@thi.ng/vectors": "^8.6.5"
+    "@thi.ng/api": "^8.12.2",
+    "@thi.ng/arrays": "^2.13.11",
+    "@thi.ng/checks": "^3.7.18",
+    "@thi.ng/equiv": "^2.1.92",
+    "@thi.ng/errors": "^2.5.42",
+    "@thi.ng/math": "^5.12.0",
+    "@thi.ng/random": "^4.1.27",
+    "@thi.ng/strings": "^3.9.22",
+    "@thi.ng/vectors": "^8.6.6"
   },
   "devDependencies": {
-    "esbuild": "^0.25.8",
-    "typedoc": "^0.28.9",
+    "esbuild": "^0.25.9",
+    "typedoc": "^0.28.12",
     "typescript": "^5.9.2"
   },
   "keywords": [
@@ -268,6 +268,9 @@
     "./relun": {
       "default": "./relun.js"
     },
+    "./sample": {
+      "default": "./sample.js"
+    },
     "./select": {
       "default": "./select.js"
     },
@@ -339,5 +342,5 @@
     "status": "alpha",
     "year": 2018
   },
-  "gitHead": "b133e905b546bff0d244826684269cdbb2fcfa25\n"
+  "gitHead": "e215a3e8de3809736ba0042c93bd8703a5a1a337\n"
 }

package/sample.d.ts

@@ -0,0 +1,27 @@
+import type { Fn2, Fn3, Fn4, Fn5, FnN, FnN2 } from "@thi.ng/api";
+import type { ITensor } from "./api.js";
+import { type Tensor1 } from "./tensor.js";
+type BoundaryFn = FnN2;
+type Sampler1 = Fn2<ITensor, number, number>;
+type Sampler2 = Fn3<ITensor, number, number, number>;
+type Sampler3 = Fn4<ITensor, number, number, number, number>;
+type Sampler4 = Fn5<ITensor, number, number, number, number, number>;
+type BoundaryType = "clamp" | "mirror" | "wrap" | "zero";
+type SamplerType = "nearest" | "linear" | "cubic" | "lanczos";
+interface SamplerKernel {
+    radius: number;
+    weight: FnN;
+}
+export declare const SAMPLE_NEAREST: SamplerKernel;
+export declare const SAMPLE_LINEAR: SamplerKernel;
+export declare const SAMPLE_CUBIC: SamplerKernel;
+export declare const SAMPLE_LANCZOS: (r?: number) => SamplerKernel;
+export declare const defSampler1: (kernel: SamplerKernel | SamplerType, boundary?: BoundaryFn | BoundaryType) => Sampler1;
+export declare const defSampler2: (kernel: SamplerType | SamplerKernel | [SamplerType | SamplerKernel, SamplerType | SamplerKernel], boundary?: BoundaryType | BoundaryFn | [BoundaryType | BoundaryFn, BoundaryType | BoundaryFn]) => Sampler2;
+export declare const defSampler3: (kernel: SamplerType | SamplerKernel | [SamplerType | SamplerKernel, SamplerType | SamplerKernel, SamplerType | SamplerKernel], boundary?: BoundaryType | BoundaryFn | [BoundaryType | BoundaryFn, BoundaryType | BoundaryFn, BoundaryType | BoundaryFn]) => Sampler3;
+export declare const defSampler4: (kernel: SamplerType | SamplerKernel | [SamplerType | SamplerKernel, SamplerType | SamplerKernel, SamplerType | SamplerKernel, SamplerType | SamplerKernel], boundary?: BoundaryType | BoundaryFn | [BoundaryType | BoundaryFn, BoundaryType | BoundaryFn, BoundaryType | BoundaryFn, BoundaryType | BoundaryFn]) => Sampler4;
+export declare const resample1: (out: Tensor1, a: Tensor1, sampler: Sampler1) => Tensor1<number>;
+export declare const resample2: (out: ITensor, a: ITensor, [samplerX, samplerY]: Sampler1[]) => ITensor<number>;
+export declare const resample3: (out: ITensor, a: ITensor, [samplerX, samplerY, samplerZ]: Sampler1[]) => ITensor<number>;
+export {};
+//# sourceMappingURL=sample.d.ts.map

package/sample.js

@@ -0,0 +1,290 @@
+import { isArray } from "@thi.ng/checks/is-array";
+import { isString } from "@thi.ng/checks/is-string";
+import { PI } from "@thi.ng/math/api";
+import { clamp } from "@thi.ng/math/interval";
+import { tensor } from "./tensor.js";
+const { abs, floor, sin } = Math;
+const __boundaryClamp = (i, max) => clamp(i, 0, max - 1);
+const __boundaryWrap = (i, max) => (i % max + max) % max;
+const __boundaryMirror = (i, max) => {
+  if (max === 1) return 0;
+  const period = 2 * (max - 1);
+  i = (i % period + period) % period;
+  return i < max ? i : period - i;
+};
+const __boundaryZero = (i, max) => i >= 0 || i < max ? i : -1;
+const BOUNDARY_MODES = {
+  clamp: __boundaryClamp,
+  wrap: __boundaryWrap,
+  mirror: __boundaryMirror,
+  zero: __boundaryZero
+};
+const SAMPLE_NEAREST = {
+  radius: 1,
+  weight: (t) => t >= -0.5 && t < 0.5 ? 1 : 0
+};
+const SAMPLE_LINEAR = {
+  radius: 1,
+  weight: (t) => {
+    t = abs(t);
+    return t < 1 ? 1 - t : 0;
+  }
+};
+const SAMPLE_CUBIC = {
+  radius: 2,
+  weight: (t) => {
+    t = abs(t);
+    const a = -0.5;
+    return t < 2 ? t <= 1 ? ((a + 2) * t - (a + 3)) * t * t + 1 : ((a * t - 5 * a) * t + 8 * a) * t - 4 * a : 0;
+  }
+};
+const SAMPLE_LANCZOS = (r = 2) => ({
+  radius: r,
+  weight: (t) => {
+    if (t === 0) return 1;
+    if (t > -r && t < r) {
+      t *= PI;
+      return r * sin(t) * sin(t / r) / (t * t);
+    }
+    return 0;
+  }
+});
+const SAMPLER_TYPES = {
+  nearest: SAMPLE_NEAREST,
+  linear: SAMPLE_LINEAR,
+  cubic: SAMPLE_CUBIC,
+  lanczos: SAMPLE_LANCZOS(2)
+};
+const defSampler1 = (kernel, boundary = "clamp") => {
+  const index = __resolveBoundary(boundary);
+  const { radius, weight } = __resolveKernel(kernel);
+  return ({ data, shape: [sx], stride: [tx], offset }, x) => {
+    const c = floor(x);
+    let sum = 0;
+    let wsum = 0;
+    for (let k = -radius; k <= radius; k++) {
+      const $x = c + k;
+      const w = weight(x - $x);
+      if (w === 0) continue;
+      const i = index($x, sx);
+      if (i < 0) {
+        wsum += w;
+        continue;
+      }
+      sum += data[offset + i * tx] * w;
+      wsum += w;
+    }
+    return wsum !== 0 ? sum / wsum : 0;
+  };
+};
+const defSampler2 = (kernel, boundary = "clamp") => {
+  const [indexX, indexY] = (isArray(boundary) ? boundary : [boundary, boundary]).map(__resolveBoundary);
+  const [kernelX, kernelY] = isArray(kernel) ? kernel : [kernel, kernel];
+  const { radius: rx, weight: weightX } = __resolveKernel(kernelX);
+  const { radius: ry, weight: weightY } = __resolveKernel(kernelY);
+  const sizeY = 2 * ry + 1;
+  const cacheY = new Array(sizeY);
+  return ({ data, shape: [sx, sy], stride: [tx, ty], offset }, x, y) => {
+    const cx = floor(x);
+    const cy = floor(y);
+    let sum = 0;
+    let wsum = 0;
+    for (let i = 0; i < sizeY; i++) {
+      cacheY[i] = weightY(y - (cy + i - ry));
+    }
+    for (let kx = -rx; kx <= rx; kx++) {
+      const $x = cx + kx;
+      const ix = indexX($x, sx);
+      const wx = weightX(x - $x);
+      const idx = offset + ix * tx;
+      for (let ky = -ry; ky <= ry; ky++) {
+        const wy = cacheY[ky + ry];
+        const weight = wx * wy;
+        if (weight === 0) continue;
+        const iy = indexY(cy + ky, sy);
+        if (ix < 0 || iy < 0) {
+          wsum += weight;
+          continue;
+        }
+        sum += data[idx + iy * ty] * weight;
+        wsum += weight;
+      }
+    }
+    return wsum !== 0 ? sum / wsum : 0;
+  };
+};
+const defSampler3 = (kernel, boundary = "clamp") => {
+  const [indexX, indexY, indexZ] = (isArray(boundary) ? boundary : [boundary, boundary, boundary]).map(__resolveBoundary);
+  const [kernelX, kernelY, kernelZ] = (isArray(kernel) ? kernel : [kernel, kernel, kernel]).map(__resolveKernel);
+  const { radius: rx, weight: weightX } = kernelX;
+  const { radius: ry, weight: weightY } = kernelY;
+  const { radius: rz, weight: weightZ } = kernelZ;
+  const sizeY = 2 * ry + 1;
+  const sizeZ = 2 * rz + 1;
+  const cacheY = new Array(sizeY);
+  const cacheZ = new Array(sizeZ);
+  return ({ data, shape: [sx, sy, sz], stride: [tx, ty, tz], offset }, x, y, z) => {
+    const cx = floor(x);
+    const cy = floor(y);
+    const cz = floor(z);
+    let sum = 0;
+    let wsum = 0;
+    for (let i = 0; i < sizeY; i++) cacheY[i] = weightY(y - (cy + i - ry));
+    for (let i = 0; i < sizeZ; i++) cacheZ[i] = weightZ(z - (cz + i - rz));
+    for (let kx = -rx; kx <= rx; kx++) {
+      const $x = cx + kx;
+      const ix = indexX($x, sx);
+      const wx = weightX(x - $x);
+      const idxX = offset + ix * tx;
+      for (let ky = -ry; ky <= ry; ky++) {
+        const iy = indexY(cy + ky, sy);
+        const wy = cacheY[ky + ry];
+        const idxXY = idxX + iy * ty;
+        for (let kz = -rz; kz <= rz; kz++) {
+          const wz = cacheZ[kz + rz];
+          const weight = wx * wy * wz;
+          if (weight === 0) continue;
+          const iz = indexZ(cz + kz, sz);
+          if (ix < 0 || iy < 0 || iz < 0) {
+            wsum += weight;
+            continue;
+          }
+          sum += data[idxXY + iz * tz] * weight;
+          wsum += weight;
+        }
+      }
+    }
+    return wsum !== 0 ? sum / wsum : 0;
+  };
+};
+const defSampler4 = (kernel, boundary = "clamp") => {
+  const [indexX, indexY, indexZ, indexW] = (isArray(boundary) ? boundary : [boundary, boundary, boundary, boundary]).map(__resolveBoundary);
+  const [kernelX, kernelY, kernelZ, kernelW] = (isArray(kernel) ? kernel : [kernel, kernel, kernel, kernel]).map(__resolveKernel);
+  const { radius: rx, weight: weightX } = kernelX;
+  const { radius: ry, weight: weightY } = kernelY;
+  const { radius: rz, weight: weightZ } = kernelZ;
+  const { radius: rw, weight: weightW } = kernelW;
+  const sizeY = 2 * ry + 1;
+  const sizeZ = 2 * rz + 1;
+  const sizeW = 2 * rw + 1;
+  const cacheY = new Array(sizeY);
+  const cacheZ = new Array(sizeZ);
+  const cacheW = new Array(sizeW);
+  return ({ data, shape: [sx, sy, sz, sw], stride: [tx, ty, tz, tw], offset }, x, y, z, w) => {
+    const cx = floor(x);
+    const cy = floor(y);
+    const cz = floor(z);
+    const cw = floor(w);
+    let sum = 0;
+    let wsum = 0;
+    for (let i = 0; i < sizeY; i++) cacheY[i] = weightY(y - (cy + i - ry));
+    for (let i = 0; i < sizeZ; i++) cacheZ[i] = weightZ(z - (cz + i - rz));
+    for (let i = 0; i < sizeW; i++) cacheW[i] = weightW(w - (cw + i - rw));
+    for (let kx = -rx; kx <= rx; kx++) {
+      const $x = cx + kx;
+      const ix = indexX($x, sx);
+      const wx = weightX(x - $x);
+      const idxX = offset + ix * tx;
+      for (let ky = -ry; ky <= ry; ky++) {
+        const iy = indexY(cy + ky, sy);
+        const wy = cacheY[ky + ry];
+        const idxXY = idxX + iy * ty;
+        for (let kz = -rz; kz <= rz; kz++) {
+          const wz = cacheZ[kz + rz];
+          const iz = indexZ(cz + kz, sz);
+          const idxXYZ = idxXY + iz * tz;
+          for (let kw = -rw; kw <= rw; kw++) {
+            const ww = cacheW[kw + rw];
+            const weight = wx * wy * wz * ww;
+            if (weight === 0) continue;
+            const iw = indexW(cw + kw, sw);
+            if (ix < 0 || iy < 0 || iz < 0 || iw < 0) {
+              wsum += weight;
+              continue;
+            }
+            sum += data[idxXYZ + iw * tw] * weight;
+            wsum += w;
+          }
+        }
+      }
+    }
+    return wsum !== 0 ? sum / wsum : 0;
+  };
+};
+const __resolveBoundary = (mode) => isString(mode) ? BOUNDARY_MODES[mode] : mode ?? __boundaryClamp;
+const __resolveKernel = (kernel) => isString(kernel) ? SAMPLER_TYPES[kernel] : kernel;
+const resample1 = (out, a, sampler) => {
+  const {
+    data: odata,
+    shape: [sxo],
+    stride: [txo],
+    offset: oo
+  } = out;
+  const {
+    shape: [sxa]
+  } = a;
+  const scale = sxa / sxo;
+  for (let i = 0; i < sxo; i++) {
+    odata[oo + i * txo] = sampler(a, (i + 0.5) * scale - 0.5);
+  }
+  return out;
+};
+const resample2 = (out, a, [samplerX, samplerY]) => {
+  const {
+    shape: [_, syo]
+  } = out;
+  const {
+    shape: [sxa]
+  } = a;
+  const tmp = tensor("num", [sxa, syo]);
+  for (let x = 0; x < sxa; x++) {
+    resample1(tmp.pick([x, -1]), a.pick([x, -1]), samplerX);
+  }
+  for (let y = 0; y < syo; y++) {
+    resample1(out.pick([-1, y]), tmp.pick([-1, y]), samplerY);
+  }
+  return out;
+};
+const resample3 = (out, a, [samplerX, samplerY, samplerZ]) => {
+  const {
+    shape: [_, syo, szo]
+  } = out;
+  const {
+    shape: [sxa, sya]
+  } = a;
+  const tmpX = tensor("num", [sxa, sya, szo]);
+  for (let i = 0; i < sxa; i++) {
+    const src = a.pick([i]);
+    const dest = tmpX.pick([i]);
+    for (let j = 0; j < sya; j++) {
+      resample1(dest.pick([j]), src.pick([j]), samplerX);
+    }
+  }
+  const tmpY = tensor("num", [sxa, syo, szo]);
+  for (let i = 0; i < sxa; i++) {
+    const src = tmpX.pick([i]);
+    const dest = tmpY.pick([i]);
+    for (let j = 0; j < szo; j++) {
+      resample1(dest.pick([-1, j]), src.pick([-1, j]), samplerY);
+    }
+  }
+  for (let i = 0; i < syo; i++) {
+    for (let j = 0; j < szo; j++) {
+      resample1(out.pick([-1, i, j]), tmpY.pick([-1, i, j]), samplerZ);
+    }
+  }
+  return out;
+};
+export {
+  SAMPLE_CUBIC,
+  SAMPLE_LANCZOS,
+  SAMPLE_LINEAR,
+  SAMPLE_NEAREST,
+  defSampler1,
+  defSampler2,
+  defSampler3,
+  defSampler4,
+  resample1,
+  resample2,
+  resample3
+};