image-js 1.0.0-alpha.3 → 1.1.0

package/src/save/encodePng.ts

@@ -1,12 +1,36 @@
-import { encode, IPNGEncoderOptions } from 'fast-png';
+import type { PngEncoderOptions } from 'fast-png';
+import { encode } from 'fast-png';
 
-import { Image } from '../Image';
+import type { Image } from '../Image.js';
+import { Mask } from '../Mask.js';
 
-export type IEncodePngOptions = IPNGEncoderOptions;
+export type EncodePngOptions = PngEncoderOptions;
 
+/**
+ * Creates a PNG buffer from an image.
+ * @param image - The image instance.
+ * @param options - PNG encoding options.
+ * @returns The buffer.
+ */
 export function encodePng(
-  image: Image,
-  options?: IPNGEncoderOptions
+  image: Image | Mask,
+  options?: EncodePngOptions,
 ): Uint8Array {
-  return encode(image, options);
+  if (
+    (image.colorModel !== 'RGB' &&
+      image.colorModel !== 'RGBA' &&
+      image.colorModel !== 'GREY' &&
+      image.colorModel !== 'GREYA') ||
+    image instanceof Mask
+  ) {
+    image = image.convertColor('GREY');
+  }
+  const { bitDepth: depth, ...other } = image.getRawImage();
+  return encode(
+    {
+      depth,
+      ...other,
+    },
+    options,
+  );
 }

package/src/save/index.ts

@@ -1,5 +1,6 @@
-export * from './encode';
-export * from './encodePng';
-export * from './encodeJpeg';
-export * from './write';
-export * from './writeCanvas';
+export * from './encode.js';
+export * from './encodePng.js';
+export * from './encodeJpeg.js';
+export * from './write.js';
+export * from './writeCanvas.js';
+export * from './encodeDataURL.js';

package/src/save/write.ts

@@ -1,92 +1,171 @@
-import { writeFile, writeFileSync } from 'fs';
-import { extname } from 'path';
-import { promisify } from 'util';
+import type { Image } from '../Image.js';
+import { Mask } from '../Mask.js';
+import { getNodeApiOrThrow } from '../utils/cross_platform.js';
 
-import { Image } from '../Image';
+import type {
+  EncodeOptionsBmp,
+  EncodeOptionsJpeg,
+  EncodeOptionsPng,
+} from './encode.js';
+import { encode } from './encode.js';
 
-import {
-  encode,
-  ImageFormat,
-  IEncodeOptionsPng,
-  IEncodeOptionsJpeg
-} from './encode';
+export interface WriteOptions {
+  /**
+   * If true, attempts to create all the missing directories recursively.
+   */
+  recursive?: boolean;
+}
 
-const writeFilePromise = promisify(writeFile);
+export type WriteOptionsPng = WriteOptions & EncodeOptionsPng;
+export type WriteOptionsJpeg = WriteOptions & EncodeOptionsJpeg;
+export type WriteOptionsBmp = WriteOptions & EncodeOptionsBmp;
 
 /**
  * Write an image to the disk.
  * The file format is determined automatically from the file's extension.
  * If the extension is not supported, an error will be thrown.
+ * This method is only implemented for Node.js.
+ * @param path - Path or file URL where the image should be written.
+ * @param image - Image to save.
+ * @param options - Write options.
+ * @returns A promise that resolves when the image is written.
  */
-export async function write(path: string, image: Image): Promise<void>;
+export async function write(
+  path: string | URL,
+  image: Image | Mask,
+  options?: WriteOptions,
+): Promise<void>;
 /**
  * Write an image to the disk as PNG.
  * When the `png` format is specified, the file's extension doesn't matter.
+ * This method is only implemented for Node.js.
+ * @param path - Path or file URL where the image should be written.
+ * @param image - Image to save.
+ * @param options - Encode options for png images.
+ * @returns A promise that resolves when the image is written.
  */
 export async function write(
-  path: string,
-  image: Image,
-  options: IEncodeOptionsPng
+  path: string | URL,
+  image: Image | Mask,
+  options: WriteOptionsPng,
 ): Promise<void>;
 /**
  * Write an image to the disk as JPEG.
  * When the `jpeg` format is specified, the file's extension doesn't matter.
+ * This method is only implemented for Node.js.
+ * @param path - Path or file URL where the image should be written.
+ * @param image - Image to save.
+ * @param options - Encode options for jpeg images.
+ * @returns A promise that resolves when the image is written.
+ */
+export async function write(
+  path: string | URL,
+  image: Image | Mask,
+  options: WriteOptionsJpeg,
+): Promise<void>;
+
+/**
+ * Write an image to the disk as BMP.
+ * When the `bmp` format is specified, the file's extension doesn't matter.
+ * This method is only implemented for Node.js.
+ * @param path - Path or file URL where the image should be written.
+ * @param image - Image to save.
+ * @param options - Encode options for bmp images.
+ * @returns A promise that resolves when the image is written.
  */
 export async function write(
-  path: string,
-  image: Image,
-  options: IEncodeOptionsJpeg
+  path: string | URL,
+  image: Mask,
+  options?: WriteOptionsBmp,
 ): Promise<void>;
