@thi.ng/imago 0.1.0

package/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./api.js";
+export * from "./ops.js";
+export * from "./path.js";
+export * from "./proc.js";
+export * from "./units.js";
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,5 @@
+export * from "./api.js";
+export * from "./ops.js";
+export * from "./path.js";
+export * from "./proc.js";
+export * from "./units.js";

package/ops.d.ts

@@ -0,0 +1,16 @@
+import type { BlurSpec, CompSpec, CropSpec, DitherSpec, EXIFSpec, ExtendSpec, GammaSpec, GrayscaleSpec, HSBLSpec, NestSpec, OutputSpec, ProcSpec, ResizeSpec, RotateSpec } from "./api.js";
+export declare const defSpec: <T extends ProcSpec>(type: T["type"]) => (opts: Omit<T, "type">) => T;
+export declare const blur: (opts: Omit<BlurSpec, "type">) => BlurSpec;
+export declare const composite: (opts: Omit<CompSpec, "type">) => CompSpec;
+export declare const crop: (opts: Omit<CropSpec, "type">) => CropSpec;
+export declare const dither: (opts: Omit<DitherSpec, "type">) => DitherSpec;
+export declare const exif: (opts: Omit<EXIFSpec, "type">) => EXIFSpec;
+export declare const extend: (opts: Omit<ExtendSpec, "type">) => ExtendSpec;
+export declare const gamma: (opts: Omit<GammaSpec, "type">) => GammaSpec;
+export declare const grayscale: (opts: Omit<GrayscaleSpec, "type">) => GrayscaleSpec;
+export declare const hsbl: (opts: Omit<HSBLSpec, "type">) => HSBLSpec;
+export declare const nest: (opts: Omit<NestSpec, "type">) => NestSpec;
+export declare const output: (opts: Omit<OutputSpec, "type">) => OutputSpec;
+export declare const resize: (opts: Omit<ResizeSpec, "type">) => ResizeSpec;
+export declare const rotate: (opts: Omit<RotateSpec, "type">) => RotateSpec;
+//# sourceMappingURL=ops.d.ts.map

package/ops.js

@@ -0,0 +1,30 @@
+const defSpec = (type) => (opts) => ({ type, ...opts });
+const blur = defSpec("blur");
+const composite = defSpec("composite");
+const crop = defSpec("crop");
+const dither = defSpec("dither");
+const exif = defSpec("exif");
+const extend = defSpec("extend");
+const gamma = defSpec("gamma");
+const grayscale = defSpec("gray");
+const hsbl = defSpec("hsbl");
+const nest = defSpec("nest");
+const output = defSpec("output");
+const resize = defSpec("resize");
+const rotate = defSpec("rotate");
+export {
+  blur,
+  composite,
+  crop,
+  defSpec,
+  dither,
+  exif,
+  extend,
+  gamma,
+  grayscale,
+  hsbl,
+  nest,
+  output,
+  resize,
+  rotate
+};

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "@thi.ng/imago",
+  "version": "0.1.0",
+  "description": "JSON & API-based declarative and extensible image processing trees/pipelines",
+  "type": "module",
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thi-ng/umbrella.git"
+  },
+  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/imago#readme",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/postspectacular"
+    },
+    {
+      "type": "patreon",
+      "url": "https://patreon.com/thing_umbrella"
+    }
+  ],
+  "author": "Karsten Schmidt (https://thi.ng)",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "yarn build:esbuild && yarn build:decl",
+    "build:decl": "tsc --declaration --emitDeclarationOnly",
+    "build:esbuild": "esbuild --format=esm --platform=neutral --target=es2022 --tsconfig=tsconfig.json --outdir=. src/**/*.ts",
+    "clean": "rimraf --glob '*.js' '*.d.ts' '*.map' doc",
+    "doc": "typedoc --excludePrivate --excludeInternal --out doc src/index.ts",
+    "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
+    "doc:readme": "bun ../../tools/src/module-stats.ts && bun ../../tools/src/readme.ts",
+    "pub": "yarn npm publish --access public",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@thi.ng/api": "^8.9.25",
+    "@thi.ng/checks": "^3.5.0",
+    "@thi.ng/date": "^2.6.0",
+    "@thi.ng/defmulti": "^3.0.25",
+    "@thi.ng/errors": "^2.4.18",
+    "@thi.ng/file-io": "^1.3.2",
+    "@thi.ng/logger": "^3.0.2",
+    "@thi.ng/pixel": "^6.1.10",
+    "@thi.ng/pixel-dither": "^1.1.108",
+    "sharp": "^0.33.2"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.40.1",
+    "@thi.ng/vectors": "^7.10.10",
+    "esbuild": "^0.20.0",
+    "rimraf": "^5.0.5",
+    "typedoc": "^0.25.7",
+    "typescript": "^5.3.3"
+  },
+  "keywords": [
+    "avif",
+    "batch",
+    "bitmap",
+    "blur",
+    "color",
+    "crop",
+    "composite",
+    "dither",
+    "exif",
+    "fileformat",
+    "gif",
+    "grayscale",
+    "image",
+    "jpeg",
+    "nested",
+    "no-browser",
+    "nodejs",
+    "pipeline",
+    "png",
+    "process",
+    "resize",
+    "svg",
+    "tiff",
+    "transformation",
+    "tree",
+    "typescript",
+    "webp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "browser": {
+    "process": false,
+    "setTimeout": false
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "./*.js",
+    "./*.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    },
+    "./ops": {
+      "default": "./ops.js"
+    },
+    "./path": {
+      "default": "./path.js"
+    },
+    "./proc": {
+      "default": "./proc.js"
+    },
+    "./units": {
+      "default": "./units.js"
+    }
+  },
+  "thi.ng": {
+    "status": "alpha",
+    "year": 2024
+  },
+  "gitHead": "4513a1c703bdbf0f0867f03e547e47692e415fac\n"
+}

