image-js 1.0.0-alpha.2 → 1.0.0

package/src/align/affineTransfrom/utils/getSourceWithoutMargins.ts

@@ -0,0 +1,30 @@
+import type { Image } from '../../../Image.js';
+import type { Point } from '../../../geometry/index.js';
+
+/**
+ * Crop source image for contrast enhancement.
+ * @param source - Source image enlarged compared to the destination image.
+ * @param destination - Destination image.
+ * @param destinationOrigin - Estimated origin of the destination image in the source image (relative to top-left corner).
+ * @returns The source image without margins.
+ */
+export function getSourceWithoutMargins(
+  source: Image,
+  destination: Image,
+  destinationOrigin: Point,
+): Image {
+  const width = Math.min(
+    destination.width,
+    source.width - destinationOrigin.column,
+  );
+  const height = Math.min(
+    destination.height,
+    source.height - destinationOrigin.row,
+  );
+
+  return source.crop({
+    origin: { row: destinationOrigin.row, column: destinationOrigin.column },
+    width,
+    height,
+  });
+}

package/src/align/alignMinDifference.ts

@@ -0,0 +1,114 @@
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface AlignMinDifferenceOptions {
+  /**
+   * Initial step size by which the images will be translated.
+   * @default `Math.max(Math.round(Math.min(source.width, source.height, Math.max(xSpan, ySpan)) / 10,),1,)`
+   */
+  startStep?: number;
+  mask?: Mask;
+}
+
+/**
+ * Aligns two images by finding the translation that minimizes the mean difference of all channels.
+ * between them. The source image should fit entirely in the destination image.
+ * @param source - Image to align.
+ * @param destination - Image to align to.
+ * @param options - Align images min difference options.
+ * @returns Translation that minimizes the mean difference between the images.
+ * Gives the origin of the source image relatively to the top-left corner of the destination image.
+ */
+export function alignMinDifference(
+  source: Image,
+  destination: Image,
+  options: AlignMinDifferenceOptions = {},
+) {
+  checkProcessable(source, {
+    bitDepth: [8, 16],
+  });
+
+  const xSpan = destination.width - source.width;
+  const ySpan = destination.height - source.height;
+  const {
+    startStep = Math.max(
+      Math.round(
+        Math.min(source.width, source.height, Math.max(xSpan, ySpan)) / 4,
+      ),
+      1,
+    ),
+    mask,
+  } = options;
+
+  if (xSpan < 0 || ySpan < 0) {
+    throw new Error('Source image must fit entirely in destination image');
+  }
+
+  let bestDifference = Number.POSITIVE_INFINITY;
+  let bestShiftX = 0;
+  let bestShiftY = 0;
+
+  let step = startStep;
+  let startX = 0;
+  let startY = 0;
+  let endX = xSpan;
+  let endY = ySpan;
+
+  if (mask && mask.size !== source.size) {
+    throw new Error('Mask size must be equal to source size');
+  }
+
+  const nbPixelsToCheck = mask ? mask.getNbNonZeroPixels() : source.size;
+
+  while (step >= 1) {
+    step = Math.round(step);
+
+    for (let shiftX = startX; shiftX <= endX; shiftX += step) {
+      for (let shiftY = startY; shiftY <= endY; shiftY += step) {
+        let currentDifference = 0;
+        next: for (let column = 0; column < source.width; column++) {
+          for (let row = 0; row < source.height; row++) {
+            if (mask && !mask.getBit(column, row)) {
+              continue;
+            }
+            for (let channel = 0; channel < source.channels; channel++) {
+              const sourceValue = source.getValue(column, row, channel);
+              const destinationValue = destination.getValue(
+                column + shiftX,
+                row + shiftY,
+                channel,
+              );
+              const difference = sourceValue - destinationValue;
+              if (difference < 0) {
+                // Math.abs is super slow, this simple trick is 5x faster
+                currentDifference -= difference;
+              } else {
+                currentDifference += difference;
+              }
+              if (currentDifference > bestDifference) {
+                break next;
+              }
+            }
+          }
+        }
+        if (currentDifference < bestDifference) {
+          bestDifference = currentDifference;
+          bestShiftX = shiftX;
+          bestShiftY = shiftY;
+        }
+      }
+    }
+    step /= 2;
+    startX = Math.round(Math.max(0, bestShiftX - step));
+    startY = Math.round(Math.max(0, bestShiftY - step));
+    endX = Math.round(Math.min(xSpan, bestShiftX + step));
+    endY = Math.round(Math.min(ySpan, bestShiftY + step));
+  }
+
+  return {
+    row: bestShiftY,
+    column: bestShiftX,
+    similarity: 1 - bestDifference / (nbPixelsToCheck * source.maxValue),
+  };
+}

