image-js 1.0.0-alpha.3 → 1.0.0

package/src/roi/RoiMapManager.ts

@@ -0,0 +1,97 @@
+import { Matrix } from 'ml-matrix';
+
+import type { Mask } from '../Mask.js';
+
+import type { Roi } from './Roi.js';
+import type { FromMaskOptions } from './fromMask.js';
+import { fromMask } from './fromMask.js';
+import type { GetRoisOptions } from './getRois.js';
+import { getRois } from './getRois.js';
+
+export interface RoiManager {
+  getRois(options: GetRoisOptions): Roi[];
+}
+
+export interface RoiMap {
+  /**
+   * Width of the map.
+   */
+  width: number;
+  /**
+   * Height of the map.
+   */
+  height: number;
+  /**
+   * Data of the ROIs. Each ROI is associated with a negative or a positive value,
+   * depending if it derives from a zone made of zeros or ones in the original mask.
+   */
+  data: Int32Array;
+  /**
+   * Number of distinct positive values in the ROI map.
+   *
+   */
+  nbPositive: number;
+  /**
+   * Number of distinct negative values in the ROI map.
+   *
+   */
+  nbNegative: number;
+}
+export class RoiMapManager implements RoiManager {
+  private map: RoiMap;
+  public whiteRois: Roi[];
+  public blackRois: Roi[];
+
+  public constructor(map: RoiMap) {
+    this.map = map;
+    this.whiteRois = [];
+    this.blackRois = [];
+  }
+
+  /**
+   * Return the ROI map of the RoiMapManager.
+   * @returns - The ROI map.
+   */
+  public getMap(): RoiMap {
+    return this.map;
+  }
+
+  /**
+   * Return the value at the given coordinates in an ROI map.
+   * @param column - Column of the value.
+   * @param row - Row of the value.
+   * @returns The value at the given coordinates.
+   */
+  public getMapValue(column: number, row: number) {
+    return this.map.data[this.map.width * row + column];
+  }
+
+  /**
+   * Returns the ROI map as a correct width and height matrix.
+   * @returns The ROI map matrix.
+   */
+  public getMapMatrix(): number[][] {
+    return Matrix.from1DArray(
+      this.map.height,
+      this.map.width,
+      this.map.data,
+    ).to2DArray();
+  }
+
+  public getRois(options: GetRoisOptions = {}): Roi[] {
+    return getRois(this, options);
+  }
+
+  public getRoiById(roiID: number): Roi {
+    const rois = this.getRois({ kind: 'bw' });
+    const foundRoi = rois.find((roi) => roi.id === roiID);
+    if (!foundRoi) {
+      throw new Error(`invalid ID: ${roiID}`);
+    }
+    return foundRoi;
+  }
+
+  public static fromMask(mask: Mask, options: FromMaskOptions = {}) {
+    return fromMask(mask, options);
+  }
+}

package/src/roi/colorRois.ts

@@ -0,0 +1,68 @@
+import { Image } from '../Image.js';
+
+import type { RoiMapManager } from './RoiMapManager.js';
+import type { RoiKind } from './getRois.js';
+import { getColorMap } from './utils/getColorMap.js';
+
+export const RoisColorMode = {
+  /**
+   * Only two acceptable values: red or green.
+   */
+  BINARY: 'binary',
+  /**
+   * Palette of reds and blues.
+   */
+  SATURATION: 'saturation',
+  /**
+   * All possible hues (gradient of colors).
+   */
+  RAINBOW: 'rainbow',
+} as const;
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type RoisColorMode = (typeof RoisColorMode)[keyof typeof RoisColorMode];
+
+export interface ColorRoisOptions {
+  /**
+   * Define the color mode to use to color the ROIs.
+   * @default `'binary'`
+   */
+  mode?: RoisColorMode;
+  /**
+   * Specify which ROIs to color.
+   * @default `'bw'`
+   */
+  roiKind?: RoiKind;
+}
+
+/**
+ * Generate an image with all the ROIs of various colors.
+ * @param roiMapManager - The ROI map manager.
+ * @param options - Color ROIs options.
+ * @returns The colored image.
+ */
+export function colorRois(
+  roiMapManager: RoiMapManager,
+  options: ColorRoisOptions = {},
+): Image {
+  const { roiKind = 'bw', mode = 'binary' } = options;
+  const map = roiMapManager.getMap();
+
+  const image = new Image(map.width, map.height, {
+    colorModel: 'RGBA',
+  });
+
+  const colorMap = getColorMap({
+    roiKind,
+    mode,
+    nbNegative: map.nbNegative,
+    nbPositive: map.nbPositive,
+  });
+
+  const data32 = new Uint32Array(image.getRawImage().data.buffer);
+
+  for (let index = 0; index < image.size; index++) {
+    data32[index] = colorMap[map.data[index] + map.nbNegative];
+  }
+
+  return image;
+}

