image-js 1.0.0-alpha.2 → 1.0.0

package/src/featureMatching/utils/extractSquareImage.ts

@@ -0,0 +1,27 @@
+import type { Image } from '../../Image.js';
+import type { Point } from '../../geometry/index.js';
+
+/**
+ * Crop the source image to given dimensions around the origin.
+ * @param image - Source image.
+ * @param origin - Center point for the crop.
+ * @param patchSize - Size of the returned image.
+ * @returns The square image around the origin extracted from the source image.
+ */
+export function extractSquareImage(
+  image: Image,
+  origin: Point,
+  patchSize: number,
+): Image {
+  const cropOffset = (patchSize - 1) / 2;
+  const cropOrigin = {
+    column: origin.column - cropOffset,
+    row: origin.row - cropOffset,
+  };
+
+  return image.crop({
+    origin: cropOrigin,
+    width: patchSize,
+    height: patchSize,
+  });
+}

package/src/featureMatching/utils/getColors.ts

@@ -0,0 +1,34 @@
+import type { Image } from '../../Image.js';
+import { getClampFromTo } from '../../utils/clamp.js';
+import type { GetColorsOptions } from '../featureMatching.types.js';
+
+/**
+ * Generate an array of colors to draw the keypoints depending on their score or the matches depending on the distance.
+ * @param image - The source image.
+ * @param baseColor - The desired shade for the colors.
+ * @param options - Get score colors options.
+ * @returns Array of colors.
+ */
+export function getColors(
+  image: Image,
+  baseColor: number[],
+  options: GetColorsOptions = {},
+): number[][] {
+  const { nbShades = 6, minValueFactor = 0.2 } = options;
+  const maxValue = Math.max(...baseColor);
+  const minValue = maxValue * minValueFactor;
+
+  const interval = Math.floor((maxValue - minValue) / (nbShades - 1));
+  const clamp = getClampFromTo(0, image.maxValue);
+
+  const colors: number[][] = [];
+  for (let i = 0; i < nbShades; i++) {
+    const color = [];
+    for (const channel of baseColor) {
+      color.push(clamp(channel - i * interval));
+    }
+    colors.push(color);
+  }
+
+  return colors;
+}

package/src/featureMatching/utils/getGaussianPoints.ts

@@ -0,0 +1,64 @@
+import { createRandomArray } from 'ml-spectra-processing';
+
+import type { Point } from '../../geometry/index.js';
+import { getClampFromTo } from '../../utils/clamp.js';
+import type { GetGaussianPointsOptions } from '../../utils/utils.types.js';
+
+/**
+ * Get the coordinates of random points inside of the given dimensions, spread with a
+ * gaussian distribution around the center of the dimensions.
+ * The reference point with coordinates (0,0) is the center of the patch.
+ * @param width - Width in which the points should be.
+ * @param height - Height in which the points should be.
+ * @param options - Get gaussian points options.
+ * @returns An array of random points with a gaussian distribution.
+ */
+export function getGaussianPoints(
+  width: number,
+  height: number,
+  options: GetGaussianPointsOptions = {},
+): Point[] {
+  const { nbPoints = 1024, xSeed = 0, ySeed = 1, sigma } = options;
+
+  const xCoordinates = getGaussianValues(width, xSeed, nbPoints, sigma);
+  const yCoordinates = getGaussianValues(height, ySeed, nbPoints, sigma);
+
+  const points: Point[] = [];
+  for (let i = 0; i < nbPoints; i++) {
+    points.push({ column: xCoordinates[i], row: yCoordinates[i] });
+  }
+
+  return points;
+}
+
+/**
+ * Generate an array of values
+ * that follow a gaussian distribution with a mean value of zero.
+ * @param size - Specifies the width of the gaussian distribution.
+ * @param seed - Seed for the random generator.
+ * @param nbValues - Number of values wanted.
+ * @param sigma - The standard deviation. The default value is the optimal SD for BRIEF.
+ * @returns Array of values with gaussian distribution.
+ */
+export function getGaussianValues(
+  size: number,
+  seed: number,
+  nbValues: number,
+  sigma = size / 5,
+): Float64Array {
+  const width = (size - 1) / 2;
+
+  const array = createRandomArray({
+    distribution: 'normal',
+    seed,
+    length: nbValues,
+    standardDeviation: sigma,
+    mean: 0,
+  });
+  const clamp = getClampFromTo(-width, width);
+
+  return array.map((value) => {
+    const rounded = Math.round(value);
+    return clamp(rounded);
+  });
+}

