image-js 1.0.0-alpha.3 → 1.0.0

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

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

package/src/morphology/cannyEdgeDetector.ts

@@ -0,0 +1,209 @@
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import type { GaussianBlurOptions } from '../filters/index.js';
+import { getIndex } from '../utils/getIndex.js';
+import { imageToOutputMask } from '../utils/getOutputImage.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface CannyEdgeOptions {
+  /**
+   * Lower threshold of the gaussian blur (indicates the weak edges to discard).
+   * @default `0.04`
+   */
+  lowThreshold?: number;
+  /**
+   * Higher threshold of the gaussian blur (indicates the strong edges to keep). Value must be between 0 and 1.
+   * @default `0.1`
+   */
+  highThreshold?: number;
+  /**
+   * Standard deviation of the gaussian blur (sigma). Value must be between 0 and 1.
+   * @default `{ sigma: 1 }`
+   */
+  gaussianBlurOptions?: GaussianBlurOptions;
+  /**
+   * Enable/ disable hysteresis steps.
+   * @default `true`
+   */
+  hysteresis?: boolean;
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Mask;
+}
+
+const kernelX = [
+  [-1, 0, 1],
+  [-2, 0, 2],
+  [-1, 0, 1],
+];
+
+const kernelY = [
+  [-1, -2, -1],
+  [0, 0, 0],
+  [1, 2, 1],
+];
+
+/**
+ * Apply Canny edge detection to an image.
+ * @param image - Image to process.
+ * @param options - Canny edge detection options.
+ * @returns The processed image.
+ */
+export function cannyEdgeDetector(
+  image: Image,
+  options: CannyEdgeOptions = {},
+): Mask {
+  const {
+    hysteresis = true,
+    lowThreshold = 0.04,
+    highThreshold = 0.1,
+    gaussianBlurOptions = { sigma: 1 },
+  } = options;
+
+  const minValue = lowThreshold * image.maxValue;
+  const maxValue = highThreshold * image.maxValue;
+
+  checkProcessable(image, {
+    colorModel: 'GREY',
+  });
+
+  const width = image.width;
+  const height = image.height;
+
+  const blurred = image.gaussianBlur(gaussianBlurOptions);
+
+  const gradientX = blurred.rawDirectConvolution(kernelY);
+  const gradientY = blurred.rawDirectConvolution(kernelX);
+
+  const gradient = new Float64Array(image.size);
+  for (let i = 0; i < image.size; i++) {
+    gradient[i] = Math.hypot(gradientX[i], gradientY[i]);
+  }
+
+  const nonMaxSuppression = new Float64Array(image.size);
+  const edges = new Float64Array(image.size);
+
+  const finalImage = imageToOutputMask(image, options);
+
+  // Non-Maximum suppression
+  for (let column = 1; column < width - 1; column++) {
+    for (let row = 1; row < height - 1; row++) {
+      const currentGradientX = gradientX[getIndex(column, row, image, 0)];
+      const currentGradientY = gradientY[getIndex(column, row, image, 0)];
+      const direction = getDirection(currentGradientX, currentGradientY);
+      const currentGradient = gradient[getIndex(column, row, image, 0)];
+      if (
+        // horizontal
+        (direction === 0 &&
+          currentGradient >= gradient[getIndex(column, row - 1, image, 0)] &&
+          currentGradient >= gradient[getIndex(column, row + 1, image, 0)]) ||
+        // upward slope
+        (direction === 1 &&
+          currentGradient >=
+            gradient[getIndex(column - 1, row - 1, image, 0)] &&
+          currentGradient >=
+            gradient[getIndex(column + 1, row + 1, image, 0)]) ||
+        // vertical
+        (direction === 2 &&
+          currentGradient >= gradient[getIndex(column - 1, row, image, 0)] &&
+          currentGradient >= gradient[getIndex(column + 1, row, image, 0)]) ||
+        // downward slope
+        (direction === 3 &&
+          currentGradient >=
+            gradient[getIndex(column - 1, row + 1, image, 0)] &&
+          currentGradient >= gradient[getIndex(column + 1, row - 1, image, 0)])
+      ) {
+        // pixels to remove from the final image
+        nonMaxSuppression[getIndex(column, row, image, 0)] = currentGradient;
+      }
+    }
+  }
+
+  for (let i = 0; i < width * height; ++i) {
+    const currentNms = nonMaxSuppression[i];
+    let currentEdge = 0;
+    if (currentNms > maxValue) {
+      currentEdge++;
+      finalImage.setBitByIndex(i, 1);
+    }
+    if (currentNms > minValue) {
+      currentEdge++;
+    }
+
+    edges[i] = currentEdge;
+  }
+
+  // Hysteresis: first pass
+  if (hysteresis) {
+    let currentPixels: number[][] = [];
+    for (let column = 1; column < width - 1; ++column) {
+      for (let row = 1; row < height - 1; ++row) {
+        if (edges[getIndex(column, row, image, 0)] !== 1) {
+          continue;
+        }
+
+        outer: for (
+          let hystColumn = column - 1;
+          hystColumn < column + 2;
+          ++hystColumn
+        ) {
+          for (let hystRow = row - 1; hystRow < row + 2; ++hystRow) {
+            if (edges[getIndex(hystColumn, hystRow, image, 0)] === 2) {
+              currentPixels.push([column, row]);
+              finalImage.setValue(column, row, 0, 1);
+              break outer;
+            }
+          }
+        }
+      }
+    }
+
+    // Hysteresis: second pass
+    while (currentPixels.length > 0) {
+      const newPixels = [];
+      for (const currentPixel of currentPixels) {
+        for (let j = -1; j < 2; ++j) {
+          for (let k = -1; k < 2; ++k) {
+            if (j === 0 && k === 0) {
+              continue;
+            }
+            const row = currentPixel[0] + j;
+            const column = currentPixel[1] + k;
+            if (
+              // there could be an error here
+              edges[getIndex(column, row, image, 0)] === 1 &&
+              finalImage.getValue(column, row, 0) === 0
+            ) {
+              newPixels.push([row, column]);
+              finalImage.setValue(column, row, 0, 1);
+            }
+          }
+        }
+      }
+      currentPixels = newPixels;
+    }
+  }
+
+  return finalImage;
+
+  /* Function for debug
+  import { Matrix } from 'ml-matrix';
+
+  function printArray(array: Float64Array): void {
+    // @ts-expect-error: only for debug
+    const matrix = Matrix.from1DArray(height, width, array);
+    console.log(matrix);
+  }
+  */
+}
+
+/**
+ * Return a 0 to 3 value indicating the four main directions (horizontal, upward diagonal, vertical, downward diagonal).
+ * @param x - The x coordinate.
+ * @param y - The y coordinate.
+ * @returns The direction as a 0 to 4 value.
+ */
+export function getDirection(x: number, y: number): number {
+  return (Math.round(Math.atan2(y, x) * (4 / Math.PI)) + 4) % 4;
+}

