image-js 1.0.0-alpha.3 → 1.1.0

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,26 @@
+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();
+  sorted.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));
+}

package/src/maskAnalysis/utils/getMbrFromPoints.ts

@@ -0,0 +1,112 @@
+import type { Point } from '../../utils/geometry/points.js';
+import { rotate } from '../../utils/geometry/points.js';
+import type { Mbr } from '../maskAnalysis.types.js';
+
+import { getAngle } from './getAngle.js';
+import { getMbrAngle } from './getMbrAngle.js';
+
+/**
+ * Get the four corners of the minimum bounding rectangle from a set of points defining a simple convex polygon.
+ * @see {@link https://www.researchgate.net/profile/Lennert_Den_Boer2/publication/303783472_A_Fast_Algorithm_for_Generating_a_Minimal_Bounding_Rectangle/links/5751a14108ae6807fafb2aa5.pdf}
+ * @param points - Points from which to compute the MBR.
+ * @returns The array of corners.
+ */
+export function getMbrFromPoints(points: readonly Point[]): Mbr {
+  if (points.length === 0) {
+    return {
+      points: [],
+      angle: 0,
+      width: 0,
+      height: 0,
+      surface: 0,
+      perimeter: 0,
+      aspectRatio: 0,
+    };
+  }
+  if (points.length === 1) {
+    return {
+      points: [points[0], points[0], points[0], points[0]],
+      perimeter: 0,
+      surface: 0,
+      angle: 0,
+      width: 0,
+      height: 0,
+      aspectRatio: 1,
+    };
+  }
+
+  let rotatedVertices: Point[] = [];
+  let minSurface = Number.POSITIVE_INFINITY;
+  let minSurfaceAngle = 0;
+  let mbr: Point[] = [];
+
+  for (let i = 0; i < points.length; i++) {
+    const angle = getAngle(points[i], points[(i + 1) % points.length]);
+
+    rotatedVertices = rotate(-angle, points);
+
+    // Rotate and translate so that this segment is at the bottom.
+    const aX = rotatedVertices[i].column;
+    const aY = rotatedVertices[i].row;
+    const bX = rotatedVertices[(i + 1) % rotatedVertices.length].column;
+    const bY = rotatedVertices[(i + 1) % rotatedVertices.length].row;
+
+    let tUndefined = true;
+    let tMin = 0;
+    let tMax = 0;
+    let maxWidth = 0;
+    for (const point of rotatedVertices) {
+      const cX = point.column;
+      const cY = point.row;
+      const t = (cX - aX) / (bX - aX);
+      if (tUndefined) {
+        tUndefined = false;
+        tMin = t;
+        tMax = t;
+      } else {
+        if (t < tMin) tMin = t;
+        if (t > tMax) tMax = t;
+      }
+      const width = (-(bX - aX) * cY + bX * aY - bY * aX) / (bX - aX);
+
+      if (Math.abs(width) > Math.abs(maxWidth)) {
+        maxWidth = width;
+      }
+    }
+    const minPoint = { column: aX + tMin * (bX - aX), row: aY };
+    const maxPoint = { column: aX + tMax * (bX - aX), row: aY };
+
+    const currentSurface = Math.abs(maxWidth * (tMin - tMax) * (bX - aX));
+
+    if (currentSurface < minSurface) {
+      minSurfaceAngle = angle;
+      minSurface = currentSurface;
+      mbr = [
+        maxPoint,
+        minPoint,
+        { column: minPoint.column, row: minPoint.row - maxWidth },
+        { column: maxPoint.column, row: maxPoint.row - maxWidth },
+      ];
+    }
+  }
+
+  const mbrRotated = rotate(minSurfaceAngle, mbr);
+  const sides = [
+    Math.hypot(mbr[0].column - mbr[1].column, mbr[0].row - mbr[1].row),
+    Math.hypot(mbr[0].column - mbr[3].column, mbr[0].row - mbr[3].row),
+  ];
+  const maxSide = Math.max(...sides);
+  const minSide = Math.min(...sides);
+  const mbrAngle = getMbrAngle(mbrRotated);
+  const ratio = minSide / maxSide;
+
+  return {
+    points: mbrRotated,
+    surface: minSurface,
+    angle: mbrAngle,
+    width: maxSide,
+    height: minSide,
+    perimeter: 2 * maxSide + 2 * minSide,
+    aspectRatio: ratio,
+  };
+}

