@thi.ng/imago 0.1.0 → 0.3.0

package/ops/dither.js

@@ -0,0 +1,68 @@
+import { typedArray } from "@thi.ng/api";
+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 sharp from "sharp";
+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 ditherProc = 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
+  ];
+};
+export {
+  ditherProc
+};

package/ops/exif.d.ts

@@ -0,0 +1,3 @@
+import type { Processor } from "../api.js";
+export declare const exifProc: Processor;
+//# sourceMappingURL=exif.d.ts.map

package/ops/exif.js

@@ -0,0 +1,9 @@
+import { meldDeepObj } from "@thi.ng/associative";
+const exifProc = async (spec, input, ctx) => {
+  const { tags } = spec;
+  meldDeepObj(ctx.exif, tags);
+  return [input, false];
+};
+export {
+  exifProc
+};

package/ops/extend.d.ts

@@ -0,0 +1,3 @@
+import type { Processor } from "../api.js";
+export declare const extendProc: Processor;
+//# sourceMappingURL=extend.d.ts.map

package/ops/extend.js

@@ -0,0 +1,20 @@
+import { coerceColor, computeMargins } from "../units.js";
+const extendProc = 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
+  ];
+};
+export {
+  extendProc
+};

package/ops/gamma.d.ts

@@ -0,0 +1,3 @@
+import type { Processor } from "../api.js";
+export declare const gammaProc: Processor;
+//# sourceMappingURL=gamma.d.ts.map

package/ops/gamma.js

@@ -0,0 +1,7 @@
+const gammaProc = async (spec, input) => {
+  const { gamma } = spec;
+  return [input.gamma(gamma, 1), false];
+};
+export {
+  gammaProc
+};

package/ops/grayscale.d.ts

@@ -0,0 +1,3 @@
+import type { Processor } from "../api.js";
+export declare const grayscaleProc: Processor;
+//# sourceMappingURL=grayscale.d.ts.map

package/ops/grayscale.js

@@ -0,0 +1,11 @@
+import { isNumber } from "@thi.ng/checks";
+const grayscaleProc = async (spec, input) => {
+  const { gamma } = spec;
+  if (gamma !== false) {
+    input = input.gamma(isNumber(gamma) ? gamma : void 0);
+  }
+  return [input.grayscale(), true];
+};
+export {
+  grayscaleProc
+};

package/ops/hsbl.d.ts

@@ -0,0 +1,3 @@
+import type { Processor } from "../api.js";
+export declare const hsblProc: Processor;
+//# sourceMappingURL=hsbl.d.ts.map

package/ops/hsbl.js

@@ -0,0 +1,15 @@
+const hsblProc = 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
+  ];
+};
+export {
+  hsblProc
+};

package/ops/nest.d.ts

@@ -0,0 +1,3 @@
+import type { Processor } from "../api.js";
+export declare const nestProc: Processor;
+//# sourceMappingURL=nest.d.ts.map

package/ops/nest.js

@@ -0,0 +1,13 @@
+import { processImage } from "../proc.js";
+const nestProc = async (spec, input, ctx) => {
+  const { procs } = spec;
+  ctx.logger.debug("--- nest start ---");
+  await Promise.all(
+    procs.map((p) => processImage(input.clone(), p, ctx.opts, ctx))
+  );
+  ctx.logger.debug("--- nest end ---");
+  return [input, false];
+};
+export {
+  nestProc
+};

package/ops/output.d.ts

@@ -0,0 +1,3 @@
+import type { Processor } from "../api.js";
+export declare const outputProc: Processor;
+//# sourceMappingURL=output.d.ts.map

package/ops/output.js

