image-js 1.0.0-alpha.3 → 1.1.0

package/src/Stack.ts

@@ -0,0 +1,204 @@
+import type { BitDepth } from 'fast-png';
+
+import type { Image } from './Image.js';
+import type { HistogramOptions } from './compute/index.js';
+import {
+  histogram,
+  maxImage,
+  meanImage,
+  medianImage,
+  minImage,
+  sum,
+} from './stack/index.js';
+import {
+  checkImagesValid,
+  verifySameDimensions,
+} from './stack/utils/checkImagesValid.js';
+import type { ImageColorModel } from './utils/constants/colorModels.js';
+
+export class Stack {
+  /**
+   * The array of images.
+   */
+  private readonly images: Image[];
+  /**
+   * The stack size.
+   */
+  public readonly size: number;
+  /**
+   * Do the images have an alpha channel?
+   */
+  public readonly alpha: boolean;
+  /**
+   * The color model of the images.
+   */
+  public readonly colorModel: ImageColorModel;
+  /**
+   * The bit depth of the images.
+   */
+  public readonly bitDepth: BitDepth;
+  /**
+   * Whether all the images of the stack have the same dimensions.
+   */
+  public readonly sameDimensions: boolean;
+  /**
+   * The number of channels of the images.
+   */
+  public readonly channels: number;
+
+  /**
+   * Create a new stack from an array of images.
+   * The images must have the same bit depth and color model.
+   * @param images - Array of images from which to create the stack.
+   */
+  public constructor(images: Image[]) {
+    checkImagesValid(images);
+    this.images = images;
+    this.size = images.length;
+    this.alpha = images[0].alpha;
+    this.colorModel = images[0].colorModel;
+    this.channels = images[0].channels;
+    this.bitDepth = images[0].bitDepth;
+    this.sameDimensions = verifySameDimensions(images);
+  }
+
+  *[Symbol.iterator](): IterableIterator<Image> {
+    for (const image of this.images) {
+      yield image;
+    }
+  }
+
+  /**
+   * Clone a stack. The images are a copy of the original images.
+   * @returns A new stack with the same images.
+   */
+  public clone(): Stack {
+    return new Stack(this.images.map((image) => image.clone()));
+  }
+
+  /**
+   * Get the images of the stack. Mainly for debugging purposes.
+   * @returns The images.
+   */
+  public getImages(): Image[] {
+    return this.images;
+  }
+
+  /**
+   * Get the image at the given index.
+   * @param index - The index of the image.
+   * @returns The image.
+   */
+  public getImage(index: number): Image {
+    return this.images[index];
+  }
+
+  /**
+   * Get a value from an image of the stack.
+   * @param stackIndex - Index of the image in the stack.
+   * @param row - Row index of the pixel.
+   * @param column - Column index of the pixel.
+   * @param channel - The channel to retrieve.
+   * @returns The value at the given position.
+   */
+  public getValue(
+    stackIndex: number,
+    row: number,
+    column: number,
+    channel: number,
+  ): number {
+    return this.images[stackIndex].getValue(row, column, channel);
+  }
+
+  /**
+   * Get a value from an image of the stack. Specify the pixel position using its index.
+   * @param stackIndex - Index of the image in the stack.
+   * @param index - The index of the pixel.
+   * @param channel - The channel to retrieve.
+   * @returns The value at the given position.
+   */
+  public getValueByIndex(
+    stackIndex: number,
+    index: number,
+    channel: number,
+  ): number {
+    return this.images[stackIndex].getValueByIndex(index, channel);
+  }
+
+  /**
+   * Return the image containing the minimum values of all the images in the stack for
+   * each pixel. All the images must have the same dimensions.
+   * @returns The minimum image.
+   */
+  public minImage(): Image {
+    return minImage(this);
+  }
+
+  /**
+   * Return the image containing the maximum values of all the images in the stack for
+   * each pixel. All the images must have the same dimensions.
+   * @returns The maximum image.
+   */
+  public maxImage(): Image {
+    return maxImage(this);
+  }
+
+  /**
+   * Return the image containing the median values of all the images in the stack for
+   * each pixel. All the images must have the same dimensions.
+   * @returns The median image.
+   */
+  public medianImage(): Image {
+    return medianImage(this);
+  }
+
+  /**
+   * Return the image containing the average values of all the images in the stack for
+   * each pixel. All the images must have the same dimensions.
+   * @returns The mean image.
+   */
+  public meanImage(): Image {
+    return meanImage(this);
+  }
+
+  /**
+   * Return a 16 bits depth image containing the sum values of all the images in the stack for
+   * each pixel.
+   * @returns The sum image.
+   */
+  public sum(): Image {
+    return sum(this);
+  }
+
+  /**
+   * Get the sum of all the histograms of the stack's images. If no channel is specified in the options, the images must be GREY.
+   * @param options - Histogram options.
+   * @returns The histogram of the stack.
+   */
+  public histogram(options: HistogramOptions = {}): Uint32Array {
+    return histogram(this, options);
+  }
+  /**
+   * Align all the images of the stack on the image at the given index.
+   * @param refIndex - The index of the reference image.
+   */
+  // public alignImages(refIndex: number): Stack {}
+
+  /**
+   * Map a function on all the images of the stack.
+   * @param callback - Function to apply on each image.
+   * @returns New stack with the modified images.
+   */
+  public map(callback: (image: Image) => Image): Stack {
+    return new Stack(this.images.map(callback));
+  }
+
+  /**
+   * Filter the images in the stack.
+   * @param callback - Function to decide which images to keep.
+   * @returns New filtered stack.
+   */
+  public filter(callback: (image: Image) => boolean): Stack {
+    return new Stack(this.images.filter(callback));
+  }
+}

