@thi.ng/imago 1.0.17 → 1.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-04-16T11:11:14Z
+- **Last updated**: 2025-05-28T12:02:39Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,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.
 
+## [1.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@1.1.0) (2025-05-28)
+
+#### 🚀 Features
+
+- add support for [@thi.ng/pixel](https://github.com/thi-ng/umbrella/tree/main/packages/pixel) int buffers as input ([e0b6de6](https://github.com/thi-ng/umbrella/commit/e0b6de6))
+  - update `processImage()`, update docs
+  - add `isIntBufferLike()` helper
+  - rename `src/units.ts` => `src/utils.ts`
+
 ## [0.8.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.8.0) (2024-07-06)
 
 #### 🚀 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 205 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.
 >
@@ -360,7 +360,7 @@ For Node.js REPL:
 const imago = await import("@thi.ng/imago");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.94 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.00 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { Fn, Fn3, IObjectOf, Keys, Range1_4, TypedArray } from "@thi.ng/api";
+import type { Fn, Fn3, IObjectOf, Keys, Range1_4, TypedArray, UIntArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type { AvifOptions, Blend, Exif, ExtendWith, FitEnum, GifOptions, Jp2Options, JpegOptions, JxlOptions, KernelEnum, Metadata, OverlayOptions, PngOptions, Sharp, TiffOptions, TileOptions, WebpOptions } from "sharp";
 /**
@@ -40,6 +40,18 @@ export interface Position {
     b?: number;
 }
 export type BufferLike = TypedArray | Buffer;
+/**
+ * Simplified interface of thi.ng/pixel `IntBuffer`, only defining parts
+ * relevant to the conversion for {@link processImage}.
+ */
+export interface IntBufferLike {
+    width: number;
+    height: number;
+    format: {
+        channels: unknown[];
+    };
+    data: UIntArray;
+}
 export type Processor = Fn3<ProcSpec, Sharp, ImgProcCtx, Promise<[Sharp, boolean]>>;
 export type CompLayerFn = Fn3<CompLayer, Sharp, ImgProcCtx, Promise<OverlayOptions>>;
 export interface ProcSpec {

package/index.d.ts

@@ -2,7 +2,7 @@ export * from "./api.js";
 export * from "./ops.js";
 export * from "./path.js";
 export * from "./proc.js";
-export * from "./units.js";
+export * from "./utils.js";
 export * from "./layers/color.js";
 export * from "./layers/image.js";
 export * from "./layers/raw.js";

package/index.js

@@ -2,7 +2,7 @@ export * from "./api.js";
 export * from "./ops.js";
 export * from "./path.js";
 export * from "./proc.js";
-export * from "./units.js";
+export * from "./utils.js";
 export * from "./layers/color.js";
 export * from "./layers/image.js";
 export * from "./layers/raw.js";

package/layers/color.js

@@ -1,4 +1,4 @@
-import { coerceColor, computeSize, positionOrGravity } from "../units.js";
+import { coerceColor, computeSize, positionOrGravity } from "../utils.js";
 const colorLayerImpl = async (layer, _, ctx) => {
   const {
     type: __,

package/layers/image.js

@@ -1,6 +1,6 @@
 import { illegalArgs } from "@thi.ng/errors";
 import sharp from "sharp";
-import { computeSize, ensureSize, positionOrGravity } from "../units.js";
+import { computeSize, ensureSize, positionOrGravity } from "../utils.js";
 const imageLayerImpl = async (layer, _, ctx) => {
   const {
     type: __,

package/layers/raw.js

@@ -1,4 +1,4 @@
-import { positionOrGravity } from "../units.js";
+import { positionOrGravity } from "../utils.js";
 const rawLayerImpl = async (layer, _, ctx) => {
   const {
     type: __,

package/layers/svg.js

@@ -1,5 +1,5 @@
 import { readText } from "@thi.ng/file-io";
-import { positionOrGravity } from "../units.js";
+import { positionOrGravity } from "../utils.js";
 import { illegalArgs } from "@thi.ng/errors";
 const svgLayerImpl = async (layer, _, ctx) => {
   let {

package/layers/text.js

@@ -1,6 +1,6 @@
 import { isFunction } from "@thi.ng/checks";
 import { XML_SVG } from "@thi.ng/prefixes";
-import { computeSize, gravityFlags, positionOrGravity } from "../units.js";
+import { computeSize, gravityFlags, positionOrGravity } from "../utils.js";
 import { readText } from "@thi.ng/file-io";
 const textLayerImpl = async (layer, _, ctx) => {
   let {

package/ops/crop.js

@@ -6,7 +6,7 @@ import {
   computeSizeWithAspect,
   gravityPosition,
   positionOrGravity
-} from "../units.js";
+} from "../utils.js";
 const cropProc = async (spec, input, ctx) => {
   const { aspect, border, gravity, pos, size, ref, unit } = spec;
   if (border == null && size == null)

package/ops/extend.js

@@ -1,4 +1,4 @@
-import { coerceColor, computeMargins } from "../units.js";
+import { coerceColor, computeMargins } from "../utils.js";
 const extendProc = async (spec, input, ctx) => {
   const { bg, border, mode, ref, unit } = spec;
   const sides = computeMargins(border, ctx.size, ref, unit);

package/ops/resize.js

@@ -1,6 +1,6 @@
 import { isNumber } from "@thi.ng/checks";
 import { GRAVITY_POSITION } from "../api.js";
-import { coerceColor, computeSize } from "../units.js";
+import { coerceColor, computeSize } from "../utils.js";
 const resizeProc = async (spec, input, ctx) => {
   const { bg, filter, fit, gravity, ref, size, unit } = spec;
   const aspect = ctx.size[0] / ctx.size[1];

package/ops/rotate.js

@@ -1,4 +1,4 @@
-import { coerceColor } from "../units.js";
+import { coerceColor } from "../utils.js";
 const rotateProc = async (spec, input, _) => {
   const { angle, bg, flipX, flipY } = spec;
   if (flipX) input = input.flop();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/imago",
-  "version": "1.0.17",
+  "version": "1.1.0",
   "description": "JSON & API-based declarative and extensible image processing trees/pipelines",
   "type": "module",
   "module": "./index.js",
@@ -39,25 +39,25 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.26",
-    "@thi.ng/blurhash": "^1.0.13",
-    "@thi.ng/checks": "^3.7.6",
-    "@thi.ng/date": "^2.7.51",
-    "@thi.ng/defmulti": "^3.0.66",
-    "@thi.ng/errors": "^2.5.32",
-    "@thi.ng/file-io": "^2.1.35",
-    "@thi.ng/logger": "^3.1.7",
-    "@thi.ng/object-utils": "^1.1.22",
-    "@thi.ng/pixel": "^7.4.4",
-    "@thi.ng/pixel-dither": "^1.1.165",
-    "@thi.ng/prefixes": "^2.3.43",
-    "sharp": "^0.34.1"
+    "@thi.ng/api": "^8.11.28",
+    "@thi.ng/blurhash": "^1.0.15",
+    "@thi.ng/checks": "^3.7.8",
+    "@thi.ng/date": "^2.7.53",
+    "@thi.ng/defmulti": "^3.0.68",
+    "@thi.ng/errors": "^2.5.34",
+    "@thi.ng/file-io": "^2.1.37",
+    "@thi.ng/logger": "^3.1.9",
+    "@thi.ng/object-utils": "^1.1.24",
+    "@thi.ng/pixel": "^7.5.0",
+    "@thi.ng/pixel-dither": "^1.1.167",
+    "@thi.ng/prefixes": "^2.3.45",
+    "sharp": "^0.34.2"
   },
   "devDependencies": {
-    "@thi.ng/vectors": "^8.0.0",
-    "@types/node": "^22.14.1",
-    "esbuild": "^0.25.2",
-    "typedoc": "^0.28.2",
+    "@thi.ng/vectors": "^8.2.1",
+    "@types/node": "^22.15.21",
+    "esbuild": "^0.25.5",
+    "typedoc": "^0.28.5",
     "typescript": "^5.8.3"
   },
   "keywords": [
@@ -181,13 +181,13 @@
     "./proc": {
       "default": "./proc.js"
     },
-    "./units": {
-      "default": "./units.js"
+    "./utils": {
+      "default": "./utils.js"
     }
   },
   "thi.ng": {
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "c464b6948f92cba90c2ea75b59203dad894fb450\n"
+  "gitHead": "61c3833b7ef7d044621454b5ea4af885d39f065e\n"
 }

package/proc.d.ts

@@ -1,14 +1,14 @@
 import sharp, { type Sharp } from "sharp";
-import type { BufferLike, ImgProcCtx, ImgProcOpts, ProcSpec } from "./api.js";
+import type { BufferLike, ImgProcCtx, ImgProcOpts, IntBufferLike, ProcSpec } from "./api.js";
 export declare const LOGGER: import("@thi.ng/logger").ProxyLogger;
 /**
- * Main API function. Takes an image input (file path, buffer or existing Sharp
- * instance) and applies given processing pipeline specs in sequence. Returns a
- * promise of final processed image, input metadata (if any), an environment
- * object of arbitrary data (likely produced by custom ops/processors) and an
- * object of all written output paths (keyed by each output's
- * {@link OutputSpec.id}). The process pipeline can be additionally configured
- * via provided options.
+ * Main API function. Takes an image input (file path, Buffer, ArrayBuffer,
+ * thi.ng/pixel IntBuffer or an existing Sharp instance) and applies given
+ * processing pipeline specs in sequence. Returns a promise of final processed
+ * image, input metadata (if any), an environment object of arbitrary data
+ * (likely produced by custom ops/processors) and an object of all written
+ * output paths (keyed by each output's {@link OutputSpec.id}). The process
+ * pipeline can be additionally configured via provided options.
  *
  * @remarks
  * The `parentCtx` arg is internal use only (nested processors)!
@@ -18,7 +18,7 @@ export declare const LOGGER: import("@thi.ng/logger").ProxyLogger;
  * @param opts
  * @param parentCtx
  */
-export declare const processImage: (src: string | BufferLike | ArrayBuffer | Sharp, specs: ProcSpec[], opts?: Partial<ImgProcOpts>, parentCtx?: ImgProcCtx) => Promise<{
+export declare const processImage: (src: string | BufferLike | ArrayBuffer | IntBufferLike | Sharp, specs: ProcSpec[], opts?: Partial<ImgProcOpts>, parentCtx?: ImgProcCtx) => Promise<{
     img: sharp.Sharp;
     meta: sharp.Metadata;
     env: import("@thi.ng/api").IObjectOf<any>;

package/proc.js

@@ -17,10 +17,16 @@ import { nestProc } from "./ops/nest.js";
 import { outputProc } from "./ops/output.js";
 import { resizeProc } from "./ops/resize.js";
 import { rotateProc } from "./ops/rotate.js";
-import { ensureSize } from "./units.js";
+import { ensureSize, isIntBufferLike } from "./utils.js";
 const LOGGER = ROOT.childLogger("imgproc");
 const processImage = async (src, specs, opts = {}, parentCtx) => {
-  let img = isString(src) || isArrayBufferView(src) ? sharp(src) : src;
+  let img = isString(src) || isArrayBufferView(src) ? sharp(src) : isIntBufferLike(src) ? sharp(new Uint8Array(src.data.buffer), {
+    raw: {
+      width: src.width,
+      height: src.height,
+      channels: src.format.channels.length
+    }
+  }) : src;
   const meta = await img.metadata();
   ensureSize(meta);
   const ctx = {

package/{units.d.ts → utils.d.ts}

@@ -1,6 +1,7 @@
 import type { Maybe } from "@thi.ng/api";
 import type { Metadata } from "sharp";
-import { type Color, type Dim, type Gravity, type Position, type Sides, type Size, type SizeRef, type SizeUnit } from "./api.js";
+import { type Color, type Dim, type Gravity, type IntBufferLike, type Position, type Sides, type Size, type SizeRef, type SizeUnit } from "./api.js";
+export declare const isIntBufferLike: (x: any) => x is IntBufferLike;
 export declare const ensureSize: (meta: Metadata) => false;
 export declare const coerceColor: (col: Color) => string | {
     r: number;
@@ -39,4 +40,4 @@ export declare const refSize: ([w, h]: Dim, ref?: SizeRef) => Dim;
 export declare const computeSize: (size: Size, curr: Dim, ref?: SizeRef, unit?: SizeUnit) => Dim;
 export declare const computeSizeWithAspect: (size: number, [w, h]: Dim, aspect: number, unit?: SizeUnit, clamp?: boolean) => Dim;
 export declare const computeMargins: (size: Size | Sides, curr: Dim, ref?: SizeRef, unit?: SizeUnit) => Sides;
-//# sourceMappingURL=units.d.ts.map
+//# sourceMappingURL=utils.d.ts.map

package/{units.js → utils.js}

@@ -1,9 +1,17 @@
-import { isArray, isArrayLike, isNumber, isString } from "@thi.ng/checks";
+import {
+  isArray,
+  isArrayLike,
+  isNumber,
+  isPlainObject,
+  isString,
+  isTypedArray
+} from "@thi.ng/checks";
 import { illegalArgs } from "@thi.ng/errors";
 import {
   GRAVITY_MAP
 } from "./api.js";
 const round = Math.round;
+const isIntBufferLike = (x) => isNumber(x.width) && isNumber(x.height) && isTypedArray(x.data) && isPlainObject(x.format);
 const ensureSize = (meta) => !(isNumber(meta.width) && isNumber(meta.height)) && illegalArgs("can't determine image size");
 const coerceColor = (col) => isString(col) ? col : isArrayLike(col) ? { r: col[0], g: col[1], b: col[2], alpha: col[3] ?? 1 } : col;
 const positionOrGravity = ([w, h], parentSize, {
@@ -129,6 +137,7 @@ export {
   ensureSize,
   gravityFlags,
   gravityPosition,
+  isIntBufferLike,
   positionOrGravity,
   refSize
 };