package/src/align/index.ts

@@ -0,0 +1,2 @@
+export * from './affineTransfrom/getAffineTransform.js';
+export * from './alignMinDifference.js';

package/src/compare/add.ts

@@ -0,0 +1,34 @@
+import { Image } from '../Image.js';
+import { getClamp } from '../utils/clamp.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+import { validateForComparison } from '../utils/validators/validators.js';
+/**
+ *
+ * Calculate a new image that is the sum between the current image and the otherImage.
+ * @param image - Image to which to add.
+ * @param otherImage - Image to add.
+ * @returns The summed image.
+ */
+export function add(image: Image, otherImage: Image): Image {
+  if (image instanceof Image) {
+    checkProcessable(image, {
+      bitDepth: [8, 16],
+      components: [1, 3],
+      alpha: false,
+    });
+  }
+
+  validateForComparison(image, otherImage);
+
+  const newImage = image.clone();
+  const clamp = getClamp(image);
+  for (let index = 0; index < image.size; index++) {
+    for (let channel = 0; channel < image.channels; channel++) {
+      const value =
+        image.getValueByIndex(index, channel) +
+        otherImage.getValueByIndex(index, channel);
+      newImage.setValueByIndex(index, channel, clamp(value));
+    }
+  }
+  return newImage;
+}

package/src/compare/computePsnr.ts

@@ -0,0 +1,17 @@
+import type { Image } from '../Image.js';
+
+import { computeRmse } from './computeRmse.js';
+
+/**
+ * Compute the Peak signal-to-noise ratio (PSNR) between two images.
+ * The larger the PSNR, the more similar the images.
+ * @see {@link https://en.wikipedia.org/wiki/Peak_signal-to-noise_ratio}
+ * @param image - First image.
+ * @param otherImage - Second image.
+ * @returns PSNR of the two images in decibels.
+ */
+export function computePsnr(image: Image, otherImage: Image): number {
+  const rmsePixel = computeRmse(image, otherImage);
+
+  return 20 * Math.log10(image.maxValue / (rmsePixel + Number.MIN_VALUE));
+}

package/src/compare/computeRmse.ts

@@ -0,0 +1,33 @@
+import type { Image } from '../Image.js';
+
+/**
+ * Compute the Root Mean Square Error (RMSE) between two images. It is just the square root of the MSE.
+ * @see {@link https://en.wikipedia.org/wiki/Root-mean-square_deviation}
+ * @param image - First image.
+ * @param otherImage - Second image.
+ * @returns RMSE of the two images.
+ */
+export function computeRmse(image: Image, otherImage: Image): number {
+  const globalMse = computeMse(image, otherImage);
+
+  return Math.sqrt(globalMse);
+}
+
+/**
+ * Compute the Mean Square Error (MSE) between two images.
+ * The input images can have any number of channels.
+ * @param image - First image.
+ * @param otherImage - Second image.
+ * @returns MSE of the two images.
+ */
+export function computeMse(image: Image, otherImage: Image): number {
+  const difference = image.subtract(otherImage, { absolute: true });
+  let sum = 0;
+  for (let i = 0; i < image.size; i++) {
+    for (let channel = 0; channel < image.channels; channel++) {
+      const value = difference.getValueByIndex(i, channel);
+      sum += value ** 2;
+    }
+  }
+  return sum / (image.size * image.channels);
+}

package/src/compare/divide.ts