package/src/align/affineTransfrom/affineFitFunction.ts

@@ -0,0 +1,27 @@
+import { getAffineTransform } from 'ml-affine-transform';
+
+import type { Point } from '../../geometry/index.js';
+
+import { getMatrixFromPoints } from './getMatrixFromPoints.js';
+
+/**
+ * The fit function for an affine transformation.
+ * Get the best transformation parameters for the given source and destination.
+ * @param source - Source points.
+ * @param destination - Destination points.
+ * @returns The model parameters in the format [angle, xTranslation, yTranslation]
+ */
+export function affineFitFunction(
+  source: Point[],
+  destination: Point[],
+): number[] {
+  const sourceMatrix = getMatrixFromPoints(source);
+  const destinationMatrix = getMatrixFromPoints(destination);
+  const result = getAffineTransform(sourceMatrix, destinationMatrix);
+  return [
+    result.rotation,
+    result.translation.x,
+    result.translation.y,
+    result.scale,
+  ];
+}

package/src/align/affineTransfrom/applyAffineTransform.ts

@@ -0,0 +1,27 @@
+import type { ModelFunction } from 'ml-ransac';
+
+import type { Point } from '../../geometry/index.js';
+
+/**
+ * Apply a given transform to a set of points.
+ * @param points - Points to process.
+ * @param model - The transformation function.
+ * @returns The transformed points.
+ */
+export function applyAffineTransfom(
+  points: Point[],
+  model: ModelFunction<Point>,
+): Point[] {
+  const result: Point[] = [];
+
+  for (const point of points) {
+    const transformed = model(point);
+    const roundedPoint = {
+      row: Math.round(transformed.row),
+      column: Math.round(transformed.column),
+    };
+    result.push(roundedPoint);
+  }
+
+  return result;
+}

package/src/align/affineTransfrom/createAffineTransformModel.ts

@@ -0,0 +1,31 @@
+import type { ModelFunction } from 'ml-ransac';
+
+import type { Point } from '../../geometry/index.js';
+
+/**
+ * Generate a function that applies the given transformation parameters to a point.
+ * The transform is an array of number in the format: [angle, x, y, scale].
+ * @param transform - Transformation to apply.
+ * @returns Function to transform a point.
+ */
+export function createAffineTransformModel(
+  transform: number[],
+): ModelFunction<Point> {
+  if (transform.length !== 4) {
+    throw new Error('Transform had wrong number of parameters');
+  }
+  return (point: Point) => {
+    const angle = (transform[0] * Math.PI) / 180;
+    const xTranslation = transform[1];
+    const yTranslation = transform[2];
+    const scale = transform[3];
+    const column =
+      scale * (Math.cos(angle) * point.column - Math.sin(angle) * point.row) +
+      xTranslation;
+    const row =
+      scale * (Math.sin(angle) * point.column + Math.cos(angle) * point.row) +
+      yTranslation;
+
+    return { column, row };
+  };
+}

package/src/align/affineTransfrom/drawResult.ts