package/src/featureMatching/utils/getKeypointColor.ts

@@ -0,0 +1,29 @@
+import type { FastKeypoint } from '../keypoints/getFastKeypoints.js';
+
+/**
+ * Get the shade the keypoint with given index should have (the color is an indicator
+ * of the score). The keypoints should be sorted with highest score first.
+ * @param keypoints - The sorted keypoints.
+ * @param index - Index of the keypoint.
+ * @param colors - The colors from which to pick (sorted from brightest to darkest).
+ * @returns The color the keypoint should have.
+ */
+export function getKeypointColor(
+  keypoints: FastKeypoint[],
+  index: number,
+  colors: number[][],
+): number[] {
+  const maxScore = keypoints[0].score;
+  const minScore = (keypoints.at(-1) as FastKeypoint).score;
+  if (minScore === maxScore) {
+    return colors[0];
+  }
+  const score = keypoints[index].score;
+  const colorIndex =
+    colors.length -
+    1 -
+    Math.floor(
+      ((colors.length - 1) * (score - minScore)) / (maxScore - minScore),
+    );
+  return colors[colorIndex];
+}

package/src/featureMatching/utils/getMatchColor.ts

@@ -0,0 +1,27 @@
+import type { Match } from '../matching/bruteForceMatch.js';
+
+/**
+ * Get the shade of the match with given index (the color is an indicator
+ * of the distance). The matches should be sorted with smallest distance first.
+ * @param matches - The sorted keypoints.
+ * @param index - Index of the keypoint.
+ * @param colors - The colors from which to pick (sorted from brightest to darkest).
+ * @returns The color the keypoint should have.
+ */
+export function getMatchColor(
+  matches: Match[],
+  index: number,
+  colors: number[][],
+): number[] {
+  const maxDistance = (matches.at(-1) as Match).distance;
+  const minDistance = matches[0].distance;
+  if (minDistance === maxDistance) {
+    return colors[0];
+  }
+  const distance = matches[index].distance;
+  const colorIndex = Math.floor(
+    ((colors.length - 1) * (distance - minDistance)) /
+      (maxDistance - minDistance),
+  );
+  return colors[colorIndex];
+}

package/src/featureMatching/utils/sortByDistance.ts

@@ -0,0 +1,12 @@
+import type { Match } from '../matching/bruteForceMatch.js';
+
+/**
+ * Source array of matches by ascending distance.
+ * @param matches - Array of matches to sort.
+ * @returns Sorted copy of the array of matches.
+ */
+export function sortByDistance(matches: Match[]): Match[] {
+  return matches.slice().sort((match1, match2) => {
+    return match1.distance - match2.distance;
+  });
+}

package/src/featureMatching/utils/sortBySourceDest.ts

@@ -0,0 +1,27 @@
+import type { Match } from '../matching/bruteForceMatch.js';
+
+/**
+ * Sort array of matches by source index and then destination index.
+ * @param matches - Array of matches to sort.
+ * @returns Sorted copy of the array of matches.
+ */
+export function sortBySourceDest(matches: Match[]): Match[] {
+  return matches.slice().sort((match1, match2) => {
+    if (match1.sourceIndex < match2.sourceIndex) return -1;
+    if (match1.sourceIndex > match2.sourceIndex) return 1;
+    return match1.destinationIndex - match2.destinationIndex;
+  });
+}
+
+/**
+ * Sort array of matches by destination index and then source index.
+ * @param matches - Array of matches to sort.
+ * @returns Sorted copy of the array of matches.
+ */
+export function sortByDestSource(matches: Match[]): Match[] {
+  return matches.slice().sort((match1, match2) => {
+    if (match1.destinationIndex < match2.destinationIndex) return -1;
+    if (match1.destinationIndex > match2.destinationIndex) return 1;
+    return match1.sourceIndex - match2.sourceIndex;
+  });
+}

package/src/featureMatching/visualize/Montage.ts

