image-js 1.0.0-alpha.3 → 1.0.0

package/src/load/decodeTiff.ts

@@ -0,0 +1,63 @@
+import { decode } from 'tiff';
+
+import type { BitDepth } from '../Image.js';
+import { Image } from '../Image.js';
+
+import { getMetadata } from './getMetadata.js';
+
+type TiffIfd = ReturnType<typeof decode>[number];
+
+/**
+ * Decode a TIFF. See the tiff module.
+ * @param buffer - The data to decode.
+ * @returns The decoded image.
+ */
+export function decodeTiff(buffer: Uint8Array): Image {
+  const result = decode(buffer);
+  return getImageFromIFD(result[0]);
+  // TODO: optimize not to decode whole file
+}
+
+/**
+ * Create image from a single IFD.
+ * @param ifd - The IFD.
+ * @returns The decoded image.
+ */
+export function getImageFromIFD(ifd: TiffIfd): Image {
+  if (ifd.type === 3) {
+    // Palette
+    const data = new Uint16Array(3 * ifd.width * ifd.height);
+    const palette = ifd.palette as Array<[number, number, number]>;
+    let ptr = 0;
+    for (const index of ifd.data) {
+      const color = palette[index];
+      data[ptr++] = color[0];
+      data[ptr++] = color[1];
+      data[ptr++] = color[2];
+    }
+    return new Image(ifd.width, ifd.height, {
+      data,
+      // TODO: handle alpha properly
+      colorModel: ifd.alpha ? 'RGBA' : 'RGB',
+      // TODO: handle other bit depths
+      bitDepth: 16,
+      meta: getMetadata(ifd),
+    });
+  } else {
+    return new Image(ifd.width, ifd.height, {
+      // TODO: handle float data
+      // @ts-expect-error float data not handled yet
+      data: ifd.data,
+      bitDepth: ifd.bitsPerSample as BitDepth,
+      colorModel:
+        ifd.type === 2
+          ? ifd.alpha
+            ? 'RGBA'
+            : 'RGB'
+          : ifd.alpha
+            ? 'GREYA'
+            : 'GREY',
+      meta: getMetadata(ifd),
+    });
+  }
+}

package/src/load/fetchURL.ts

@@ -0,0 +1,13 @@
+import { decode } from './decode.js';
+
+/**
+ * Fetches image URL and decodes it.
+ * @param dataUrl - Image URL.
+ * @returns decoded image data.
+ */
+export async function fetchURL(dataUrl: string) {
+  const response = await fetch(dataUrl);
+  const arrayBuffer = await response.arrayBuffer();
+  const image = decode(new DataView(arrayBuffer));
+  return image;
+}

package/src/load/getMetadata.ts

@@ -0,0 +1,18 @@
+import type { decode } from 'tiff';
+
+type TiffIfd = ReturnType<typeof decode>[number];
+
+/**
+ * Get metadata from an IFD.
+ * @param ifd - The IFD.
+ * @returns The metadata.
+ */
+export function getMetadata(ifd: TiffIfd) {
+  return {
+    tiff: {
+      fields: ifd.fields,
+      tags: ifd.map,
+    },
+    exif: ifd.exif as unknown as Record<string, unknown>,
+  };
+}

package/src/load/index.ts

@@ -1,6 +1,9 @@
-export * from './decode';
-export * from './decodeJpeg';
-export * from './decodePng';
-export * from './read';
-export * from './readCanvas';
-export * from './readImg';
+export * from './decode.js';
+export * from './decodeJpeg.js';
+export * from './decodePng.js';
+export * from './decodeTiff.js';
+export * from './load.types.js';
+export * from './read.js';
+export * from './readCanvas.js';
+export * from './readImg.js';
+export * from './fetchURL.js';

package/src/load/load.types.ts

@@ -0,0 +1,7 @@
+export interface ImageMetadata {
+  tiff: {
+    fields: Map<number, unknown>;
+    tags: Record<string, unknown>;
+  };
+  exif: Record<string, unknown>;
+}

package/src/load/read.ts

@@ -1,25 +1,28 @@
-import { readFile, readFileSync } from 'fs';
-import { promisify } from 'util';
+import type { Image } from '../Image.js';
+import { getNodeApiOrThrow } from '../utils/cross_platform.js';
 
-import { Image } from '../Image';
-
-import { decode } from './decode';
-
-const readFilePromise = promisify(readFile);
+import { decode } from './decode.js';
 
 /**
  * Read an image from the disk.
  * The file format is automatically selected based on the first few bytes.
- * @param path - The file path to read.
+ * This method is only implemented for Node.js.
+ * @param path - The path to the image.
+ * @returns Image instance.
  */
