feat(imago): add blurhash output option, update deps

Author: postspectacular

packages/imago/package.json

@@ -37,6 +37,7 @@
 	"dependencies": {
 		"@thi.ng/api": "^8.9.26",
 		"@thi.ng/associative": "^6.3.43",
+		"@thi.ng/blurhash": "^0.1.10",
 		"@thi.ng/checks": "^3.5.0",
 		"@thi.ng/date": "^2.7.1",
 		"@thi.ng/defmulti": "^3.0.26",

packages/imago/src/api.ts

@@ -189,14 +189,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
 		| {
@@ -210,8 +250,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;
 }
 

packages/imago/src/ops/output.ts

@@ -1,15 +1,20 @@
 // thing:no-export
+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 type { Sharp } from "sharp";
 import type { ImgProcCtx, OutputSpec, Processor } from "../api.js";
 import { formatPath } from "../path.js";
-import type { Sharp } from "sharp";
-import { isPlainObject } from "@thi.ng/checks";
 
 export const outputProc: Processor = async (spec, input, ctx) => {
 	const opts = <OutputSpec>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];
@@ -78,6 +83,7 @@ const outputRaw = async (
 		: {};
 	if (alpha) output = output.ensureAlpha();
 	const { data, info } = await output
+		.ensureAlpha()
 		.raw()
 		.toBuffer({ resolveWithObject: true });
 	const path = join(outDir, formatPath(opts.path, ctx, opts, data));
@@ -93,3 +99,25 @@ const outputRaw = async (
 		);
 	}
 };
+
+const outputBlurHash = async (
+	opts: OutputSpec,
+	output: Sharp,
+	ctx: ImgProcCtx
+) => {
+	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;
+};

yarn.lock

@@ -3689,7 +3689,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@thi.ng/blurhash@workspace:^, @thi.ng/blurhash@workspace:packages/blurhash":
+"@thi.ng/blurhash@npm:^0.1.10, @thi.ng/blurhash@workspace:^, @thi.ng/blurhash@workspace:packages/blurhash":
   version: 0.0.0-use.local
   resolution: "@thi.ng/blurhash@workspace:packages/blurhash"
   dependencies:
@@ -5068,6 +5068,7 @@ __metadata:
     "@microsoft/api-extractor": "npm:^7.40.1"
     "@thi.ng/api": "npm:^8.9.26"
     "@thi.ng/associative": "npm:^6.3.43"
+    "@thi.ng/blurhash": "npm:^0.1.10"
     "@thi.ng/checks": "npm:^3.5.0"
     "@thi.ng/date": "npm:^2.7.1"
     "@thi.ng/defmulti": "npm:^3.0.26"