package/src/morphology/clearBorder.ts

@@ -0,0 +1,41 @@
+import type { Mask } from '../Mask.js';
+import { borderIterator } from '../utils/borderIterator.js';
+
+import { multipleFloodFill } from './multipleFloodFill.js';
+
+export interface ClearBorderOptions {
+  /**
+   * Consider pixels connected by corners?
+   * @default `false`
+   */
+  allowCorners?: boolean;
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Mask;
+  /**
+   * Clear either white or black area touching the border.
+   * In practice it will invert the color.
+   * @default `'white'`
+   */
+  color?: 'white' | 'black';
+}
+/**
+ * Set the pixels connected to the border of the mask to zero. You can chose to allow corner connection of not with the `allowCorners` option.
+ * @param mask - The mask to process.
+ * @param options - Clear border options.
+ * @returns The image with cleared borders.
+ */
+export function clearBorder(
+  mask: Mask,
+  options: ClearBorderOptions = {},
+): Mask {
+  const { allowCorners = false, out, color = 'white' } = options;
+  return multipleFloodFill(mask, {
+    startPixels: borderIterator(mask),
+    startPixelValue: color === 'white' ? 1 : 0,
+    newPixelValue: color === 'white' ? 0 : 1,
+    allowCorners,
+    out,
+  });
+}

package/src/morphology/close.ts

@@ -0,0 +1,59 @@
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import { checkKernel } from '../utils/validators/checkKernel.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface CloseOptions {
+  /**
+   * 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 close(image: Image, options?: CloseOptions): Image;
+export function close(image: Mask, options?: CloseOptions): Mask;
+/**
+ * In mathematical morphology, the closing of a set A by a structuring element B is the erosion of the dilation of that set (Wikipedia).
+ * In image processing, closing is, together with opening, the basic workhorse of morphological noise removal.
+ * Opening removes small objects, while closing removes small holes.
+ * @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 - Close options.
+ * @returns Closed image.
+ */
+export function close(
+  image: Image | Mask,
+  options: CloseOptions = {},
+): 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++) {
+    newImage = newImage.dilate({ kernel }).erode({ kernel });
+  }
+  return newImage;
+}