image-js 1.0.0-alpha.2 → 1.0.0

package/src/featureMatching/visualize/overlapImages.ts

@@ -0,0 +1,67 @@
+import { Image, ImageCoordinates } from '../../Image.js';
+import type { Point } from '../../geometry/index.js';
+import { merge } from '../../operations/index.js';
+import { ImageColorModel } from '../../utils/constants/colorModels.js';
+
+export interface OverlapImageOptions {
+  /**
+   * Origin of the second image relatively to top-left corner of first image.
+   * @default `{row: 0, column: 0}`
+   */
+  origin?: Point;
+
+  /**
+   * Desired rotation of image 2 in degrees around its top-left corner.
+   * @default `0`
+   */
+  angle?: number;
+
+  /**
+   * Factor by which to scale the second image.
+   *  @default `1`
+   */
+  scale?: number;
+}
+
+/**
+ * Overlap two images and specify. The first image can be translated,
+ * rotated and scaled to match the second one.
+ * The first image is drawn in red and the second one in green.
+ * @param image1 - First image.
+ * @param image2 - Second image.
+ * @param options - Overlap image options.
+ * @returns The overlapping images.
+ */
+export function overlapImages(
+  image1: Image,
+  image2: Image,
+  options: OverlapImageOptions = {},
+): Image {
+  const { origin = { row: 0, column: 0 }, angle = 0, scale = 1 } = options;
+
+  if (scale === 0) {
+    throw new Error('Scale cannot be 0');
+  }
+
+  if (image1.colorModel !== ImageColorModel.GREY) {
+    image1 = image1.grey();
+  }
+  if (image2.colorModel !== ImageColorModel.GREY) {
+    image2 = image2.grey();
+  }
+  const inverted1 = image1.invert();
+  const inverted2 = image2.invert();
+
+  const rotated = inverted1.transformRotate(angle, {
+    center: ImageCoordinates.TOP_LEFT,
+  });
+  const scaled = rotated.resize({ xFactor: scale, yFactor: scale });
+
+  const empty = Image.createFrom(inverted2);
+
+  const alignedGrey1 = scaled.copyTo(empty, { origin });
+
+  const result = merge([alignedGrey1, inverted2, empty]);
+
+  return result;
+}

package/src/featureMatching/visualize/scaleKeypoints.ts

@@ -0,0 +1,24 @@
+import type { FastKeypoint } from '../keypoints/getFastKeypoints.js';
+
+/**
+ * Scales the coordinates of the keypoints.
+ * @param keypoints - Keypoints to scale.
+ * @param scale - Scalar by which to multiply the coordinates.
+ * @returns Scaled keypoints (copy of the original array).
+ */
+export function scaleKeypoints(
+  keypoints: FastKeypoint[],
+  scale: number,
+): FastKeypoint[] {
+  if (scale === 1) return keypoints.slice();
+
+  return keypoints.map((kpt) => {
+    return {
+      origin: {
+        row: kpt.origin.row * scale,
+        column: kpt.origin.column * scale,
+      },
+      score: kpt.score,
+    };
+  });
+}

package/src/filters/and.ts

@@ -0,0 +1,33 @@
+import type { Mask } from '../Mask.js';
+import { maskToOutputMask } from '../utils/getOutputImage.js';
+
+export interface AndOptions {
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Mask;
+}
+
+/**
+ * Perform an AND operation on two masks.
+ * @param mask - First mask.
+ * @param otherMask - Second mask.
+ * @param options - And options.
+ * @returns AND of the two masks.
+ */
+export function and(mask: Mask, otherMask: Mask, options?: AndOptions): Mask {
+  const newMask = maskToOutputMask(mask, options);
+
+  if (mask.width !== otherMask.width || mask.height !== otherMask.height) {
+    throw new RangeError('both masks must have the same size');
+  }
+
+  for (let i = 0; i < newMask.size; i++) {
+    if (mask.getBitByIndex(i) && otherMask.getBitByIndex(i)) {
+      newMask.setBitByIndex(i, 1);
+    } else {
+      newMask.setBitByIndex(i, 0);
+    }
+  }
+  return newMask;
+}

package/src/filters/blur.ts

@@ -1,23 +1,58 @@
-import { Image } from '../Image';
-import { BorderType } from '../types';
+import type { Image } from '../Image.js';
+import type { BorderType } from '../utils/interpolateBorder.js';
 
