image-js 1.1.0 → 1.2.0

package/src/extra/draw/draw_text.ts

@@ -0,0 +1,194 @@
+import type { CanvasRenderingContext2D as SkiaCanvasRenderingContext2D } from 'skia-canvas';
+
+import type { Image, ImageDataArray } from '../../Image.ts';
+import type { Point } from '../../geometry/index.ts';
+import { getCanvasContext } from '../../utils/cross_platform.ts';
+import { getOutputImage } from '../../utils/getOutputImage.ts';
+import { validateValues } from '../../utils/validators/validators.ts';
+
+export interface DrawTextLabel {
+  /**
+   * Text of the label.
+   */
+  content: number | string;
+  /**
+   * Position to draw the label at.
+   */
+  position: Point;
+  /**
+   *  Size and type of font.
+   *  If specified, this overrides the general font from DrawTextOptions.
+   */
+  font?: string;
+  /**
+   *  Font color. Should be in rgba8 format.
+   *  If specified, this overrides the general fontColor from DrawTextOptions.
+   */
+  fontColor?: number[];
+}
+
+export interface DrawTextOptions {
+  /**
+   *  General size and type of font.
+   *  Used as the default when font is not specified in individual text labels.
+   */
+  font?: string;
+  /**
+   *  General font color.
+   *  Used as the default when fontColor is not specified in individual text labels.
+   */
+  fontColor?: number[];
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Image;
+}
+
+/**
+ * Draws text on an image.
+ * @param image - Image to write text on.
+ * @param text - Text to write on the image.
+ * @param options - Out Options
+ * @returns Image with drawn text.
+ */
+export function drawText(
+  image: Image,
+  text: DrawTextLabel | DrawTextLabel[],
+  options?: DrawTextOptions,
+) {
+  if (Array.isArray(text) && text.length === 0) {
+    throw new Error('At least one text element must be provided');
+  }
+
+  const newImage = getOutputImage(image, options, { clone: true });
+  const defaultFont = options?.font ?? '12px Helvetica';
+  const defaultColor = options?.fontColor ?? [255, 255, 255, 255];
+
+  const ctx = getCanvasContext(image.width, image.height);
+  if (!Array.isArray(text)) {
+    drawTextElement(image, ctx, text, defaultFont, defaultColor);
+  } else {
+    for (const label of text) {
+      drawTextElement(image, ctx, label, defaultFont, defaultColor);
+    }
+  }
+
+  layerCanvas(
+    newImage.getRawImage().data,
+    ctx.getImageData(0, 0, image.width, image.height).data,
+    image.channels,
+    image.bitDepth,
+  );
+
+  return newImage;
+}
+
+function drawTextElement(
+  image: Image,
+  ctx: OffscreenCanvasRenderingContext2D | SkiaCanvasRenderingContext2D,
+  text: DrawTextLabel,
+  defaultFont: string,
+  defaultColor: number[],
+) {
+  ctx.font = text.font ?? defaultFont;
+  const fontColor = text.fontColor ?? defaultColor;
+  validateValues(fontColor, image);
+  const alpha = fontColor[3] ? fontColor[3] / 255 : 1;
+  const normalizedColor = [
+    fontColor[0] ?? 0,
+    fontColor[1] ?? 0,
+    fontColor[2] ?? 0,
+    alpha,
+  ];
+  ctx.fillStyle = `rgba(${normalizedColor.join(',')})`;
+  ctx.fillText(String(text.content), text.position.column, text.position.row);
+}
+
+/**
+ * Draws labels on the image data from canvas.
+ * @param imageData - Image data to draw text on.
+ * @param canvasData - Canvas data to draw on the image.
+ * @param numberOfChannels - Number of channels of the initial image.
+ * @param bitDepth - Bit depth of the initial image.
+ */
+function layerCanvas(
+  imageData: ImageDataArray,
+  canvasData: Uint8ClampedArray,
+  numberOfChannels: number,
+  bitDepth: number,
+) {
+  const config = CHANNEL_CONFIGS[numberOfChannels] || CHANNEL_CONFIGS[1];
+  const pixelCount = canvasData.length >>> 2;
+  const bitShift = bitDepth - 8;
+
+  let imageIndex = 0;
+  let canvasIndex = 0;
+
+  for (let pixel = 0; pixel < pixelCount; pixel++) {
+    const canvasAlpha = canvasData[canvasIndex + 3] / 255;
+
+    // Skip transparent canvas pixels completely
+    if (canvasAlpha === 0) {
+      imageIndex += numberOfChannels;
+      canvasIndex += 4;
+      continue;
+    }
+
+    const invAlpha = 1 - canvasAlpha;
+
+    for (const channel of config.channelOffsets) {
+      const targetIndex = imageIndex + channel;
+      imageData[targetIndex] =
+        Math.round(
+          canvasData[canvasIndex + channel] * canvasAlpha +
+            imageData[targetIndex] * invAlpha,
+        ) << bitShift;
+    }
+    if (config.hasAlpha) {
+      const alphaIndex = imageIndex + (config.alphaOffset as number);
+      const imageAlpha = (imageData[alphaIndex] >>> bitShift) / 255;
+
+      const newAlpha = canvasAlpha + imageAlpha * (1 - canvasAlpha);
+      imageData[alphaIndex] = Math.round(newAlpha * 255) << bitShift;
+    }
+
+    imageIndex += numberOfChannels;
+    canvasIndex += 4;
+  }
+}
+
+/**
+ * Configuration for different channel numbers when layering canvas with onto destination image.
+ */
+interface ChannelConfig {
+  channelOffsets: number[];
+  hasAlpha: boolean;
+  alphaOffset: number | undefined; // Required when hasAlpha is true
+}
+
+const CHANNEL_CONFIGS: Record<number, ChannelConfig> = {
+  // GREY
+  1: {
+    channelOffsets: [0],
+    hasAlpha: false,
+    alphaOffset: undefined,
+  },
+  // GREYA
+  2: {
+    channelOffsets: [0],
+    hasAlpha: true,
+    alphaOffset: 1,
+  },
+  3: {
+    // RGB
+    channelOffsets: [0, 1, 2],
+    hasAlpha: false,
+    alphaOffset: undefined,
+  },
+  4: {
+    // RGBA
+    channelOffsets: [0, 1, 2],
+    hasAlpha: true,
+    alphaOffset: 3,
+  },
+};