@@ -0,0 +1,95 @@
+import { writeFile, writeJSON } from "@thi.ng/file-io";
+import { join, resolve } from "node:path";
+import { formatPath } from "../path.js";
+import { isPlainObject } from "@thi.ng/checks";
+const outputProc = async (spec, input, ctx) => {
+  const opts = spec;
+  const outDir = resolve(ctx.opts.outDir || ".");
+  let output = input.clone();
+  if (opts.raw) {
+    await outputRaw(opts, output, ctx, outDir);
+    return [input, false];
+  }
+  if (ctx.meta.exif && ctx.opts.keepEXIF) {
+    ctx.logger.warn(
+      "TODO injecting & merging EXIF in output still not supported"
+    );
+  }
+  if (Object.keys(ctx.exif).length) {
+    ctx.logger.debug("setting custom EXIF", ctx.exif);
+    output = output.withExif(ctx.exif);
+  }
+  if (ctx.iccFile && ctx.opts.keepICC) {
+    ctx.logger.debug("using stored ICC profile:", ctx.iccFile);
+    output = output.withIccProfile(ctx.iccFile);
+  }
+  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();
+  const path = join(
+    outDir,
+    formatPath(opts.path, ctx, spec, result)
+  );
+  writeFile(path, result, null, ctx.logger);
+  ctx.outputs[opts.id] = path;
+  return [input, false];
+};
+const outputRaw = async (opts, output, ctx, outDir) => {
+  const { alpha = false, meta = false } = isPlainObject(opts.raw) ? opts.raw : {};
+  if (alpha)
+    output = output.ensureAlpha();
+  const { data, info } = await output.raw().toBuffer({ resolveWithObject: true });
+  const path = join(outDir, formatPath(opts.path, ctx, opts, data));
+  writeFile(path, data, null, ctx.logger);
+  ctx.outputs[opts.id] = path;
+  if (meta) {
+    writeJSON(
+      path + ".meta.json",
+      { ...info, exif: ctx.exif },
+      void 0,
+      void 0,
+      ctx.logger
+    );
+  }
+};
+export {
+  outputProc
+};

package/ops/resize.d.ts

@@ -0,0 +1,3 @@
+import { type Processor } from "../api.js";
+export declare const resizeProc: Processor;
+//# sourceMappingURL=resize.d.ts.map

package/ops/resize.js

@@ -0,0 +1,20 @@
+import { GRAVITY_POSITION } from "../api.js";
+import { coerceColor, computeSize } from "../units.js";
+const resizeProc = 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
+  ];
+};
+export {
+  resizeProc
+};

package/ops/rotate.d.ts

@@ -0,0 +1,3 @@
+import type { Processor } from "../api.js";
+export declare const rotateProc: Processor;
+//# sourceMappingURL=rotate.d.ts.map

package/ops/rotate.js

@@ -0,0 +1,12 @@
+import { coerceColor } from "../units.js";
+const rotateProc = 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];
+};
+export {
+  rotateProc
+};

package/ops.d.ts

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

package/ops.js

@@ -1,4 +1,4 @@
-const defSpec = (type) => (opts) => ({ type, ...opts });
+const defSpec = (op) => (opts) => ({ op, ...opts });
 const blur = defSpec("blur");
 const composite = defSpec("composite");
 const crop = defSpec("crop");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/imago",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "JSON & API-based declarative and extensible image processing trees/pipelines",
   "type": "module",
   "module": "./index.js",