package/path.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="node" />
+import type { TypedArray } from "@thi.ng/api";
+import type { ImgProcCtx } from "./api.js";
+/**
+ * Expands/replaces all `{xyz}`-templated identifiers in given file path.
+ *
+ * @remarks
+ * The following IDs are supported. Any others will remain as is.
+ *
+ * - date: yyyyMMdd
+ * - time: HHmmss
+ * - name: original base filename (w/o ext)
+ * - sha1/224/256/384/512: truncated hash of output
+ * - w: current width
+ * - h: current height
+ *
+ * @param path
+ * @param buf
+ * @param ctx
+ */
+export declare const formatPath: (path: string, buf: Buffer | TypedArray, ctx: ImgProcCtx) => string;
+//# sourceMappingURL=path.d.ts.map

package/path.js

@@ -0,0 +1,34 @@
+import { FMT_HHmmss_ALT, FMT_yyyyMMdd_ALT } from "@thi.ng/date";
+import { illegalArgs as unsupported } from "@thi.ng/errors";
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+const formatPath = (path, buf, ctx) => path.replace(/\{(\w+)\}/g, (match, id) => {
+  switch (id) {
+    case "name": {
+      !path && unsupported(
+        "cannot format `{name}`, image has no file source"
+      );
+      const name = basename(ctx.path);
+      const idx = name.lastIndexOf(".");
+      return idx > 0 ? name.substring(0, idx) : name;
+    }
+    case "sha1":
+    case "sha224":
+    case "sha256":
+    case "sha384":
+    case "sha512":
+      return createHash(id).update(buf).digest("hex").substring(0, 8);
+    case "w":
+      return String(ctx.size[0]);
+    case "h":
+      return String(ctx.size[1]);
+    case "date":
+      return FMT_yyyyMMdd_ALT();
+    case "time":
+      return FMT_HHmmss_ALT();
+  }
+  return match;
+});
+export {
+  formatPath
+};

package/proc.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="node" />
+import sharp, { type Sharp } from "sharp";
+import { type CompLayer, type ImgProcCtx, type ImgProcOpts, type ProcSpec } from "./api.js";
+export declare const LOGGER: import("@thi.ng/logger").ProxyLogger;
+export declare const processImage: (src: string | Buffer | Sharp, procs: ProcSpec[], opts?: Partial<ImgProcOpts>, parentCtx?: ImgProcCtx) => Promise<sharp.Sharp>;
+/**
+ * Extensible polymorphic function performing a single image processing step.
+ *
+ * @remarks
+ * The function returns a tuple of `[img, bake-flag]`. If the flag (2nd value)
+ * is true, the returned image will be serialized/baked to an internal buffer
+ * (also wiping any EXIF!) after the current processing step and then used as
+ * input for the next processing step.
+ *
+ * Due to most ops in sharp's API merely setting internal state rather than
+ * applying changes directly, all size or channel changing procs will require
+ * "baking" in order to produce predictable results... The {@link processImage}
+ * function checks this flag after each processing step and its down to each
+ * processor to determine if baking is required or not...
+ *
+ * @param spec
+ * @param img
+ * @param ctx
+ **/
+export declare const process: import("@thi.ng/defmulti").MultiFn3<ProcSpec, sharp.Sharp, ImgProcCtx, Promise<[sharp.Sharp, boolean]>>;
+export declare const defLayer: import("@thi.ng/defmulti").MultiFn3<CompLayer, sharp.Sharp, ImgProcCtx, Promise<sharp.OverlayOptions>>;
+//# sourceMappingURL=proc.d.ts.map