package/src/roi/computeRois.ts

@@ -0,0 +1,90 @@
+import { Roi } from './Roi.js';
+import type { RoiMapManager } from './RoiMapManager.js';
+
+/**
+ * Generate an array of ROIs based on an ROI map manager.
+ * @param roiMapManager - Roi map manager to use.
+ */
+export function computeRois(roiMapManager: RoiMapManager): void {
+  const map = roiMapManager.getMap();
+
+  const whites = new Array(map.nbPositive);
+  const blacks = new Array(map.nbNegative);
+  for (let i = 0; i < map.nbPositive; i++) {
+    whites[i] = {
+      minRow: map.height,
+      minColumn: map.width,
+      maxRow: -1,
+      maxColumn: -1,
+      surface: 0,
+      id: i + 1,
+    };
+  }
+
+  for (let i = 0; i < map.nbNegative; i++) {
+    blacks[i] = {
+      borderLengths: [],
+      borderIDs: [],
+      minRow: map.height,
+      minColumn: map.width,
+      maxRow: -1,
+      maxColumn: -1,
+      surface: 0,
+      id: -i - 1,
+    };
+  }
+
+  for (let row = 0; row < map.height; row++) {
+    for (let column = 0; column < map.width; column++) {
+      const currentIndex = roiMapManager.getMapValue(column, row);
+      if (currentIndex === 0) {
+        continue;
+      }
+      let currentRoi;
+      if (currentIndex < 0) {
+        currentRoi = blacks[-currentIndex - 1];
+      } else {
+        currentRoi = whites[currentIndex - 1];
+      }
+
+      currentRoi.surface++;
+
+      if (row < currentRoi.minRow) {
+        currentRoi.minRow = row;
+      }
+      if (row > currentRoi.maxRow) {
+        currentRoi.maxRow = row;
+      }
+      if (column < currentRoi.minColumn) {
+        currentRoi.minColumn = column;
+      }
+      if (column > currentRoi.maxColumn) {
+        currentRoi.maxColumn = column;
+      }
+    }
+  }
+
+  roiMapManager.whiteRois = new Array<Roi>(map.nbPositive);
+  roiMapManager.blackRois = new Array<Roi>(map.nbNegative);
+
+  for (let i = 0; i < map.nbNegative; i++) {
+    const width = blacks[i].maxColumn - blacks[i].minColumn + 1;
+    const height = blacks[i].maxRow - blacks[i].minRow + 1;
+    const origin = { row: blacks[i].minRow, column: blacks[i].minColumn };
+    const id = blacks[i].id;
+    const surface = blacks[i].surface;
+    const blackRoi = new Roi(map, id, width, height, origin, surface);
+    roiMapManager.blackRois[i] = blackRoi;
+  }
+
+  for (let i = 0; i < map.nbPositive; i++) {
+    const width = whites[i].maxColumn - whites[i].minColumn + 1;
+    const height = whites[i].maxRow - whites[i].minRow + 1;
+    const origin = { row: whites[i].minRow, column: whites[i].minColumn };
+    const id = whites[i].id;
+    const surface = whites[i].surface;
+    const whiteRoi = new Roi(map, id, width, height, origin, surface);
+
+    roiMapManager.whiteRois[i] = whiteRoi;
+  }
+}

package/src/roi/fromMask.ts