-import { separableConvolution } from './convolution';
+import { separableConvolution } from './convolution.js';
 
-export interface IBlurOptions {
+export interface BlurOptions {
+  /**
+   * Width of the blurring matrix, must be an odd integer.
+   */
   width: number;
+  /**
+   * Height of the blurring matrix, must be an odd integer.
+   */
   height: number;
+  /**
+   * Explicit how to handle the borders.
+   * @default `'reflect101'`
+   */
   borderType?: BorderType;
+  /**
+   * Value of the border if BorderType is 'constant'.
+   * @default `0`
+   */
+  borderValue?: number;
+  /**
+   * Image to which to output.
+   */
   out?: Image;
 }
 
-export function blur(image: Image, options: IBlurOptions): Image {
+/**
+ * Blur an image. The pixel in the center becomes an average of the surrounding ones.
+ * @param image - Image to blur.
+ * @param options - Blur options.
+ * @returns The blurred image.
+ */
+export function blur(image: Image, options: BlurOptions): Image {
   const { width, height } = options;
+
+  if (width < 1 || width % 2 === 0) {
+    throw new RangeError(
+      `Invalid property "width". Must be an odd number greater than 0. Received ${width}.`,
+    );
+  }
+  if (height < 1 || height % 2 === 0) {
+    throw new RangeError(
+      `Invalid property "height". Must be an odd number greater than 0. Received ${height}.`,
+    );
+  }
+
   const kernelX = new Array(width).fill(1);
   const kernelY = new Array(height).fill(1);
 
   return separableConvolution(image, kernelX, kernelY, {
     normalize: true,
-    borderType: options.borderType,
-    out: options.out
+    ...options,
   });
 }

package/src/filters/convolution.ts

@@ -1,161 +1,187 @@
 import {
+  BorderType as ConvolutionBorderType,
   DirectConvolution,
-  BorderType as ConvolutionBorderType
 } from 'ml-convolution';
-import { Matrix } from 'ml-matrix';
 
-import { Image } from '../Image';
-import { clamp } from '../utils/clamp';
-import { BorderType } from '../types';
-import { interpolateBorder } from '../utils/interpolateBorder';
-import { round } from '../utils/round';
-import { getOutputImage } from '../utils/getOutputImage';
+import { Image } from '../Image.js';
+import { extendBorders } from '../operations/extendBorders.js';
+import { getClamp } from '../utils/clamp.js';
+import { getIndex } from '../utils/getIndex.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+import type { BorderType } from '../utils/interpolateBorder.js';
+import { getBorderInterpolation } from '../utils/interpolateBorder.js';
+import { round } from '../utils/round.js';
+import type {
+  BorderInterpolationFunction,
+  ClampFunction,
+} from '../utils/utils.types.js';
 
-interface ISeparableConvolutionOptions {
+export interface ConvolutionOptions {
+  /**
+   * Specify how the borders should be handled.
+   * @default `'reflect101'`
+   */
   borderType?: BorderType;
+  /**
+   * Value of the border if BorderType is 'constant'.
+   * @default `0`
+   */
+  borderValue?: number;
+  /**
+   * Whether the kernel should be normalized.
+   * @default `false`
+   */
   normalize?: boolean;
+  /**
+   * Image to which to output.
+   */
   out?: Image;
 }
 
+/**
+ * Apply a direct convolution on an image using the specified kernel. The convolution corresponds of a weighted average of the surrounding pixels, the weights being defined in the kernel.
+ * @param image - The image to process.
+ * @param kernel - Kernel to use for the convolution. Should be a 2D matrix with odd number of rows and columns.
+ * @param options - Convolution options.
+ * @returns The convoluted image.
+ */
 export function directConvolution(
   image: Image,
   kernel: number[][],
-  options: ISeparableConvolutionOptions = {}
+  options: ConvolutionOptions = {},
 ): Image {
-  const { borderType } = options;
+  const { borderType = 'reflect101', borderValue = 0 } = options;
+
+  const convolutedData = rawDirectConvolution(image, kernel, {
+    borderType,
+    borderValue,
+  });
 
   const newImage = getOutputImage(image, options);
+  const clamp = getClamp(newImage);
+
+  for (let i = 0; i < image.size; i++) {
+    for (let channel = 0; channel < image.channels; channel++) {
+      const dataIndex = i * image.channels + channel;
+      const newValue = round(clamp(convolutedData[dataIndex]));
+      newImage.setValueByIndex(i, channel, newValue);
+    }
+  }
+
+  return newImage;
+}
+
+/**
+ * Compute direct convolution of an image and return an array with the raw values.
+ * @param image - Image to process.
+ * @param kernel - 2D kernel used for the convolution.
+ * @param options - Convolution options.
+ * @returns Array with the raw convoluted values.
+ */
+export function rawDirectConvolution(
+  image: Image,
+  kernel: number[][],
+  options: ConvolutionOptions = {},
+): Float64Array {
+  const { borderType = 'reflect101', borderValue = 0 } = options;
+  const interpolateBorder = getBorderInterpolation(borderType, borderValue);
+
+  const result = new Float64Array(image.size * image.channels);
 
-  for (let c = 0; c < image.channels; c++) {
-    for (let x = 0; x < image.width; x++) {
-      for (let y = 0; y < image.height; y++) {
-        const idx = (y * image.width + x) * image.channels + c;
-        newImage.data[idx] = computeConvolutionPixel(
-          x,
-          y,
-          c,
+  for (let channel = 0; channel < image.channels; channel++) {
+    for (let row = 0; row < image.height; row++) {
+      for (let column = 0; column < image.width; column++) {
+        const index = getIndex(column, row, image, channel);
+        result[index] = computeConvolutionValue(
+          column,
+          row,
+          channel,
           image,
           kernel,
-          borderType
+          interpolateBorder,
+          { returnRawValue: true },
         );
       }
     }
   }
 
-  return newImage;
+  return result;
 }
 
+/**
+ * Compute the separable convolution of an image.
+ * @param image - Image to convolute.
+ * @param kernelX - Kernel along x axis.
+ * @param kernelY - Kernel along y axis.
+ * @param options - Convolution options.
+ * @returns The convoluted image.
+ */
 export function separableConvolution(
   image: Image,
   kernelX: number[],
   kernelY: number[],
-  options: ISeparableConvolutionOptions = {}
+  options: ConvolutionOptions = {},
 ): Image {
-  const { normalize, borderType } = options;
+  const { normalize, borderType = 'reflect101', borderValue = 0 } = options;
   if (normalize) {
     [kernelX, kernelY] = normalizeSeparatedKernel(kernelX, kernelY);
   }
-  const kernelOffsetX = (kernelX.length - 1) / 2;
-  const kernelOffsetY = (kernelY.length - 1) / 2;
-  const hFactor = image.channels * image.width;
+
+  const doubleKernelOffsetX = kernelX.length - 1;
+  const kernelOffsetX = doubleKernelOffsetX / 2;
+  const doubleKernelOffsetY = kernelY.length - 1;
+  const kernelOffsetY = doubleKernelOffsetY / 2;
+
+  const extendedImage = extendBorders(image, {
+    horizontal: kernelOffsetX,
+    vertical: kernelOffsetY,
+    borderType,
+    borderValue,
+  });
+
   const newImage = Image.createFrom(image);
+  const clamp = getClamp(newImage);
 
   const rowConvolution = new DirectConvolution(
-    image.width,
+    extendedImage.width,
     kernelX,
-    ConvolutionBorderType.CUT
+    ConvolutionBorderType.CUT,
   );
   const columnConvolution = new DirectConvolution(
-    image.height,
+    extendedImage.height,
     kernelY,
-    ConvolutionBorderType.CUT
+    ConvolutionBorderType.CUT,
   );
 
-  for (let c = 0; c < image.channels; c++) {
-    const imgArr = [];
-    for (let y = 0; y < image.height; y++) {
-      const row = [];
-      const rowIndex = y * image.width * image.channels;
-      for (let x = 0; x < image.width; x++) {
-        row.push(image.data[rowIndex + x * image.channels + c]);
-      }
-      imgArr.push(rowConvolution.convolve(row).slice());
-    }
+  const rowData = new Float64Array(extendedImage.width);
+  const columnData = new Float64Array(extendedImage.height);
+  const convolvedData = new Float64Array(
+    // Use `image.width` because convolution with BorderType.CUT reduces the size of the convolved data.
+    image.width * extendedImage.height,
+  );
 
-    for (let x = 0; x < image.width - 2 * kernelOffsetX; x++) {
-      const wOffset = (x + kernelOffsetX) * image.channels;
-      const column = [];
-      for (let y = 0; y < image.height; y++) {
-        column.push(imgArr[y][x]);
+  for (let channel = 0; channel < extendedImage.channels; channel++) {
+    for (let row = 0; row < extendedImage.height; row++) {
+      for (let column = 0; column < extendedImage.width; column++) {
+        rowData[column] = extendedImage.getValue(column, row, channel);
       }
-      const result = columnConvolution.convolve(column);
-      for (let i = 0; i < result.length; i++) {
-        const idx = (i + kernelOffsetY) * hFactor + wOffset + c;
-        newImage.data[idx] = round(clamp(result[i], newImage));
+      const convolvedRow = rowConvolution.convolve(rowData);
+      for (let column = 0; column < image.width; column++) {
+        convolvedData[row * image.width + column] = convolvedRow[column];
       }
     }
-  }
-
-  // Calculate kernel from separated kernels.
-
-  const matrixX = Matrix.rowVector(kernelX);
-  const matrixY = Matrix.columnVector(kernelY);
-  const kernel = matrixY.mmul(matrixX).to2DArray();
 
-  // Apply convolution on the left and right borders
-  for (let c = 0; c < image.channels; c++) {
-    for (let bY = 0; bY < image.height; bY++) {
-      for (let bX = 0; bX < kernelOffsetX; bX++) {
-        const idx = (bY * image.width + bX) * image.channels + c;
-
-        const bXopp = image.width - bX - 1;
-        const bYopp = image.height - bY - 1;
-        const idxOpp = (bYopp * image.width + bXopp) * image.channels + c;
-
-        newImage.data[idx] = computeConvolutionPixel(
-          bX,
-          bY,
-          c,
-          image,
-          kernel,
-          borderType
-        );
-        newImage.data[idxOpp] = computeConvolutionPixel(
-          bXopp,
-          bYopp,
-          c,
-          image,
-          kernel,
-          borderType
-        );
+    for (let column = 0; column < image.width; column++) {
+      for (let row = 0; row < extendedImage.height; row++) {
+        columnData[row] = convolvedData[row * image.width + column];
       }
-    }
-  }
-
-  // apply the convolution on the top and bottom borders
-  for (let c = 0; c < image.channels; c++) {
-    for (let bX = 0; bX < image.width; bX++) {
-      for (let bY = 0; bY < kernelOffsetY; bY++) {
-        const idx = (bY * image.width + bX) * image.channels + c;
-        const bXopp = image.width - bX - 1;
-        const bYopp = image.height - bY - 1;
-        const idxOpp = (bYopp * image.width + bXopp) * image.channels + c;
-
-        newImage.data[idx] = computeConvolutionPixel(
-          bX,
-          bY,
-          c,
-          image,
-          kernel,
-          borderType
-        );
-        newImage.data[idxOpp] = computeConvolutionPixel(
-          bXopp,
-          bYopp,
-          c,
-          image,
-          kernel,
-          borderType
+      const convolvedColumn = columnConvolution.convolve(columnData);
+      for (let row = 0; row < image.height; row++) {
+        newImage.setValue(
+          column,
+          row,
+          channel,
+          round(clamp(convolvedColumn[row])),
         );
       }
     }
@@ -164,14 +190,44 @@ export function separableConvolution(
   return newImage;
 }
 
-function computeConvolutionPixel(
-  x: number,
-  y: number,
+export interface ComputeConvolutionValueOptions {
+  /**
+   * Specify wether the return value should not be clamped and rounded.
+   */
+  returnRawValue?: boolean;
+  /**
+   * If the value has to be clamped, specify the clamping function.
+   */
+  clamp?: ClampFunction;
+}
+
+/**
+ * Compute the convolution of a value of a pixel in an image.
+ * @param column - Column of the pixel.
+ * @param row - Row of the pixel.
+ * @param channel - Channel to process.
+ * @param image - Image to process.
+ * @param kernel - Kernel for the convolutions.
+ * @param interpolateBorder - Function to interpolate the border pixels.
+ * @param options - Compute convolution value options.
+ * @returns The convoluted value.
+ */
+export function computeConvolutionValue(
+  column: number,
+  row: number,
   channel: number,
   image: Image,
   kernel: number[][],
-  borderType: BorderType = BorderType.REFLECT_101
+  interpolateBorder: BorderInterpolationFunction,
+  options: ComputeConvolutionValueOptions = {},
 ): number {
+  let { clamp } = options;
+  const { returnRawValue = false } = options;
+
+  if (returnRawValue) {
+    clamp = undefined;
+  }
+
   let val = 0;
   const kernelWidth = kernel[0].length;
   const kernelHeight = kernel.length;
@@ -181,32 +237,38 @@ function computeConvolutionPixel(
   for (let kY = 0; kY < kernelHeight; kY++) {
     for (let kX = 0; kX < kernelWidth; kX++) {
       const kernelValue = kernel[kY][kX];
-      const imgX = interpolateBorder(
-        x + kX - kernelOffsetX,
-        image.width,
-        borderType
-      );
-      const imgY = interpolateBorder(
-        y + kY - kernelOffsetY,
-        image.height,
-        borderType
-      );
-      val += kernelValue * image.getValue(imgY, imgX, channel);
+      val +=
+        kernelValue *
+        interpolateBorder(
+          column + kX - kernelOffsetX,
+          row + kY - kernelOffsetY,
+          channel,
+          image,
+        );
     }
   }
-
-  return round(clamp(val, image));
+  if (!clamp) {
+    return val;
+  } else {
+    return round(clamp(val));
+  }
 }
 
+/**
+ * Normalize a separated kernel.
+ * @param kernelX - Horizontal component of the separated kernel.
+ * @param kernelY - Vertical component of the separated kernel.
+ * @returns The normalized kernel.
+ */
 function normalizeSeparatedKernel(
   kernelX: number[],
-  kernelY: number[]
+  kernelY: number[],
 ): [number[], number[]] {
   const sumKernelX = kernelX.reduce((prev, current) => prev + current, 0);
   const sumKernelY = kernelY.reduce((prev, current) => prev + current, 0);
   const prod = sumKernelX * sumKernelY;
   if (prod < 0) {
-    throw new Error('this separated kernel cannot be normalized');
+    throw new RangeError('this separated kernel cannot be normalized');
   }
   const factor = 1 / Math.sqrt(Math.abs(prod));
   return [kernelX.map((v) => v * factor), kernelY.map((v) => v * factor)];

package/src/filters/derivativeFilter.ts

@@ -0,0 +1,71 @@
+import { match } from 'ts-pattern';
+
+import type { BitDepth, Image } from '../Image.js';
+import {
+  PREWITT_X,
+  PREWITT_Y,
+  SCHARR_X,
+  SCHARR_Y,
+  SOBEL_X,
+  SOBEL_Y,
+} from '../utils/constants/kernels.js';
+import type { BorderType } from '../utils/interpolateBorder.js';
+
+export const DerivativeFilter = {
+  SOBEL: 'sobel',
+  SCHARR: 'scharr',
+  PREWITT: 'prewitt',
+  // todo: handle even sized kernels to implement Roberts' filter
+  // for 2x2 matrices, the current pixel corresponds to the top-left
+  //  ROBERTS = 'roberts',
+} as const;
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type DerivativeFilter =
+  (typeof DerivativeFilter)[keyof typeof DerivativeFilter];
+
+export interface DerivativeFilterOptions {
+  /**
+   * Algorithm to use for the derivative filter.
+   * @default `SOBEL`
+   */
+  filter?: DerivativeFilter;
+  /**
+   * Specify how the borders should be handled.
+   * @default `'replicate'`
+   */
+  borderType?: BorderType;
+  /**
+   * Value of the border if BorderType is 'constant'.
+   * @default `0`
+   */
+  borderValue?: number;
+  /**
+   * Specify the bit depth of the resulting image.
+   * @default `image.bitDepth`
+   */
+  bitDepth?: BitDepth;
+}
+
+/**
+ * Apply a derivative filter to an image.
+ * @param image - Image to process.
+ * @param options - Derivative filter options.
+ * @returns The processed image.
+ */
+export function derivativeFilter(
+  image: Image,
+  options: DerivativeFilterOptions = {},
+): Image {
+  const { filter = 'sobel' } = options;
+
+  const kernels = match<
+    DerivativeFilter,
+    { kernelX: number[][]; kernelY: number[][] }
+  >(filter)
+    .with('sobel', () => ({ kernelX: SOBEL_X, kernelY: SOBEL_Y }))
+    .with('scharr', () => ({ kernelX: SCHARR_X, kernelY: SCHARR_Y }))
+    .with('prewitt', () => ({ kernelX: PREWITT_X, kernelY: PREWITT_Y }))
+    .exhaustive();
+
+  return image.gradientFilter({ ...kernels, ...options });
+}