@@ -0,0 +1,165 @@
+import { Image } from '../../Image.js';
+import type { Point } from '../../geometry/index.js';
+import type { FastKeypoint } from '../keypoints/getFastKeypoints.js';
+import type { Match } from '../matching/bruteForceMatch.js';
+
+import type { DrawKeypointsOptions } from './drawKeypoints.js';
+import { drawKeypoints } from './drawKeypoints.js';
+import type { DrawMatchesOptions } from './drawMatches.js';
+import { drawMatches } from './drawMatches.js';
+import { scaleKeypoints } from './scaleKeypoints.js';
+
+export const MontageDisposition = {
+  HORIZONTAL: 'horizontal',
+  VERTICAL: 'vertical',
+} as const;
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type MontageDisposition =
+  (typeof MontageDisposition)[keyof typeof MontageDisposition];
+
+export interface MontageOptions {
+  /**
+   * Factor by which to scale the images.
+   *  @default `1`
+   */
+  scale?: number;
+  /**
+   * How should the images be aligned: vertically or horizontally.
+   * @default `'horizontal'`
+   */
+  disposition?: MontageDisposition;
+}
+
+export class Montage {
+  /**
+   * Scaled width of the first image.
+   */
+  public readonly sourceWidth: number;
+  /**
+   * Scaled height of the first image.
+   */
+  public readonly sourceHeight: number;
+  /**
+   * Scaled width of the second image.
+   */
+  public readonly destinationWidth: number;
+  /**
+   * Scaled height of the second image.
+   */
+  public readonly destinationHeight: number;
+  /**
+   * Origin of the destination / second image relative to top-left corner of the Montage.
+   */
+  public readonly destinationOrigin: Point;
+  /**
+   * Width of the Montage.
+   */
+  public readonly width: number;
+  /**
+   * Height of the Montage.
+   */
+  public readonly height: number;
+  /**
+   * Factor by which to scale the images are scaled in the montage.
+   */
+  public readonly scale: number;
+
+  public readonly disposition: MontageDisposition;
+
+  /**
+   * Image of the Montage.
+   */
+  public image: Image;
+
+  /**
+   * Create a Montage of two images. The two images are placed side by side for comparison.
+   * @param source - First image.
+   * @param destination - Second image.
+   * @param options  - Montage options.
+   */
+  public constructor(
+    source: Image,
+    destination: Image,
+    options: MontageOptions = {},
+  ) {
+    const { scale = 1, disposition = 'horizontal' } = options;
+
+    if (!Number.isInteger(scale)) {
+      throw new TypeError('scale must be an integer');
+    }
+
+    this.scale = scale;
+    this.disposition = disposition;
+
+    this.sourceWidth = scale * source.width;
+    this.destinationWidth = scale * destination.width;
+    this.sourceHeight = scale * source.height;
+    this.destinationHeight = scale * destination.height;
+
+    if (disposition === 'horizontal') {
+      this.destinationOrigin = { row: 0, column: this.sourceWidth };
+      this.width = this.sourceWidth + this.destinationWidth;
+      this.height = Math.max(this.sourceHeight, this.destinationHeight);
+    } else if (disposition === 'vertical') {
+      this.destinationOrigin = { row: this.sourceHeight, column: 0 };
+      this.width = Math.max(this.sourceWidth, this.destinationWidth);
+      this.height = this.sourceHeight + this.destinationHeight;
+    } else {
+      throw new RangeError(`invalid disposition type: ${disposition}`);
+    }
+
+    if (source.colorModel !== 'RGB') {
+      source = source.convertColor('RGB');
+    }
+    if (destination.colorModel !== 'RGB') {
+      destination = destination.convertColor('RGB');
+    }
+
+    const image = new Image(this.width, this.height);
+
+    source
+      .resize({ xFactor: scale, yFactor: scale })
+      .copyTo(image, { out: image });
+    destination.resize({ xFactor: scale, yFactor: scale }).copyTo(image, {
+      out: image,
+      origin: this.destinationOrigin,
+    });
+
+    this.image = image;
+  }
+
+  /**
+   * Draw keypoints on the Montage.
+   * @param keypoints - Keypoints to draw.
+   * @param options - Draw keypoints options.
+   */
+  public drawKeypoints(
+    keypoints: FastKeypoint[],
+    options: DrawKeypointsOptions = {},
+  ): void {
+    const scaledKeypoints = scaleKeypoints(keypoints, this.scale);
+    this.image = drawKeypoints(this.image, scaledKeypoints, options);
+  }
+
+  /**
+   * Draw the matches between source and destination keypoints.
+   * @param matches - Matches to draw.
+   * @param sourceKeypoints - Source keypoints.
+   * @param destinationKeypoints  - Destination keypoints.
+   * @param options - Draw matches options.
+   */
+  public drawMatches(
+    matches: Match[],
+    sourceKeypoints: FastKeypoint[],
+    destinationKeypoints: FastKeypoint[],
+    options: DrawMatchesOptions = {},
+  ): void {
+    this.image = drawMatches(
+      this,
+      matches,
+      sourceKeypoints,
+      destinationKeypoints,
+      options,
+    );
+  }
+}