@@ -0,0 +1,56 @@
+import { Image } from '../../Image.js';
+import { Mask } from '../../Mask.js';
+import type { Point } from '../../geometry/index.js';
+import { ImageColorModel } from '../../utils/constants/colorModels.js';
+
+/**
+ * Draw source, destination and transformed points on an image.
+ * @param source - Source points.
+ * @param destination - Destination points.
+ * @param result - Transformed points.
+ * @param imageSide - Dimension of the image. Should be odd integer.
+ * @returns The image with the points.
+ */
+export function drawResult(
+  source: Point[],
+  destination: Point[],
+  result: Point[],
+  imageSide = 21,
+): Image {
+  const center = (imageSide - 1) / 2;
+  const image = new Image(imageSide, imageSide, {
+    colorModel: ImageColorModel.RGB,
+  });
+
+  // draw coordinates axes
+  image.drawLine(
+    { row: center, column: 0 },
+    { row: center, column: imageSide },
+    { out: image, strokeColor: [255, 255, 255] },
+  );
+  image.drawLine(
+    { row: 0, column: center },
+    { row: imageSide, column: center },
+    { out: image, strokeColor: [255, 255, 255] },
+  );
+
+  // draw points: source (green), destination (blue), result (red)
+  drawBlendedPoints(source, [null, 255, null]);
+  drawBlendedPoints(destination, [null, null, 255]);
+  drawBlendedPoints(result, [255, null, null]);
+
+  return image;
+
+  function drawBlendedPoints(points: Point[], color: Array<number | null>) {
+    const mask = new Mask(imageSide, imageSide);
+    const withPoints = mask.drawPoints(points, {
+      color: [1],
+      origin: { row: center, column: center },
+    });
+    image.paintMask(withPoints, {
+      out: image,
+      color,
+      blend: false,
+    });
+  }
+}

package/src/align/affineTransfrom/getAffineTransform.ts

