@thi.ng/imago 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-02-25T14:07:53Z
+- **Last updated**: 2024-02-28T14:23:30Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,18 @@ 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.4.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.4.1) (2024-02-28)
+
+#### 🩹 Bug fixes
+
+- fix typedarray input handling in processImage() ([075ecaa](https://github.com/thi-ng/umbrella/commit/075ecaa))
+
+## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.4.0) (2024-02-27)
+
+#### 🚀 Features
+
+- add blurhash output option, update deps ([b7ffedd](https://github.com/thi-ng/umbrella/commit/b7ffedd))
+
 ## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.3.0) (2024-02-23)
 
 #### 🚀 Features

package/README.md

@@ -76,9 +76,10 @@ 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 (using templated output path)
+- output this current stage as high quality AVIF (and record expanded output path)
 - crop center square region
-- output as JPEG thumbnail
+- output as JPEG thumbnail (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
 [
@@ -113,7 +114,8 @@ The following pipeline performs these steps (in sequence):
         "avif": { "quality": 80 }
     },
     { "op": "crop", "size": [240, 240], "gravity": "c" },
-    { "op": "output", "id": "thumb", "path": "{name}-thumb.jpg" }
+    { "op": "output", "id": "thumb", "path": "{name}-thumb.jpg" },
+    { "op": "output", "id": "hash", "path": "", blurhash: { detail: 4 } }
 ]
 ```
 
@@ -232,6 +234,11 @@ File output in any of these formats:
 - tiff
 - webp
 
+Alternatively, a
+[blurhash](https://github.com/thi-ng/umbrella/blob/develop/packages/blurhash) of
+the image can be computed and stored in the outputs. In this case, no file will
+be written.
+
 #### Templated output paths
 
 Output paths can contain `{id}`-templated parts which will be replaced/expanded.
@@ -302,12 +309,13 @@ For Node.js REPL:
 const imago = await import("@thi.ng/imago");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.06 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.15 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/associative](https://github.com/thi-ng/umbrella/tree/develop/packages/associative)
+- [@thi.ng/blurhash](https://github.com/thi-ng/umbrella/tree/develop/packages/blurhash)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/date](https://github.com/thi-ng/umbrella/tree/develop/packages/date)
 - [@thi.ng/defmulti](https://github.com/thi-ng/umbrella/tree/develop/packages/defmulti)

package/api.d.ts

@@ -126,14 +126,54 @@ export interface OutputSpec extends ProcSpec {
     id: string;
     /**
      * Possibly templated output path. See {@link formatPath} for details.
+     * Ignored if {@link OutputSpec.blurhash} is being used.
      */
     path: string;
+    /**
+     * AVIF output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#avif)
+     */
     avif?: AvifOptions;
+    /**
+     * If given, ONLY the blurhash of the image will be computed and stored in
+     * the `outputs` object returned by {@link processImage}. The
+     * {@link OutputSpec.path} will be ignored and no file will be written.
+     *
+     * @remarks
+     * 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];
+    };
+    /**
+     * GIF output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#gif)
+     */
     gif?: GifOptions;
+    /**
+     * JPEG 2000 output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#jp2)
+     */
     jp2?: Jp2Options;
+    /**
+     * JPEG output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#jpeg)
+     */
     jpeg?: JpegOptions;
+    /**
+     * JPEG XL output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#jxl)
+     */
     jxl?: JxlOptions;
+    /**
+     * PNG output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#avif)
+     */
     png?: PngOptions;
+    /**
+     * Raw binary output options.
+     */
     raw?: boolean | {
         /**
          * If true, ensures the buffer has an alpha channel
@@ -145,8 +185,17 @@ export interface OutputSpec extends ProcSpec {
          */
         meta?: boolean;
     };
+    /**
+     * Tiled format output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#tile)
+     */
     tile?: TileOptions;
+    /**
+     * TIFF output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#tiff)
+     */
     tiff?: TiffOptions;
+    /**
+     * WebP output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#webp)
+     */
     webp?: WebpOptions;
 }
 export interface ResizeSpec extends ProcSpec {

package/ops/output.js

@@ -1,11 +1,16 @@
+import { encode } from "@thi.ng/blurhash";
+import { isNumber, isPlainObject } from "@thi.ng/checks";
 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.blurhash) {
+    await outputBlurHash(opts, output, ctx);
+    return [input, false];
+  }
   if (opts.raw) {
     await outputRaw(opts, output, ctx, outDir);
     return [input, false];
@@ -76,7 +81,7 @@ 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 { data, info } = await output.ensureAlpha().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;
@@ -90,6 +95,20 @@ const outputRaw = async (opts, output, ctx, outDir) => {
     );
   }
 };
+const outputBlurHash = async (opts, output, ctx) => {
+  const { data, info } = await output.ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const detail = opts.blurhash.detail || 4;
+  const [dx, dy] = isNumber(detail) ? [detail, detail] : detail;
+  const hash = encode(
+    new Uint32Array(data.buffer),
+    info.width,
+    info.height,
+    dx,
+    dy
+  );
+  ctx.logger.debug("computed blurhash:", hash);
+  ctx.outputs[opts.id] = hash;
+};
 export {
   outputProc
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/imago",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "JSON & API-based declarative and extensible image processing trees/pipelines",
   "type": "module",
   "module": "./index.js",
@@ -37,20 +37,21 @@
   "dependencies": {
     "@thi.ng/api": "^8.9.26",
     "@thi.ng/associative": "^6.3.43",
+    "@thi.ng/blurhash": "^0.1.11",
     "@thi.ng/checks": "^3.5.0",
-    "@thi.ng/date": "^2.7.1",
+    "@thi.ng/date": "^2.7.2",
     "@thi.ng/defmulti": "^3.0.26",
     "@thi.ng/errors": "^2.4.18",
     "@thi.ng/file-io": "^1.3.4",
     "@thi.ng/logger": "^3.0.3",
-    "@thi.ng/pixel": "^6.1.12",
-    "@thi.ng/pixel-dither": "^1.1.110",
+    "@thi.ng/pixel": "^6.1.13",
+    "@thi.ng/pixel-dither": "^1.1.111",
     "@thi.ng/prefixes": "^2.3.10",
     "sharp": "^0.33.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.40.1",
-    "@thi.ng/vectors": "^7.10.12",
+    "@thi.ng/vectors": "^7.10.13",
     "esbuild": "^0.20.0",
     "rimraf": "^5.0.5",
     "typedoc": "^0.25.7",
@@ -125,5 +126,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "6e20f80dd9df1c8055ffa3c1e4d6f7598add0c0b\n"
+  "gitHead": "190d68e7f7524631b333cfdbf32c6a23be27c166\n"
 }

package/proc.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+import type { TypedArray } from "@thi.ng/api";
 import sharp, { type Sharp } from "sharp";
 import type { ImgProcCtx, ImgProcOpts, ProcSpec } from "./api.js";
 export declare const LOGGER: import("@thi.ng/logger").ProxyLogger;
@@ -17,7 +18,7 @@ export declare const LOGGER: import("@thi.ng/logger").ProxyLogger;
  * @param opts
  * @param parentCtx
  */
-export declare const processImage: (src: string | Buffer | Sharp, specs: ProcSpec[], opts?: Partial<ImgProcOpts>, parentCtx?: ImgProcCtx) => Promise<{
+export declare const processImage: (src: string | TypedArray | Buffer | ArrayBuffer | Sharp, specs: ProcSpec[], opts?: Partial<ImgProcOpts>, parentCtx?: ImgProcCtx) => Promise<{
     img: sharp.Sharp;
     meta: sharp.Metadata;
     outputs: Record<string, string>;

package/proc.js

@@ -1,5 +1,6 @@
 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, {} from "sharp";
 import { blurProc } from "./ops/blur.js";
@@ -16,10 +17,9 @@ import { outputProc } from "./ops/output.js";
 import { resizeProc } from "./ops/resize.js";
 import { rotateProc } from "./ops/rotate.js";
 import { ensureSize } from "./units.js";
-import { createTempFile, deleteFile } from "@thi.ng/file-io";
 const LOGGER = ROOT.childLogger("imgproc");
 const processImage = async (src, specs, opts = {}, parentCtx) => {
-  let img = isString(src) || isArrayBufferView(src.buffer) ? sharp(src) : src;
+  let img = isString(src) || isArrayBufferView(src) ? sharp(src) : src;
   const meta = await img.metadata();
   ensureSize(meta);
   const ctx = {