package/src/extra/draw/index.ts

@@ -0,0 +1,2 @@
+export * from './draw_text.ts';
+export * from '../../draw/index.ts';

package/src/{ssim → extra/ssim}/compute_dssim.ts

@@ -1,7 +1,7 @@
-import type { Image } from '../Image.js';
+import type { Image } from '../../Image.ts';
 
-import type { SsimOptions } from './compute_ssim.js';
-import { computeSsim } from './compute_ssim.js';
+import type { SsimOptions } from './compute_ssim.ts';
+import { computeSsim } from './compute_ssim.ts';
 
 /**
  * Compute the Structural Dissimilarity (DSSIM) of two GREY images.

package/src/{ssim → extra/ssim}/compute_ssim.ts

@@ -1,8 +1,8 @@
 import { ssim as bufferSsim } from 'ssim.js';
 
-import type { Image } from '../Image.js';
-import checkProcessable from '../utils/validators/checkProcessable.js';
-import { validateForComparison } from '../utils/validators/validators.js';
+import type { Image } from '../../Image.ts';
+import checkProcessable from '../../utils/validators/checkProcessable.ts';
+import { validateForComparison } from '../../utils/validators/validators.ts';
 
 export interface SsimOptions {
   /**

package/src/extra/ssim/index.ts

@@ -0,0 +1,2 @@
+export * from './compute_dssim.ts';
+export * from './compute_ssim.ts';

package/src/index_browser.ts

@@ -0,0 +1,4 @@
+// API for the browser build.
+// TODO: figure out how to bundle the SSIM library. Then we can just use `index_full.ts` instead.
+export * from './index.ts';
+export * from './extra/draw/index.ts';

package/src/index_full.ts

@@ -0,0 +1,4 @@
+// Full API.
+export * from './index.ts';
+export * from './extra/draw/index.ts';
+export * from './extra/ssim/index.ts';

package/src/load/read.ts

@@ -17,7 +17,7 @@ export async function read(path: string | URL): Promise<Image> {
 }
 
 /**
- * Synchronous version of @see {@link read}.
+ * Synchronous version of {@link read}.
  * This method is only implemented for Node.js.
  * @param path - The path to the image.
  * @returns Image instance.

package/src/save/write.ts

@@ -106,7 +106,7 @@ export async function write(
 }
 
 /**
- * Synchronous version of @see {@link write}.
+ * Synchronous version of {@link write}.
  * This method is only implemented for Node.js.
  * @param path - Path where the image should be written.
  * @param image - Image to save.

package/src/utils/cross_platform.ts

@@ -1,13 +1,15 @@
+import type {
+  Canvas as SkiaCanvas,
+  CanvasRenderingContext2D as SkiaCanvasRenderingContext2D,
+} from 'skia-canvas';
+
 /**
  * Returns builtin Node.js modules or throws an error saying that the method is only implemented in Node.js.
  * @param methodName - Name of the method that calls this function
  * @returns - The `fs`, `path` and `url` Node.js modules.
  */
 export function getNodeApiOrThrow(methodName: string) {
-  if (
-    typeof process === 'undefined' ||
-    typeof process.getBuiltinModule !== 'function'
-  ) {
+  if (!isNode()) {
     throw new Error(`${methodName} is only implemented for Node.js`);
   }
   return {
@@ -16,3 +18,44 @@ export function getNodeApiOrThrow(methodName: string) {
     url: process.getBuiltinModule('node:url'),
   };
 }
+
+let CanvasCtorBrowser: typeof OffscreenCanvas;
+let CanvasCtorNode: typeof SkiaCanvas;
+
+/**
+ * Returns a 2D canvas context for rendering on the browser or Node.js.
+ * @param width - Width of the canvas.
+ * @param height - Height of the canvas.
+ * @returns The initialised canvas context.
+ */
+export function getCanvasContext(
+  width: number,
+  height: number,
+): OffscreenCanvasRenderingContext2D | SkiaCanvasRenderingContext2D {
+  if (isNode()) {
+    CanvasCtorNode ??= getRequireFn()('skia-canvas').Canvas;
+    return new CanvasCtorNode(width, height).getContext('2d');
+  } else {
+    CanvasCtorBrowser ??= globalThis.OffscreenCanvas;
+    const context = new CanvasCtorBrowser(width, height).getContext('2d');
+    if (!context) {
+      throw new Error('Failed to create canvas context');
+    }
+    return context;
+  }
+}
+
+function isNode() {
+  return (
+    typeof process !== 'undefined' &&
+    typeof process.getBuiltinModule === 'function'
+  );
+}
+
+let requireFn: NodeJS.Require;
+function getRequireFn() {
+  requireFn ??= process
+    .getBuiltinModule('node:module')
+    .createRequire(import.meta.url);
+  return requireFn;
+}

package/src/utils/setBlendedPixel.ts

@@ -9,7 +9,7 @@ import { assert } from './validators/assert.js';
  * @param image - The image with which to blend.
  * @param column - Column of the target pixel.
  * @param row - Row of the target pixel.
- * @param color - Color with which to blend the image pixel. @default `'Opaque black'`.
+ * @param color - Color with which to blend the image pixel. Default: `Opaque black`.
  */
 
 export function setBlendedPixel(

package/src/utils/setBlendedVisiblePixel.ts

@@ -8,7 +8,7 @@ import { setBlendedPixel } from './setBlendedPixel.js';
  * @param image - The image with which to blend.
  * @param column - Column of the target pixel.
  * @param row - Row of the target pixel.
- * @param color - Color with which to blend the image pixel. @default `'Opaque black'`.
+ * @param color - Color with which to blend the image pixel. Default: `Opaque black`.
  */
 export function setBlendedVisiblePixel(
   image: Image | Mask,

package/lib/ssim/compute_dssim.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"compute_dssim.d.ts","sourceRoot":"","sources":["../../src/ssim/compute_dssim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,KAAK,EACjB,OAAO,GAAE,WAAgB,GACxB,MAAM,CAGR"}

package/lib/ssim/compute_dssim.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"compute_dssim.js","sourceRoot":"","sources":["../../src/ssim/compute_dssim.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAY,EACZ,UAAiB,EACjB,UAAuB,EAAE;IAEzB,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC;IAC3D,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC"}

package/lib/ssim/compute_ssim.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"compute_ssim.d.ts","sourceRoot":"","sources":["../../src/ssim/compute_ssim.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIzC,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC;CACzD;AAED,MAAM,WAAW,IAAI;IACnB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,KAAK,EACjB,OAAO,GAAE,WAAgB,GACxB,IAAI,CA8CN"}

package/lib/ssim/compute_ssim.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"compute_ssim.js","sourceRoot":"","sources":["../../src/ssim/compute_ssim.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,gBAAgB,MAAM,yCAAyC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AA4B1E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,KAAY,EACZ,UAAiB,EACjB,UAAuB,EAAE;IAEzB,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,EAAE,SAAS,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;IAE3C,IAAI,UAAU,EAAE,CAAC;QACf,IAAI,UAAU,GAAG,KAAK,CAAC,KAAK,IAAI,UAAU,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC1D,MAAM,IAAI,UAAU,CAAC,2CAA2C,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IACD,gBAAgB,CAAC,KAAK,EAAE;QACtB,QAAQ,EAAE,CAAC,CAAC,CAAC;QACb,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;KACpB,CAAC,CAAC;IAEH,qBAAqB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAEzC,IAAI,KAAK,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;QAChC,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACnC,UAAU,GAAG,UAAU,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,iBAAiB,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,WAAW,GAAG;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAE,SAAS;KAChB,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,iBAAiB,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC;IACvE,MAAM,WAAW,GAAG;QAClB,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,IAAI,EAAE,SAAS;KAChB,CAAC;IAEF,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,EAAE,WAAW,EAAE;QAChD,UAAU;QACV,IAAI,EAAE,SAAS;KAChB,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO,EAAE,IAAI,CAAC,QAAQ;KACvB,CAAC;AACJ,CAAC"}

package/lib/ssim/index.d.ts

@@ -1,3 +0,0 @@
-export * from './compute_dssim.js';
-export * from './compute_ssim.js';
-//# sourceMappingURL=index.d.ts.map

package/lib/ssim/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ssim/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/lib/ssim/index.js

@@ -1,3 +0,0 @@
-export * from './compute_dssim.js';
-export * from './compute_ssim.js';
-//# sourceMappingURL=index.js.map

package/lib/ssim/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ssim/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/src/ssim/index.ts

@@ -1,2 +0,0 @@
-export * from './compute_dssim.js';
-export * from './compute_ssim.js';