-export async function read(path: string): Promise<Image> {
-  const data = await readFilePromise(path);
+export async function read(path: string | URL): Promise<Image> {
+  const nodeApi = getNodeApiOrThrow('read');
+  const data = await nodeApi.fs.promises.readFile(path);
   return decode(data);
 }
 
 /**
  * Synchronous version of @see {@link read}.
+ * This method is only implemented for Node.js.
+ * @param path - The path to the image.
+ * @returns Image instance.
  */
-export function readSync(path: string): Image {
-  return decode(readFileSync(path));
+export function readSync(path: string | URL): Image {
+  const nodeApi = getNodeApiOrThrow('readSync');
+  return decode(nodeApi.fs.readFileSync(path));
 }

package/src/load/readCanvas.ts

@@ -1,19 +1,21 @@
-import { Image, ImageKind } from '../Image';
+import { Image } from '../Image.js';
+import { assert } from '../utils/validators/assert.js';
 
+/**
+ * Read an image from an HTML canvas element.
+ * @param canvas - Canvas element.
+ * @returns The read image.
+ */
 export function readCanvas(canvas: HTMLCanvasElement): Image {
   const ctx = canvas.getContext('2d');
-  if (ctx === null) {
-    throw new Error('could not get context from canvas element');
-  }
+  assert(ctx);
   const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
-  return new Image({
-    width: imageData.width,
-    height: imageData.height,
+  return new Image(imageData.width, imageData.height, {
     data: new Uint8Array(
       imageData.data.buffer,
       imageData.data.byteOffset,
-      imageData.data.byteLength
+      imageData.data.byteLength,
     ),
-    kind: ImageKind.RGBA
+    colorModel: 'RGBA',
   });
 }

package/src/load/readImg.ts

@@ -1,16 +1,22 @@
-import { Image } from '../Image';
+import type { Image } from '../Image.js';
+import { assert } from '../utils/validators/assert.js';
 
-import { readCanvas } from './readCanvas';
+import { readCanvas } from './readCanvas.js';
+// TODO: Create nodejs version that throws an error
 
-export function readImg(img: CanvasImageSource): Image {
-  // eslint-disable-next-line no-undef
+/**
+ * Read an image from an HTML image source.
+ * @param img - Image source such as an <img> or <svg> element.
+ * @returns The read image.
+ */
+export function readImg(
+  img: Extract<CanvasImageSource, Record<'width' | 'height', number>>,
+): Image {
   const canvas = document.createElement('canvas');
-  canvas.width = img.width as number;
-  canvas.height = img.height as number;
+  canvas.width = img.width;
+  canvas.height = img.height;
   const ctx = canvas.getContext('2d');
-  if (ctx === null) {
-    throw new Error('could not get context from canvas element');
-  }
+  assert(ctx);
   ctx.drawImage(img, 0, 0);
   return readCanvas(canvas);
 }

package/src/maskAnalysis/getBorderPoints.ts

@@ -0,0 +1,70 @@
+import type { Mask } from '../Mask.js';
+import type { Point } from '../utils/geometry/points.js';
+
+import type { GetBorderPointsOptions } from './maskAnalysis.types.js';
+
+// TODO: This function could be optimised by following the contour instead of scanning all pixels.
+/**
+ * Return an array with the coordinates of the pixels that are on the border of the mask.
+ * The reference is the top-left corner of the ROI.
+ * @param mask - Mask to process.
+ * @param options - Get border points options.
+ * @returns The array of border pixels.
+ */
+export function getBorderPoints(
+  mask: Mask,
+  options: GetBorderPointsOptions = {},
+): Point[] {
+  const { innerBorders = false, allowCorners = false } = options;
+
+  if (!innerBorders) {
+    mask = mask.solidFill();
+  }
+
+  const borders: Point[] = [];
+
+  // first process frame pixels
+  for (let column = 0; column < mask.width; column++) {
+    if (mask.getBit(column, 0)) {
+      borders.push({ column, row: 0 });
+    }
+    if (mask.getBit(column, mask.height - 1)) {
+      borders.push({ column, row: mask.height - 1 });
+    }
+  }
+  for (let row = 0; row < mask.height; row++) {
+    if (mask.getBit(0, row)) {
+      borders.push({ column: 0, row });
+    }
+    if (mask.getBit(mask.width - 1, row)) {
+      borders.push({ column: mask.width - 1, row });
+    }
+  }
+
+  for (let row = 1; row < mask.height - 1; row++) {
+    for (let column = 1; column < mask.width - 1; column++) {
+      if (mask.getBit(column, row)) {
+        if (
+          mask.getBit(column - 1, row) === 0 ||
+          mask.getBit(column, row - 1) === 0 ||
+          mask.getBit(column + 1, row) === 0 ||
+          mask.getBit(column, row + 1) === 0
+        ) {
+          borders.push({ column, row });
+        }
+
+        if (
+          allowCorners &&
+          (mask.getBit(column - 1, row - 1) === 0 ||
+            mask.getBit(column - 1, row + 1) === 0 ||
+            mask.getBit(column + 1, row - 1) === 0 ||
+            mask.getBit(column + 1, row + 1) === 0)
+        ) {
+          borders.push({ column, row });
+        }
+      }
+    }
+  }
+
+  return borders;
+}

package/src/maskAnalysis/getConvexHull.ts

@@ -0,0 +1,29 @@
+import type { Mask } from '../Mask.js';
+import {
+  getPolygonArea,
+  getPolygonPerimeter,
+} from '../utils/geometry/polygons.js';
+
+import type { ConvexHull } from './maskAnalysis.types.js';
+import { getExtendedBorderPoints } from './utils/getExtendedBorderPoints.js';
+import { monotoneChainConvexHull as mcch } from './utils/monotoneChainConvexHull.js';
+
+/**
+ * Get the vertices of the convex Hull polygon of a mask.
+ * @param mask - Mask to process.
+ * @returns Array of the vertices of the convex Hull in clockwise order.
+ */
+export function getConvexHull(mask: Mask): ConvexHull {
+  const borderPoints = getExtendedBorderPoints(mask);
+  if (borderPoints.length === 0) {
+    return {
+      points: [],
+      surface: 0,
+      perimeter: 0,
+    };
+  }
+  const points = mcch(borderPoints);
+  const perimeter = getPolygonPerimeter(points);
+  const surface = getPolygonArea(points);
+  return { points, perimeter, surface };
+}

package/src/maskAnalysis/getFeret.ts

@@ -0,0 +1,239 @@
+import type { Mask } from '../Mask.js';
+import type { Point } from '../geometry/index.js';
+import { toDegrees } from '../utils/geometry/angles.js';
+import { rotate } from '../utils/geometry/points.js';
+
+import type { Feret, FeretDiameter } from './maskAnalysis.types.js';
+import { getAngle } from './utils/getAngle.js';
+
+/**
+ * Computes the Feret diameters.
+ * @see {@link https://www.sympatec.com/en/particle-measurement/glossary/particle-shape/#}
+ * @see {@link http://portal.s2nano.org:8282/files/TEM_protocol_NANoREG.pdf}
+ * @param mask - The mask of the ROI.
+ * @returns The Feret diameters.
+ */
+export function getFeret(mask: Mask): Feret {
+  const hull = mask.getConvexHull();
+  const hullPoints = hull.points;
+  if (hull.surface === 0) {
+    return {
+      minDiameter: {
+        length: 0,
+        points: [
+          { column: 0, row: 0 },
+          { column: 0, row: 0 },
+        ],
+        angle: 0,
+        calliperLines: [
+          [
+            { column: 0, row: 0 },
+            { column: 0, row: 0 },
+          ],
+          [
+            { column: 0, row: 0 },
+            { column: 0, row: 0 },
+          ],
+        ],
+      },
+      maxDiameter: {
+        length: 0,
+        points: [
+          { column: 0, row: 0 },
+          { column: 0, row: 0 },
+        ],
+        angle: 0,
+        calliperLines: [
+          [
+            { column: 0, row: 0 },
+            { column: 0, row: 0 },
+          ],
+          [
+            { column: 0, row: 0 },
+            { column: 0, row: 0 },
+          ],
+        ],
+      },
+      aspectRatio: 1,
+    };
+  }
+
+  // Compute minimum diameter
+  let minWidth = Number.POSITIVE_INFINITY;
+  let minWidthAngle = 0;
+  let minLinePoints: Point[] = [];
+  let minLines: [[Point, Point], [Point, Point]] | undefined;
+  for (let i = 0; i < hullPoints.length; i++) {
+    const angle = getAngle(
+      hullPoints[i],
+      hullPoints[(i + 1) % hullPoints.length],
+    );
+
+    // We rotate so that it is parallel to X axis.
+    const rotatedPoints = rotate(-angle, hullPoints);
+    let currentWidth = 0;
+    let currentMinLinePoints: Point[] = [];
+
+    for (let j = 0; j < hullPoints.length; j++) {
+      const absWidth = Math.abs(rotatedPoints[i].row - rotatedPoints[j].row);
+      if (absWidth > currentWidth) {
+        currentWidth = absWidth;
+        currentMinLinePoints = [rotatedPoints[i], rotatedPoints[j]];
+      }
+    }
+    if (currentWidth < minWidth) {
+      minWidth = currentWidth;
+      minWidthAngle = angle;
+      minLinePoints = currentMinLinePoints;
+      const { minIndex: currentMin, maxIndex: currentMax } =
+        findPointIndexesOfExtremeColumns(rotatedPoints);
+      minLines = getMinLines(
+        minWidthAngle,
+        currentMin,
+        currentMax,
+        rotatedPoints,
+        minLinePoints,
+      );
+    }
+  }
+
+  const minDiameter: FeretDiameter = {
+    points: rotate(minWidthAngle, minLinePoints),
+    length: minWidth,
+    angle: toDegrees(minWidthAngle),
+    calliperLines: minLines as [[Point, Point], [Point, Point]],
+  };
+
+  // Compute maximum diameter
+  let maxLinePoints: Point[] = [];
+  let maxSquaredWidth = 0;
+  let maxLineIndex: number[] = [];
+  for (let i = 0; i < hullPoints.length - 1; i++) {
+    for (let j = i + 1; j < hullPoints.length; j++) {
+      const currentSquaredWidth =
+        (hullPoints[i].column - hullPoints[j].column) ** 2 +
+        (hullPoints[i].row - hullPoints[j].row) ** 2;
+      if (currentSquaredWidth > maxSquaredWidth) {
+        maxSquaredWidth = currentSquaredWidth;
+        maxLinePoints = [hullPoints[i], hullPoints[j]];
+        maxLineIndex = [i, j];
+      }
+    }
+  }
+  const maxAngle = getAngle(maxLinePoints[0], maxLinePoints[1]);
+  const rotatedMaxPoints = rotate(-maxAngle, hullPoints);
+
+  const { minIndex: currentMin, maxIndex: currentMax } =
+    findPointsIndexesOfExtremeRows(rotatedMaxPoints);
+  const maxLines = getMaxLines(
+    maxAngle,
+    currentMin,
+    currentMax,
+    rotatedMaxPoints,
+    maxLineIndex,
+  );
+  const maxDiameter = {
+    length: Math.sqrt(maxSquaredWidth),
+    angle: toDegrees(getAngle(maxLinePoints[0], maxLinePoints[1])),
+    points: maxLinePoints,
+    calliperLines: maxLines,
+  };
+
+  return {
+    minDiameter,
+    maxDiameter,
+    aspectRatio: minDiameter.length / maxDiameter.length,
+  };
+}
+
+function findPointIndexesOfExtremeColumns(points: Point[]): {
+  minIndex: number;
+  maxIndex: number;
+} {
+  let maxIndex = 0;
+  let minIndex = 0;
+
+  for (let i = 0; i < points.length; i++) {
+    if (points[i].column > points[maxIndex].column) {
+      maxIndex = i;
+    }
+    if (points[i].column < points[minIndex].column) {
+      minIndex = i;
+    }
+  }
+  return { minIndex, maxIndex };
+}
+function findPointsIndexesOfExtremeRows(points: Point[]): {
+  minIndex: number;
+  maxIndex: number;
+} {
+  let maxIndex = 0;
+  let minIndex = 0;
+  for (let i = 0; i < points.length; i++) {
+    if (points[i].row > points[maxIndex].row) {
+      maxIndex = i;
+    }
+    if (points[i].row < points[minIndex].row) {
+      minIndex = i;
+    }
+  }
+  return { minIndex, maxIndex };
+}
+
+function getMinLines(
+  angle: number,
+  min: number,
+  max: number,
+  rotatedPoints: Point[],
+  feretPoints: Point[],
+): [[Point, Point], [Point, Point]] {
+  const minLine1: [Point, Point] = [
+    { column: rotatedPoints[min].column, row: feretPoints[0].row },
+    {
+      column: rotatedPoints[max].column,
+      row: feretPoints[0].row,
+    },
+  ];
+  const minLine2: [Point, Point] = [
+    {
+      column: rotatedPoints[min].column,
+      row: feretPoints[1].row,
+    },
+    {
+      column: rotatedPoints[max].column,
+      row: feretPoints[1].row,
+    },
+  ];
+
+  return [rotate(angle, minLine1), rotate(angle, minLine2)] as [
+    [Point, Point],
+    [Point, Point],
+  ];
+}
+function getMaxLines(
+  angle: number,
+  min: number,
+  max: number,
+  rotatedPoints: Point[],
+  index: number[],
+): [[Point, Point], [Point, Point]] {
+  const maxLine1: [Point, Point] = [
+    { column: rotatedPoints[index[0]].column, row: rotatedPoints[min].row },
+    {
+      column: rotatedPoints[index[0]].column,
+      row: rotatedPoints[max].row,
+    },
+  ];
+  const maxLine2: [Point, Point] = [
+    { column: rotatedPoints[index[1]].column, row: rotatedPoints[min].row },
+    {
+      column: rotatedPoints[index[1]].column,
+      row: rotatedPoints[max].row,
+    },
+  ];
+
+  return [rotate(angle, maxLine1), rotate(angle, maxLine2)] as [
+    [Point, Point],
+    [Point, Point],
+  ];
+}

package/src/maskAnalysis/getMbr.ts

@@ -0,0 +1,17 @@
+import type { Mask } from '../Mask.js';
+
+import type { Mbr } from './maskAnalysis.types.js';
+import { getExtendedBorderPoints } from './utils/getExtendedBorderPoints.js';
+import { getMbrFromPoints } from './utils/getMbrFromPoints.js';
+import { monotoneChainConvexHull } from './utils/monotoneChainConvexHull.js';
+
+/**
+ * Get the four corners of the minimum bounding rectangle of an ROI.
+ * @param mask - The ROI to process.
+ * @returns The array of corners.
+ */
+export function getMbr(mask: Mask): Mbr {
+  const vertices = monotoneChainConvexHull(getExtendedBorderPoints(mask));
+
+  return getMbrFromPoints(vertices);
+}

package/src/maskAnalysis/index.ts

@@ -0,0 +1 @@
+export * from './maskAnalysis.types.js';

package/src/maskAnalysis/maskAnalysis.types.ts

@@ -0,0 +1,100 @@
+import type { Point } from '../utils/geometry/points.js';
+
+export interface FeretDiameter {
+  /**
+   * Start and end point of the Feret diameter.
+   */
+  points: Point[];
+  /**
+   * Length of the diameter.
+   */
+  length: number;
+  /**
+   * Angle between the diameter and a horizontal line in degrees.
+   */
+  angle: number;
+  /**
+   * Calliper lines that pass by endpoints of Feret diameters.
+   */
+  calliperLines: [[Point, Point], [Point, Point]];
+}
+export interface Feret {
+  /**
+   * Smaller Feret diameter.
+   */
+  minDiameter: FeretDiameter;
+  /**
+   * Bigger Feret diameter.
+   */
+  maxDiameter: FeretDiameter;
+  /**
+   * Ratio between the smaller and the bigger diameter.
+   * Expresses how elongated the shape is. This is a value between 0 and 1.
+   */
+  aspectRatio: number;
+}
+
+/**
+ * Minimum bounding rectangle of a mask.
+ */
+export interface Mbr {
+  /**
+   * Vertices of the MBR in clockwise order.
+   */
+  points: Point[];
+  /**
+   * Perimeter of the MBR.
+   */
+  perimeter: number;
+  /**
+   * Surface of the MBR.
+   */
+  surface: number;
+  /**
+   * Width of the rectangle.
+   */
+  width: number;
+  /**
+   * Height of the rectangle.
+   */
+  height: number;
+  /**
+   * Angle between the rectangle and a horizontal line in radians.
+   */
+  angle: number;
+  /**
+   * Ratio between width and height.
+   */
+  aspectRatio: number;
+}
+
+export interface GetBorderPointsOptions {
+  /**
+   * Should the inner borders be returned too?
+   * @default `false`
+   */
+  innerBorders?: boolean;
+  /**
+   * Consider pixels connected by corners?
+   * @default `false`
+   */
+  allowCorners?: boolean;
+}
+
+/**
+ * Convex Hull polygon of a mask.
+ */
+export interface ConvexHull {
+  /**
+   * Vertices of the convex Hull in clockwise order.
+   */
+  points: Point[];
+  /**
+   * Perimeter of the convex Hull.
+   */
+  perimeter: number;
+  /**
+   * Surface of the convex Hull.
+   */
+  surface: number;
+}