feat(imago): add support for thi.ng/pixel int buffers as input

- update `processImage()`, update docs
- add `isIntBufferLike()` helper
- rename `src/units.ts` => `src/utils.ts`

Author: postspectacular

packages/imago/package.json

@@ -181,8 +181,8 @@
 		"./proc": {
 			"default": "./proc.js"
 		},
-		"./units": {
-			"default": "./units.js"
+		"./utils": {
+			"default": "./utils.js"
 		}
 	},
 	"thi.ng": {

packages/imago/src/api.ts

@@ -6,6 +6,7 @@ import type {
 	Keys,
 	Range1_4,
 	TypedArray,
+	UIntArray,
 } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type {
@@ -85,6 +86,17 @@ export interface Position {
 
 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,

packages/imago/src/index.ts

@@ -3,7 +3,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";

packages/imago/src/layers/color.ts

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { ColorLayer, CompLayerFn } from "../api.js";
-import { coerceColor, computeSize, positionOrGravity } from "../units.js";
+import { coerceColor, computeSize, positionOrGravity } from "../utils.js";
 
 export const colorLayerImpl: CompLayerFn = async (layer, _, ctx) => {
 	const {

packages/imago/src/layers/image.ts

@@ -2,7 +2,7 @@
 import { illegalArgs } from "@thi.ng/errors";
 import sharp from "sharp";
 import type { CompLayerFn, Dim, ImgLayer } from "../api.js";
-import { computeSize, ensureSize, positionOrGravity } from "../units.js";
+import { computeSize, ensureSize, positionOrGravity } from "../utils.js";
 
 export const imageLayerImpl: CompLayerFn = async (layer, _, ctx) => {
 	const {

packages/imago/src/layers/raw.ts

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { CompLayerFn, RawLayer } from "../api.js";
-import { positionOrGravity } from "../units.js";
+import { positionOrGravity } from "../utils.js";
 
 export const rawLayerImpl: CompLayerFn = async (layer, _, ctx) => {
 	const {

packages/imago/src/layers/svg.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { readText } from "@thi.ng/file-io";
 import type { CompLayerFn, SVGLayer } from "../api.js";
-import { positionOrGravity } from "../units.js";
+import { positionOrGravity } from "../utils.js";
 import { illegalArgs } from "@thi.ng/errors";
 
 export const svgLayerImpl: CompLayerFn = async (layer, _, ctx) => {

packages/imago/src/layers/text.ts

@@ -2,7 +2,7 @@
 import { isFunction } from "@thi.ng/checks";
 import { XML_SVG } from "@thi.ng/prefixes";
 import type { CompLayerFn, Dim, TextLayer } from "../api.js";
-import { computeSize, gravityFlags, positionOrGravity } from "../units.js";
+import { computeSize, gravityFlags, positionOrGravity } from "../utils.js";
 import { readText } from "@thi.ng/file-io";
 
 export const textLayerImpl: CompLayerFn = async (layer, _, ctx) => {

packages/imago/src/ops/crop.ts

@@ -8,7 +8,7 @@ import {
 	computeSizeWithAspect,
 	gravityPosition,
 	positionOrGravity,
-} from "../units.js";
+} from "../utils.js";
 
 export const cropProc: Processor = async (spec, input, ctx) => {
 	const { aspect, border, gravity, pos, size, ref, unit } = <CropSpec>spec;

packages/imago/src/ops/extend.ts

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { ExtendSpec, Processor } from "../api.js";
-import { coerceColor, computeMargins } from "../units.js";
+import { coerceColor, computeMargins } from "../utils.js";
 
 export const extendProc: Processor = async (spec, input, ctx) => {
 	const { bg, border, mode, ref, unit } = <ExtendSpec>spec;

packages/imago/src/ops/resize.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { isNumber } from "@thi.ng/checks";
 import { GRAVITY_POSITION, type Processor, type ResizeSpec } from "../api.js";
-import { coerceColor, computeSize } from "../units.js";
+import { coerceColor, computeSize } from "../utils.js";
 
 export const resizeProc: Processor = async (spec, input, ctx) => {
 	const { bg, filter, fit, gravity, ref, size, unit } = <ResizeSpec>spec;

packages/imago/src/ops/rotate.ts

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { Processor, RotateSpec } from "../api.js";
-import { coerceColor } from "../units.js";
+import { coerceColor } from "../utils.js";
 
 export const rotateProc: Processor = async (spec, input, _) => {
 	const { angle, bg, flipX, flipY } = <RotateSpec>spec;

packages/imago/src/proc.ts

@@ -1,10 +1,17 @@
 // SPDX-License-Identifier: Apache-2.0
+import type { Range1_4 } from "@thi.ng/api";
 import { isArrayBufferView, isString } from "@thi.ng/checks";
 import { defmulti } from "@thi.ng/defmulti";
 import { createTempFile, deleteFile } from "@thi.ng/file-io";
 import { ROOT } from "@thi.ng/logger";
 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";
 import { blurProc } from "./ops/blur.js";
 import { compositeProc } from "./ops/composite.js";
 import { cropProc } from "./ops/crop.js";
@@ -19,19 +26,19 @@ 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";
 
 // ROOT.set(new ConsoleLogger());
 export const LOGGER = ROOT.childLogger("imgproc");
 
 /**
- * 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)!
@@ -42,14 +49,22 @@ export const LOGGER = ROOT.childLogger("imgproc");
  * @param parentCtx
  */
 export const processImage = async (
-	src: string | BufferLike | ArrayBuffer | Sharp,
+	src: string | BufferLike | ArrayBuffer | IntBufferLike | Sharp,
 	specs: ProcSpec[],
 	opts: Partial<ImgProcOpts> = {},
 	parentCtx?: ImgProcCtx
 ) => {
 	let img =
 		isString(src) || isArrayBufferView(src)
 			? sharp(<string | BufferLike>src)
+			: isIntBufferLike(src)
+			? sharp(new Uint8Array(src.data.buffer), {
+					raw: {
+						width: src.width,
+						height: src.height,
+						channels: <Range1_4>src.format.channels.length,
+					},
+			  })
 			: <Sharp>src;
 	const meta = await img.metadata();
 	ensureSize(meta);

packages/imago/src/units.ts renamed to packages/imago/src/utils.ts

@@ -1,13 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { Maybe } from "@thi.ng/api";
-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 type { Metadata } from "sharp";
 import {
 	GRAVITY_MAP,
 	type Color,
 	type Dim,
 	type Gravity,
+	type IntBufferLike,
 	type Position,
 	type Sides,
 	type Size,
@@ -17,6 +25,12 @@ import {
 
 const round = Math.round;
 
+export const isIntBufferLike = (x: any): x is IntBufferLike =>
+	isNumber(x.width) &&
+	isNumber(x.height) &&
+	isTypedArray(x.data) &&
+	isPlainObject(x.format);
+
 export const ensureSize = (meta: Metadata) =>
 	!(isNumber(meta.width) && isNumber(meta.height)) &&
 	illegalArgs("can't determine image size");