@@ -0,0 +1,182 @@
+import type { Mask } from '../Mask.js';
+import { assert } from '../utils/validators/assert.js';
+
+import { RoiMapManager } from './RoiMapManager.js';
+
+export interface FromMaskOptions {
+  /**
+   * Consider pixels connected by corners as same ROI?
+   * @default `false`
+   */
+  allowCorners?: boolean;
+}
+
+/**
+ * Extract the ROIs of an image.
+ * @param mask - Mask to extract the ROIs from.
+ * @param options - From mask options.
+ * @returns The corresponding ROI manager.
+ */
+export function fromMask(
+  mask: Mask,
+  options: FromMaskOptions = {},
+): RoiMapManager {
+  const { allowCorners = false } = options;
+
+  const MAX_TODO_ARRAY_FILTER = 65535; // 65535 should be enough for most of the cases
+
+  const MAX_POSITIVE_ID = 2 ** 31 - 1;
+  const MAX_NEGATIVE_ID = -(2 ** 31 - 1);
+
+  // based on a binary image we will create plenty of small images
+  const data = new Int32Array(mask.size); // maxValue: maxPositiveId, minValue: maxNegativeId
+
+  // split will always return an array of images
+  let positiveId = 0;
+  let negativeId = 0;
+
+  const columnToProcess = new Uint16Array(MAX_TODO_ARRAY_FILTER + 1);
+  const rowToProcess = new Uint16Array(MAX_TODO_ARRAY_FILTER + 1);
+
+  for (let column = 0; column < mask.width; column++) {
+    for (let row = 0; row < mask.height; row++) {
+      if (data[row * mask.width + column] === 0) {
+        // need to process the whole surface
+        analyseSurface(column, row);
+      }
+    }
+  }
+  // x column
+  // y row
+  function analyseSurface(column: number, row: number) {
+    let from = 0;
+    let to = 0;
+    const targetState = mask.getBit(column, row);
+    const id = targetState ? ++positiveId : --negativeId;
+    assert(
+      positiveId <= MAX_POSITIVE_ID && negativeId >= MAX_NEGATIVE_ID,
+      'too many regions of interest',
+    );
+    columnToProcess[0] = column;
+    rowToProcess[0] = row;
+    while (from <= to) {
+      const currentColumn = columnToProcess[from & MAX_TODO_ARRAY_FILTER];
+      const currentRow = rowToProcess[from & MAX_TODO_ARRAY_FILTER];
+      data[currentRow * mask.width + currentColumn] = id;
+      // need to check all around mask pixel
+      if (
+        currentColumn > 0 &&
+        data[currentRow * mask.width + currentColumn - 1] === 0 &&
+        mask.getBit(currentColumn - 1, currentRow) === targetState
+      ) {
+        // LEFT
+        to++;
+        columnToProcess[to & MAX_TODO_ARRAY_FILTER] = currentColumn - 1;
+        rowToProcess[to & MAX_TODO_ARRAY_FILTER] = currentRow;
+        data[currentRow * mask.width + currentColumn - 1] = MAX_NEGATIVE_ID;
+      }
+      if (
+        currentRow > 0 &&
+        data[(currentRow - 1) * mask.width + currentColumn] === 0 &&
+        mask.getBit(currentColumn, currentRow - 1) === targetState
+      ) {
+        // TOP
+        to++;
+        columnToProcess[to & MAX_TODO_ARRAY_FILTER] = currentColumn;
+        rowToProcess[to & MAX_TODO_ARRAY_FILTER] = currentRow - 1;
+        data[(currentRow - 1) * mask.width + currentColumn] = MAX_NEGATIVE_ID;
+      }
+      if (
+        currentColumn < mask.width - 1 &&
+        data[currentRow * mask.width + currentColumn + 1] === 0 &&
+        mask.getBit(currentColumn + 1, currentRow) === targetState
+      ) {
+        // RIGHT
+        to++;
+        columnToProcess[to & MAX_TODO_ARRAY_FILTER] = currentColumn + 1;
+        rowToProcess[to & MAX_TODO_ARRAY_FILTER] = currentRow;
+        data[currentRow * mask.width + currentColumn + 1] = MAX_NEGATIVE_ID;
+      }
+      if (
+        currentRow < mask.height - 1 &&
+        data[(currentRow + 1) * mask.width + currentColumn] === 0 &&
+        mask.getBit(currentColumn, currentRow + 1) === targetState
+      ) {
+        // BOTTOM
+        to++;
+        columnToProcess[to & MAX_TODO_ARRAY_FILTER] = currentColumn;
+        rowToProcess[to & MAX_TODO_ARRAY_FILTER] = currentRow + 1;
+        data[(currentRow + 1) * mask.width + currentColumn] = MAX_NEGATIVE_ID;
+      }
+      if (allowCorners) {
+        if (
+          currentColumn > 0 &&
+          currentRow > 0 &&
+          data[(currentRow - 1) * mask.width + currentColumn - 1] === 0 &&
+          mask.getBit(currentColumn - 1, currentRow - 1) === targetState
+        ) {
+          // TOP LEFT
+          to++;
+          columnToProcess[to & MAX_TODO_ARRAY_FILTER] = currentColumn - 1;
+          rowToProcess[to & MAX_TODO_ARRAY_FILTER] = currentRow - 1;
+          data[(currentRow - 1) * mask.width + currentColumn - 1] =
+            MAX_NEGATIVE_ID;
+        }
+        if (
+          currentColumn < mask.width - 1 &&
+          currentRow > 0 &&
+          data[(currentRow - 1) * mask.width + currentColumn + 1] === 0 &&
+          mask.getBit(currentColumn + 1, currentRow - 1) === targetState
+        ) {
+          // TOP RIGHT
+          to++;
+          columnToProcess[to & MAX_TODO_ARRAY_FILTER] = currentColumn + 1;
+          rowToProcess[to & MAX_TODO_ARRAY_FILTER] = currentRow - 1;
+          data[(currentRow - 1) * mask.width + currentColumn + 1] =
+            MAX_NEGATIVE_ID;
+        }
+        if (
+          currentColumn > 0 &&
+          currentRow < mask.height - 1 &&
+          data[(currentRow + 1) * mask.width + currentColumn - 1] === 0 &&
+          mask.getBit(currentColumn - 1, currentRow + 1) === targetState
+        ) {
+          // BOTTOM LEFT
+          to++;
+          columnToProcess[to & MAX_TODO_ARRAY_FILTER] = currentColumn - 1;
+          rowToProcess[to & MAX_TODO_ARRAY_FILTER] = currentRow + 1;
+          data[(currentRow + 1) * mask.width + currentColumn - 1] =
+            MAX_NEGATIVE_ID;
+        }
+        if (
+          currentColumn < mask.width - 1 &&
+          currentRow < mask.height - 1 &&
+          data[(currentRow + 1) * mask.width + currentColumn + 1] === 0 &&
+          mask.getBit(currentColumn + 1, currentRow + 1) === targetState
+        ) {
+          // BOTTOM RIGHT
+          to++;
+          columnToProcess[to & MAX_TODO_ARRAY_FILTER] = currentColumn + 1;
+          rowToProcess[to & MAX_TODO_ARRAY_FILTER] = currentRow + 1;
+          data[(currentRow + 1) * mask.width + currentColumn + 1] =
+            MAX_NEGATIVE_ID;
+        }
+      }
+
+      from++;
+
+      assert(
+        to - from <= MAX_TODO_ARRAY_FILTER,
+        'fromMask can not finish, the array to manage internal data is not big enough.' +
+          'You could improve mask by changing MAX_ARRAY',
+      );
+    }
+  }
+  return new RoiMapManager({
+    width: mask.width,
+    height: mask.height,
+    data,
+    nbNegative: Math.abs(negativeId),
+    nbPositive: positiveId,
+  });
+}

