@thi.ng/imago 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-02-22T11:59:16Z
+- **Last updated**: 2024-02-23T13:36:17Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,31 @@ 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.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.3.0) (2024-02-23)
+
+#### 🚀 Features
+
+- major update ([f938d60](https://github.com/thi-ng/umbrella/commit/f938d60))
+  - restructure package, split out all ops into separate files
+  - update `ProcSpec`, rename `type` => `op`
+  - add text layer support (via SVG)
+  - add/update EXIF handling & opts
+  - add ICC profile handling & opts
+  - update output path collection to use object
+    - update `OutputSpec` to require output `id`
+  - update `NestSpec` to support multiple child pipelines
+    - spawn children via Promise.all()
+  - add/update docstrings
+  - update deps & pkg exports
+
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.2.0) (2024-02-22)
+
+#### 🚀 Features
+
+- add support for custom path part replacements ([b0419e1](https://github.com/thi-ng/umbrella/commit/b0419e1))
+- add more path part replacements ([9f84a8a](https://github.com/thi-ng/umbrella/commit/9f84a8a))
+- collect all output paths, update processImage() result ([a3ca52f](https://github.com/thi-ng/umbrella/commit/a3ca52f))
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.1.0) (2024-02-22)
 
 #### 🚀 Features

package/README.md

@@ -33,6 +33,7 @@
     - [Common options](#common-options)
     - [Bitmap layers](#bitmap-layers)
     - [SVG layers](#svg-layers)
+    - [Text layers](#text-layers)
   - [crop](#crop)
   - [dither](#dither)
   - [exif](#exif)
@@ -42,9 +43,11 @@
   - [hsbl](#hsbl)
   - [nest](#nest)
   - [output](#output)
+    - [Templated output paths](#templated-output-paths)
   - [resize](#resize)
   - [rotate](#rotate)
 - [Status](#status)
+- [Metadata handling](#metadata-handling)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [API](#api)
@@ -66,11 +69,11 @@ In this new TypeScript version all image I/O and processing is delegated to
 
 Transformation trees/pipelines are simple JSON objects (but can be programmatically created):
 
-The following pipeline performs the following steps:
+The following pipeline performs these steps (in sequence):
 
-- auto-rotate image (using EXIF orientation info)
+- auto-rotate image (using EXIF orientation info, if available)
 - add 5% white border (size relative to shortest side)
-- proportionally resize to 1920px (by default longest side)
+- proportionally resize image to 1920px (longest side by default)
 - overlay bitmap logo layer, positioned at 45% left / 5% bottom
 - add custom EXIF metadata
 - output this current stage as high quality AVIF (using templated output path)
@@ -79,11 +82,11 @@ The following pipeline performs the following steps:
 
 ```json tangle:export/readme-example1.json
 [
-    { "type": "rotate" },
-    { "type": "extend", "border": 5, "unit": "%", "ref": "min", "bg": "#fff" },
-    { "type": "resize", "size": 1920 },
+    { "op": "rotate" },
+    { "op": "extend", "border": 5, "unit": "%", "ref": "min", "bg": "#fff" },
+    { "op": "resize", "size": 1920 },
     {
-        "type": "composite",
+        "op": "composite",
         "layers": [
             {
                 "type": "img",
@@ -95,7 +98,7 @@ The following pipeline performs the following steps:
         ]
     },
     {
-        "type": "exif",
+        "op": "exif",
         "tags": {
             "IFD0": {
                 "Copyright": "Karsten Schmidt",
@@ -104,12 +107,13 @@ The following pipeline performs the following steps:
         }
     },
     {
-        "type": "output",
+        "op": "output",
+        "id": "hires",
         "path": "{name}-{sha256}-{w}x{h}.avif",
         "avif": { "quality": 80 }
     },
-    { "type": "crop", "size": [240, 240], "gravity": "c" },
-    { "type": "output", "path": "{name}-thumb.jpg" }
+    { "op": "crop", "size": [240, 240], "gravity": "c" },
+    { "op": "output", "id": "thumb", "path": "{name}-thumb.jpg" }
 ]
 ```
 
@@ -154,6 +158,14 @@ Compositing multiple layers:
 
 - from file or inline doc
 
+#### Text layers
+
+- optional background color (alpha supported)
+- text color
+- horizontal/vertical text align
+- font family & size
+- constrained to text box
+
 ### crop
 
 Cropping a part of the image
@@ -179,7 +191,7 @@ Supported dither modes from
 
 ### exif
 
-Set EXIF metadata (can only be given directly before [output](#output))
+Set custom EXIF metadata (can be given multiple times, will be merged)
 
 ### extend
 
@@ -187,6 +199,7 @@ Add pixels on all sides of the image
 
 - supports px or percent units
 - proportional to a given reference side/size
+- can be individually configured per side
 
 ### gamma
 
@@ -202,8 +215,8 @@ Hue, saturation, brightness and lightness adjustments
 
 ### nest
 
-Nested branch/pipeline of operations with no effect on image state of
-current/parent pipeline...
+Performing nested branches/pipelines of operations with no effect on image state
+of current/parent pipeline...
 
 ### output
 
@@ -219,6 +232,36 @@ File output in any of these formats:
 - tiff
 - webp
 
+#### Templated output paths
+
+Output paths can contain `{id}`-templated parts which will be replaced/expanded.
+The following built-in IDs are supported and custom IDs will be looked up via
+the
+[pathParts](https://docs.thi.ng/umbrella/imago/interfaces/ImgProcOpts.html#pathParts)
+options provided to
+[processImage()](https://docs.thi.ng/umbrella/imago/functions/processImage.html).
+Any others will remain as is. Custom IDs take precedence over built-in ones.
+
+- `name`: original base filename (w/o ext)
+- `sha1`/`sha224`/`sha256`/`sha384`/`sha512`: truncated hash of output (8 chars)
+- `w`: current image width
+- `h`: current image height
+- `date`: yyyyMMdd date format, e.g. 20240223
+- `time`: HHmmss time format, e.g. 234459
+- `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
+
+Output paths can contain sub-directories which will be automatically created
+(relative to the [configured output
+dir](https://docs.thi.ng/umbrella/imago/interfaces/ImgProcOpts.html#outDir)).
+For example, the path template `{year}/{month}/{day}/{name}-{sha1}.jpg` might
+get replaced to: `2024/02/22/test-123cafe4.jpg`...
+
 ### resize
 
 Resizing image
@@ -230,7 +273,7 @@ Resizing image
 
 ### rotate
 
-Auto-rotate, rotate and/or mirror image
+Auto-rotate, rotate by angle and/or flip image along x/y
 
 ## Status
 
@@ -238,6 +281,15 @@ Auto-rotate, rotate and/or mirror image
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bimago%5D+in%3Atitle)
 
+## Metadata handling
+
+By default all input metadata will be lost in the outputs. The `keepEXIF` and
+`keepICC` options can be used to retain EXIF and/or ICC profile information
+(only if also supported in the output format).
+
+**Important:** Retaining EXIF and merging it with [custom additions](#exif) is
+still WIP...
+
 ## Installation
 
 ```bash
@@ -250,7 +302,7 @@ For Node.js REPL:
 const imago = await import("@thi.ng/imago");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.13 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.17 KB
 
 ## Dependencies
 
@@ -263,6 +315,7 @@ Package sizes (brotli'd, pre-treeshake): ESM: 3.13 KB
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
 - [@thi.ng/pixel](https://github.com/thi-ng/umbrella/tree/develop/packages/pixel)
 - [@thi.ng/pixel-dither](https://github.com/thi-ng/umbrella/tree/develop/packages/pixel-dither)
+- [exif-reader](https://github.com/devongovett/exif-reader)
 - [sharp](https://sharp.pixelplumbing.com)
 
 ## API

package/api.d.ts

@@ -1,6 +1,7 @@
-import type { Keys } from "@thi.ng/api";
+/// <reference types="node" />
+import type { Fn, Fn3, Keys, TypedArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-import type { AvifOptions, Blend, Exif, ExtendWith, FitEnum, GifOptions, Jp2Options, JpegOptions, JxlOptions, KernelEnum, Metadata, PngOptions, TiffOptions, TileOptions, WebpOptions } from "sharp";
+import type { AvifOptions, Blend, Exif, ExtendWith, FitEnum, GifOptions, Jp2Options, JpegOptions, JxlOptions, KernelEnum, Metadata, OverlayOptions, PngOptions, Sharp, TiffOptions, TileOptions, WebpOptions } from "sharp";
 export type Gravity = "c" | "e" | "n" | "ne" | "nw" | "s" | "se" | "sw" | "w";
 export type DitherMode = "atkinson" | "burkes" | "column" | "diffusion" | "floyd" | "jarvis" | "row" | "sierra" | "stucki" | "bayer";
 export type Dim = [number, number];
@@ -20,15 +21,17 @@ export interface Position {
     t?: number;
     b?: number;
 }
+export type Processor = Fn3<ProcSpec, Sharp, ImgProcCtx, Promise<[Sharp, boolean]>>;
+export type CompLayerFn = Fn3<CompLayer, Sharp, ImgProcCtx, Promise<OverlayOptions>>;
 export interface ProcSpec {
-    type: string;
+    op: string;
 }
 export interface BlurSpec extends ProcSpec {
-    type: "blur";
+    op: "blur";
     radius: number;
 }
 export interface CompSpec extends ProcSpec {
-    type: "composite";
+    op: "composite";
     layers: CompLayer[];
 }
 export type CompLayer = ImgLayer | SVGLayer;
@@ -50,8 +53,20 @@ export interface SVGLayer extends CompLayerBase {
     body: string;
     path: string;
 }
+export interface TextLayer extends CompLayerBase {
+    type: "text";
+    textGravity: Gravity;
+    bg: string;
+    body: string | Fn<ImgProcCtx, string>;
+    color: string;
+    font: string;
+    fontSize: number | string;
+    padding: number;
+    path: string;
+    size: [number, number];
+}
 export interface CropSpec extends ProcSpec {
-    type: "crop";
+    op: "crop";
     border?: Size | Sides;
     gravity?: Gravity;
     pos?: Position;
@@ -60,18 +75,18 @@ export interface CropSpec extends ProcSpec {
     unit?: SizeUnit;
 }
 export interface DitherSpec extends ProcSpec {
-    type: "dither";
+    op: "dither";
     mode: DitherMode;
     num: number;
     rgb?: boolean;
     size: 2 | 4 | 8;
 }
 export interface EXIFSpec extends ProcSpec {
-    type: "exif";
+    op: "exif";
     tags: Exif;
 }
 export interface ExtendSpec extends ProcSpec {
-    type: "extend";
+    op: "extend";
     bg?: Color;
     border: Size | Sides;
     mode?: ExtendWith;
@@ -79,26 +94,39 @@ export interface ExtendSpec extends ProcSpec {
     unit?: SizeUnit;
 }
 export interface GammaSpec extends ProcSpec {
-    type: "gamma";
+    op: "gamma";
     gamma: number;
 }
 export interface GrayscaleSpec extends ProcSpec {
-    type: "gray";
+    op: "gray";
     gamma?: number | boolean;
 }
 export interface HSBLSpec extends ProcSpec {
-    type: "hsbl";
+    op: "hsbl";
     h?: number;
     s?: number;
     b?: number;
     l?: number;
 }
 export interface NestSpec extends ProcSpec {
-    type: "nest";
-    procs: ProcSpec[];
+    op: "nest";
+    /**
+     * Array of one or more arrays of processing pipeline specs. All pipelines
+     * are spawned via `Promise.all()` and each one receives a separate clone of
+     * the current input image.
+     */
+    procs: ProcSpec[][];
 }
 export interface OutputSpec extends ProcSpec {
-    type: "output";
+    op: "output";
+    /**
+     * Unique ID of this output, used to record the file path in the `outputs`
+     * object returned by {@link processImage}.
+     */
+    id: string;
+    /**
+     * Possibly templated output path. See {@link formatPath} for details.
+     */
     path: string;
     avif?: AvifOptions;
     gif?: GifOptions;
@@ -122,7 +150,7 @@ export interface OutputSpec extends ProcSpec {
     webp?: WebpOptions;
 }
 export interface ResizeSpec extends ProcSpec {
-    type: "resize";
+    op: "resize";
     bg?: Color;
     filter?: Keys<KernelEnum>;
     fit?: Keys<FitEnum>;
@@ -131,7 +159,7 @@ export interface ResizeSpec extends ProcSpec {
     unit?: SizeUnit;
 }
 export interface RotateSpec extends ProcSpec {
-    type: "rotate";
+    op: "rotate";
     angle?: number;
     bg: Color;
     flipX?: boolean;
@@ -147,14 +175,46 @@ export interface ImgProcOpts {
      * Base directory for {@link output} steps
      */
     outDir: string;
+    /**
+     * By default all input metadata will be lost in the output(s). If this
+     * option is enabled, keeps existing EXIF data and attaches it to output
+     * (also where the output format actually supports it).
+     *
+     * @remarks
+     * TODO currently still unsupported
+     */
+    keepEXIF: boolean;
+    /**
+     * By default all input metadata will be lost in the output(s). If this
+     * option is enabled, keeps existing ICC profile from input image and
+     * attaches it to output (also where the output format actually supports
+     * it).
+     */
+    keepICC: boolean;
+    /**
+     * An object with custom output path replacements for {@link formatPath}. If
+     * a given replacement value is a function, it will be called with the
+     * current {@link ImgProcCtx}, the current {@link OutputSpec} (e.g. to
+     * obtain configured options) and the already serialized image as buffer.
+     *
+     * @remarks
+     * Replacement IDs in this object will take precedence over built-in
+     * replacement IDs, e.g. allowing to override `name`, `date` etc.
+     */
+    pathParts: Record<string, Fn3<ImgProcCtx, OutputSpec, Buffer | TypedArray, string> | string>;
 }
 export interface ImgProcCtx {
     path?: string;
     size: Dim;
-    channels: 1 | 2 | 3 | 4;
     meta: Metadata;
+    exif: Exif;
+    iccFile?: string;
     logger: ILogger;
     opts: Partial<ImgProcOpts>;
+    /**
+     * Paths of all exported images.
+     */
+    outputs: Record<string, string>;
 }
 export declare const GRAVITY_POSITION: Record<Gravity, string>;
 export declare const GRAVITY_MAP: Record<Gravity, string>;

package/layers/image.d.ts

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

package/layers/image.js

@@ -0,0 +1,29 @@
+import sharp from "sharp";
+import { computeSize, ensureSize, positionOrGravity } from "../units.js";
+const imageLayer = async (layer, _, ctx) => {
+  const {
+    type: __,
+    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
+  };
+};
+export {
+  imageLayer
+};

package/layers/svg.d.ts

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

package/layers/svg.js

@@ -0,0 +1,17 @@
+import { readText } from "@thi.ng/file-io";
+import { positionOrGravity } from "../units.js";
+const svgLayer = async (layer, _, ctx) => {
+  let { type: __, 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 {
+  svgLayer
+};

package/layers/text.d.ts

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

package/layers/text.js

@@ -0,0 +1,46 @@
+import { isFunction } from "@thi.ng/checks";
+import { writeText } from "@thi.ng/file-io";
+import { XML_SVG } from "@thi.ng/prefixes";
+import { computeSize, positionOrGravity } from "../units.js";
+const textLayer = async (layer, _, ctx) => {
+  const {
+    type: __,
+    bg = "transparent",
+    color = "white",
+    font = "sans-serif",
+    fontSize = 16,
+    padding = 0,
+    textGravity = "c",
+    body,
+    gravity,
+    path,
+    pos,
+    size,
+    unit,
+    ...opts
+  } = layer;
+  const [w, h] = computeSize(size, ctx.size, unit);
+  const [isE, isW, isN, isS] = ["e", "w", "n", "s"].map(
+    (x2) => textGravity.includes(x2)
+  );
+  const x = isW ? padding : isE ? w - padding : w / 2;
+  const y = isN ? padding : isS ? h - padding : h / 2;
+  const align = isW ? "start" : isE ? "end" : "middle";
+  const valign = isN ? 0.75 : isS ? 0 : 0.25;
+  const $body = isFunction(body) ? body(ctx) : body;
+  const svg = [
+    `<svg xmlns="${XML_SVG}" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">`,
+    `<rect x="0" y="0" width="${w}" height="${h}" fill="${bg}"/>`,
+    `<text x="${x}" y="${y}" text-anchor="${align}" dy="${valign}em" fill="${color}" font-family="${font}" font-size="${fontSize}">${$body}</text>`,
+    `</svg>`
+  ].join("");
+  writeText("text-debug.svg", svg);
+  return {
+    input: Buffer.from(svg),
+    ...positionOrGravity(pos, gravity, [w, h], ctx.size, unit),
+    ...opts
+  };
+};
+export {
+  textLayer
+};

package/ops/blur.d.ts

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

package/ops/blur.js

@@ -0,0 +1,7 @@
+const blurProc = async (spec, input) => {
+  const { radius } = spec;
+  return [input.blur(1 + radius / 2), false];
+};
+export {
+  blurProc
+};

package/ops/composite.d.ts

@@ -0,0 +1,5 @@
+import type { OverlayOptions, Sharp } from "sharp";
+import type { CompLayer, ImgProcCtx, Processor } from "../api.js";
+export declare const compositeProc: Processor;
+export declare const defLayer: import("@thi.ng/defmulti").MultiFn3<CompLayer, Sharp, ImgProcCtx, Promise<OverlayOptions>>;
+//# sourceMappingURL=composite.d.ts.map

package/ops/composite.js

@@ -0,0 +1,25 @@
+import { defmulti } from "@thi.ng/defmulti";
+import { imageLayer } from "../layers/image.js";
+import { svgLayer } from "../layers/svg.js";
+import { textLayer } from "../layers/text.js";
+const compositeProc = async (spec, input, ctx) => {
+  const { layers } = spec;
+  const layerSpecs = await Promise.all(
+    layers.map((l) => defLayer(l, input, ctx))
+  );
+  ctx.logger.debug("layer specs", layerSpecs);
+  return [input.composite(layerSpecs), true];
+};
+const defLayer = defmulti(
+  (x) => x.type,
+  {},
+  {
+    img: imageLayer,
+    svg: svgLayer,
+    text: textLayer
+  }
+);
+export {
+  compositeProc,
+  defLayer
+};

package/ops/crop.d.ts

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

package/ops/crop.js

@@ -0,0 +1,44 @@
+import { illegalArgs } from "@thi.ng/errors";
+import {
+  computeMargins,
+  computeSize,
+  gravityPosition,
+  positionOrGravity
+} from "../units.js";
+const cropProc = 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
+  ];
+};
+export {
+  cropProc
+};

package/ops/dither.d.ts

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