@@ -0,0 +1,50 @@
+import type { Image } from '../Image.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+import { validateChannels } from '../utils/validators/validators.js';
+
+export interface DivideOptions {
+  /**
+   * Channels where value will be divided.
+   * @default all channels
+   */
+  channels?: number[];
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Image;
+}
+
+/**
+ *
+ * Divides image pixels by a certain value.
+ * @param image - image to which division will be applied.
+ * @param value - Value by which each pixel will be divided.
+ * @param options - Divide options
+ * @returns image.
+ */
+export function divide(
+  image: Image,
+  value: number,
+  options: DivideOptions = {},
+) {
+  const {
+    channels = new Array(image.channels).fill(0).map((value, index) => index),
+  } = options;
+  validateChannels(channels, image);
+  if (value === 0) {
+    throw new TypeError(`Cannot divide by 0`);
+  }
+  const newImage = getOutputImage(image, options, { clone: true });
+  if (channels.length === 0) {
+    return newImage;
+  }
+  for (const channel of channels) {
+    for (let row = 0; row < newImage.height; row++) {
+      for (let column = 0; column < newImage.width; column++) {
+        const newIntensity = newImage.getValue(column, row, channel) / value;
+        newImage.setClampedValue(column, row, channel, newIntensity);
+      }
+    }
+  }
+  return newImage;
+}

package/src/compare/index.ts

@@ -0,0 +1,6 @@
+export * from './computePsnr.js';
+export * from './computeRmse.js';
+export * from './subtract.js';
+export * from './add.js';
+export * from './divide.js';
+export * from './multiply.js';

package/src/compare/multiply.ts

@@ -0,0 +1,48 @@
+import type { Image } from '../Image.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+import { validateChannels } from '../utils/validators/validators.js';
+
+export interface MultiplyOptions {
+  /**
+   * Channels where value will be multiplied.
+   * @default all channels
+   */
+  channels?: number[];
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Image;
+}
+
+/**
+ *
+ * Multiplies points by a certain value.
+ * @param image - image to which multiplication will be applied.
+ * @param value - Value by which each pixel will be multiplied.
+ * @param options - Multiply options
+ * @returns image.
+ */
+export function multiply(
+  image: Image,
+  value: number,
+  options: MultiplyOptions = {},
+) {
+  const {
+    channels = new Array(image.channels).fill(0).map((value, index) => index),
+  } = options;
+  validateChannels(channels, image);
+
+  const newImage = getOutputImage(image, options, { clone: true });
+  if (channels.length === 0) {
+    return newImage;
+  }
+  for (const channel of channels) {
+    for (let row = 0; row < newImage.height; row++) {
+      for (let column = 0; column < newImage.width; column++) {
+        const newIntensity = newImage.getValue(column, row, channel) * value;
+        newImage.setClampedValue(column, row, channel, newIntensity);
+      }
+    }
+  }
+  return newImage;
+}

package/src/compare/subtract.ts

@@ -0,0 +1,86 @@
+import { Image } from '../Image.js';
+import { Mask } from '../Mask.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+import { validateForComparison } from '../utils/validators/validators.js';
+
+export interface SubtractImageOptions {
+  /**
+   * Return the absolute difference for each pixel.
+   * @default `false`
+   */
+  absolute?: boolean;
+}
+
+export function subtract(
+  image: Image,
+  otherImage: Image,
+  options?: SubtractImageOptions,
+): Image;
+export function subtract(
+  image: Mask,
+  otherImage: Mask,
+  options?: SubtractImageOptions,
+): Mask;
+export function subtract(
+  image: Image | Mask,
+  otherImage: Image | Mask,
+  options: SubtractImageOptions,
+): Image | Mask;
+/**
+ * Calculate a new image that is the subtraction between the current image and the otherImage.
+ * @param image - Image from which to subtract.
+ * @param otherImage - Image to subtract.
+ * @param options - Subtract options.
+ * @returns The subtracted image.
+ */
+export function subtract(
+  image: Image | Mask,
+  otherImage: Image | Mask,
+  options: SubtractImageOptions = {},
+): Image | Mask {
+  const { absolute = false } = options;
+
+  if (image instanceof Image) {
+    checkProcessable(image, {
+      bitDepth: [1, 8, 16],
+      components: [1, 3],
+      alpha: false,
+    });
+  }
+
+  validateForComparison(image, otherImage);
+
+  const newImage = image.clone();
+  if (newImage instanceof Image) {
+    for (let index = 0; index < image.size; index++) {
+      for (let channel = 0; channel < image.channels; channel++) {
+        const value =
+          image.getValueByIndex(index, channel) -
+          otherImage.getValueByIndex(index, channel);
+        if (absolute) {
+          if (value < 0) {
+            newImage.setValueByIndex(index, channel, -value);
+          } else {
+            newImage.setValueByIndex(index, channel, value);
+          }
+        } else if (value < 0) {
+          newImage.setValueByIndex(index, channel, 0);
+        } else {
+          newImage.setValueByIndex(index, channel, value);
+        }
+      }
+    }
+  } else if (image instanceof Mask && otherImage instanceof Mask) {
+    for (let index = 0; index < image.size; index++) {
+      const value =
+        image.getBitByIndex(index) - otherImage.getBitByIndex(index);
+      if (absolute) {
+        newImage.setBitByIndex(index, value ? 1 : 0);
+      } else {
+        newImage.setBitByIndex(index, value > 0 ? 1 : 0);
+      }
+    }
+  }
+
+  return newImage;
+}

