image-js 1.0.0-alpha.2 → 1.0.0

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;
+}

package/src/maskAnalysis/utils/getAngle.ts

@@ -0,0 +1,40 @@
+import type { Point } from '../../utils/geometry/points.js';
+import { difference, normalize } from '../../utils/geometry/points.js';
+
+/**
+ * The angle in radians of a vector relatively to the x axis.
+ * The angle is positive in the clockwise direction.
+ * This is an optimized version because it assumes that one of
+ * the points is on the line y = 0.
+ * @param p1 - First point.
+ * @param p2 - Second point.
+ * @returns Rotation angle in radians to make the line horizontal. -π <= angle <= π.
+ */
+export function getAngle(p1: Point, p2: Point): number {
+  const diff = difference(p2, p1);
+  const vector = normalize(diff);
+  const angle = Math.acos(vector.column);
+  if (vector.row < 0) return -angle;
+  return angle;
+}
+
+/**
+ * Compute the clockwise angle in radians between the x-axis and the segment p1-p2.
+ * @param p1 - First point.
+ * @param p2 - Second point.
+ * @returns Clockwise angle between x-axis and the segment.
+ */
+export function getClockwiseAngle(p1: Point, p2: Point): number {
+  const diff = difference(p2, p1);
+  const vector = normalize(diff);
+  const atan = -Math.atan(vector.row / vector.column);
+  if (vector.column < 0) {
+    if (vector.row < 0) {
+      return atan - Math.PI;
+    } else {
+      return atan + Math.PI;
+    }
+  } else {
+    return atan;
+  }
+}

package/src/maskAnalysis/utils/getExtendedBorderPoints.ts

@@ -0,0 +1,30 @@
+import type { Mask } from '../../Mask.js';
+import type { Point } from '../../utils/geometry/points.js';
+
+/**
+ * Get the pixels that surround an ROI. The pixels include the top and left borders,
+ * but extend the right and bottom one by one pixel.
+ * This allows to compute the minimum bounding rectangle with the correct surface.
+ * This method is only used to calculate minimalBoundRectangle and convexHull.
+ * @param mask - The ROI for which to get the extended border points.
+ * @returns - The array of points.
+ */
+export function getExtendedBorderPoints(mask: Mask): Point[] {
+  const borderPoints = mask.getBorderPoints({
+    allowCorners: true,
+    innerBorders: false,
+  });
+
+  const result: Point[] = [];
+
+  for (const point of borderPoints) {
+    result.push(
+      point,
+      { column: point.column + 1, row: point.row },
+      { column: point.column + 1, row: point.row + 1 },
+      { column: point.column, row: point.row + 1 },
+    );
+  }
+
+  return result;
+}

package/src/maskAnalysis/utils/getMbrAngle.ts

@@ -0,0 +1,25 @@
+import type { Point } from '../../geometry/index.js';
+import { toDegrees } from '../../utils/geometry/angles.js';
+
+import { getAngle } from './getAngle.js';
+
+const leftFirst = (mbrPoint1: Point, mbrPoint2: Point) =>
+  mbrPoint1.column <= mbrPoint2.column ? -1 : 1;
+const topFirst = (mbrPoint1: Point, mbrPoint2: Point) =>
+  mbrPoint1.row >= mbrPoint2.row ? -1 : 1;
+
+/**
+ * Get the anti-clockwise angle in degrees between the MBR and a horizontal line.
+ * @param mbr - MBR to process.
+ * @returns The angle in degrees.
+ */
+export function getMbrAngle(mbr: readonly Point[]): number {
+  const sorted = mbr.slice().sort(leftFirst);
+  const left = sorted.slice(0, 2);
+  const right = sorted.slice(2, 4);
+  left.sort(topFirst);
+  right.sort(topFirst);
+  const topLeft = left[0];
+  const topRight = right[0];
+  return -toDegrees(getAngle(topLeft, topRight));
+}