@@ -0,0 +1,310 @@
+import { getAffineTransform as matrixGetAffineTransform } from 'ml-affine-transform';
+import { ransac } from 'ml-ransac';
+
+import type { Image } from '../../Image.js';
+import { getBrief } from '../../featureMatching/descriptors/getBrief.js';
+import type { Match } from '../../featureMatching/index.js';
+import {
+  Montage,
+  MontageDisposition,
+  bruteForceOneMatch,
+  getCrosscheckMatches,
+} from '../../featureMatching/index.js';
+import { filterEuclideanDistance } from '../../featureMatching/matching/filterEuclideanDistance.js';
+import type { Point } from '../../geometry/index.js';
+import { writeSync } from '../../save/index.js';
+import { ImageColorModel } from '../../utils/constants/colorModels.js';
+import { getMinMax } from '../../utils/getMinMax.js';
+
+import { affineFitFunction } from './affineFitFunction.js';
+import { createAffineTransformModel } from './createAffineTransformModel.js';
+import { getEuclideanDistance } from './getEuclideanDistance.js';
+import { getMatrixFromPoints } from './getMatrixFromPoints.js';
+import { getSourceWithoutMargins } from './utils/getSourceWithoutMargins.js';
+
+export interface GetAffineTransformOptions {
+  /**
+   * @default `31`
+   */
+  centroidPatchDiameter?: number;
+  /**
+   * @default `10`
+   */
+  bestKeypointRadius?: number;
+  /**
+   * Should only the crossckeck matches be considered.
+   * @default `true`
+   */
+  crosscheck?: boolean;
+  /**
+   * Should the contrast of the images be enhanced before feature matching.
+   * @default `true`
+   */
+  enhanceContrast?: boolean;
+  /**
+   * Origin of the destination image relative to the top-left corner of the source image.
+   * Roughly indicates the position of the destination image in the source image. Is used
+   * to filter matches by distance as well as to define a subarea of the source image to
+   * use for contrast enhancement.
+   * @default `{ column: 0, row: 0 }`
+   */
+  destinationOrigin?: Point;
+  /**
+   * Max number of iterations of the ransac algorithm.
+   */
+  maxRansacNbIterations?: number;
+  /**
+   * Save images with matches for debugging.
+   * @default `false`
+   */
+  debug?: boolean;
+  /**
+   * Path of the debug image.
+   * @default `${import.meta.dirname}/montage.png`
+   */
+  debugImagePath?: string;
+}
+
+export interface AffineTransform {
+  /**
+   * Translation of source points along x and y axes.
+   */
+  translation: Point;
+  /**
+   * Clockwise angle in degrees.
+   */
+  rotation: number;
+  /**
+   * Scaling factor from source to destination.
+   */
+  scale: number;
+}
+
+export interface GetAffineTransformResult {
+  /**
+   * Affine transformation from source to destination.
+   */
+  transform: AffineTransform;
+  stats: {
+    /**
+     * Number of matches of feature matching between source and destination.
+     * The bigger this number is, the better.
+     */
+    nbMatches: number;
+    /**
+     * Number of inliers resulting from the ransac algorithm.
+     */
+    nbInliers: number;
+    /**
+     * Number of iterations of the RANSAC algorithm.
+     */
+    nbRansacIterations: number;
+    /**
+     * Number of source keypoints used for matching.
+     */
+    nbSourceKeypoints: number;
+    /**
+     * Number of destination keypoints used for matching.
+     */
+    nbDestinationKeypoints: number;
+  };
+}
+
+/**
+ * Get the affine transformation from the source to the destination image.
+ * @param source - Source image. Should be the image to align on the reference image.
+ * It can have an additional margin, specified in the options.
+ * @param destination - Destination image. Should be the reference image.
+ * @param options - Get destination translation options.
+ * @returns The affine transformation from source to destination image.
+ */
+export function getAffineTransform(
+  source: Image,
+  destination: Image,
+  options: GetAffineTransformOptions = {},
+): GetAffineTransformResult {
+  const {
+    centroidPatchDiameter = 31,
+    bestKeypointRadius = 5,
+    enhanceContrast = true,
+    crosscheck = true,
+    destinationOrigin = { column: 0, row: 0 },
+    maxRansacNbIterations,
+    debug = false,
+    debugImagePath = `${import.meta.dirname}/montage.png`,
+  } = options;
+
+  if (source.colorModel !== ImageColorModel.GREY) {
+    source = source.grey();
+  }
+  if (destination.colorModel !== ImageColorModel.GREY) {
+    destination = destination.grey();
+  }
+
+  // enhance images contrast
+  if (enhanceContrast) {
+    const sourceWithoutMargin = getSourceWithoutMargins(
+      source,
+      destination,
+      destinationOrigin,
+    );
+
+    const sourceExtremums = getMinMax(sourceWithoutMargin);
+    source.level({
+      inputMin: sourceExtremums.min[0],
+      inputMax: sourceExtremums.max[0],
+      out: source,
+    });
+
+    const destinationExtremums = getMinMax(destination);
+    destination.level({
+      inputMin: destinationExtremums.min[0],
+      inputMax: destinationExtremums.max[0],
+      out: destination,
+    });
+  }
+
+  // compute briefs
+  const sourceBrief = getBrief(source, {
+    centroidPatchDiameter,
+    bestKptRadius: bestKeypointRadius,
+  });
+  const destinationBrief = getBrief(destination, {
+    centroidPatchDiameter,
+    bestKptRadius: bestKeypointRadius,
+  });
+
+  const nbSourceKeypoints = sourceBrief.keypoints.length;
+  const nbDestinationKeypoints = destinationBrief.keypoints.length;
+
+  // match reference and destination keypoints
+  let matches: Match[] = [];
+  if (crosscheck) {
+    matches = getCrosscheckMatches(
+      sourceBrief.descriptors,
+      destinationBrief.descriptors,
+    );
+  } else {
+    matches = bruteForceOneMatch(
+      sourceBrief.descriptors,
+      destinationBrief.descriptors,
+    );
+
+    matches = filterEuclideanDistance(
+      matches,
+      sourceBrief.keypoints,
+      destinationBrief.keypoints,
+      { origin: destinationOrigin },
+    );
+  }
+
+  if (matches.length < 2) {
+    throw new Error(
+      'Insufficient number of matches found to compute affine transform (less than 2).',
+    );
+  }
+
+  // extract source and destination points
+  let sourcePoints: Point[] = [];
+  let destinationPoints: Point[] = [];
+  for (const match of matches) {
+    sourcePoints.push(sourceBrief.keypoints[match.sourceIndex].origin);
+    destinationPoints.push(
+      destinationBrief.keypoints[match.destinationIndex].origin,
+    );
+  }
+
+  // find inliers with ransac
+  let nbInliers = sourcePoints.length;
+  let nbRansacIterations = 0;
+  let inliers: number[] = [0, 1];
+  if (sourcePoints.length > 2) {
+    const ransacResult = ransac(sourcePoints, destinationPoints, {
+      distanceFunction: getEuclideanDistance,
+      modelFunction: createAffineTransformModel,
+      fitFunction: affineFitFunction,
+      maxNbIterations: maxRansacNbIterations,
+    });
+    nbRansacIterations = ransacResult.nbIterations;
+
+    inliers = ransacResult.inliers;
+    nbInliers = inliers.length;
+
+    const newSrcPoints = [];
+    const newDstPoints = [];
+    for (const inlier of inliers) {
+      newSrcPoints.push(sourcePoints[inlier]);
+      newDstPoints.push(destinationPoints[inlier]);
+    }
+    sourcePoints = newSrcPoints;
+    destinationPoints = newDstPoints;
+  }
+
+  // create debug image
+  if (debug) {
+    const montage = new Montage(source, destination, {
+      disposition: MontageDisposition.VERTICAL,
+    });
+
+    montage.drawMatches(
+      matches,
+      sourceBrief.keypoints,
+      destinationBrief.keypoints,
+      { showDistance: true },
+    );
+
+    const inlierMatches: Match[] = [];
+
+    for (const inlier of inliers) {
+      inlierMatches.push(matches[inlier]);
+    }
+
+    montage.drawMatches(
+      inlierMatches,
+      sourceBrief.keypoints,
+      destinationBrief.keypoints,
+      { strokeColor: [0, 0, 255] },
+    );
+
+    const drawKeypointsBaseOptions = {
+      fill: true,
+      color: [0, 255, 0],
+      showScore: true,
+      markerSize: 3,
+    };
+
+    montage.drawKeypoints(sourceBrief.keypoints, drawKeypointsBaseOptions);
+    montage.drawKeypoints(destinationBrief.keypoints, {
+      origin: montage.destinationOrigin,
+      ...drawKeypointsBaseOptions,
+    });
+
+    writeSync(debugImagePath, montage.image);
+  }
+
+  // compute affine transform from destination to reference
+  const sourceMatrix = getMatrixFromPoints(sourcePoints);
+  const destinationMatrix = getMatrixFromPoints(destinationPoints);
+  const affineTransform = matrixGetAffineTransform(
+    sourceMatrix,
+    destinationMatrix,
+  );
+
+  return {
+    transform: {
+      rotation: affineTransform.rotation,
+      scale: affineTransform.scale,
+      translation: {
+        column: Math.round(affineTransform.translation.x),
+        row: Math.round(affineTransform.translation.y),
+      },
+    },
+    stats: {
+      nbMatches: matches.length,
+      nbInliers,
+      nbRansacIterations,
+      nbSourceKeypoints,
+      nbDestinationKeypoints,
+    },
+  };
+}

