image-js 0.0.0-next-e30968a2d8

package/src/filters/convolution.ts

@@ -0,0 +1,357 @@
+import {
+  DirectConvolution,
+  BorderType as ConvolutionBorderType,
+} from 'ml-convolution';
+import { Matrix } from 'ml-matrix';
+
+import { IJS } from '../IJS';
+import { getClamp, ClampFunction } from '../utils/clamp';
+import { getIndex } from '../utils/getIndex';
+import { getOutputImage } from '../utils/getOutputImage';
+import {
+  BorderType,
+  getBorderInterpolation,
+  BorderInterpolationFunction,
+} from '../utils/interpolateBorder';
+import { round } from '../utils/round';
+
+export interface ConvolutionOptions {
+  /**
+   * Specify how the borders should be handled.
+   *
+   * @default BorderType.REFLECT_101
+   */
+  borderType?: BorderType;
+  /**
+   * Value of the border if BorderType is CONSTANT.
+   *
+   * @default 0
+   */
+  borderValue?: number;
+  /**
+   * Should the kernel be normalised?
+   *
+   * @default false
+   */
+  normalize?: boolean;
+  /**
+   * Image to which to output.
+   */
+  out?: IJS;
+}
+
+/**
+ * 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: IJS,
+  kernel: number[][],
+  options: ConvolutionOptions = {},
+): IJS {
+  const { borderType = BorderType.REFLECT_101, 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++) {
+      let dataIndex = i * image.channels + channel;
+      let 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: IJS,
+  kernel: number[][],
+  options: ConvolutionOptions = {},
+): Float64Array {
+  const { borderType = BorderType.REFLECT_101, borderValue = 0 } = options;
+  const interpolateBorder = getBorderInterpolation(borderType, borderValue);
+
+  let result = new Float64Array(image.size * image.channels);
+
+  for (let channel = 0; channel < image.channels; channel++) {
+    for (let row = 0; row < image.height; row++) {
+      for (let column = 0; column < image.width; column++) {
+        let index = getIndex(row, column, channel, image);
+        result[index] = computeConvolutionValue(
+          column,
+          row,
+          channel,
+          image,
+          kernel,
+          interpolateBorder,
+          { returnRawValue: true },
+        );
+      }
+    }
+  }
+
+  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: IJS,
+  kernelX: number[],
+  kernelY: number[],
+  options: ConvolutionOptions = {},
+): IJS {
+  const {
+    normalize,
+    borderType = BorderType.REFLECT_101,
+    borderValue = 0,
+  } = options;
+  const interpolateBorder = getBorderInterpolation(borderType, borderValue);
+  if (normalize) {
+    [kernelX, kernelY] = normalizeSeparatedKernel(kernelX, kernelY);
+  }
+  const doubleKernelOffsetX = kernelX.length - 1;
+  const kernelOffsetX = doubleKernelOffsetX / 2;
+  const doubleKernelOffsetY = kernelY.length - 1;
+  const kernelOffsetY = doubleKernelOffsetY / 2;
+
+  const { width, height, channels } = image;
+
+  const cutWidth = width - doubleKernelOffsetX;
+
+  const newImage = IJS.createFrom(image);
+  const clamp = getClamp(newImage);
+
+  const rowConvolution = new DirectConvolution(
+    width,
+    kernelX,
+    ConvolutionBorderType.CUT,
+  );
+  const columnConvolution = new DirectConvolution(
+    height,
+    kernelY,
+    ConvolutionBorderType.CUT,
+  );
+
+  const rowData = new Float64Array(width);
+  const columnData = new Float64Array(height);
+  const convolvedData = new Float64Array(cutWidth * height);
+
+  for (let channel = 0; channel < channels; channel++) {
+    for (let row = 0; row < height; row++) {
+      for (let column = 0; column < width; column++) {
+        rowData[column] = image.getValue(row, column, channel);
+      }
+      const convolvedRow = rowConvolution.convolve(rowData);
+      for (let column = 0; column < cutWidth; column++) {
+        convolvedData[row * cutWidth + column] = convolvedRow[column];
+      }
+    }
+
+    for (let column = 0; column < cutWidth; column++) {
+      const wOffset = column + kernelOffsetX;
+      for (let row = 0; row < height; row++) {
+        columnData[row] = convolvedData[row * cutWidth + column];
+      }
+      const result = columnConvolution.convolve(columnData);
+      for (let i = 0; i < result.length; i++) {
+        const index = (i + kernelOffsetY) * width + wOffset;
+        newImage.setValueByIndex(index, channel, round(clamp(result[i])));
+      }
+    }
+  }
+
+  // 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 channel = 0; channel < channels; channel++) {
+    for (let bY = 0; bY < height; bY++) {
+      for (let bX = 0; bX < kernelOffsetX; bX++) {
+        const index = bY * width + bX;
+
+        const bXopp = width - bX - 1;
+        const bYopp = height - bY - 1;
+        const indexOpp = bYopp * width + bXopp;
+        newImage.setValueByIndex(
+          index,
+          channel,
+          computeConvolutionValue(
+            bX,
+            bY,
+            channel,
+            image,
+            kernel,
+            interpolateBorder,
+            { clamp },
+          ),
+        );
+        newImage.setValueByIndex(
+          indexOpp,
+          channel,
+          computeConvolutionValue(
+            bXopp,
+            bYopp,
+            channel,
+            image,
+            kernel,
+            interpolateBorder,
+            { clamp },
+          ),
+        );
+      }
+    }
+  }
+
+  // apply the convolution on the top and bottom borders
+  for (let channel = 0; channel < channels; channel++) {
+    for (let bX = 0; bX < width; bX++) {
+      for (let bY = 0; bY < kernelOffsetY; bY++) {
+        const index = bY * width + bX;
+        const bXopp = width - bX - 1;
+        const bYopp = height - bY - 1;
+        const indexOpp = bYopp * width + bXopp;
+
+        newImage.setValueByIndex(
+          index,
+          channel,
+          computeConvolutionValue(
+            bX,
+            bY,
+            channel,
+            image,
+            kernel,
+            interpolateBorder,
+            { clamp },
+          ),
+        );
+        newImage.setValueByIndex(
+          indexOpp,
+          channel,
+          computeConvolutionValue(
+            bXopp,
+            bYopp,
+            channel,
+            image,
+            kernel,
+            interpolateBorder,
+            { clamp },
+          ),
+        );
+      }
+    }
+  }
+
+  return newImage;
+}
+
+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: IJS,
+  kernel: number[][],
+  interpolateBorder: BorderInterpolationFunction,
+  options: ComputeConvolutionValueOptions = {},
+): number {
+  let { returnRawValue = false, clamp } = options;
+
+  if (returnRawValue) {
+    clamp = undefined;
+  }
+
+  let val = 0;
+  const kernelWidth = kernel[0].length;
+  const kernelHeight = kernel.length;
+  const kernelOffsetX = (kernelWidth - 1) / 2;
+  const kernelOffsetY = (kernelHeight - 1) / 2;
+
+  for (let kY = 0; kY < kernelHeight; kY++) {
+    for (let kX = 0; kX < kernelWidth; kX++) {
+      const kernelValue = kernel[kY][kX];
+      val +=
+        kernelValue *
+        interpolateBorder(
+          column + kX - kernelOffsetX,
+          row + kY - kernelOffsetY,
+          channel,
+          image,
+        );
+    }
+  }
+  if (!clamp) {
+    return val;
+  } else {
+    return round(clamp(val));
+  }
+}
+
+/**
+ * @param kernelX
+ * @param kernelY
+ */
+function normalizeSeparatedKernel(
+  kernelX: 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');
+  }
+  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,77 @@
+import { ColorDepth, IJS } from '..';
+import { BorderType } from '../utils/interpolateBorder';
+import {
+  PREWITT_X,
+  PREWITT_Y,
+  SCHARR_X,
+  SCHARR_Y,
+  SOBEL_X,
+  SOBEL_Y,
+} from '../utils/kernels';
+
+export enum DerivativeFilters {
+  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',
+}
+
+export interface DerivativeFilterOptions {
+  /**
+   * Algorithm to use for the derivative filter.
+   */
+  filter?: DerivativeFilters;
+  /**
+   * Specify how the borders should be handled.
+   *
+   * @default BorderType.REPLICATE
+   */
+  borderType?: BorderType;
+  /**
+   * Value of the border if BorderType is CONSTANT.
+   *
+   * @default 0
+   */
+  borderValue?: number;
+  /**
+   * Specify the bitDepth of the resulting image.
+   *
+   * @default image.bitDepth
+   */
+  bitDepth?: ColorDepth;
+}
+
+/**
+ * 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: IJS,
+  options: DerivativeFilterOptions = {},
+): IJS {
+  const { filter = DerivativeFilters.SOBEL } = options;
+  let kernelX = SOBEL_X;
+  let kernelY = SOBEL_Y;
+
+  switch (filter) {
+    case DerivativeFilters.SOBEL:
+      break;
+    case DerivativeFilters.SCHARR:
+      kernelX = SCHARR_X;
+      kernelY = SCHARR_Y;
+      break;
+    case DerivativeFilters.PREWITT:
+      kernelX = PREWITT_X;
+      kernelY = PREWITT_Y;
+      break;
+    default:
+      throw new Error('derivativeFilter: unrecognised derivative filter.');
+  }
+
+  return image.gradientFilter({ kernelX, kernelY, ...options });
+}

package/src/filters/gaussianBlur.ts

@@ -0,0 +1,124 @@
+import { IJS } from '../IJS';
+import { BorderType } from '../utils/interpolateBorder';
+
+import { separableConvolution } from './convolution';
+
+interface GaussianBlurBaseOptions {
+  /**
+   * Specify how the borders should be handled.
+   *
+   * @default BorderType.REFLECT_101
+   */
+  borderType?: BorderType;
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: IJS;
+}
+
+export interface GaussianBlurSigmaOptions extends GaussianBlurBaseOptions {
+  /**
+   * Size of the kernel.
+   */
+  size?: number;
+  /**
+   * The standard deviation. Specifies the width of the gaussian function in the case where it is the same for x and y.
+   *
+   * @default 2 * Math.ceil(2 * sigma) + 1
+   */
+
+  sigma: number;
+}
+
+export interface GaussianBlurXYOptions extends GaussianBlurBaseOptions {
+  /**
+   * The standard deviation for the x axis. Specifies the width of the gaussian function along x.
+   */
+  sigmaX: number;
+  /**
+   * The standard deviation for the y axis. Specifies the width of the gaussian function along y.
+   */
+  sigmaY: number;
+  /**
+   * Size of the X axis kernel
+   *
+   * @default 2 * Math.ceil(2 * sigmaX) + 1
+   */
+  sizeX?: number;
+  /**
+   * Size of the Y axis kernel
+   *
+   * @default 2 * Math.ceil(2 * sigma) + 1
+   */
+  sizeY?: number;
+}
+
+export type GaussianBlurOptions =
+  | GaussianBlurSigmaOptions
+  | GaussianBlurXYOptions;
+
+function getRadius(size: number): number {
+  if (size % 2 !== 1 || size < 0) {
+    throw new Error(
+      'gaussianBlur: gaussian blur size must be positive and odd',
+    );
+  }
+  return (size - 1) / 2;
+}
+
+/**
+ * Apply a gaussian filter to an image.
+ *
+ * @param image - Image to blur.
+ * @param options - Gaussian blur options.
+ * @returns The blurred image.
+ */
+export function gaussianBlur(image: IJS, options: GaussianBlurOptions): IJS {
+  if ('sigma' in options) {
+    const { sigma, size = getSize(sigma) } = options;
+    const radius = getRadius(size);
+    const kernel = getKernel(radius, sigma);
+    return separableConvolution(image, kernel, kernel, {
+      borderType: options.borderType,
+    });
+  } else {
+    const {
+      sigmaX,
+      sigmaY,
+      sizeX = getSize(sigmaX),
+      sizeY = getSize(sigmaY),
+    } = options;
+
+    const radiusX = getRadius(sizeX);
+    const radiusY = getRadius(sizeY);
+
+    const kernelX = getKernel(radiusX, sigmaX);
+    const kernelY = getKernel(radiusY, sigmaY);
+    return separableConvolution(image, kernelX, kernelY, {
+      borderType: options.borderType,
+    });
+  }
+}
+
+function getKernel(radius: number, sigma: number): number[] {
+  const n = radius * 2 + 1;
+  const kernel = new Array(n);
+  const sigmaX = sigma ? sigma : ((n - 1) * 0.5 - 1) * 0.3 + 0.8;
+  const scale2X = -0.5 / (sigmaX * sigmaX);
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    const x = i - radius;
+    const t = Math.exp(scale2X * x * x);
+    kernel[i] = t;
+    sum += t;
+  }
+
+  for (let i = 0; i < n; i++) {
+    kernel[i] /= sum;
+  }
+  return kernel;
+}
+
+function getSize(sigma: number): number {
+  return 2 * Math.ceil(2 * sigma) + 1;
+}