+/**
+ * Asynchronously write an image to the disk.
+ * This method is only implemented for Node.js.
+ * @param path - Path where the image should be written.
+ * @param image - Image to save.
+ * @param options - Encode options.
+ */
 export async function write(
-  path: string,
-  image: Image,
-  options?: IEncodeOptionsPng | IEncodeOptionsJpeg
+  path: string | URL,
+  image: Image | Mask,
+  options?: WriteOptionsBmp | WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
 ): Promise<void> {
-  const toWrite = getDataToWrite(path, image, options);
-  await writeFilePromise(path, toWrite);
+  const nodeApi = getNodeApiOrThrow('write');
+  if (typeof path !== 'string') {
+    path = nodeApi.url.fileURLToPath(path);
+  }
+  if (image instanceof Mask) {
+    image = image.convertColor('GREY');
+  }
+  const toWrite = getDataToWrite(path, image, options, nodeApi);
+  if (options?.recursive) {
+    const dir = nodeApi.path.dirname(path);
+    await nodeApi.fs.promises.mkdir(dir, { recursive: true });
+  }
+  await nodeApi.fs.promises.writeFile(path, toWrite);
 }
 
 /**
  * Synchronous version of @see {@link write}.
+ * This method is only implemented for Node.js.
+ * @param path - Path where the image should be written.
+ * @param image - Image to save.
+ * @param options - Encode options.
  */
 export function writeSync(
-  path: string,
-  image: Image,
-  options?: IEncodeOptionsPng | IEncodeOptionsJpeg
+  path: string | URL,
+  image: Image | Mask,
+  options?: WriteOptionsBmp | WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
 ): void {
-  const toWrite = getDataToWrite(path, image, options);
-  writeFileSync(path, toWrite);
+  const nodeApi = getNodeApiOrThrow('writeSync');
+  if (typeof path !== 'string') {
+    path = nodeApi.url.fileURLToPath(path);
+  }
+  const toWrite = getDataToWrite(path, image, options, nodeApi);
+  if (options?.recursive) {
+    const dir = nodeApi.path.dirname(path);
+    nodeApi.fs.mkdirSync(dir, { recursive: true });
+  }
+  nodeApi.fs.writeFileSync(path, toWrite);
 }
 