package/src/featureMatching/visualize/drawKeypoints.ts

@@ -0,0 +1,146 @@
+import type { Image } from '../../Image.js';
+import type { Point } from '../../geometry/index.js';
+import { sum } from '../../utils/geometry/points.js';
+import { getOutputImage } from '../../utils/getOutputImage.js';
+import type { GetColorsOptions } from '../featureMatching.types.js';
+import type { FastKeypoint } from '../keypoints/getFastKeypoints.js';
+import type { OrientedFastKeypoint } from '../keypoints/getOrientedFastKeypoints.js';
+import { getColors } from '../utils/getColors.js';
+import { getKeypointColor } from '../utils/getKeypointColor.js';
+
+export interface DrawKeypointsOptions {
+  /**
+   * Origin of the keypoints in the image.
+   * @default `{row: 0, column: 0}`
+   */
+  origin?: Point;
+  /**
+   * Markers size in pixels.
+   * @default `10`
+   */
+  markerSize?: number;
+  /**
+   * Keypoint's color - An array of numerical values, one for each channel of the image. If less values are defined than there are channels in the image, the remaining channels will be set to 0.
+   * @default `[255,0,0]`
+   */
+  strokeColor?: number[];
+  /**
+   * Whether to fill the markers.
+   * @default `false`
+   */
+  fill?: boolean;
+  /**
+   * Whether the score of the keypoints should be reflected in their color.
+   * @default `false`
+   */
+  showScore?: boolean;
+  /**
+   * Maximal number of matches with smallest distance to draw.
+   * @default `keypoints.length`
+   */
+
+  maxNbKeypoints?: number;
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Image;
+  /**
+   * Options for the coloring of the keypoints depending on their score (useful if showScore = true).
+   */
+  showScoreOptions?: GetColorsOptions;
+}
+
+export interface DrawOrientedKeypointsOptions extends DrawKeypointsOptions {
+  /**
+   * Show the orientation of the keypoints.
+   * @default `false`
+   */
+  showOrientation?: boolean;
+}
+
+export function drawKeypoints(
+  image: Image,
+  keypoints: FastKeypoint[],
+  options?: DrawKeypointsOptions,
+): Image;
+export function drawKeypoints(
+  image: Image,
+  keypoints: OrientedFastKeypoint[],
+  options?: DrawOrientedKeypointsOptions,
+): Image;
+/**
+ * Draw keypoints on an image.
+ * @param image - The source image of the keypoints.
+ * @param keypoints - The FAST keypoints.
+ * @param options - Draw keypoints options.
+ * @returns The image with the keypoints indicated by empty circles.
+ */
+export function drawKeypoints(
+  image: Image,
+  keypoints: FastKeypoint[] | OrientedFastKeypoint[],
+  options: DrawKeypointsOptions | DrawOrientedKeypointsOptions = {},
+): Image {
+  const {
+    markerSize = 10,
+    fill = false,
+    showScore = false,
+    origin = { row: 0, column: 0 },
+    showScoreOptions,
+  } = options;
+  let { maxNbKeypoints = keypoints.length } = options;
+  const { strokeColor = [255, 0, 0] } = options;
+
+  if (maxNbKeypoints > keypoints.length) {
+    maxNbKeypoints = keypoints.length;
+  }
+
+  let newImage = getOutputImage(image, options, { clone: true });
+
+  if (image.colorModel !== 'RGB') {
+    newImage = newImage.convertColor('RGB');
+  }
+
+  const colors = getColors(image, strokeColor, showScoreOptions);
+
+  const radius = Math.ceil(markerSize / 2);
+  for (let i = 0; i < maxNbKeypoints; i++) {
+    const keypoint = keypoints[i];
+    let keypointColor = strokeColor;
+    if (showScore) {
+      keypointColor = getKeypointColor(keypoints, i, colors);
+    }
+    const fillColor = fill ? keypointColor : undefined;
+
+    const absoluteOrigin = sum(keypoint.origin, origin);
+
+    newImage.drawCircle(absoluteOrigin, radius, {
+      fillColor,
+      strokeColor: keypointColor,
+      out: newImage,
+    });
+    if (
+      isOrientedFastKeypoint(keypoint) &&
+      (options as DrawOrientedKeypointsOptions).showOrientation
+    ) {
+      const angle = keypoint.angle;
+      const from = absoluteOrigin;
+      const radAngle = (angle * Math.PI) / 180;
+      const to: Point = {
+        column: from.column + Math.round(radius * Math.cos(radAngle)),
+        row: from.row - Math.round(radius * Math.sin(radAngle)),
+      };
+      newImage.drawLine(from, to, {
+        strokeColor: keypointColor,
+        out: newImage,
+      });
+    }
+  }
+
+  return newImage;
+}
+
+function isOrientedFastKeypoint(
+  kpt: FastKeypoint,
+): kpt is OrientedFastKeypoint {
+  return 'angle' in kpt && typeof kpt.angle === 'number';
+}