package/src/filters/gradientFilter.ts

@@ -0,0 +1,106 @@
+import { ColorDepth, IJS, ImageColorModel } from '..';
+import checkProcessable from '../utils/checkProcessable';
+import { BorderType } from '../utils/interpolateBorder';
+
+export interface GradientFilterBaseOptions {
+  /**
+   * Specify how the borders should be handled.
+   *
+   * @default BorderType.REPLICATE
+   */
+  borderType?: BorderType;
+  /**
+   * Value of the border if BorderType is CONSTANT.
+   *
+   * @default 0
+   */
+  borderValue?: number;
+  /**
+   * Specify the bitDepth of the resulting image.
+   *
+   * @default image.bitDepth
+   */
+  bitDepth?: ColorDepth;
+}
+
+export interface GradientFilterXOptions extends GradientFilterBaseOptions {
+  /**
+   * Kernel along x axis.
+   */
+  kernelX: number[][];
+}
+export interface GradientFilterYOptions extends GradientFilterBaseOptions {
+  /**
+   * Kernel along y axis.
+   */
+  kernelY: number[][];
+}
+
+export interface GradientFilterXYOptions extends GradientFilterBaseOptions {
+  /**
+   * Kernel along x axis.
+   */
+  kernelX: number[][];
+  /**
+   * Kernel along y axis.
+   */
+  kernelY: number[][];
+}
+
+export type GradientFilterOptions =
+  | GradientFilterXOptions
+  | GradientFilterYOptions
+  | GradientFilterXYOptions;
+
+/**
+ * Apply a gradient filter to an image.
+ *
+ * @param image - The image to process.
+ * @param options - Gradient filter options.
+ * @returns The gradient image.
+ */
+export function gradientFilter(
+  image: IJS,
+  options: GradientFilterOptions,
+): IJS {
+  const { borderType = BorderType.REPLICATE, borderValue = 0 } = options;
+
+  checkProcessable(image, 'gradientFilter', {
+    bitDepth: [8, 16],
+    colorModel: ImageColorModel.GREY,
+  });
+
+  if ('kernelX' in options && 'kernelY' in options) {
+    const { kernelX, kernelY } = options;
+    const gradientX = image.rawDirectConvolution(kernelX, {
+      borderType,
+      borderValue,
+    });
+
+    const gradientY = image.rawDirectConvolution(kernelY, {
+      borderType,
+      borderValue,
+    });
+
+    let gradient = new IJS(image.width, image.height, {
+      colorModel: ImageColorModel.GREY,
+    });
+
+    for (let i = 0; i < image.size; i++) {
+      gradient.setValueByIndex(i, 0, Math.hypot(gradientX[i], gradientY[i]));
+    }
+    return gradient;
+  } else if ('kernelX' in options) {
+    return image.directConvolution(options.kernelX, {
+      borderType,
+      borderValue,
+    });
+  } else if ('kernelY' in options) {
+    return image.directConvolution(options.kernelY, {
+      borderType,
+      borderValue,
+    });
+  } else {
+    throw new Error(`kernelX and KernelY are not defined`);
+  }
+}