@thi.ng/imago 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-02-28T14:23:30Z
+- **Last updated**: 2024-03-01T15:07:40Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,39 @@ 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.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.5.0) (2024-03-01)
+
+#### 🚀 Features
+
+- update/improve/fix fluid position handling ([55284cd](https://github.com/thi-ng/umbrella/commit/55284cd))
+  - update computeSize(), computMargins(), refSize(), positionOrGravity()
+  - update CompLayerBase
+  - add `ref`-side support for crop, resize, and all comp layer types
+  - update imageLayer(), use "fill" mode for resizing
+  - add tests
+  - add docs
+- add defLayerSpec() and layer factory fns ([2fc4334](https://github.com/thi-ng/umbrella/commit/2fc4334))
+- add/update layer types, positioning, origin, gravity ([eae646f](https://github.com/thi-ng/umbrella/commit/eae646f))
+- add RawLayer, update other layer types ([ad59ce3](https://github.com/thi-ng/umbrella/commit/ad59ce3))
+  - add rawLayer() & impl
+  - update CompLayer types & impls
+  - update imageLayer() to support buffer inputs
+  - add docs
+- add suport for cropping with aspect ratio ([2b3db06](https://github.com/thi-ng/umbrella/commit/2b3db06))
+- add `aspect` format ID for formatPath() ([25d8377](https://github.com/thi-ng/umbrella/commit/25d8377))
+- update resize, add support for proportional resize ([6b13b0d](https://github.com/thi-ng/umbrella/commit/6b13b0d))
+  - update resizeProc() to handle scalar `size` to scale proportionally
+    with automatic aspect detection
+
+#### 🩹 Bug fixes
+
+- use transparent black as default `extend()` bg color ([d5a98ef](https://github.com/thi-ng/umbrella/commit/d5a98ef))
+
+#### ♻️ Refactoring
+
+- update defLayer() & CompLayerFn args ([294c6d0](https://github.com/thi-ng/umbrella/commit/294c6d0))
+- update types, add docs, minor changes ([e3de1e2](https://github.com/thi-ng/umbrella/commit/e3de1e2))
+
 ### [0.4.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.4.1) (2024-02-28)
 
 #### 🩹 Bug fixes

package/README.md

@@ -31,7 +31,8 @@
   - [blur](#blur)
   - [composite](#composite)
     - [Common options](#common-options)
-    - [Bitmap layers](#bitmap-layers)
+    - [Bitmap image layers](#bitmap-image-layers)
+    - [Color layers](#color-layers)
     - [SVG layers](#svg-layers)
     - [Text layers](#text-layers)
   - [crop](#crop)
@@ -47,10 +48,13 @@
   - [resize](#resize)
   - [rotate](#rotate)
 - [Status](#status)
+- [Positions & sizes](#positions--sizes)
+  - [Gravity](#gravity)
 - [Metadata handling](#metadata-handling)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [API](#api)
+  - [Multistage processing pipeline](#multistage-processing-pipeline)
 - [Authors](#authors)
 - [License](#license)
 
@@ -67,7 +71,8 @@ In this new TypeScript version all image I/O and processing is delegated to
 
 ### Basic example
 
-Transformation trees/pipelines are simple JSON objects (but can be programmatically created):
+Transformation trees/pipelines are simple JSON objects (but can be
+programmatically created):
 
 The following pipeline performs these steps (in sequence):
 
@@ -76,10 +81,13 @@ The following pipeline performs these steps (in sequence):
 - 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 (and record expanded output path)
+- output this current stage as high quality AVIF (and record expanded output
+  path)
 - crop center square region
 - output as JPEG thumbnail (and record in outputs)
-- compute [blurhash](https://github.com/thi-ng/umbrella/blob/develop/packages/blurhash) (and record in outputs)
+- compute
+  [blurhash](https://github.com/thi-ng/umbrella/blob/develop/packages/blurhash)
+  (and record in outputs)
 
 ```json tangle:export/readme-example1.json
 [
@@ -115,11 +123,12 @@ The following pipeline performs these steps (in sequence):
     },
     { "op": "crop", "size": [240, 240], "gravity": "c" },
     { "op": "output", "id": "thumb", "path": "{name}-thumb.jpg" },
-    { "op": "output", "id": "hash", "path": "", blurhash: { detail: 4 } }
+    { "op": "output", "id": "hash", "path": "", blurhash: 4 }
 ]
 ```
 
-Then to process an image:
+Then to process an image using above JSON spec (there're also API wrappers to
+create these operator specs programmatically):
 
 ```ts tangle:export/readme1.ts
 import { processImage } from "@thi.ng/imago";
@@ -144,18 +153,27 @@ Gaussian blur
 
 ### composite
 
-Compositing multiple layers:
+Compositing multiple layers. The following layer types are available, and custom
+layer types can be registered via the polymorphic
+[`defLayer()`](https://docs.thi.ng/umbrella/imago/functions/defLayer.html)
+function.
 
 #### Common options
 
 - blend mode
-- gravity or position
+- position & origin
+- gravity
 - tiled repetition
 
-#### Bitmap layers
+#### Bitmap image layers
 
 - resizable
 
+#### Color layers
+
+- size
+- fill color (w/ alpha)
+
 #### SVG layers
 
 - from file or inline doc
@@ -253,6 +271,7 @@ Any others will remain as is. Custom IDs take precedence over built-in ones.
 - `sha1`/`sha224`/`sha256`/`sha384`/`sha512`: truncated hash of output (8 chars)
 - `w`: current image width
 - `h`: current image height
+- `aspect`: "p" (portrait), "l" (landscape) or "sq" (square)
 - `date`: yyyyMMdd date format, e.g. 20240223
 - `time`: HHmmss time format, e.g. 234459
 - `year`: 4-digit year
@@ -288,6 +307,28 @@ Auto-rotate, rotate by angle and/or flip image along x/y
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bimago%5D+in%3Atitle)
 
+## Positions & sizes
+
+Border sizes, general dimensions, and positions can be specified in pixels
+(default) or as percentages (using `unit: "%"`). For the latter case, an
+additional reference side (`ref` option) can be provided. The default ref is
+`min`, referring to whatever is the smaller side of an image.
+
+The `ref` option/reference side can take the following values (default: `both`):
+
+- `both`: image width for horizontal uses, image height for vertical uses
+- `min`: smaller side of an image (aka `min(width,height)`)
+- `max`: larger side of an image (aka `min(width,height)`)
+- `w`: image width
+- `h`: image height
+
+### Gravity
+
+In some operations positioning or alignment can be abstractly stated via one of
+the following gravity values:
+
+![diagram of the 9 possible gravity directions](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/imago/gravity.png)
+
 ## Metadata handling
 
 By default all input metadata will be lost in the outputs. The `keepEXIF` and
@@ -309,7 +350,7 @@ For Node.js REPL:
 const imago = await import("@thi.ng/imago");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.15 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.81 KB
 
 ## Dependencies
 
@@ -331,7 +372,102 @@ Package sizes (brotli'd, pre-treeshake): ESM: 4.15 KB
 
 [Generated API docs](https://docs.thi.ng/umbrella/imago/)
 
-TODO
+### Multistage processing pipeline
+
+```ts tangle:export/readme-api.ts
+import {
+    colorLayer,
+    composite,
+    crop,
+    extend,
+    imageLayer,
+    nest,
+    output,
+    processImage,
+    rawLayer,
+    resize,
+    rotate,
+} from "@thi.ng/imago";
+import { ConsoleLogger } from "@thi.ng/logger";
+
+const res = await processImage(
+    "test.jpg",
+    // operator pipeline
+    [
+        // auto-rotate (EXIF orientation)
+        rotate({}),
+        // composite w/ semi-transparent color layer (screen)
+        composite({
+            layers: [
+                colorLayer({
+                    // magenta with 50% opacity
+                    bg: "#f0f8",
+                    blend: "screen",
+                    // layer size is 50x100% of image
+                    size: [50, 100],
+                    // aligned left (west)
+                    gravity: "w",
+                    // size given in percent
+                    unit: "%",
+                }),
+                // diagonal hairline pattern overlay (with tiling) from raw
+                // pixel data in ABGR format, i.e. 0xAABBGGRR
+                rawLayer({
+                    // prettier-ignore
+                    buffer: new Uint32Array([
+                        0x00000000, 0x00000000, 0x00000000, 0x80ffffff,
+                        0x00000000, 0x00000000, 0x80ffffff, 0x00000000,
+                        0x00000000, 0x80ffffff, 0x00000000, 0x00000000,
+                        0x80ffffff, 0x00000000, 0x00000000, 0x00000000,
+                    ]),
+                    channels: 4,
+                    size: [4, 4],
+                    tile: true,
+                }),
+            ],
+        }),
+        // nested operations each operate on a clone of the current (already
+        // semi-transformed) image, they have no impact on the processing pipeline
+        // of their parent(s)
+        // multiple child pipelines can be spawned, here only a single one
+        nest({
+            procs: [
+                // this pipeline only creates blurhash (stored in `outputs` of result)
+                [resize({ size: 100 }), output({ id: "hash", blurhash: true })],
+            ],
+        }),
+        // crop to 3:2 aspect ratio (always based on longest side)
+        crop({ size: 100, aspect: 3 / 2, unit: "%" }),
+        // back in the main pipleline, add 5% white border (based on smallest side)
+        extend({ border: 5, unit: "%", bg: "white", ref: "min" }),
+        // resize image to 1920 (largest side)
+        resize({ size: 1920 }),
+        // add logo watermark centered horizontally and near the bottom
+        composite({
+            layers: [
+                imageLayer({
+                    path: "logo-128.png",
+                    unit: "%",
+                    origin: "s",
+                    pos: { l: 50, b: 5 },
+                    ref: "both",
+                    blend: "screen",
+                }),
+            ],
+        }),
+        output({ id: "main", path: "{date}-1920-frame.jpg" }),
+    ],
+    {
+        logger: new ConsoleLogger("img"),
+    }
+);
+
+console.log(res.outputs);
+// {
+//   hash: "UVKmR.^SIVR$_NRiM{jupLRjjEWC%goxofoM",
+//   main: "...../20240301-144948-1920-frame.jpg",
+// }
+```
 
 ## Authors
 

package/api.d.ts

@@ -1,13 +1,22 @@
 /// <reference types="node" />
-import type { Fn, Fn3, Keys, TypedArray } from "@thi.ng/api";
+import type { Fn, Fn3, Keys, Range1_4, 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, OverlayOptions, PngOptions, Sharp, TiffOptions, TileOptions, WebpOptions } from "sharp";
+/**
+ * ```text
+ * nw -- n -- ne
+ *  |    |    |
+ *  w -- c -- e
+ *  |    |    |
+ * sw -- s -- se
+ * ```
+ */
 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];
 export type Size = number | Dim;
 export type Sides = [number, number, number, number];
-export type SizeRef = "min" | "max" | "w" | "h";
+export type SizeRef = "min" | "max" | "w" | "h" | "both";
 export type SizeUnit = "px" | "%";
 export type Color = string | number[] | {
     r: number;
@@ -15,60 +24,198 @@ export type Color = string | number[] | {
     b: number;
     alpha?: number;
 };
+/**
+ * Position defined by max. 2 components/coordinates. If none are defined, the
+ * position will be interpreted as centered.
+ */
 export interface Position {
     l?: number;
     r?: number;
     t?: number;
     b?: number;
 }
+export type BufferLike = TypedArray | Buffer;
 export type Processor = Fn3<ProcSpec, Sharp, ImgProcCtx, Promise<[Sharp, boolean]>>;
 export type CompLayerFn = Fn3<CompLayer, Sharp, ImgProcCtx, Promise<OverlayOptions>>;
 export interface ProcSpec {
+    /**
+     * Unique processor ID. Used to by {@link processor} to select correct
+     * implementation.
+     */
     op: string;
 }
 export interface BlurSpec extends ProcSpec {
     op: "blur";
+    /**
+     * Blur radius in pixels (can be fractional)
+     */
     radius: number;
 }
 export interface CompSpec extends ProcSpec {
     op: "composite";
     layers: CompLayer[];
 }
-export type CompLayer = ImgLayer | SVGLayer;
-export interface CompLayerBase {
+export interface CompLayer {
+    /**
+     * Unique layer type, used by {@link composite} and {@link defLayer} to
+     * select correct layer implementation.
+     */
     type: string;
+    /**
+     * Layer blend mode. See [Sharp
+     * docs](https://sharp.pixelplumbing.com/api-composite#composite) for list
+     * of available modes.
+     *
+     * @defaultValue "over"
+     */
     blend?: Blend;
+    /**
+     * Abstracted layer position. This option is only used if no
+     * {@link CompLayer.pos} is specified. It also controls alignment
+     * of tiling when {@link CompLayer.tile} is enabled. If neither gravity
+     * or position are configured, the layer will be centered.
+     */
     gravity?: Gravity;
+    /**
+     * Partial layer position given in units of {@link CompLayer.unit}. At
+     * most 2 coordinate can be given here (e.g. left & top). The right & bottom
+     * values are overriding left/top (in case of conflict).
+     *
+     * @remarks
+     * Note: This option takes precedence over {@link CompLayer.gravity}. If
+     * neither gravity or position are configured, the layer will be centered.
+     */
     pos?: Position;
+    /**
+     * Origin/reference point for the given layer position
+     * {@link CompLayer.pos}. Only used if position is given.
+     *
+     * @remarks
+     * The given value specifies one of the 9 points in the layer which is to be
+     * used for the layer position (e.g. "se" for south-east aka bottom-right
+     * corner).
+     *
+     * If not given, it will be auto-determined by provided position config,
+     * e.g. a `pos` with right & top coords will have an implicit origin of `ne`
+     * (aka north-east). See gravity diagram {@link Gravity}.
+     */
+    origin?: Gravity;
+    /**
+     * Only used if {@link CompLayer.unit} is percent (`%`). Reference side
+     * ID for computing positions and sizes. See {@link SizeRef} for details.
+     *
+     * @defaultValue "both"
+     */
+    ref?: SizeRef;
+    /**
+     * If true, the layer will be repeated across the entire image with the
+     * given {@link CompLayer.gravity}.
+     */
     tile?: boolean;
+    /**
+     * Unit to use for {@link CompLayer.pos} and sizes (where
+     * supported). If `%`, the given values are interpreted as percentages,
+     * relative to configured {@link CompLayer.ref} side.
+     *
+     * @defaultValue "px"
+     */
     unit?: SizeUnit;
+    [id: string]: any;
 }
-export interface ImgLayer extends CompLayerBase {
-    path: string;
+export interface ColorLayer extends CompLayer {
+    type: "color";
+    /**
+     * Layer fill/background color.
+     */
+    bg: Color;
     size?: Size;
-    unit?: SizeUnit;
 }
-export interface SVGLayer extends CompLayerBase {
+export interface ImgLayer extends CompLayer {
+    type: "img";
+    /**
+     * Image as buffer (must be in one of sharp's supported image formats, use
+     * {@link rawLayer} / {@link RawLayer} for compositing raw image data)
+     */
+    buffer?: BufferLike;
+    /**
+     * File path to image, alternative to {@link ImgLayer.buffer}.
+     */
+    path?: string;
+    /**
+     * Layer target size (in units defined via {@link CompLayer.unit})
+     */
+    size?: Size;
+}
+export interface RawLayer extends CompLayer {
+    type: "raw";
+    buffer: BufferLike;
+    channels: Range1_4;
+    size: [number, number];
+}
+export interface SVGLayer extends CompLayer {
     type: "svg";
-    body: string;
-    path: string;
+    /**
+     * Inline SVG document, alternative to {@link SVGLayer.path}.
+     */
+    body?: string;
+    /**
+     * File path to SVG document.
+     */
+    path?: string;
 }
-export interface TextLayer extends CompLayerBase {
+export interface TextLayer extends CompLayer {
     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];
+    /**
+     * Background color.
+     *
+     * @defaultValue "#0000"
+     */
+    bg?: string;
+    /**
+     * Body text. Alternative to {@link TextLayer.path}. If given as function,
+     * the function will be called with the processing context and must return a
+     * string.
+     *
+     * @defaultValue ""
+     */
+    body?: string | Fn<ImgProcCtx, string>;
+    /**
+     * Text color
+     *
+     * @defaultValue "#fff"
+     */
+    color?: string;
+    font?: string;
+    fontSize?: number | string;
+    padding?: number;
+    path?: string;
+    /**
+     * Layer/textbox size. Required
+     */
+    size: Dim;
+    textGravity?: Gravity;
 }
 export interface CropSpec extends ProcSpec {
     op: "crop";
+    /**
+     * Target aspect ratio. Only used if {@link CropSpec.size} is given as
+     * single numeric value (pixels or percentage). If the aspect ratio is >1,
+     * the general aspect of the cropped image will remain principally the same,
+     * i.e. a portait image will remain portait (but cropped), ditto for
+     * landscape. If the given aspect raatio is <1, the aspect of the image will
+     * be flipped/swapped, i.e. a portait aspect becomes landscape and vice
+     * versa.
+     *
+     * @example
+     * ```js
+     * // crop image to 3:2 aspect ratio
+     * { op: "crop", size: 100, unit: "%", aspect: 3/2 }
+     * ```
+     */
+    aspect?: number;
     border?: Size | Sides;
     gravity?: Gravity;
+    origin?: Gravity;
     pos?: Position;
     ref?: SizeRef;
     size?: Size;
@@ -79,7 +226,7 @@ export interface DitherSpec extends ProcSpec {
     mode: DitherMode;
     num: number;
     rgb?: boolean;
-    size: 2 | 4 | 8;
+    size?: 2 | 4 | 8;
 }
 export interface EXIFSpec extends ProcSpec {
     op: "exif";
@@ -126,9 +273,9 @@ export interface OutputSpec extends ProcSpec {
     id: string;
     /**
      * Possibly templated output path. See {@link formatPath} for details.
-     * Ignored if {@link OutputSpec.blurhash} is being used.
+     * Ignored if {@link OutputSpec.blurhash} is being used, otherwise **required**.
      */
-    path: string;
+    path?: string;
     /**
      * AVIF output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#avif)
      */
@@ -139,18 +286,13 @@ export interface OutputSpec extends ProcSpec {
      * {@link OutputSpec.path} will be ignored and no file will be written.
      *
      * @remarks
+     * The value given is the blurhash detail setting in the [1,9] range (usual
+     * default is 4), possibly given separately for X/Y axes.
+     *
      * Important: Ensure the image has already been downsized to ~50-500 pixels.
      * Larger images are causing unnecessary & long processing...
      */
-    blurhash?: {
-        /**
-         * Blurhash detail setting in 1-9 range, possibly given separately for
-         * X/Y axis.
-         *
-         * @defaultValue 4
-         */
-        detail?: number | [number, number];
-    };
+    blurhash?: true | number | [number, number];
     /**
      * GIF output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#gif)
      */
@@ -204,13 +346,27 @@ export interface ResizeSpec extends ProcSpec {
     filter?: Keys<KernelEnum>;
     fit?: Keys<FitEnum>;
     gravity?: Gravity;
+    ref?: SizeRef;
+    /**
+     * New size of the image, expressed in pixels or percentages.
+     *
+     * @remarks
+     * If using pixels and size is a single number, it will be interpreted as
+     * the target size of the longest side and the other side scaled
+     * proportionally, using current aspect ratio.
+     *
+     * If given as `[width,height]` tuple, a negative value for a side makes
+     * that side proportionally scaled. relative to the other. E.g. a size of
+     * `[1280,-1]` scales the image to 1280 pixels wide and the height computed
+     * based on current aspect ratio.
+     */
     size: Size;
     unit?: SizeUnit;
 }
 export interface RotateSpec extends ProcSpec {
     op: "rotate";
     angle?: number;
-    bg: Color;
+    bg?: Color;
     flipX?: boolean;
     flipY?: boolean;
 }
@@ -250,7 +406,7 @@ export interface ImgProcOpts {
      * 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>;
+    pathParts: Record<string, Fn3<ImgProcCtx, OutputSpec, BufferLike, string> | string>;
 }
 export interface ImgProcCtx {
     path?: string;
@@ -261,7 +417,8 @@ export interface ImgProcCtx {
     logger: ILogger;
     opts: Partial<ImgProcOpts>;
     /**
-     * Paths of all exported images.
+     * Paths of all exported images, keyed by IDs given via {@link OutputSpec} /
+     * {@link output}.
      */
     outputs: Record<string, string>;
 }

package/index.d.ts

@@ -3,4 +3,22 @@ export * from "./ops.js";
 export * from "./path.js";
 export * from "./proc.js";
 export * from "./units.js";
+export * from "./layers/color.js";
+export * from "./layers/image.js";
+export * from "./layers/raw.js";
+export * from "./layers/svg.js";
+export * from "./layers/text.js";
+export * from "./ops/blur.js";
+export * from "./ops/composite.js";
+export * from "./ops/crop.js";
+export * from "./ops/dither.js";
+export * from "./ops/exif.js";
+export * from "./ops/extend.js";
+export * from "./ops/gamma.js";
+export * from "./ops/grayscale.js";
+export * from "./ops/hsbl.js";
+export * from "./ops/nest.js";
+export * from "./ops/output.js";
+export * from "./ops/resize.js";
+export * from "./ops/rotate.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -3,3 +3,21 @@ export * from "./ops.js";
 export * from "./path.js";
 export * from "./proc.js";
 export * from "./units.js";
+export * from "./layers/color.js";
+export * from "./layers/image.js";
+export * from "./layers/raw.js";
+export * from "./layers/svg.js";
+export * from "./layers/text.js";
+export * from "./ops/blur.js";
+export * from "./ops/composite.js";
+export * from "./ops/crop.js";
+export * from "./ops/dither.js";
+export * from "./ops/exif.js";
+export * from "./ops/extend.js";
+export * from "./ops/gamma.js";
+export * from "./ops/grayscale.js";
+export * from "./ops/hsbl.js";
+export * from "./ops/nest.js";
+export * from "./ops/output.js";
+export * from "./ops/resize.js";
+export * from "./ops/rotate.js";

package/layers/color.d.ts

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