package/proc.js

@@ -0,0 +1,362 @@
+import { typedArray } from "@thi.ng/api";
+import { isArrayBufferView, isNumber, isString } from "@thi.ng/checks";
+import { defmulti } from "@thi.ng/defmulti";
+import { illegalArgs } from "@thi.ng/errors";
+import { readText, writeFile, writeJSON } from "@thi.ng/file-io";
+import { ROOT } from "@thi.ng/logger";
+import { ABGR8888, GRAY8, Lane, intBuffer } from "@thi.ng/pixel";
+import {
+  ATKINSON,
+  BURKES,
+  DIFFUSION_2D,
+  DIFFUSION_COLUMN,
+  DIFFUSION_ROW,
+  FLOYD_STEINBERG,
+  JARVIS_JUDICE_NINKE,
+  SIERRA2,
+  STUCKI,
+  defBayer,
+  ditherWith,
+  orderedDither
+} from "@thi.ng/pixel-dither";
+import { join, resolve } from "node:path";
+import sharp, {} from "sharp";
+import {
+  GRAVITY_POSITION
+} from "./api.js";
+import { formatPath } from "./path.js";
+import {
+  coerceColor,
+  computeMargins,
+  computeSize,
+  ensureSize,
+  gravityPosition,
+  positionOrGravity
+} from "./units.js";
+const LOGGER = ROOT.childLogger("imgproc");
+const DITHER_KERNELS = {
+  atkinson: ATKINSON,
+  burkes: BURKES,
+  column: DIFFUSION_COLUMN,
+  diffusion: DIFFUSION_2D,
+  floyd: FLOYD_STEINBERG,
+  jarvis: JARVIS_JUDICE_NINKE,
+  row: DIFFUSION_ROW,
+  sierra: SIERRA2,
+  stucki: STUCKI
+};
+const processImage = async (src, procs, opts = {}, parentCtx) => {
+  let img = isString(src) || isArrayBufferView(src.buffer) ? sharp(src) : src;
+  const meta = await img.metadata();
+  ensureSize(meta);
+  const ctx = {
+    path: isString(src) ? src : parentCtx?.path,
+    logger: opts?.logger || LOGGER,
+    size: [meta.width, meta.height],
+    channels: meta.channels,
+    meta,
+    opts
+  };
+  let bake;
+  for (let proc of procs) {
+    ctx.logger.debug("processing spec:", proc);
+    [img, bake] = await process(proc, img, ctx);
+    if (!bake) {
+      ctx.logger.debug("skip baking processor's results...");
+      continue;
+    }
+    const { data, info } = await img.raw().toBuffer({ resolveWithObject: true });
+    ctx.size = [info.width, info.height];
+    ctx.channels = info.channels;
+    img = sharp(data, {
+      raw: {
+        width: info.width,
+        height: info.height,
+        channels: info.channels
+      }
+    });
+  }
+  return img;
+};
+const process = defmulti(
+  (spec) => spec.type,
+  {},
+  {
+    blur: async (spec, input) => {
+      const { radius } = spec;
+      return [input.blur(1 + radius / 2), false];
+    },
+    composite: async (spec, input, ctx) => {
+      const { layers } = spec;
+      const layerSpecs = await Promise.all(
+        layers.map((l) => defLayer(l, input, ctx))
+      );
+      return [input.composite(layerSpecs), false];
+    },
+    crop: async (spec, input, ctx) => {
+      const { border, gravity, pos, size, ref, unit } = spec;
+      if (border == null && size == null)
+        illegalArgs("require `border` or `size` option");
+      if (border != null) {
+        const sides = computeMargins(border, ctx.size, ref, unit);
+        const [left2, right, top2, bottom] = sides;
+        return [
+          input.extract({
+            left: left2,
+            top: top2,
+            width: ctx.size[0] - left2 - right,
+            height: ctx.size[1] - top2 - bottom
+          }),
+          true
+        ];
+      }
+      const $size = computeSize(size, ctx.size, unit);
+      let left = 0, top = 0;
+      if (pos) {
+        ({ left = 0, top = 0 } = positionOrGravity(pos, gravity, $size, ctx.size, unit) || {});
+      } else {
+        [left, top] = gravityPosition(gravity || "c", $size, ctx.size);
+      }
+      return [
+        input.extract({
+          left,
+          top,
+          width: $size[0],
+          height: $size[1]
+        }),
+        true
+      ];
+    },
+    dither: async (spec, input, ctx) => {
+      let { mode, num = 2, rgb = false, size = 8 } = spec;
+      const [w, h] = ctx.size;
+      let raw;
+      if (rgb) {
+        const tmp = await input.clone().ensureAlpha(1).toColorspace("srgb").raw().toBuffer({ resolveWithObject: true });
+        raw = tmp.data.buffer;
+        rgb = tmp.info.channels === 4;
+      } else {
+        raw = (await input.clone().grayscale().raw().toBuffer()).buffer;
+      }
+      let img = intBuffer(
+        w,
+        h,
+        rgb ? ABGR8888 : GRAY8,
+        typedArray(rgb ? "u32" : "u8", raw)
+      );
+      if (mode === "bayer") {
+        orderedDither(
+          img,
+          defBayer(size),
+          rgb ? [num, num, num] : [num]
+        );
+      } else {
+        ditherWith(DITHER_KERNELS[mode], img, {
+          channels: rgb ? [Lane.RED, Lane.GREEN, Lane.BLUE] : void 0
+        });
+      }
+      if (!rgb)
+        img = img.as(ABGR8888);
+      return [
+        sharp(new Uint8Array(img.data.buffer), {
+          raw: {
+            width: img.width,
+            height: img.height,
+            channels: 4
+          }
+        }),
+        true
+      ];
+    },
+    exif: async (spec, input) => {
+      const { tags } = spec;
+      return [input.withExif(tags), false];
+    },
+    extend: async (spec, input, ctx) => {
+      const { bg, border, mode, ref, unit } = spec;
+      const sides = computeMargins(border, ctx.size, ref, unit);
+      const [left, right, top, bottom] = sides;
+      return [
+        input.extend({
+          left,
+          right,
+          top,
+          bottom,
+          background: coerceColor(bg || "#000"),
+          extendWith: mode
+        }),
+        true
+      ];
+    },
+    gamma: async (spec, input) => {
+      const { gamma } = spec;
+      return [input.gamma(gamma, 1), false];
+    },
+    gray: async (spec, input) => {
+      const { gamma } = spec;
+      if (gamma !== false) {
+        input = input.gamma(isNumber(gamma) ? gamma : void 0);
+      }
+      return [input.grayscale(), true];
+    },
+    hsbl: async (spec, input) => {
+      const { h = 0, s = 1, b = 1, l = 0 } = spec;
+      return [
+        input.modulate({
+          hue: h,
+          brightness: b,
+          saturation: s,
+          lightness: l * 255
+        }),
+        true
+      ];
+    },
+    nest: async (spec, input, ctx) => {
+      const { procs } = spec;
+      ctx.logger.debug("--- nest start ---");
+      await processImage(input.clone(), procs, ctx.opts, ctx);
+      ctx.logger.debug("--- nest end ---");
+      return [input, false];
+    },
+    output: async (spec, input, ctx) => {
+      const opts = spec;
+      const outDir = resolve(ctx.opts.outDir || ".");
+      let output = input.clone();
+      if (opts.raw) {
+        const { alpha = false, meta = false } = opts.raw !== true ? opts.raw : {};
+        if (alpha)
+          output = output.ensureAlpha();
+        const { data, info } = await output.raw().toBuffer({ resolveWithObject: true });
+        const path = join(outDir, formatPath(opts.path, data, ctx));
+        writeFile(path, data, null, ctx.logger);
+        if (meta) {
+          writeJSON(
+            path + ".meta.json",
+            info,
+            void 0,
+            void 0,
+            ctx.logger
+          );
+        }
+        return [input, false];
+      }
+      let format = /\.(\w+)$/.exec(opts.path)?.[1];
+      switch (format) {
+        case "avif":
+          if (opts.avif)
+            output = output.avif(opts.avif);
+          break;
+        case "gif":
+          if (opts.gif)
+            output = output.gif(opts.gif);
+          break;
+        case "jpg":
+        case "jpeg":
+          if (opts.jpeg)
+            output = output.jpeg(opts.jpeg);
+          break;
+        case "jp2":
+          if (opts.jp2)
+            output = output.jp2(opts.jp2);
+          break;
+        case "jxl":
+          if (opts.jxl)
+            output = output.jxl(opts.jxl);
+          break;
+        case "png":
+          if (opts.png)
+            output = output.png(opts.png);
+          break;
+        case "tiff":
+          if (opts.tiff)
+            output = output.tiff(opts.tiff);
+          break;
+        case "webp":
+          if (opts.webp)
+            output = output.webp(opts.webp);
+          break;
+      }
+      if (opts.tile)
+        output = output.tile(opts.tile);
+      if (format)
+        output = output.toFormat(format);
+      const result = await output.toBuffer();
+      writeFile(
+        join(outDir, formatPath(opts.path, result, ctx)),
+        result,
+        null,
+        ctx.logger
+      );
+      return [input, false];
+    },
+    resize: async (spec, input, ctx) => {
+      const { bg, filter, fit, gravity, size, unit } = spec;
+      const [width, height] = computeSize(size, ctx.size, unit);
+      return [
+        input.resize({
+          width,
+          height,
+          fit,
+          kernel: filter,
+          position: gravity ? GRAVITY_POSITION[gravity] : void 0,
+          background: bg ? coerceColor(bg) : void 0
+        }),
+        true
+      ];
+    },
+    rotate: async (spec, input, _) => {
+      const { angle, bg, flipX, flipY } = spec;
+      if (flipX)
+        input = input.flop();
+      if (flipY)
+        input = input.flip();
+      return [input.rotate(angle, { background: coerceColor(bg) }), true];
+    }
+  }
+);
+const defLayer = defmulti(
+  (x) => x.type,
+  {},
+  {
+    img: async (layer, _, ctx) => {
+      const { gravity, path, pos, size, unit, ...opts } = layer;
+      const input = sharp(path);
+      const meta = await input.metadata();
+      let imgSize = [meta.width, meta.height];
+      const $pos = positionOrGravity(
+        pos,
+        gravity,
+        imgSize,
+        ctx.size,
+        unit
+      );
+      if (!size)
+        return { input: path, ...$pos, ...opts };
+      ensureSize(meta);
+      imgSize = computeSize(size, imgSize, unit);
+      return {
+        input: await input.resize(imgSize[0], imgSize[1]).png({ compressionLevel: 0 }).toBuffer(),
+        ...$pos,
+        ...opts
+      };
+    },
+    svg: async (layer, _, ctx) => {
+      let { body, gravity, path, pos, unit, ...opts } = layer;
+      if (path)
+        body = readText(path, ctx.logger);
+      const w = +(/width="(\d+)"/.exec(body)?.[1] || 0);
+      const h = +(/height="(\d+)"/.exec(body)?.[1] || 0);
+      return {
+        input: Buffer.from(body),
+        ...positionOrGravity(pos, gravity, [w, h], ctx.size, unit),
+        ...opts
+      };
+    }
+  }
+);
+export {
+  LOGGER,
+  defLayer,
+  process,
+  processImage
+};