package/src/compute/getExtrema.ts

@@ -0,0 +1,103 @@
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import type { Point } from '../geometry/index.js';
+import { assertUnreachable } from '../utils/validators/assert.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface ExtremaOptions {
+  /**
+   * Chooses what kind of extremum to compute.
+   * @default `'maximum'`
+   */
+  kind?: 'minimum' | 'maximum';
+  /**
+   * Uses mask to check if a point belongs to a ROI or not
+   * @default `undefined`
+   */
+  mask?: Mask;
+  /**
+   * Chooses what kind of coverage algorithm to use to compute the extremum.
+   * @default `'star'`
+   */
+  algorithm?: 'cross' | 'square' | 'star';
+  /**
+   * Maximum number of points that can be equal to the extremum
+   * @default `2`
+   */
+  maxEquals?: number;
+}
+/**
+ * Checks the surrounding values of a point. If they are all bigger or smaller than the pixel in question then this point is considered an extremum.
+ * @param image - Image to find extrema from.
+ * @param options - ExtremaOptions
+ * @returns Array of Points.
+ */
+export function getExtrema(image: Image, options: ExtremaOptions): Point[] {
+  const { kind = 'maximum', mask, algorithm = 'star', maxEquals = 2 } = options;
+  checkProcessable(image, {
+    bitDepth: [8, 16],
+  });
+  const searchingMinimum = kind === 'minimum';
+
+  const maskExpectedValue = searchingMinimum ? 0 : 1;
+
+  const dx = [1, 0, -1, 0, 1, 1, -1, -1, 2, 0, -2, 0, 2, 2, -2, -2];
+  const dy = [0, 1, 0, -1, 1, -1, 1, -1, 0, 2, 0, -2, 2, -2, 2, -2];
+  switch (algorithm) {
+    case 'cross':
+      dx.length = 4;
+      dy.length = 4;
+      break;
+    case 'square':
+      dx.length = 8;
+      dy.length = 8;
+      break;
+    case 'star':
+      break;
+    default:
+      assertUnreachable(algorithm);
+  }
+  const shift = dx.length <= 8 ? 1 : 2; // deal with borders
+  const points: Point[] = [];
+  for (let channel = 0; channel < image.channels; channel++) {
+    for (let currentY = shift; currentY < image.height - shift; currentY++) {
+      for (let currentX = shift; currentX < image.width - shift; currentX++) {
+        if (mask && mask.getBit(currentX, currentY) !== maskExpectedValue) {
+          continue;
+        }
+        let counter = 0;
+        let nbEquals = 0;
+        const currentValue = image.getValue(currentX, currentY, channel);
+        for (let dir = 0; dir < dx.length; dir++) {
+          const currentAroundValue = image.getValue(
+            currentX + dx[dir],
+            currentY + dy[dir],
+            channel,
+          );
+          if (searchingMinimum) {
+            // we search for minima
+            if (currentAroundValue > currentValue) {
+              counter++;
+            }
+          } else if (currentAroundValue < currentValue) {
+            counter++;
+          }
+          if (currentAroundValue === currentValue) {
+            nbEquals++;
+          }
+        }
+        if (counter + nbEquals === dx.length && nbEquals <= maxEquals) {
+          points.push({ column: currentX, row: currentY });
+        }
+      }
+    }
+  }
+
+  // TODO How to make a more performant and general way
+  // we don't deal correctly here with groups of points that should be grouped if at the
+  // beginning one of them is closer to another
+  // Seems that we would ened to calculate a matrix and then split this matrix in 'independant matrices'
+  // Or to assign a cluster to each point and regroup them if 2 clusters are close to each other
+  // later approach seems much better
+  return points;
+}

