@thi.ng/tensors 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-05-12T07:03:24Z
+- **Last updated**: 2025-06-05T12:59:44Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,28 @@ 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.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.6.0) (2025-06-05)
+
+#### 🚀 Features
+
+- update defOpRT()/defOpRTT() ([8099abc](https://github.com/thi-ng/umbrella/commit/8099abc))
+  - add optional `complete` fn to produce/transform final result (reducer like)
+- add mean() tensor op ([2f15d21](https://github.com/thi-ng/umbrella/commit/2f15d21))
+
+## [0.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.5.0) (2025-05-28)
+
+#### 🚀 Features
+
+- add convolve() (1D/2D/3D versions) ([bc9a6eb](https://github.com/thi-ng/umbrella/commit/bc9a6eb))
+- add `constant()`, refactor `ones()` ([8cdd68c](https://github.com/thi-ng/umbrella/commit/8cdd68c))
+- add convolution kernel presets ([e553f06](https://github.com/thi-ng/umbrella/commit/e553f06))
+  - add 1D/2D/3D sobel kernels
+  - add 2D box blur
+  - add 2D gaussian blur
+- add/update/rename convolution kernels ([025c7ba](https://github.com/thi-ng/umbrella/commit/025c7ba))
+- add `applyKernel()`, add/update kernel presets ([b8c2a7a](https://github.com/thi-ng/umbrella/commit/b8c2a7a))
+- add `fromFloatBuffer()` conversion ([d78a0d3](https://github.com/thi-ng/umbrella/commit/d78a0d3))
+
 ## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.4.0) (2025-05-12)
 
 #### 🚀 Features

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 206 standalone projects, maintained as part
+> This is one of 208 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -17,6 +17,8 @@
 - [About](#about)
 - [Built-in tensor operations](#built-in-tensor-operations)
   - [Broadcasting support](#broadcasting-support)
+  - [Convolution support](#convolution-support)
+  - [Conversions](#conversions)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -51,6 +53,7 @@ conventions are closely aligned to the ones used by the
 - [argMin](https://docs.thi.ng/umbrella/tensors/variables/argMin.html): Minimum component index/value
 - [clamp](https://docs.thi.ng/umbrella/tensors/variables/clamp.html): Tensor-tensor interval clamping
 - [clampN](https://docs.thi.ng/umbrella/tensors/variables/clampN.html): Tensor-scalar interval clamping
+- [convolve](https://docs.thi.ng/umbrella/tensors/variables/convolve.html): Tensor convolution (1D/2D/3D only)
 - [cos](https://docs.thi.ng/umbrella/tensors/variables/cos.html): Componentwise `Math.cos`
 - [diagonal](https://docs.thi.ng/umbrella/tensors/variables/diagonal.html): Diagonal extraction
 - [div](https://docs.thi.ng/umbrella/tensors/variables/div.html): Tensor-tensor division
@@ -149,6 +152,40 @@ print(add(null, tensor([[10, 20], [100, 200]]), tensor([[[1, 2], [3, 4]], [[5, 6
 //  107.0000  208.0000
 ```
 
+### Convolution support
+
+Tensor convolution is only possible if both the domain tensor and the kernel
+tensor have same dimensionality. No broadcasting support.
+
+The following kernel presets and tensor factories are included and can be used
+with
+[`convolve()`](https://docs.thi.ng/umbrella/tensors/variables/convolve.html):
+
+- `BOX_BLUR2(radius)`: Box blur kernel factory
+- `GAUSSION2(radius)`: Gaussian blur kernel factory
+- `EDGE2(radius)`: Edge/ridge detection kernel factory
+- `SOBEL1`: 1D Sobel kernel
+- `SOBEL2`: 2D Sobel kernel
+- `SOBEL3`: 3D Sobel kernel
+
+For more generalized convolution-like functionality, the following kernel
+factories can be used with
+[`applyKernel()`](https://docs.thi.ng/umbrella/tensors/variables/applyKernel.html):
+
+- `MAX2_POOL(width,height?)`: max pooling
+- `MIN2_POOL(width,height?)`: min pooling
+- `MAXIMA2(radius)`: local maxima detection
+- `MINIMA2(radius)`: local minima detection
+
+### Conversions
+
+The following functions can be used to convert/coerce other data structures into
+tensors:
+
+- [`fromFloatBuffer()`](https://docs.thi.ng/umbrella/tensors/functions/fromFloatBuffer.html):
+  Coerce [thi.ng/pixel] float buffer/image (or compatible data structures) into
+  a 2D/3D tensor
+
 ## Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -181,7 +218,7 @@ For Node.js REPL:
 const ten = await import("@thi.ng/tensors");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 8.08 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 9.40 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -275,4 +275,42 @@ export interface MultiTensorOp<TOP> {
     impl(dim?: number): Maybe<TOP>;
 }
 export type MultiTensorOpImpl<T> = T & MultiTensorOp<T>;
+/**
+ * Convolution kernel spec for use with {@link applyKernel}.
+ *
+ * @remarks
+ * Provided implementations:
+ *
+ * - {@link MAX2_MOORE}
+ * - {@link MAX2_VON_NEUMANN}
+ * - {@link MAXIMA2_MOORE}
+ * - {@link MAXIMA2_VON_NEUMANN}
+ */
+export interface KernelSpec<T = any> {
+    /**
+     * Kernel shape/size
+     */
+    shape: Shape;
+    /**
+     * Windowed intialization. Returns initial accumulator for each new kernel
+     * window.
+     */
+    init: () => T;
+    /**
+     * Windowed reduction function. Receives current accumulator, domain value
+     * and kernel-local coordinates. Returns updated accumulator.
+     *
+     * @param acc
+     * @param value
+     * @param coords
+     */
+    reduce: (acc: T, value: number, ...coords: number[]) => T;
+    /**
+     * Windowed reducer result function. Produces final result from current
+     * accumulator.
+     *
+     * @param acc
+     */
+    complete: (acc: T) => number;
+}
 //# sourceMappingURL=api.d.ts.map

package/apply-kernel.d.ts

@@ -0,0 +1,28 @@
+import type { KernelSpec, ITensor } from "./api.js";
+/**
+ * Generalized convolution using a set of kenrel functions instead of static
+ * kernel tensor (as with {@link convolve}). The kernel function is applied as a
+ * windowed reducer. For each window (size defined by the kernel), the
+ * {@link KernelSpec.init} function initializes an accumulator value. Then
+ * {@link KernelSpec.reduce} is called with the current accumulator, a domain
+ * value from tensor `a` and the current kernel coordinates. The final window
+ * result is produced by the kernel's {@link KernelSpec.complete} function.
+ *
+ * @remarks
+ * The output tensor has the same shape as domain `a`. If `pad = true`
+ * (default), edge values in `a` will be repeated, otherwise padded with given
+ * value. If `out` is null, a new tensor will be created using `a`'s storage
+ * backend.
+ *
+ * References:
+ *
+ * - https://en.wikipedia.org/wiki/Convolution
+ * - https://en.wikipedia.org/wiki/Kernel_(image_processing)#Convolution
+ *
+ * @param out - output tensor
+ * @param a - input tensor
+ * @param kernel - kernel spec
+ * @param pad - padding
+ */
+export declare const applyKernel: import("./api.js").MultiTensorOpImpl<(<T extends ITensor>(out: T | null, a: T, kernel: KernelSpec, pad?: true | number) => T)>;
+//# sourceMappingURL=apply-kernel.d.ts.map

package/apply-kernel.js

@@ -0,0 +1,163 @@
+import { top } from "./top.js";
+const applyKernel1 = (out, a, { init, reduce, complete, shape: [sxk] }, pad = true) => {
+  !out && (out = a.empty());
+  const {
+    data: odata,
+    offset: oo,
+    stride: [txo]
+  } = out;
+  const {
+    data: adata,
+    offset: oa,
+    shape: [sxa],
+    stride: [txa]
+  } = a;
+  const sxk2 = sxk >> 1;
+  const maxx = sxa - 1;
+  const repeat = pad === true;
+  let x, xx, i, acc, maskx;
+  for (x = 0; x < sxa; x++) {
+    for (acc = init(), i = 0; i < sxk; i++) {
+      xx = x + i - sxk2;
+      if (xx < 0) {
+        maskx = false;
+        xx = 0;
+      } else if (xx > maxx) {
+        maskx = false;
+        xx = maxx;
+      } else maskx = true;
+      acc = reduce(acc, maskx || repeat ? adata[oa + xx * txa] : pad, i);
+    }
+    odata[oo + x * txo] = complete(acc);
+  }
+  return out;
+};
+const applyKernel2 = (out, a, { init, reduce, complete, shape: [sxk, syk] }, pad = true) => {
+  !out && (out = a.empty());
+  const {
+    data: odata,
+    offset: oo,
+    stride: [txo, tyo]
+  } = out;
+  const {
+    data: adata,
+    offset: oa,
+    shape: [sxa, sya],
+    stride: [txa, tya]
+  } = a;
+  const sxk2 = sxk >> 1;
+  const syk2 = syk >> 1;
+  const maxx = sxa - 1;
+  const maxy = sya - 1;
+  const repeat = pad === true;
+  let x, xx, y, yy, oox, oax, i, j, acc, maskx, masky;
+  for (x = 0; x < sxa; x++) {
+    oox = oo + x * txo;
+    for (y = 0; y < sya; y++) {
+      for (acc = init(), i = 0; i < sxk; i++) {
+        xx = x + i - sxk2;
+        if (xx < 0) {
+          maskx = false;
+          xx = 0;
+        } else if (xx > maxx) {
+          maskx = false;
+          xx = maxx;
+        } else maskx = true;
+        oax = oa + xx * txa;
+        for (j = 0; j < syk; j++) {
+          yy = y + j - syk2;
+          if (yy < 0) {
+            masky = false;
+            yy = 0;
+          } else if (yy > maxy) {
+            masky = false;
+            yy = maxy;
+          } else masky = maskx;
+          acc = reduce(
+            acc,
+            masky || repeat ? adata[oax + yy * tya] : pad,
+            i,
+            j
+          );
+        }
+      }
+      odata[oox + y * tyo] = complete(acc);
+    }
+  }
+  return out;
+};
+const applyKernel3 = (out, a, { init, reduce, complete, shape: [sxk, syk, szk] }, pad = true) => {
+  !out && (out = a.empty());
+  const {
+    data: odata,
+    offset: oo,
+    stride: [txo, tyo, tzo]
+  } = out;
+  const {
+    data: adata,
+    offset: oa,
+    shape: [sxa, sya, sza],
+    stride: [txa, tya, tza]
+  } = a;
+  const sxk2 = sxk >> 1;
+  const syk2 = syk >> 1;
+  const szk2 = szk >> 1;
+  const maxx = sxa - 1;
+  const maxy = sya - 1;
+  const maxz = sza - 1;
+  const repeat = pad === true;
+  let x, xx, y, yy, z, zz, oox, oax, ooy, oay, i, j, k, acc, maskx, masky, maskz;
+  for (x = 0; x < sxa; x++) {
+    oox = oo + x * txo;
+    for (y = 0; y < sya; y++) {
+      ooy = oox + y * tyo;
+      for (z = 0; z < sza; z++) {
+        for (acc = init(), i = 0; i < sxk; i++) {
+          xx = x + i - sxk2;
+          if (xx < 0) {
+            maskx = false;
+            xx = 0;
+          } else if (xx > maxx) {
+            maskx = false;
+            xx = maxx;
+          } else maskx = true;
+          oax = oa + xx * txa;
+          for (j = 0; j < syk; j++) {
+            yy = y + j - syk2;
+            if (yy < 0) {
+              masky = false;
+              yy = 0;
+            } else if (yy > maxy) {
+              masky = false;
+              yy = maxy;
+            } else masky = maskx;
+            oay = oax + yy * tya;
+            for (k = 0; k < szk; k++) {
+              zz = z + k - szk2;
+              if (zz < 0) {
+                maskz = false;
+                zz = 0;
+              } else if (zz > maxz) {
+                maskz = false;
+                zz = maxz;
+              } else maskz = masky;
+              acc = reduce(
+                acc,
+                maskz || repeat ? adata[oay + zz * tza] : pad,
+                i,
+                j,
+                k
+              );
+            }
+          }
+        }
+        odata[ooy + z * tzo] = complete(acc);
+      }
+    }
+  }
+  return out;
+};
+const applyKernel = top(1, void 0, applyKernel1, applyKernel2, applyKernel3);
+export {
+  applyKernel
+};

package/convert.d.ts

@@ -0,0 +1,23 @@
+import type { NumericArray } from "@thi.ng/api";
+/**
+ * Simplified interface of thi.ng/pixel `FloatBuffer`, only defining parts
+ * relevant to the conversion.
+ */
+export interface FloatBufferLike {
+    size: [number, number];
+    stride: [number, number];
+    data: NumericArray;
+    format: {
+        size: number;
+    };
+}
+/**
+ * Helper function to coerce a thi.ng/pixel float buffer (or compatible data
+ * structures) into a tensor. Single-channel (i.e. grayscale) buffers will
+ * result in 2D tensors, otherwise 3D (with the innermost dimension representing
+ * different color channels). In all cases, this is a zero-copy operation.
+ *
+ * @param buffer
+ */
+export declare const fromFloatBuffer: ({ size: [sx, sy], stride: [tx, ty], data, format: { size }, }: FloatBufferLike) => import("./tensor.js").Tensor3<number> | import("./tensor.js").Tensor2<number>;
+//# sourceMappingURL=convert.d.ts.map

package/convert.js

@@ -0,0 +1,22 @@
+import { typedArrayType } from "@thi.ng/api/typedarray";
+import { tensor } from "./tensor.js";
+const fromFloatBuffer = ({
+  size: [sx, sy],
+  stride: [tx, ty],
+  data,
+  format: { size }
+}) => {
+  const type = typedArrayType(data);
+  return size > 1 ? tensor(type, [sy, sx, size], {
+    stride: [ty, tx, 1],
+    copy: false,
+    data
+  }) : tensor(type, [sy, sx], {
+    stride: [ty, tx],
+    copy: false,
+    data
+  });
+};
+export {
+  fromFloatBuffer
+};

package/convolve.d.ts

@@ -0,0 +1,20 @@
+import type { ITensor } from "./api.js";
+/**
+ * Tensor convolution (without broadcasting support).
+ *
+ * @remarks
+ * The output tensor has the same shape as domain `a`. Edge values in `a` will
+ * be repeated. If `out` is null, a new tensor will be created using `a`'s
+ * storage backend.
+ *
+ * References:
+ *
+ * - https://en.wikipedia.org/wiki/Convolution
+ * - https://en.wikipedia.org/wiki/Kernel_(image_processing)#Convolution
+ *
+ * @param out - output tensor
+ * @param a - input tensor
+ * @param k - kernel tensor
+ */
+export declare const convolve: import("./api.js").MultiTensorOpImpl<(<T extends ITensor>(out: T | null, a: T, k: T) => T)>;
+//# sourceMappingURL=convolve.d.ts.map

package/convolve.js

@@ -0,0 +1,140 @@
+import { top } from "./top.js";
+const convolve1 = (out, a, k) => {
+  !out && (out = a.empty());
+  const {
+    data: odata,
+    offset: oo,
+    stride: [txo]
+  } = out;
+  const {
+    data: adata,
+    offset: oa,
+    shape: [sxa],
+    stride: [txa]
+  } = a;
+  const {
+    data: kdata,
+    offset: ok,
+    shape: [sxk],
+    stride: [txk]
+  } = k;
+  const sxk2 = sxk >> 1;
+  const mx = sxa - 1;
+  let x, xx, i, sum;
+  for (x = 0; x < sxa; x++) {
+    for (sum = 0, i = 0; i < sxk; i++) {
+      xx = x + i - sxk2;
+      if (xx < 0) xx = 0;
+      else if (xx > mx) xx = mx;
+      sum += adata[oa + xx * txa] * kdata[ok + i * txk];
+    }
+    odata[oo + x * txo] = sum;
+  }
+  return out;
+};
+const convolve2 = (out, a, k) => {
+  !out && (out = a.empty());
+  const {
+    data: odata,
+    offset: oo,
+    stride: [txo, tyo]
+  } = out;
+  const {
+    data: adata,
+    offset: oa,
+    shape: [sxa, sya],
+    stride: [txa, tya]
+  } = a;
+  const {
+    data: kdata,
+    offset: ok,
+    shape: [sxk, syk],
+    stride: [txk, tyk]
+  } = k;
+  const sxk2 = sxk >> 1;
+  const syk2 = syk >> 1;
+  const mx = sxa - 1;
+  const my = sya - 1;
+  let x, xx, y, yy, oox, oax, okx, i, j, sum;
+  for (x = 0; x < sxa; x++) {
+    oox = oo + x * txo;
+    for (y = 0; y < sya; y++) {
+      for (sum = 0, i = 0; i < sxk; i++) {
+        xx = x + i - sxk2;
+        if (xx < 0) xx = 0;
+        else if (xx > mx) xx = mx;
+        oax = oa + xx * txa;
+        okx = ok + i * txk;
+        for (j = 0; j < syk; j++) {
+          yy = y + j - syk2;
+          if (yy < 0) yy = 0;
+          else if (yy > my) yy = my;
+          sum += adata[oax + yy * tya] * kdata[okx + j * tyk];
+        }
+      }
+      odata[oox + y * tyo] = sum;
+    }
+  }
+  return out;
+};
+const convolve3 = (out, a, k) => {
+  !out && (out = a.empty());
+  const {
+    data: odata,
+    offset: oo,
+    stride: [txo, tyo, tzo]
+  } = out;
+  const {
+    data: adata,
+    offset: oa,
+    shape: [sxa, sya, sza],
+    stride: [txa, tya, tza]
+  } = a;
+  const {
+    data: kdata,
+    offset: ok,
+    shape: [sxk, syk, szk],
+    stride: [txk, tyk, tzk]
+  } = k;
+  const sxk2 = sxk >> 1;
+  const syk2 = syk >> 1;
+  const szk2 = szk >> 1;
+  const mx = sxa - 1;
+  const my = sya - 1;
+  const mz = sza - 1;
+  let x, xx, y, yy, z, zz, oox, oax, okx, ooy, oay, oky, i, j, l, sum;
+  for (x = 0; x < sxa; x++) {
+    oox = oo + x * txo;
+    for (y = 0; y < sya; y++) {
+      ooy = oox + y * tyo;
+      for (z = 0; z < sza; z++) {
+        for (sum = 0, i = 0; i < sxk; i++) {
+          xx = x + i - sxk2;
+          if (xx < 0) xx = 0;
+          else if (xx > mx) xx = mx;
+          oax = oa + xx * txa;
+          okx = ok + i * txk;
+          for (j = 0; j < syk; j++) {
+            yy = y + j - syk2;
+            if (yy < 0) yy = 0;
+            else if (yy > my) yy = my;
+            oay = oax + yy * tya;
+            oky = okx + j * tyk;
+            for (l = 0; l < szk; l++) {
+              zz = z + l - szk2;
+              if (zz < 0) zz = 0;
+              else if (zz > mz) zz = mz;
+              sum += adata[oay + zz * tza] * kdata[oky + l * tzk];
+            }
+          }
+        }
+        odata[ooy + z * tzo] = sum;
+      }
+    }
+  }
+  return out;
+};
+const convolve = top(1, void 0, convolve1, convolve2, convolve3);
+export {
+  convolve
+};

package/defoprt.d.ts

@@ -1,12 +1,12 @@
-import type { Fn0 } from "@thi.ng/api";
-import type { TensorData, TensorOpRT } from "./api.js";
+import type { ITensor, TensorData, TensorOpRT } from "./api.js";
 /**
  * Higher order tensor reduction op factory. Takes given reduction `rfn` and
- * `init` function to produce an initial result. Returns a {@link TensorOpRT}
- * applying the given function component-wise.
+ * `init` function to produce an initial result and optional `complete` to
+ * produce the final result. Returns a {@link TensorOpRT} applying the given
+ * function component-wise.
  *
  * @param rfn
  * @param init
  */
-export declare const defOpRT: <A = number, B = A>(rfn: (acc: B, data: TensorData<A>, i: number) => B, init: Fn0<B>) => import("./api.js").MultiTensorOpImpl<TensorOpRT<A, B>>;
+export declare const defOpRT: <A = number, B = A>(rfn: (acc: B, data: TensorData<A>, i: number) => B, init: () => B, complete?: (acc: B, a: ITensor<A>) => B) => import("./api.js").MultiTensorOpImpl<TensorOpRT<A, B>>;
 //# sourceMappingURL=defoprt.d.ts.map

package/defoprt.js

@@ -1,5 +1,6 @@
+import { identity } from "@thi.ng/api/fn";
 import { top } from "./top.js";
-const defOpRT = (rfn, init) => {
+const defOpRT = (rfn, init, complete = identity) => {
   const f1 = (a) => {
     const {
       data,
@@ -11,7 +12,7 @@ const defOpRT = (rfn, init) => {
     for (let x = 0; x < sx; x++) {
       res = rfn(res, data, offset + x * tx);
     }
-    return res;
+    return complete(res, a);
   };
   const f2 = (a) => {
     const {
@@ -28,7 +29,7 @@ const defOpRT = (rfn, init) => {
         res = rfn(res, data, ox + y * ty);
       }
     }
-    return res;
+    return complete(res, a);
   };
   const f3 = (a) => {
     const {
@@ -48,7 +49,7 @@ const defOpRT = (rfn, init) => {
         }
       }
     }
-    return res;
+    return complete(res, a);
   };
   const f4 = (a) => {
     const {
@@ -71,7 +72,7 @@ const defOpRT = (rfn, init) => {
         }
       }
     }
-    return res;
+    return complete(res, a);
   };
   return top(
     0,

package/defoprtt.d.ts

@@ -1,14 +1,15 @@
-import type { Fn0 } from "@thi.ng/api";
-import type { TensorData, TensorOpRTT } from "./api.js";
+import type { ITensor, TensorData, TensorOpRTT } from "./api.js";
 /**
  * Higher order tensor reduction op factory. Takes given reduction `rfn` and
- * `init` function to produce an initial result. Returns a {@link TensorOpRTT}
- * applying the given function componentwise, by default with broadcasting rules
- * (see {@link broadcast} for details).
+ * `init` function to produce an initial result and optional `complete` to
+ * produce the final result. Returns a {@link TensorOpRTT} applying the given
+ * function componentwise, by default with broadcasting rules (see
+ * {@link broadcast} for details).
  *
  * @param rfn
  * @param init
+ * @param complete
  * @param useBroadcast
  */
-export declare const defOpRTT: <A = number, B = A>(rfn: (acc: B, adata: TensorData<A>, bdata: TensorData<A>, ia: number, ib: number) => B, init: Fn0<B>, useBroadcast?: boolean) => TensorOpRTT<A, B>;
+export declare const defOpRTT: <A = number, B = A>(rfn: (acc: B, adata: TensorData<A>, bdata: TensorData<A>, ia: number, ib: number) => B, init: () => B, complete?: (acc: B, a: ITensor<A>, b: ITensor<A>) => B, useBroadcast?: boolean) => TensorOpRTT<A, B>;
 //# sourceMappingURL=defoprtt.d.ts.map

package/defoprtt.js

@@ -1,5 +1,6 @@
+import { identity } from "@thi.ng/api/fn";
 import { broadcast } from "./broadcast.js";
-const defOpRTT = (rfn, init, useBroadcast = true) => {
+const defOpRTT = (rfn, init, complete = identity, useBroadcast = true) => {
   const f1 = (a, b) => {
     const {
       data: adata,
@@ -16,7 +17,7 @@ const defOpRTT = (rfn, init, useBroadcast = true) => {
     for (let x = 0; x < sx; x++) {
       res = rfn(res, adata, bdata, oa + x * txa, ob + x * txb);
     }
-    return res;
+    return complete(res, a, b);
   };
   const f2 = (a, b) => {
     const {
@@ -39,7 +40,7 @@ const defOpRTT = (rfn, init, useBroadcast = true) => {
         res = rfn(res, adata, bdata, oax + y * tya, obx + y * tyb);
       }
     }
-    return res;
+    return complete(res, a, b);
   };
   const f3 = (a, b) => {
     const {
@@ -66,7 +67,7 @@ const defOpRTT = (rfn, init, useBroadcast = true) => {
         }
       }
     }
-    return res;
+    return complete(res, a, b);
   };
   const f4 = (a, b) => {
     const {
@@ -103,7 +104,7 @@ const defOpRTT = (rfn, init, useBroadcast = true) => {
         }
       }
     }
-    return res;
+    return complete(res, a, b);
   };
   const impls = [, f1, f2, f3, f4];
   const wrapper = useBroadcast ? (a, b) => {

package/errors.d.ts

@@ -9,7 +9,7 @@ export declare const IllegalShapeError: {
         cause?: unknown;
     };
     captureStackTrace(targetObject: object, constructorOpt?: Function): void;
-    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
     stackTraceLimit: number;
 };
 export declare const illegalShape: (shape: NumericArray) => never;

package/index.d.ts

@@ -2,9 +2,12 @@ export * from "./abs.js";
 export * from "./add.js";
 export * from "./addn.js";
 export * from "./api.js";
+export * from "./apply-kernel.js";
 export * from "./broadcast.js";
 export * from "./clamp.js";
 export * from "./clampn.js";
+export * from "./convert.js";
+export * from "./convolve.js";
 export * from "./cos.js";
 export * from "./defopn.js";
 export * from "./defoprt.js";
@@ -24,12 +27,14 @@ export * from "./exp2.js";
 export * from "./filtered-indices.js";
 export * from "./format.js";
 export * from "./identity.js";
+export * from "./kernels.js";
 export * from "./log.js";
 export * from "./log2.js";
 export * from "./mag.js";
 export * from "./magsq.js";
 export * from "./max.js";
 export * from "./maxn.js";
+export * from "./mean.js";
 export * from "./min.js";
 export * from "./minn.js";
 export * from "./mul.js";

package/index.js

@@ -2,9 +2,12 @@ export * from "./abs.js";
 export * from "./add.js";
 export * from "./addn.js";
 export * from "./api.js";
+export * from "./apply-kernel.js";
 export * from "./broadcast.js";
 export * from "./clamp.js";
 export * from "./clampn.js";
+export * from "./convert.js";
+export * from "./convolve.js";
 export * from "./cos.js";
 export * from "./defopn.js";
 export * from "./defoprt.js";
@@ -24,12 +27,14 @@ export * from "./exp2.js";
 export * from "./filtered-indices.js";
 export * from "./format.js";
 export * from "./identity.js";
+export * from "./kernels.js";
 export * from "./log.js";
 export * from "./log2.js";
 export * from "./mag.js";
 export * from "./magsq.js";
 export * from "./max.js";
 export * from "./maxn.js";
+export * from "./mean.js";
 export * from "./min.js";
 export * from "./minn.js";
 export * from "./mul.js";

package/kernels.d.ts

@@ -0,0 +1,77 @@
+import type { KernelSpec } from "./api.js";
+/**
+ * 1D Sobel convolution kernel.
+ */
+export declare const SOBEL1: import("./tensor.js").Tensor1<number>;
+/**
+ * 2D Sobel convolution kernel (along outer axis).
+ *
+ * @remarks
+ * Use `SOBEL2.transpose([1, 0])` for inner axis.
+ */
+export declare const SOBEL2: import("./tensor.js").Tensor2<number>;
+/**
+ * 3D Sobel convolution kernel (along outer axis).
+ *
+ * @remarks
+ * Use `SOBEL3.transpose()` for other axes.
+ */
+export declare const SOBEL3: import("./tensor.js").Tensor3<number>;
+/**
+ * 2D edge detection convolution kernel factory for given integer radius `r`.
+ * Returns 2D tensor of size `2*r+1`.
+ *
+ * @param r
+ */
+export declare const EDGE2: (r: number) => import("./tensor.js").Tensor2<number>;
+/**
+ * 2D sharpen 3x3 kernel preset.
+ */
+export declare const SHARPEN2_3x3: import("./tensor.js").Tensor2<number>;
+/**
+ * 2D box blur convolution kernel factory for given integer radius `r`. Returns
+ * 2D tensor of size `2*r+1`.
+ *
+ * @param r
+ */
+export declare const BOX_BLUR2: (r: number) => import("./tensor.js").Tensor2<number>;
+/**
+ * 2D Gaussian blur kernel factory for given integer radius `r`. Returns 2D
+ * tensor of size `2r+1`.
+ *
+ * @param r -
+ */
+export declare const GAUSSIAN_BLUR2: (r: number) => import("./tensor.js").Tensor2<number>;
+/**
+ * Max. pool kernel factory for given window size and use with
+ * {@link applyKernel}. The kernel produces the maximum value in its window.
+ *
+ * @param w
+ * @param h
+ */
+export declare const MAX2_POOL: (w: number, h?: number) => KernelSpec<number>;
+/**
+ * Min. pool kernel factory for given window size and use with
+ * {@link applyKernel}. The kernel produces the minimum value in its window.
+ *
+ * @param w
+ * @param h
+ */
+export declare const MIN2_POOL: (w: number, h?: number) => KernelSpec<number>;
+/**
+ * Kernel factory for given integer radius `r` and use with {@link applyKernel}.
+ * The kernel marks local maxima within its window and produces only 0 or 1
+ * result values (where 1 is used to mark the maxima).
+ *
+ * @param r
+ */
+export declare const MAXIMA2: (r: number) => KernelSpec<[number, number]>;
+/**
+ * Kernel factory for given integer radius `r` and use with {@link applyKernel}.
+ * The kernel marks local minima within its window and produces only 0 or 1
+ * result values (where 1 is used to mark the minima).
+ *
+ * @param r
+ */
+export declare const MINIMA2: (r: number) => KernelSpec<[number, number]>;
+//# sourceMappingURL=kernels.d.ts.map

package/kernels.js

@@ -0,0 +1,117 @@
+import { identity } from "@thi.ng/api/fn";
+import { constant, tensor } from "./tensor.js";
+const SOBEL1 = tensor([-1, 0, 1]);
+const SOBEL2 = tensor([
+  [-1, -2, -1],
+  [0, 0, 0],
+  [1, 2, 1]
+]);
+const SOBEL3 = tensor([
+  [
+    [-1, -2, -1],
+    [-2, -4, -2],
+    [-1, -2, -1]
+  ],
+  [
+    [0, 0, 0],
+    [0, 0, 0],
+    [0, 0, 0]
+  ],
+  [
+    [1, 2, 1],
+    [2, 4, 2],
+    [1, 2, 1]
+  ]
+]);
+const EDGE2 = (r) => {
+  r |= 0;
+  const w = 2 * r + 1;
+  const data = new Array(w * w).fill(-1);
+  data[data.length >> 1] = w * w - 1;
+  return tensor("num", [w, w], { data, copy: false });
+};
+const SHARPEN2_3x3 = tensor([
+  [0, -1, 0],
+  [-1, 5, -1],
+  [0, -1, 0]
+]);
+const BOX_BLUR2 = (r) => {
+  r = 2 * r + 1;
+  return constant([r, r], 1 / (r * r), "num");
+};
+const GAUSSIAN_BLUR2 = (r) => {
+  r |= 0;
+  const sigma = -1 / (2 * (Math.SQRT2 * r / 3) ** 2);
+  const res = [];
+  let sum = 0;
+  for (let y = -r; y <= r; y++) {
+    for (let x = -r; x <= r; x++) {
+      const g = Math.exp((x * x + y * y) * sigma);
+      res.push(g);
+      sum += g;
+    }
+  }
+  const size = r * 2 + 1;
+  return tensor("num", [size, size], {
+    data: res.map((x) => x / sum),
+    copy: false
+  });
+};
+const { max, min } = Math;
+const MAX2_POOL = (w, h = w) => {
+  return {
+    shape: [w, h],
+    init: () => -Infinity,
+    reduce: (acc, val) => max(acc, val),
+    complete: identity
+  };
+};
+const MIN2_POOL = (w, h = w) => {
+  return {
+    shape: [w, h],
+    init: () => Infinity,
+    reduce: (acc, val) => min(acc, val),
+    complete: identity
+  };
+};
+const MAXIMA2 = (r) => {
+  r |= 0;
+  const w = 2 * r + 1;
+  return {
+    shape: [w, w],
+    init: () => [-Infinity, 0],
+    reduce: (acc, val, i, j) => {
+      if (i === r && j === r) acc[1] = val;
+      else acc[0] = max(acc[0], val);
+      return acc;
+    },
+    complete: (acc) => acc[1] > acc[0] ? 1 : 0
+  };
+};
+const MINIMA2 = (r) => {
+  r |= 0;
+  const w = 2 * r + 1;
+  return {
+    shape: [w, w],
+    init: () => [Infinity, 0],
+    reduce: (acc, val, i, j) => {
+      if (i === r && j === r) acc[1] = val;
+      else acc[0] = min(acc[0], val);
+      return acc;
+    },
+    complete: (acc) => acc[1] < acc[0] ? 1 : 0
+  };
+};
+export {
+  BOX_BLUR2,
+  EDGE2,
+  GAUSSIAN_BLUR2,
+  MAX2_POOL,
+  MAXIMA2,
+  MIN2_POOL,
+  MINIMA2,
+  SHARPEN2_3x3,
+  SOBEL1,
+  SOBEL2,
+  SOBEL3
+};

package/mean.d.ts

@@ -0,0 +1,8 @@
+import type { ITensor } from "./api.js";
+/**
+ * Computes the mean value of given nD tensor, aka `sum(a) / a.length`.
+ *
+ * @param a - input tensor
+ */
+export declare const mean: (a: ITensor) => number;
+//# sourceMappingURL=mean.d.ts.map

package/mean.js

@@ -0,0 +1,5 @@
+import { sum } from "./sum.js";
+const mean = (a) => sum(a) / a.length;
+export {
+  mean
+};

package/normalize.d.ts

@@ -7,5 +7,5 @@ import type { ITensor } from "./api.js";
  * @param a
  * @param n
  */
-export declare const normalize: (out: ITensor | null, a: ITensor, n?: number) => import("./tensor.js").Tensor1<any> | ITensor<number>;
+export declare const normalize: (out: ITensor | null, a: ITensor, n?: number) => ITensor<number> | import("./tensor.js").Tensor1<any>;
 //# sourceMappingURL=normalize.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/tensors",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "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.11.27",
-    "@thi.ng/arrays": "^2.11.0",
-    "@thi.ng/checks": "^3.7.7",
-    "@thi.ng/equiv": "^2.1.83",
-    "@thi.ng/errors": "^2.5.33",
-    "@thi.ng/math": "^5.11.27",
-    "@thi.ng/random": "^4.1.18",
-    "@thi.ng/strings": "^3.9.12",
-    "@thi.ng/vectors": "^8.2.0"
+    "@thi.ng/api": "^8.11.28",
+    "@thi.ng/arrays": "^2.11.1",
+    "@thi.ng/checks": "^3.7.8",
+    "@thi.ng/equiv": "^2.1.84",
+    "@thi.ng/errors": "^2.5.34",
+    "@thi.ng/math": "^5.11.28",
+    "@thi.ng/random": "^4.1.19",
+    "@thi.ng/strings": "^3.9.13",
+    "@thi.ng/vectors": "^8.2.1"
   },
   "devDependencies": {
-    "esbuild": "^0.25.3",
-    "typedoc": "^0.28.3",
+    "esbuild": "^0.25.5",
+    "typedoc": "^0.28.5",
     "typescript": "^5.8.3"
   },
   "keywords": [
@@ -62,19 +62,28 @@
     "activation",
     "algebra",
     "array",
+    "blur",
     "broadcast",
+    "convolution",
     "data-oriented",
     "datastructure",
     "decomposition",
+    "detect",
     "diagonal",
     "dotproduct",
+    "edge",
     "equality",
+    "filter",
+    "gaussian",
+    "gradient",
     "interval",
     "math",
     "matrix",
     "memory-mapped",
     "nd",
     "polymorphic",
+    "pool",
+    "presets",
     "random",
     "step",
     "svd",
@@ -113,6 +122,9 @@
     "./api": {
       "default": "./api.js"
     },
+    "./apply-kernel": {
+      "default": "./apply-kernel.js"
+    },
     "./broadcast": {
       "default": "./broadcast.js"
     },
@@ -122,6 +134,12 @@
     "./clampn": {
       "default": "./clampn.js"
     },
+    "./convert": {
+      "default": "./convert.js"
+    },
+    "./convolve": {
+      "default": "./convolve.js"
+    },
     "./cos": {
       "default": "./cos.js"
     },
@@ -179,6 +197,9 @@
     "./identity": {
       "default": "./identity.js"
     },
+    "./kernels": {
+      "default": "./kernels.js"
+    },
     "./log": {
       "default": "./log.js"
     },
@@ -197,6 +218,9 @@
     "./maxn": {
       "default": "./maxn.js"
     },
+    "./mean": {
+      "default": "./mean.js"
+    },
     "./min": {
       "default": "./min.js"
     },
@@ -301,5 +325,5 @@
     "status": "alpha",
     "year": 2018
   },
-  "gitHead": "99ea3cda41e61b66f3914c5c9c9b7bb60ee3ee84\n"
+  "gitHead": "5a1224bbd501c0dad203fa231749f21740350db7\n"
 }

package/swap.js

@@ -7,6 +7,7 @@ const $swap = defOpRTT(
   },
   () => {
   },
+  void 0,
   false
 );
 const swap = (a, b) => $swap(a, b);

package/tensor.d.ts

@@ -131,6 +131,7 @@ export declare function tensorFromArray<T extends NumType, N extends Nested<numb
 export declare function tensorFromArray<N extends Nested<string>>(data: N, opts?: TensorFromArrayOpts<"str", string>): NestedTensor<N, string>;
 export declare const zeroes: <S extends Shape>(shape: S, type?: NumType, storage?: ITensorStorage<number>) => ShapeTensor<S, number>;
 export declare const ones: <S extends Shape>(shape: S, type?: NumType, storage?: ITensorStorage<number>) => ShapeTensor<S, number>;
+export declare const constant: <T extends Type, S extends Shape>(shape: S, value: TypeMap[T], type: T, storage?: ITensorStorage<TypeMap[T]>) => ShapeTensor<S, TypeMap[T]>;
 export declare const shapeToStride: (shape: number[]) => any[];
 export declare const strideOrder: (strides: number[]) => number[];
 //# sourceMappingURL=tensor.d.ts.map

package/tensor.js

@@ -481,9 +481,10 @@ function tensorFromArray(data, opts) {
   });
 }
 const zeroes = (shape, type = "num", storage) => tensor(type, shape, { storage });
-const ones = (shape, type = "num", storage) => {
+const ones = (shape, type = "num", storage) => constant(shape, 1, type, storage);
+const constant = (shape, value, type, storage) => {
   const res = tensor(type, shape, { storage });
-  res.data.fill(1);
+  res.data.fill(value);
   return res;
 };
 const shapeToStride = (shape) => {
@@ -551,6 +552,7 @@ export {
   Tensor2,
   Tensor3,
   Tensor4,
+  constant,
   ones,
   shapeToStride,
   strideOrder,