package/units.d.ts

@@ -0,0 +1,24 @@
+import type { Nullable } from "@thi.ng/api";
+import type { Metadata } from "sharp";
+import { type Color, type CompLayer, type Dim, type Gravity, type Sides, type Size, type SizeRef, type SizeUnit } from "./api.js";
+export declare const ensureSize: (meta: Metadata) => false;
+export declare const coerceColor: (col: Color) => string | {
+    r: number;
+    g: number;
+    b: number;
+    alpha?: number | undefined;
+};
+export declare const positionOrGravity: (pos: CompLayer["pos"], gravity: Nullable<Gravity>, [w, h]: Dim, [parentW, parentH]: Dim, unit?: SizeUnit) => {
+    gravity: string;
+    left?: undefined;
+    top?: undefined;
+} | {
+    left: number | undefined;
+    top: number | undefined;
+    gravity?: undefined;
+} | undefined;
+export declare const gravityPosition: (gravity: Gravity, [w, h]: Dim, [parentW, parentH]: Dim) => number[];
+export declare const refSize: ([w, h]: Dim, ref?: SizeRef) => number;
+export declare const computeSize: (size: Size, curr: Dim, unit?: SizeUnit) => Dim;
+export declare const computeMargins: (size: Size | Sides, curr: Dim, ref?: SizeRef, unit?: SizeUnit) => Sides;
+//# sourceMappingURL=units.d.ts.map