package/src/featureMatching/visualize/drawMatches.ts

@@ -0,0 +1,107 @@
+import type { Image } from '../../Image.js';
+import type { GetColorsOptions } from '../featureMatching.types.js';
+import type { FastKeypoint } from '../keypoints/getFastKeypoints.js';
+import type { Match } from '../matching/bruteForceMatch.js';
+import { getColors } from '../utils/getColors.js';
+import { getMatchColor } from '../utils/getMatchColor.js';
+import { sortByDistance } from '../utils/sortByDistance.js';
+
+import type { Montage } from './Montage.js';
+import { scaleKeypoints } from './scaleKeypoints.js';
+
+export interface DrawMatchesOptions {
+  /**
+   * Circles diameter in pixels.
+   * @default `10`
+   */
+  circleDiameter?: number;
+  /**
+   * Annotations color - An array of numerical values, one for each channel of the image. If less values are defined than there are channels in the image, the remaining channels will be set to 0.
+   * @default `[255,0,0]`
+   */
+  strokeColor?: number[];
+  /**
+   * Whether the matches should be colored depending on the distance.
+   * @default `false`
+   */
+  showDistance?: boolean;
+  /**
+   * Options for the coloring of the matches depending on their distance (useful if showDistance = true).
+   */
+  showDistanceOptions?: GetColorsOptions;
+  /**
+   * Maximal number of keypoints with best score to draw.
+   * @default `matches.length`
+   */
+  maxNbMatches?: number;
+}
+
+/**
+ * Draw the the matches between two images on their montage.
+ * @param montage - The montage of two images to match.
+ * @param matches - The matches between source and destination.
+ * @param sourceKeypoints - Source keypoints.
+ * @param destinationKeypoints - Destination keypoints.
+ * @param options - Draw matches options.
+ * @returns The comparison image.
+ */
+export function drawMatches(
+  montage: Montage,
+  matches: Match[],
+  sourceKeypoints: FastKeypoint[],
+  destinationKeypoints: FastKeypoint[],
+
+  options: DrawMatchesOptions = {},
+): Image {
+  const {
+    circleDiameter = 10,
+    strokeColor = [255, 0, 0],
+    showDistance = false,
+    showDistanceOptions,
+  } = options;
+  let { maxNbMatches = matches.length } = options;
+
+  if (maxNbMatches > matches.length) {
+    maxNbMatches = matches.length;
+  }
+
+  const scaledSource = scaleKeypoints(sourceKeypoints, montage.scale);
+  const scaledDestination = scaleKeypoints(destinationKeypoints, montage.scale);
+
+  const result = montage.image;
+
+  const colors = getColors(result, strokeColor, showDistanceOptions);
+
+  const radius = Math.ceil(circleDiameter / 2);
+  const matchesSortedByDistance = sortByDistance(matches);
+  for (let i = 0; i < maxNbMatches; i++) {
+    let matchColor = strokeColor;
+    if (showDistance) {
+      matchColor = getMatchColor(matchesSortedByDistance, i, colors);
+    }
+    const sourcePoint = scaledSource[matches[i].sourceIndex].origin;
+    result.drawCircle(sourcePoint, radius, {
+      strokeColor: matchColor,
+      out: result,
+    });
+
+    const relativeDestinationPoint =
+      scaledDestination[matches[i].destinationIndex].origin;
+
+    const destinationPoint = {
+      column:
+        relativeDestinationPoint.column + montage.destinationOrigin.column,
+      row: relativeDestinationPoint.row + montage.destinationOrigin.row,
+    };
+    result.drawCircle(destinationPoint, radius, {
+      strokeColor: matchColor,
+      out: result,
+    });
+    result.drawLine(sourcePoint, destinationPoint, {
+      out: result,
+      strokeColor: matchColor,
+    });
+  }
+
+  return result;
+}