package/src/roi/getBorderPoints.ts

@@ -0,0 +1,20 @@
+import type { GetBorderPointsOptions } from '../maskAnalysis/index.js';
+import type { Point } from '../utils/geometry/points.js';
+
+import type { Roi } from './Roi.js';
+
+/**
+ * Return an array with the coordinates of the pixels that are on the border of the ROI.
+ * The reference is the top-left corner of the ROI.
+ * @param roi - ROI to process.
+ * @param options - Get border points options.
+ * @returns The array of border pixels.
+ */
+export function getBorderPoints(
+  roi: Roi,
+  options: GetBorderPointsOptions = {},
+): Point[] {
+  const mask = roi.getMask();
+
+  return mask.getBorderPoints(options);
+}

package/src/roi/getMask.ts

@@ -0,0 +1,41 @@
+import { Mask } from '../Mask.js';
+
+import type { Roi } from './Roi.js';
+
+export interface GetMaskOptions {
+  /**
+   * Should the ROI holes be filled in the resulting mask?
+   * @default `false`
+   */
+  solidFill?: boolean;
+}
+
+/**
+ * Generate a mask of an ROI.
+ * @param roi - The ROI to generate a mask for.
+ * @param options - Get mask options.
+ * @returns The ROI mask.
+ */
+export function getMask(roi: Roi, options: GetMaskOptions = {}): Mask {
+  const { solidFill = false } = options;
+  const mask = new Mask(roi.width, roi.height, { origin: roi.origin });
+
+  for (let row = 0; row < roi.height; row++) {
+    for (let column = 0; column < roi.width; column++) {
+      if (
+        roi.getMapValue(roi.origin.column + column, roi.origin.row + row) ===
+        roi.id
+      ) {
+        mask.setBit(column, row, 1);
+      } else {
+        mask.setBit(column, row, 0);
+      }
+    }
+  }
+
+  if (solidFill) {
+    mask.solidFill({ out: mask });
+  }
+
+  return mask;
+}