package/src/align/affineTransfrom/getEuclideanDistance.ts

@@ -0,0 +1,11 @@
+import type { Point } from '../../geometry/index.js';
+
+/**
+ * Compute the distance between point 1 and point 2.
+ * @param point1 - First point.
+ * @param point2 - Second  point.
+ * @returns Euclidean distance.
+ */
+export function getEuclideanDistance(point1: Point, point2: Point): number {
+  return Math.hypot(point1.row - point2.row, point1.column - point2.column);
+}

package/src/align/affineTransfrom/getMatrixFromPoints.ts

@@ -0,0 +1,20 @@
+import { Matrix } from 'ml-matrix';
+
+import type { Point } from '../../geometry/index.js';
+
+/**
+ * Convert row/column points to a matrix.
+ * Last row is padded with **ones** (ignore third dimension).
+ * @param points - Points to process.
+ * @returns The matrix.
+ */
+export function getMatrixFromPoints(points: Point[]): Matrix {
+  const matrix = new Matrix(3, points.length);
+  for (let i = 0; i < points.length; i++) {
+    matrix.set(0, i, points[i].column);
+    matrix.set(1, i, points[i].row);
+    matrix.set(2, i, 1);
+  }
+
+  return matrix;
+}

package/src/align/affineTransfrom/getPointsFromMatrix.ts

@@ -0,0 +1,17 @@
+import type { Matrix } from 'ml-matrix';
+
+import type { Point } from '../../geometry/index.js';
+
+/**
+ * Convert matrix to points.
+ * @param matrix - Matrix to process.
+ * @returns Array of points.
+ */
+export function getPointsFromMatrix(matrix: Matrix): Point[] {
+  const result: Point[] = [];
+  for (let i = 0; i < matrix.columns; i++) {
+    result.push({ row: matrix.get(1, i), column: matrix.get(0, i) });
+  }
+
+  return result;
+}