@@ -37,18 +37,19 @@
   "dependencies": {
     "@thi.ng/api": "^8.9.25",
     "@thi.ng/checks": "^3.5.0",
-    "@thi.ng/date": "^2.6.0",
+    "@thi.ng/date": "^2.7.0",
     "@thi.ng/defmulti": "^3.0.25",
     "@thi.ng/errors": "^2.4.18",
-    "@thi.ng/file-io": "^1.3.2",
+    "@thi.ng/file-io": "^1.3.3",
     "@thi.ng/logger": "^3.0.2",
-    "@thi.ng/pixel": "^6.1.10",
-    "@thi.ng/pixel-dither": "^1.1.108",
+    "@thi.ng/pixel": "^6.1.11",
+    "@thi.ng/pixel-dither": "^1.1.109",
+    "exif-reader": "^2.0.1",
     "sharp": "^0.33.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.40.1",
-    "@thi.ng/vectors": "^7.10.10",
+    "@thi.ng/vectors": "^7.10.11",
     "esbuild": "^0.20.0",
     "rimraf": "^5.0.5",
     "typedoc": "^0.25.7",
@@ -95,7 +96,9 @@
   },
   "files": [
     "./*.js",
-    "./*.d.ts"
+    "./*.d.ts",
+    "layers",
+    "ops"
   ],
   "exports": {
     ".": {
@@ -121,5 +124,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "4513a1c703bdbf0f0867f03e547e47692e415fac\n"
+  "gitHead": "c744c5f804ca763bc03163a41a0e150d8e7a9e54\n"
 }

package/path.d.ts

@@ -1,22 +1,34 @@
 /// <reference types="node" />
 import type { TypedArray } from "@thi.ng/api";
-import type { ImgProcCtx } from "./api.js";
+import type { ImgProcCtx, OutputSpec } 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.
+ * The following built-in IDs are supported and custom IDs will be looked up via
+ * the {@link ImgProcOpts.pathParts} options provided to {@link processImage}.
+ * Any others will remain as is. Custom IDs take precedence over built-in ones.
  *
- * - 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
+ * - date: yyyyMMdd
+ * - time: HHmmss
+ * - year: 4-digit year
+ * - month: 2-digit month
+ * - week: 2-digit week
+ * - day: 2-digit day in month
+ * - hour: 2-digit hour (24h system)
+ * - minute: 2-digit minute
+ * - second: 2-digit second
+ *
+ * All date/time related values will be in UTC.
  *
  * @param path
- * @param buf
  * @param ctx
+ * @param spec
+ * @param buf
  */
-export declare const formatPath: (path: string, buf: Buffer | TypedArray, ctx: ImgProcCtx) => string;
+export declare const formatPath: (path: string, ctx: ImgProcCtx, spec: OutputSpec, buf: Buffer | TypedArray) => string;
 //# sourceMappingURL=path.d.ts.map

package/path.js

@@ -1,8 +1,24 @@
-import { FMT_HHmmss_ALT, FMT_yyyyMMdd_ALT } from "@thi.ng/date";
+import { isFunction } from "@thi.ng/checks";
+import {
+  FMT_HH,
+  FMT_HHmmss_ALT,
+  FMT_MM,
+  FMT_dd,
+  FMT_mm,
+  FMT_ss,
+  FMT_ww,
+  FMT_yyyy,
+  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) => {
+const _ = void 0;
+const formatPath = (path, ctx, spec, buf) => path.replace(/\{(\w+)\}/g, (match, id) => {
+  const custom = ctx.opts.pathParts?.[id];
+  if (custom != null) {
+    return isFunction(custom) ? custom(ctx, spec, buf) : custom;
+  }
   switch (id) {
     case "name": {
       !path && unsupported(
@@ -23,9 +39,23 @@ const formatPath = (path, buf, ctx) => path.replace(/\{(\w+)\}/g, (match, id) =>
     case "h":
       return String(ctx.size[1]);
     case "date":
-      return FMT_yyyyMMdd_ALT();
+      return FMT_yyyyMMdd_ALT(_, true);
     case "time":
-      return FMT_HHmmss_ALT();
+      return FMT_HHmmss_ALT(_, true);
+    case "year":
+      return FMT_yyyy(_, true);
+    case "month":
+      return FMT_MM(_, true);
+    case "week":
+      return FMT_ww(_, true);
+    case "day":
+      return FMT_dd(_, true);
+    case "hour":
+      return FMT_HH(_, true);
+    case "minute":
+      return FMT_mm(_, true);
+    case "second":
+      return FMT_ss(_, true);
   }
   return match;
 });

package/proc.d.ts

@@ -1,13 +1,32 @@
 /// <reference types="node" />
 import sharp, { type Sharp } from "sharp";
-import { type CompLayer, type ImgProcCtx, type ImgProcOpts, type ProcSpec } from "./api.js";
+import type { ImgProcCtx, ImgProcOpts, 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>;
+/**
+ * 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) and an object of
+ * all written output paths (keyed by each output's {@link OutputSpec.id}). The
+ * process can be configured via provided options.
+ *
+ * @remarks
+ * The `parentCtx` arg is internal use only!
+ *
+ * @param src
+ * @param specs
+ * @param opts
+ * @param parentCtx
+ */
+export declare const processImage: (src: string | Buffer | Sharp, specs: ProcSpec[], opts?: Partial<ImgProcOpts>, parentCtx?: ImgProcCtx) => Promise<{
+    img: sharp.Sharp;
+    meta: sharp.Metadata;
+    outputs: Record<string, string>;
+}>;
 /**
  * Extensible polymorphic function performing a single image processing step.
  *
  * @remarks
- * The function returns a tuple of `[img, bake-flag]`. If the flag (2nd value)
+ * The function returns a tuple of `[img, bakeFlag]`. 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.
@@ -18,10 +37,13 @@ export declare const processImage: (src: string | Buffer | Sharp, procs: ProcSpe
  * function checks this flag after each processing step and its down to each
  * processor to determine if baking is required or not...
  *
+ * To add support for a custom operation/processor, call: `processor.add("myid",
+ * myProcessor)`. Note that registered IDs should be unique (but can also
+ * override existing impls).
+ *
  * @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>>;
+export declare const processor: import("@thi.ng/defmulti").MultiFn3<ProcSpec, sharp.Sharp, ImgProcCtx, Promise<[sharp.Sharp, boolean]>>;
 //# sourceMappingURL=proc.d.ts.map