package/src/roi/getRois.ts

@@ -0,0 +1,65 @@
+import { match } from 'ts-pattern';
+
+import type { Roi } from './Roi.js';
+import type { RoiMapManager } from './RoiMapManager.js';
+import { computeRois } from './computeRois.js';
+
+export const RoiKind = {
+  BLACK: 'black',
+  WHITE: 'white',
+  BW: 'bw',
+} as const;
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type RoiKind = (typeof RoiKind)[keyof typeof RoiKind];
+
+export interface GetRoisOptions {
+  /**
+   * Minimal surface of the ROIs to keep.
+   * @default `0`
+   */
+  minSurface?: number;
+  /**
+   * Maximal surface of the ROIs to keep.
+   * @default `Number.MAX_SAFE_INTEGER`
+   */
+  maxSurface?: number;
+  /**
+   * Kind of ROIs to keep.
+   * @default `'white'`
+   */
+  kind?: RoiKind;
+}
+
+/**
+ * Return an array of ROIs matching the options.
+ * @param roiMapManager - The ROI map manager containing the ROIs.
+ * @param options - Get ROIs options.
+ * @returns The array of ROIs.
+ */
+export function getRois(
+  roiMapManager: RoiMapManager,
+  options: GetRoisOptions = {},
+): Roi[] {
+  const {
+    minSurface = 0,
+    maxSurface = Number.MAX_SAFE_INTEGER,
+    kind = 'white',
+  } = options;
+
+  if (
+    roiMapManager.blackRois.length === 0 &&
+    roiMapManager.whiteRois.length === 0
+  ) {
+    computeRois(roiMapManager);
+  }
+
+  const rois = match(kind)
+    .with('black', () => roiMapManager.blackRois)
+    .with('white', () => roiMapManager.whiteRois)
+    .with('bw', () => [...roiMapManager.whiteRois, ...roiMapManager.blackRois])
+    .exhaustive();
+
+  return rois.filter(
+    (roi) => roi.surface >= minSurface && roi.surface <= maxSurface,
+  );
+}

package/src/roi/index.ts

@@ -0,0 +1,10 @@
+export * from './colorRois.js';
+export * from './computeRois.js';
+export * from './fromMask.js';
+export * from './getBorderPoints.js';
+export * from './getMask.js';
+export * from './getRois.js';
+export * from './Roi.js';
+export * from './RoiMapManager.js';
+export * from './waterShed.js';
+export * from './roi.types.js';

package/src/roi/properties/getEllipse.ts