package/src/maskAnalysis/utils/monotoneChainConvexHull.ts

@@ -0,0 +1,66 @@
+import type { Point } from '../../utils/geometry/points.js';
+
+interface McchOptions {
+  /**
+   * Whether the input points are already sorted or not (sort by column and then row).
+   * @default `false`
+   */
+  sorted?: boolean;
+}
+
+/**
+ * Computes the convex hull of a binary image using Andrew's Monotone Chain Algorithm
+ * @see {@link http://www.algorithmist.com/index.php/Monotone_Chain_Convex_Hull}
+ * @param points - An array of points.
+ * @param options - MCCH Algorithm options.
+ * @returns Coordinates of the convex hull in clockwise order.
+ */
+export function monotoneChainConvexHull(
+  points: Point[],
+  options: McchOptions = {},
+): Point[] {
+  const { sorted = false } = options;
+  if (!sorted) {
+    points = points.slice();
+    points.sort(byXThenY);
+  }
+
+  const n = points.length;
+  const result = new Array(n * 2);
+  let k = 0;
+
+  for (let i = 0; i < n; i++) {
+    const point = points[i];
+    while (k >= 2 && cw(result[k - 2], result[k - 1], point) <= 0) {
+      k--;
+    }
+    result[k++] = point;
+  }
+
+  const t = k + 1;
+  for (let i = n - 2; i >= 0; i--) {
+    const point = points[i];
+    while (k >= t && cw(result[k - 2], result[k - 1], point) <= 0) {
+      k--;
+    }
+    result[k++] = point;
+  }
+
+  return result.slice(0, k - 1);
+}
+
+function cw(p1: Point, p2: Point, p3: Point) {
+  return (
+    (p2.row - p1.row) * (p3.column - p1.column) -
+    (p2.column - p1.column) * (p3.row - p1.row)
+  );
+}
+
+function byXThenY(point1: Point, point2: Point) {
+  if (point1.column === point2.column) {
+    return point1.row - point2.row;
+  }
+  return point1.column - point2.column;
+}
+
+// 0 -> column, 1 -> row

package/src/morphology/bottomHat.ts

@@ -0,0 +1,64 @@
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import { subtract } from '../compare/index.js';
+import { checkKernel } from '../utils/validators/checkKernel.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface BottomHatOptions {
+  /**
+   * 3x3 matrix. The kernel can only have ones and zeros.
+   * Accessing a value: kernel[row][column].
+   * @default `[[1, 1, 1], [1, 1, 1], [1, 1, 1]]`
+   */
+  kernel?: number[][];
+  /**
+   * Number of iterations of the algorithm.
+   * @default `1`
+   */
+  iterations?: number;
+}
+
+export function bottomHat(image: Image, options?: BottomHatOptions): Image;
+export function bottomHat(image: Mask, options?: BottomHatOptions): Mask;
+/**
+ * This function is the black top hat (also called bottom hat).
+ * In mathematical morphology and digital image processing,
+ * top-hat transform is an operation that extracts small elements and details from given images.
+ * The black top-hat transform is defined dually as the difference between the closed and the input image.
+ * Top-hat transforms are used for various image processing tasks, such as feature extraction, background equalization,
+ * image enhancement, and others. (Wikipedia)
+ * @see {@link http://docs.opencv.org/2.4/doc/tutorials/imgproc/opening_closing_hats/opening_closing_hats.html}
+ * @param image - Image to process.
+ * @param options - Bottom hat options.
+ * @returns The bottom-hatted image.
+ */
+export function bottomHat(
+  image: Image | Mask,
+  options: BottomHatOptions = {},
+): Image | Mask {
+  const {
+    kernel = [
+      [1, 1, 1],
+      [1, 1, 1],
+      [1, 1, 1],
+    ],
+    iterations = 1,
+  } = options;
+
+  if (image instanceof Image) {
+    checkProcessable(image, {
+      bitDepth: [1, 8, 16],
+      components: 1,
+      alpha: false,
+    });
+  }
+
+  checkKernel(kernel);
+
+  let newImage = image;
+  for (let i = 0; i < iterations; i++) {
+    const openImage = newImage.close({ kernel });
+    newImage = subtract(openImage, newImage, { absolute: true });
+  }
+  return newImage;
+}