+/**
+ * Encode the image to the format specified by the file's extension.
+ * @param destinationPath - Image destination.
+ * @param image - Image to save.
+ * @param options - Encode options.
+ * @param nodeApi - Object with Node.js APIs.
+ * @returns Buffer containing the encoded image.
+ */
 function getDataToWrite(
-  path: string,
-  image: Image,
-  options?: IEncodeOptionsPng | IEncodeOptionsJpeg
+  destinationPath: string,
+  image: Image | Mask,
+  options:
+    | WriteOptionsBmp
+    | WriteOptionsPng
+    | WriteOptionsJpeg
+    | WriteOptions
+    | undefined,
+  nodeApi: ReturnType<typeof getNodeApiOrThrow>,
 ): Uint8Array {
-  let format: ImageFormat;
-  if (options === undefined) {
-    const extension = extname(path)
+  if (!options || !('format' in options)) {
+    const extension = nodeApi.path
+      .extname(destinationPath)
       .slice(1)
       .toLowerCase();
-    if (extension === 'png') {
-      format = ImageFormat.png;
-      return encode(image, { format });
-    } else if (extension === 'jpg' || extension === 'jpeg') {
-      format = ImageFormat.jpg;
-      return encode(image, { format });
+    if (
+      extension === 'png' ||
+      extension === 'jpg' ||
+      extension === 'jpeg' ||
+      extension === 'bmp'
+    ) {
+      return encode(image, { ...options, format: extension });
     } else {
-      throw new Error(
-        'image format could not be determined from file extension. Please use a supported extension or specify the format option'
+      throw new RangeError(
+        'image format could not be determined from file extension. Use a supported extension or specify the format option',
       );
     }
-  } else if (options.format === ImageFormat.png) {
-    return encode(image, options);
-  } else if (
-    options.format === ImageFormat.jpg ||
-    options.format === ImageFormat.jpeg
-  ) {
-    return encode(image, options);
   } else {
-    throw new RangeError(`unknown format: ${options.format}`);
+    return encode(image, options);
   }
 }

package/src/save/writeCanvas.ts

@@ -1,25 +1,56 @@
-import { Image, ImageKind } from '../Image';
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import { assert } from '../utils/validators/assert.js';
 
-export interface IWriteCanvasOptions {
+export interface WriteCanvasOptions {
   /**
-   * If set to `true` (default), the canvas element will be resized to fit the image.
+   * If set to `true`, the canvas element will be resized to fit the image.
+   * @default `true`
    */
   resizeCanvas?: boolean;
+  /**
+   * @default `0`
+   */
   dx?: number;
+  /**
+   *  @default `0`
+   */
   dy?: number;
+  /**
+   * @default `0`
+   */
   dirtyX?: number;
+  /**
+   * @default `0`
+   */
   dirtyY?: number;
+  /**
+   * @default `image.width`
+   */
   dirtyWidth?: number;
+  /**
+   * @default `image.height`
+   */
   dirtyHeight?: number;
 }
 
+// TODO: Create nodejs version that throws an error
+/**
+ * Draw the image in an HTML canvas.
+ * @param image - The image to draw.
+ * @param canvas - The HTML canvas.
+ * @param options - Write canvas options.
+ */
 export function writeCanvas(
+  image: Image | Mask,
   canvas: HTMLCanvasElement,
-  image: Image,
-  options: IWriteCanvasOptions = {}
+  options: WriteCanvasOptions = {},
 ): void {
-  if (image.kind !== ImageKind.RGBA) {
-    image = image.convertColor(ImageKind.RGBA);
+  if (image.colorModel !== 'RGBA') {
+    image = image.convertColor('RGBA');
+  }
+  if (image.bitDepth !== 8 && image instanceof Image) {
+    image = image.convertBitDepth(8);
   }
   const {
     resizeCanvas = true,
@@ -28,32 +59,27 @@ export function writeCanvas(
     dirtyX = 0,
     dirtyY = 0,
     dirtyWidth = image.width,
-    dirtyHeight = image.height
+    dirtyHeight = image.height,
   } = options;
   if (resizeCanvas) {
     canvas.width = image.width;
     canvas.height = image.height;
   }
   const ctx = canvas.getContext('2d');
-  if (ctx === null) {
-    throw new Error('could not get context from canvas element');
-  }
+  assert(ctx);
+  const data = image.getRawImage().data;
   ctx.putImageData(
-    // eslint-disable-next-line no-undef
     new ImageData(
-      new Uint8ClampedArray(
-        image.data.buffer,
-        image.data.byteOffset,
-        image.data.byteLength
-      ),
+      // @ts-expect-error ImageData types don't support SharedArrayBuffer.
+      new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength),
       image.width,
-      image.height
+      image.height,
     ),
     dx,
     dy,
     dirtyX,
     dirtyY,
     dirtyWidth,
-    dirtyHeight
+    dirtyHeight,
   );
 }

package/src/ssim/compute_dssim.ts

@@ -0,0 +1,21 @@
+import type { Image } from '../Image.js';
+
+import type { SsimOptions } from './compute_ssim.js';
+import { computeSsim } from './compute_ssim.js';
+
+/**
+ * Compute the Structural Dissimilarity (DSSIM) of two GREY images.
+ * @see {@link https://en.wikipedia.org/wiki/Structural_similarity}
+ * @param image - First image.
+ * @param otherImage - Second image.
+ * @param options - Options.
+ * @returns SSIM of the two images.
+ */
+export function computeDssim(
+  image: Image,
+  otherImage: Image,
+  options: SsimOptions = {},
+): number {
+  const ssim = computeSsim(image, otherImage, options).mssim;
+  return (1 - ssim) / 2;
+}

package/src/ssim/compute_ssim.ts

@@ -0,0 +1,94 @@
+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';
+
+export interface SsimOptions {
+  /**
+   * Window size for SSIM map.
+   * @default `Math.min(11, image.width, image.height)`
+   */
+  windowSize?: number;
+  /**
+   * Algorithm to use to compute the SSIM.
+   * @default `'original'`
+   */
+  algorithm?: 'fast' | 'original' | 'bezkrovny' | 'weber';
+}
+
+export interface Ssim {
+  /**
+   * Mean SSIM of the whole image. It is the mean value of the SSIM map.
+   * It is a similarity score between two images.
+   */
+  mssim: number;
+  /**
+   * Similarity map of the two images. The dimensions of the map depend the windowSize option.
+   * Create a GREY image based on this map to visualize the similarity of the different regions of the image.
+   */
+  ssimMap: { data: number[]; width: number; height: number };
+}
+
+/**
+ * Compute the Structural Similarity (SSIM) of two RGBA or two GREY images.
+ * "The resultant SSIM index is a decimal value between -1 and 1,
+ * where 1 indicates perfect similarity, 0 indicates no similarity,
+ * and -1 indicates perfect anti-correlation."
+ * @see {@link https://en.wikipedia.org/wiki/Structural_similarity}
+ * @param image - First image.
+ * @param otherImage - Second image.
+ * @param options - SSIM options.
+ * @returns SSIM of the two images.
+ */
+export function computeSsim(
+  image: Image,
+  otherImage: Image,
+  options: SsimOptions = {},
+): Ssim {
+  let { windowSize } = options;
+  const { algorithm = 'original' } = options;
+
+  if (windowSize) {
+    if (windowSize > image.width || windowSize > image.height) {
+      throw new RangeError('windowSize cannot exceed image dimensions');
+    }
+  } else {
+    windowSize = Math.min(11, image.height, image.width);
+  }
+  checkProcessable(image, {
+    bitDepth: [8],
+    channels: [1, 3, 4],
+  });
+
+  validateForComparison(image, otherImage);
+
+  if (image.colorModel !== 'RGBA') {
+    image = image.convertColor('RGBA');
+    otherImage = otherImage.convertColor('RGBA');
+  }
+
+  const imageData = new Uint8ClampedArray(image.getRawImage().data);
+  const imageBuffer = {
+    height: image.height,
+    width: image.width,
+    data: imageData,
+  };
+
+  const otherData = new Uint8ClampedArray(otherImage.getRawImage().data);
+  const otherBuffer = {
+    height: otherImage.height,
+    width: otherImage.width,
+    data: otherData,
+  };
+
+  const ssim = bufferSsim(imageBuffer, otherBuffer, {
+    windowSize,
+    ssim: algorithm,
+  });
+
+  return {
+    mssim: ssim.mssim,
+    ssimMap: ssim.ssim_map,
+  };
+}

package/src/ssim/index.ts

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

package/src/stack/compute/histogram.ts

@@ -0,0 +1,26 @@
+import type { Stack } from '../../Stack.js';
+import type { HistogramOptions } from '../../compute/index.js';
+import { checkProcessable } from '../utils/checkProcessable.js';
+
+/**
+ * Get the sum of all the histograms of the stack's images. If no channel is specified in the options, the images must be GREY.
+ * @param stack - Stack to process.
+ * @param options - Histogram options.
+ * @returns The histogram of the stack.
+ */
+export function histogram(
+  stack: Stack,
+  options: HistogramOptions,
+): Uint32Array {
+  checkProcessable(stack, { bitDepth: [8, 16] });
+  const { slots = 2 ** stack.bitDepth, channel = 0 } = options;
+  const result = new Uint32Array(slots);
+  for (let i = 0; i < stack.size; i++) {
+    const image = stack.getImage(i);
+    const histogram = image.histogram({ channel, slots });
+    for (const [index, value] of histogram.entries()) {
+      result[index] += value;
+    }
+  }
+  return result;
+}

package/src/stack/compute/maxImage.ts

@@ -0,0 +1,31 @@
+import { Image } from '../../Image.js';
+import type { Stack } from '../../Stack.js';
+import { checkProcessable } from '../utils/checkProcessable.js';
+
+/**
+ *  Returns a new image with the maximum values of each pixel from the stack.
+ * @param stack - Stack to process.
+ * @returns The maximum image.
+ */
+export function maxImage(stack: Stack): Image {
+  checkProcessable(stack, { sameDimensions: true });
+  const newImage = Image.createFrom(stack.getImage(0));
+
+  const nbChannels = newImage.channels;
+
+  for (let i = 0; i < stack.size; i++) {
+    for (let j = 0; j < newImage.size; j++) {
+      for (let channel = 0; channel < nbChannels; channel++) {
+        newImage.setValueByIndex(
+          j,
+          channel,
+          Math.max(
+            newImage.getValueByIndex(j, channel),
+            stack.getValueByIndex(i, j, channel),
+          ),
+        );
+      }
+    }
+  }
+  return newImage;
+}

package/src/stack/compute/meanImage.ts

@@ -0,0 +1,37 @@
+import { Image } from '../../Image.js';
+import type { Stack } from '../../Stack.js';
+import { checkProcessable } from '../utils/checkProcessable.js';
+
+/**
+ *  Returns a new image with the average values of each pixel of the images of the stack.
+ * @param stack - Stack to process.
+ * @returns The mean image.
+ */
+export function meanImage(stack: Stack): Image {
+  checkProcessable(stack, { sameDimensions: true, bitDepth: [8, 16] });
+
+  const image = stack.getImage(0);
+  const dataSize = image.size * stack.channels;
+  const sum = new Uint32Array(dataSize).fill(0);
+
+  for (let i = 0; i < stack.size; i++) {
+    for (let j = 0; j < image.size; j++) {
+      for (let channel = 0; channel < stack.channels; channel++) {
+        sum[j * stack.channels + channel] += stack.getValueByIndex(
+          i,
+          j,
+          channel,
+        );
+      }
+    }
+  }
+  const meanImage = Image.createFrom(image);
+  for (let i = 0; i < image.size; i++) {
+    for (let channel = 0; channel < stack.channels; channel++) {
+      const index = i * stack.channels + channel;
+      meanImage.setValueByIndex(i, channel, sum[index] / stack.size);
+    }
+  }
+
+  return meanImage;
+}

package/src/stack/compute/medianImage.ts

@@ -0,0 +1,30 @@
+// @ts-expect-error: median-quisckselect has no types
+import quickMedian from 'median-quickselect';
+
+import { Image } from '../../Image.js';
+import type { Stack } from '../../Stack.js';
+import { checkProcessable } from '../utils/checkProcessable.js';
+
+/**
+ *  Returns a new image with the median values of each pixel of the images of the stack.
+ * @param stack - Stack to process.
+ * @returns The median image.
+ */
+export function medianImage(stack: Stack): Image {
+  checkProcessable(stack, { sameDimensions: true, bitDepth: [8, 16] });
+
+  const image = stack.getImage(0);
+  const result = Image.createFrom(image);
+
+  for (let j = 0; j < image.size; j++) {
+    for (let channel = 0; channel < stack.channels; channel++) {
+      const currentValues = new Array(stack.size);
+      for (let i = 0; i < stack.size; i++) {
+        currentValues[i] = stack.getValueByIndex(i, j, channel);
+      }
+      result.setValueByIndex(j, channel, quickMedian(currentValues));
+    }
+  }
+
+  return result;
+}

package/src/stack/compute/minImage.ts

@@ -0,0 +1,32 @@
+import { Image } from '../../Image.js';
+import type { Stack } from '../../Stack.js';
+import { checkProcessable } from '../utils/checkProcessable.js';
+
+/**
+ *  Returns a new image with the minimum values of each pixel from the stack.
+ * @param stack - Stack to process.
+ * @returns The minimum image.
+ */
+export function minImage(stack: Stack): Image {
+  checkProcessable(stack, { sameDimensions: true });
+  const newImage = Image.createFrom(stack.getImage(0));
+  newImage.fill(newImage.maxValue);
+
+  const nbChannels = newImage.channels;
+
+  for (let i = 0; i < stack.size; i++) {
+    for (let j = 0; j < newImage.size; j++) {
+      for (let channel = 0; channel < nbChannels; channel++) {
+        newImage.setValueByIndex(
+          j,
+          channel,
+          Math.min(
+            newImage.getValueByIndex(j, channel),
+            stack.getValueByIndex(i, j, channel),
+          ),
+        );
+      }
+    }
+  }
+  return newImage;
+}