@@ -0,0 +1,124 @@
+import { EigenvalueDecomposition } from 'ml-matrix';
+import { xVariance, xyCovariance } from 'ml-spectra-processing';
+
+import type { Point } from '../../geometry/index.js';
+import { getAngle } from '../../maskAnalysis/utils/getAngle.js';
+import { toDegrees } from '../../utils/geometry/angles.js';
+import { assert } from '../../utils/validators/assert.js';
+import type { Roi } from '../Roi.js';
+import type { Ellipse } from '../roi.types.js';
+/**
+ * Calculates ellipse on around ROI.
+ * @param roi - Region of interest.
+ * @returns Ellipse.
+ */
+export function getEllipse(roi: Roi): Ellipse {
+  const xCenter = roi.centroid.column;
+  const yCenter = roi.centroid.row;
+
+  const xCentered = roi.relativePoints.map(
+    (point: Point) => point.column - xCenter,
+  );
+  const yCentered = roi.relativePoints.map(
+    (point: Point) => point.row - yCenter,
+  );
+
+  const centeredXVariance = xVariance(xCentered, { unbiased: false });
+  const centeredYVariance = xVariance(yCentered, { unbiased: false });
+
+  const centeredCovariance = xyCovariance(
+    {
+      x: xCentered,
+      y: yCentered,
+    },
+    { unbiased: false },
+  );
+
+  //spectral decomposition of the sample covariance matrix
+  const sampleCovarianceMatrix = [
+    [centeredXVariance, centeredCovariance],
+    [centeredCovariance, centeredYVariance],
+  ];
+  const e = new EigenvalueDecomposition(sampleCovarianceMatrix);
+  const eigenvalues = e.realEigenvalues;
+  const vectors = e.eigenvectorMatrix;
+
+  assert(eigenvalues[0] <= eigenvalues[1]);
+
+  let radiusMajor = Math.sqrt(eigenvalues[1]);
+  let radiusMinor = Math.sqrt(eigenvalues[0]);
+  const vectorMajor = vectors.getColumn(1);
+  const vectorMinor = vectors.getColumn(0);
+
+  let majorAxisPoint1 = {
+    column: xCenter + radiusMajor * vectorMajor[0],
+    row: yCenter + radiusMajor * vectorMajor[1],
+  };
+  let majorAxisPoint2 = {
+    column: xCenter - radiusMajor * vectorMajor[0],
+    row: yCenter - radiusMajor * vectorMajor[1],
+  };
+  let minorAxisPoint1 = {
+    column: xCenter + radiusMinor * vectorMinor[0],
+    row: yCenter + radiusMinor * vectorMinor[1],
+  };
+  let minorAxisPoint2 = {
+    column: xCenter - radiusMinor * vectorMinor[0],
+    row: yCenter - radiusMinor * vectorMinor[1],
+  };
+
+  let majorLength = Math.hypot(
+    majorAxisPoint1.column - majorAxisPoint2.column,
+    majorAxisPoint1.row - majorAxisPoint2.row,
+  );
+  let minorLength = Math.hypot(
+    minorAxisPoint1.column - majorAxisPoint2.column,
+    minorAxisPoint1.row - minorAxisPoint2.row,
+  );
+
+  let ellipseSurface = (((minorLength / 2) * majorLength) / 2) * Math.PI;
+  if (ellipseSurface !== roi.surface) {
+    const scaleFactor = Math.sqrt(roi.surface / ellipseSurface);
+    radiusMajor *= scaleFactor;
+    radiusMinor *= scaleFactor;
+    majorAxisPoint1 = {
+      column: xCenter + radiusMajor * vectorMajor[0],
+      row: yCenter + radiusMajor * vectorMajor[1],
+    };
+    majorAxisPoint2 = {
+      column: xCenter - radiusMajor * vectorMajor[0],
+      row: yCenter - radiusMajor * vectorMajor[1],
+    };
+    minorAxisPoint1 = {
+      column: xCenter + radiusMinor * vectorMinor[0],
+      row: yCenter + radiusMinor * vectorMinor[1],
+    };
+    minorAxisPoint2 = {
+      column: xCenter - radiusMinor * vectorMinor[0],
+      row: yCenter - radiusMinor * vectorMinor[1],
+    };
+
+    majorLength *= scaleFactor;
+
+    minorLength *= scaleFactor;
+    ellipseSurface *= scaleFactor ** 2;
+  }
+
+  return {
+    center: {
+      column: xCenter,
+      row: yCenter,
+    },
+    majorAxis: {
+      points: [majorAxisPoint1, majorAxisPoint2],
+      length: majorLength,
+      angle: toDegrees(getAngle(majorAxisPoint1, majorAxisPoint2)),
+    },
+    minorAxis: {
+      points: [minorAxisPoint1, minorAxisPoint2],
+      length: minorLength,
+      angle: toDegrees(getAngle(minorAxisPoint1, minorAxisPoint2)),
+    },
+    surface: ellipseSurface,
+  };
+}