package/src/compute/histogram.ts

@@ -1,34 +1,56 @@
-import { Image } from '../Image';
-import { validateChannel } from '../utils/validators';
+import type { Image } from '../Image.js';
+import { validateChannel } from '../utils/validators/validators.js';
 
-export interface IHistogramOptions {
+export interface HistogramOptions {
   /**
    * The channel for which to compute the histogram.
    * If it is unspecified, the image must have one channel or the method will
    * throw an error.
+   * @default `0`
    */
   channel?: number;
+  /**
+   * The number of slots that histogram can have.
+   * @default 2 ** image.bitDepth
+   */
+  slots?: number;
 }
 
 /**
  * Returns a histogram of pixel intensities.
- * @param image
+ * @param image - The original image.
+ * @param options - Histogram options.
+ * @returns - The histogram.
  */
 export function histogram(
   image: Image,
-  options: IHistogramOptions = {}
-): number[] {
+  options: HistogramOptions = {},
+): Uint32Array {
   let { channel } = options;
+  const { slots = 2 ** image.bitDepth } = options;
+  if (!(slots !== 0 && (slots & (slots - 1)) === 0)) {
+    throw new RangeError(
+      'slots must be a power of 2, for example: 64, 256, 1024',
+    );
+  }
   if (typeof channel !== 'number') {
     if (image.channels !== 1) {
-      throw new Error('channel option is mandatory for multi-channel images');
+      throw new TypeError(
+        'channel option is mandatory for multi-channel images',
+      );
     }
     channel = 0;
   }
   validateChannel(channel, image);
-  const hist = new Array(image.maxValue + 1).fill(0);
-  for (let i = channel; i < image.data.length; i += image.channels) {
-    hist[image.data[i]]++;
+
+  const hist = new Uint32Array(slots);
+
+  let bitShift = 0;
+  const bitSlots = Math.log2(slots);
+  bitShift = image.bitDepth - bitSlots;
+  for (let i = 0; i < image.size; i++) {
+    hist[image.getValueByIndex(i, channel) >> bitShift]++;
   }
+
   return hist;
 }

package/src/compute/index.ts

@@ -1 +1,5 @@
-export * from './histogram';
+export * from './mean.js';
+export * from './histogram.js';
+export * from './median.js';
+export * from './getExtrema.js';
+export * from './variance.js';

package/src/compute/mean.ts

@@ -0,0 +1,48 @@
+import type { Image } from '../Image.js';
+import type { Point } from '../geometry/index.js';
+
+export interface MeanOptions {
+  /**
+   * Points to calculate mean from.
+   */
+  points: Point[];
+}
+
+/**
+ * Compute the mean of an image. The mean can be either computed on each channel
+ * individually or on the whole image.
+ * @param image - Image to process.
+ * @param options - Mean options.
+ * @returns The mean pixel.
+ */
+export function mean(image: Image, options?: MeanOptions): number[] {
+  const pixelSum = new Array<number>(image.channels).fill(0);
+  const nbValues = options ? options.points.length : image.size;
+  if (nbValues === 0) throw new RangeError('Array of coordinates is empty.');
+  if (options) {
+    for (const point of options.points) {
+      for (let channel = 0; channel < image.channels; channel++) {
+        if (
+          point.column < 0 ||
+          point.column >= image.width ||
+          point.row < 0 ||
+          point.row >= image.height
+        ) {
+          throw new RangeError(
+            `Invalid coordinate: {column: ${point.column}, row: ${point.row}}.`,
+          );
+        }
+        pixelSum[channel] += image.getValueByPoint(point, channel);
+      }
+    }
+  } else {
+    for (let row = 0; row < image.height; row++) {
+      for (let column = 0; column < image.width; column++) {
+        for (let channel = 0; channel < image.channels; channel++) {
+          pixelSum[channel] += image.getValue(column, row, channel);
+        }
+      }
+    }
+  }
+  return pixelSum.map((channelSum) => channelSum / nbValues);
+}