image-js 1.0.0-alpha.3 → 1.0.0

package/src/filters/medianFilter.ts

@@ -0,0 +1,83 @@
+import { xMedian } from 'ml-spectra-processing';
+
+import { Image } from '../Image.js';
+import type { BorderType } from '../utils/interpolateBorder.js';
+import { getBorderInterpolation } from '../utils/interpolateBorder.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface MedianFilterOptions {
+  /**
+   * Type of border algorithm to interpolate from.
+   * @default `'reflect101'`
+   */
+  borderType: BorderType;
+  /**
+   * Value of border.
+   */
+  borderValue?: number;
+  /**
+   * The radius of the cell to extract median value from. Must be odd.
+   *  @default `1`
+   */
+  cellSize: number;
+}
+/**
+ * Calculate a new image that replaces all pixel values by the median of neighbouring pixels.
+ * @param image - Image to be filtered.
+ * @param options - MedianFilterOptions
+ * @returns Image after median filter.
+ */
+export function medianFilter(image: Image, options: MedianFilterOptions) {
+  const { cellSize = 3, borderType = 'reflect101', borderValue } = options;
+
+  checkProcessable(image, {
+    bitDepth: [8, 16],
+  });
+
+  if (cellSize < 1) {
+    throw new RangeError(
+      `Invalid property "cellSize". Must be greater than 0. Received ${cellSize}.`,
+    );
+  }
+
+  if (cellSize % 2 === 0) {
+    throw new RangeError(
+      `Invalid property "cellSize". Must be an odd number. Received ${cellSize}.`,
+    );
+  }
+
+  const interpolateBorder = getBorderInterpolation(
+    borderType,
+    borderValue as number,
+  );
+
+  const newImage = Image.createFrom(image);
+  const size = cellSize ** 2;
+  const cellValues = new Uint16Array(size);
+
+  const halfCellSize = (cellSize - 1) / 2;
+
+  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 n = 0;
+        for (let cellRow = -halfCellSize; cellRow <= halfCellSize; cellRow++) {
+          for (
+            let cellColumn = -halfCellSize;
+            cellColumn <= halfCellSize;
+            cellColumn++
+          ) {
+            cellValues[n++] = interpolateBorder(
+              column + cellColumn,
+              row + cellRow,
+              channel,
+              image,
+            );
+          }
+        }
+        newImage.setValue(column, row, channel, xMedian(cellValues));
+      }
+    }
+  }
+  return newImage;
+}

package/src/filters/or.ts

@@ -0,0 +1,33 @@
+import type { Mask } from '../Mask.js';
+import { maskToOutputMask } from '../utils/getOutputImage.js';
+
+export interface OrOptions {
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Mask;
+}
+
+/**
+ * Perform an OR operation on two masks.
+ * @param mask - First mask.
+ * @param otherMask - Second mask.
+ * @param options - Or options.
+ * @returns OR of the two masks.
+ */
+export function or(mask: Mask, otherMask: Mask, options?: OrOptions): 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/pixelate.ts

@@ -0,0 +1,178 @@
+import { xMedian } from 'ml-spectra-processing';
+
+import type { Image } from '../Image.js';
+import type { Point } from '../utils/geometry/points.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+import { assertUnreachable } from '../utils/validators/assert.js';
+
+export interface PixelateOptions {
+  /**
+   *  Range of pixelated area.
+   */
+  cellSize: number;
+  /**
+   * algorithm to use.
+   * @default `'center'`
+   */
+  algorithm?: 'center' | 'median' | 'mean';
+  /**
+   * Image to which to output.
+   */
+  out?: Image;
+}
+
+interface GetValueOptions {
+  /*
+   * width of a region to look for center
+   */
+  width: number;
+  /*
+   * height of a region to look for center
+   */
+  height: number;
+  /*
+   * top left point of a region which serves as point of origin
+   */
+  origin: Point;
+}
+
+/**
+ * Function to pixelate an image.
+ * @param image - Image to be pixelated.
+ * @param options - PixelateOptions.
+ * @returns Pixelated Image.
+ */
+export function pixelate(image: Image, options: PixelateOptions): Image {
+  const { cellSize, algorithm = 'center' } = options;
+  if (!Number.isInteger(cellSize)) {
+    throw new TypeError('cellSize must be an integer');
+  }
+  if (cellSize < 2) {
+    throw new RangeError('cellSize must be greater than 1');
+  }
+  const newImage = getOutputImage(image, options);
+
+  const getCellValue = getCellValueFunction(algorithm);
+
+  for (let channel = 0; channel < image.channels; channel++) {
+    for (let column = 0; column < image.width; column += cellSize) {
+      for (let row = 0; row < image.height; row += cellSize) {
+        const currentCellWidth = Math.min(cellSize, image.width - column);
+        const currentCellHeight = Math.min(cellSize, image.height - row);
+        const value = getCellValue(image, channel, {
+          width: currentCellWidth,
+          height: currentCellHeight,
+          origin: { column, row },
+        });
+
+        for (
+          let newColumn = column;
+          newColumn < column + currentCellWidth;
+          newColumn++
+        ) {
+          for (let newRow = row; newRow < row + currentCellHeight; newRow++) {
+            newImage.setValue(newColumn, newRow, channel, value);
+          }
+        }
+      }
+    }
+  }
+
+  return newImage;
+}
+
+/**
+ * Computes the center value for the current sector
+ * @param image - image used for the algorithm
+ * @param channel - image channel toto find center value of
+ * @param options - GetValueOptions
+ * @returns center value
+ */
+function getCellCenter(
+  image: Image,
+  channel: number,
+  options: GetValueOptions,
+): number {
+  const center = {
+    column: Math.floor(
+      (options.origin.column + options.origin.column + options.width - 1) / 2,
+    ),
+    row: Math.floor(
+      (options.origin.row + options.origin.row + options.height - 1) / 2,
+    ),
+  };
+  const value = image.getValue(center.column, center.row, channel);
+  return value;
+}
+/**
+ * Computes mean value for the current sector
+ * @param image - image used for algorithm
+ * @param channel - current channel of an image
+ * @param options - GetValueOptions
+ * @returns mean value
+ */
+function getCellMean(image: Image, channel: number, options: GetValueOptions) {
+  let sum = 0;
+
+  for (
+    let column = options.origin.column;
+    column < options.origin.column + options.width;
+    column++
+  ) {
+    for (
+      let row = options.origin.row;
+      row < options.origin.row + options.height;
+      row++
+    ) {
+      sum += image.getValue(column, row, channel);
+    }
+  }
+  return Math.round(sum / (options.width * options.height));
+}
+/**
+ * Computes a median value for the current sector
+ * @param image - image used algorithm
+ * @param channel - current channel of an image
+ * @param options - GetValueOptions
+ * @returns median value
+ */
+function getCellMedian(
+  image: Image,
+  channel: number,
+  options: GetValueOptions,
+) {
+  const array = [];
+  for (
+    let column = options.origin.column;
+    column < options.origin.column + options.width;
+    column++
+  ) {
+    for (
+      let row = options.origin.row;
+      row < options.origin.row + options.height;
+      row++
+    ) {
+      array.push(image.getValue(column, row, channel));
+    }
+  }
+
+  return xMedian(array);
+}
+/**
+ *  Chooses which algorithm to use for pixelization and returns a function to use for computation
+ * @param algorithm - string with the name of an algorithm
+ * @returns function
+ */
+function getCellValueFunction(algorithm: 'center' | 'mean' | 'median') {
+  switch (algorithm) {
+    case 'mean':
+      return getCellMean;
+    case 'median':
+      return getCellMedian;
+    case 'center':
+      return getCellCenter;
+    default:
+      assertUnreachable(algorithm);
+      break;
+  }
+}

package/src/geometry/getPerspectiveWarp.ts

@@ -0,0 +1,169 @@
+import { Matrix, SingularValueDecomposition } from 'ml-matrix';
+
+import type { Point } from '../utils/geometry/points.js';
+
+/**
+ * Options for getPerspectiveWarp function.
+ */
+export interface GetPerspectiveWarpOptions {
+  /**
+   * The horizontal dimension (in pixels) of the final rectified rectangular image.
+   */
+  width?: number;
+  /**
+   * The vertical dimension (in pixels) of the final rectified rectangular image.
+   */
+  height?: number;
+}
+/**
+ * Returns result matrix along with vertical and horizontal dimensions for the rectangular image.
+ */
+export type GetPerspectiveWarpData = Required<GetPerspectiveWarpOptions> & {
+  matrix: number[][];
+};
+
+// REFERENCES :
+// http://graphics.cs.cmu.edu/courses/15-463/2011_fall/Lectures/morphing.pdf
+/**
+ * Computes a perspective transformation matrix to rectify a quadrilateral region into a rectangle.
+ *
+ * This function takes four corner points of a quadrilateral (e.g., a document photographed at an angle) and calculates the transformation matrix needed to "unwarp" it into a rectangular image.
+ * The output dimensions can be specified or calculated automatically based on the input geometry.
+ * @param pts - 4 reference corners.
+ * @param options - PerspectiveWarpOptions.
+ * @returns - Matrix from 4 points.
+ */
+export function getPerspectiveWarp(
+  pts: Point[],
+  options: GetPerspectiveWarpOptions = {},
+): GetPerspectiveWarpData {
+  if (pts.length !== 4) {
+    throw new Error(
+      `The array pts must have four elements, which are the four corners. Currently, pts have ${pts.length} elements`,
+    );
+  }
+  const { width, height } = options;
+  const [tl, tr, br, bl] = order4Points(pts);
+
+  let widthRect;
+  let heightRect;
+  if (height && width) {
+    widthRect = width;
+    heightRect = height;
+  } else if (!height && !width) {
+    widthRect = Math.ceil(
+      Math.max(distance2Points(tl, tr), distance2Points(bl, br)),
+    );
+    heightRect = Math.ceil(
+      Math.max(distance2Points(tl, bl), distance2Points(tr, br)),
+    );
+  } else {
+    throw new Error(
+      `Invalid dimensions: ${width ? '`height`' : '`width`'} is missing. ` +
+        `Either provide both width and height, or omit both to auto-calculate dimensions.`,
+    );
+  }
+
+  const [x1, y1] = [0, 0];
+  const [x2, y2] = [widthRect - 1, 0];
+  const [x3, y3] = [widthRect - 1, heightRect - 1];
+  const [x4, y4] = [0, heightRect - 1];
+
+  const S = new Matrix([
+    [x1, y1, 1, 0, 0, 0, -x1 * tl.column, -y1 * tl.column],
+    [x2, y2, 1, 0, 0, 0, -x2 * tr.column, -y2 * tr.column],
+    [x3, y3, 1, 0, 0, 0, -x3 * br.column, -y3 * br.column],
+    [x4, y4, 1, 0, 0, 0, -x4 * bl.column, -y4 * bl.column],
+    [0, 0, 0, x1, y1, 1, -x1 * tl.row, -y1 * tl.row],
+    [0, 0, 0, x2, y2, 1, -x2 * tr.row, -y2 * tr.row],
+    [0, 0, 0, x3, y3, 1, -x3 * br.row, -y3 * br.row],
+    [0, 0, 0, x4, y4, 1, -x4 * bl.row, -y4 * bl.row],
+  ]);
+  const D = Matrix.columnVector([
+    tl.column,
+    tr.column,
+    br.column,
+    bl.column,
+    tl.row,
+    tr.row,
+    br.row,
+    bl.row,
+  ]);
+
+  const svd = new SingularValueDecomposition(S);
+  const T = svd.solve(D).to1DArray(); // solve S*T = D
+  T.push(1);
+
+  const M = [];
+  for (let i = 0; i < 3; i++) {
+    const row = [];
+    for (let j = 0; j < 3; j++) {
+      row.push(T[i * 3 + j]);
+    }
+    M.push(row);
+  }
+  return { matrix: M, width: widthRect, height: heightRect };
+}
+
+/**
+ * Sorts 4 points in order =>[top-left,top-right,bottom-right,bottom-left]. Input points must be in clockwise or counter-clockwise order.
+ * @param pts - Array of 4 points.
+ * @returns Sorted array of 4 points.
+ */
+export function order4Points(pts: Point[]) {
+  let tl: Point;
+  let tr: Point;
+  let br: Point;
+  let bl: Point;
+
+  let minX = pts[0].column;
+  let indexMinX = 0;
+
+  for (let i = 1; i < pts.length; i++) {
+    if (pts[i].column < minX) {
+      minX = pts[i].column;
+      indexMinX = i;
+    }
+  }
+
+  let minX2 = pts[(indexMinX + 1) % pts.length].column;
+  let indexMinX2 = (indexMinX + 1) % pts.length;
+
+  for (let i = 0; i < pts.length; i++) {
+    if (pts[i].column < minX2 && i !== indexMinX) {
+      minX2 = pts[i].column;
+      indexMinX2 = i;
+    }
+  }
+  if (pts[indexMinX2].row < pts[indexMinX].row) {
+    tl = pts[indexMinX2];
+    bl = pts[indexMinX];
+    if (indexMinX !== (indexMinX2 + 1) % 4) {
+      tr = pts[(indexMinX2 + 1) % 4];
+      br = pts[(indexMinX2 + 2) % 4];
+    } else {
+      tr = pts[(indexMinX2 + 2) % 4];
+      br = pts[(indexMinX2 + 3) % 4];
+    }
+  } else {
+    bl = pts[indexMinX2];
+    tl = pts[indexMinX];
+    if (indexMinX2 !== (indexMinX + 1) % 4) {
+      tr = pts[(indexMinX + 1) % 4];
+      br = pts[(indexMinX + 2) % 4];
+    } else {
+      tr = pts[(indexMinX + 2) % 4];
+      br = pts[(indexMinX + 3) % 4];
+    }
+  }
+  return [tl, tr, br, bl];
+}
+/**
+ *  Calculates distance between points.
+ * @param p1 - Point1
+ * @param p2 - Point2
+ * @returns distance between points.
+ */
+function distance2Points(p1: Point, p2: Point) {
+  return Math.hypot(p1.column - p2.column, p1.row - p2.row);
+}

package/src/geometry/index.ts

@@ -1,3 +1,6 @@
-export * from './transform';
-export * from './resize';
-export * from './rotate';
+export * from './resize.js';
+export * from './rotate.js';
+export * from './transform.js';
+export * from './transformRotate.js';
+export * from './getPerspectiveWarp.js';
+export type { Point } from '../utils/geometry/points.js';

package/src/geometry/resize.ts

@@ -1,66 +1,95 @@
-import { Image } from '../Image';
-import { InterpolationType, BorderType } from '../types';
-import { getInterpolationFunction } from '../utils/interpolatePixel';
-import { getBorderInterpolation } from '../utils/interpolateBorder';
-import { getClamp } from '../utils/clamp';
+import type { Image } from '../Image.js';
+import type { BorderType } from '../utils/interpolateBorder.js';
+import type { InterpolationType } from '../utils/interpolatePixel.js';
+import { assert } from '../utils/validators/assert.js';
 
-export interface IResizeOptions {
+import { transform } from './transform.js';
+
+export interface ResizeOptions {
+  /**
+   * Width of the output image.
+   */
   width?: number;
+  /**
+   * Height of the output image.
+   */
   height?: number;
+  /**
+   * Factor by which to scale the width.
+   */
   xFactor?: number;
+  /**
+   * Factor by which to scale the width.
+   */
   yFactor?: number;
+  /**
+   * Whether the aspect ratio of the image should be preserved.
+   * @default `true`
+   */
   preserveAspectRatio?: boolean;
+  /**
+   * Method to use to interpolate the new pixels.
+   * @default `'bilinear'`
+   */
   interpolationType?: InterpolationType;
+  /**
+   * Specify how the borders should be handled.
+   * @default `'constant'`
+   */
   borderType?: BorderType;
+  /**
+   * Value of the border if BorderType is 'constant'.
+   * @default `0`
+   */
   borderValue?: number;
 }
 
-export function resize(image: Image, options: IResizeOptions): Image {
+/**
+ * Returns a resized copy of an image.
+ * @param image - Original image.
+ * @param options - Resize options.
+ * @returns The new image.
+ */
+export function resize(image: Image, options: ResizeOptions): Image {
   const {
-    interpolationType = InterpolationType.BILINEAR,
-    borderType = BorderType.CONSTANT,
-    borderValue = 0
+    interpolationType = 'bilinear',
+    borderType = 'replicate',
+    borderValue = 0,
   } = options;
-  const { width, height } = checkOptions(image, options);
-  const newImage = Image.createFrom(image, { width, height });
-  const interpolate = getInterpolationFunction(interpolationType);
-  const interpolateBorder = getBorderInterpolation(borderType, borderValue);
-  const clamp = getClamp(newImage);
-  const hFactor = newImage.width * newImage.channels;
-  const intervalX = (image.width - 1) / (width - 1);
-  const intervalY = (image.height - 1) / (height - 1);
-  for (let y = 0; y < newImage.height; y++) {
-    const hOffset = hFactor * y;
-    for (let x = 0; x < newImage.width; x++) {
-      const wOffset = hOffset + x * image.channels;
-      const nx = x * intervalX;
-      const ny = y * intervalY;
-      for (let c = 0; c < newImage.channels; c++) {
-        const newValue = interpolate(
-          image,
-          nx,
-          ny,
-          c,
-          interpolateBorder,
-          clamp
-        );
-        newImage.data[wOffset + c] = newValue;
-      }
-    }
-  }
-  return newImage;
+  const { width, height, xFactor, yFactor } = checkOptions(image, options);
+
+  return transform(
+    image,
+    [
+      [xFactor, 0, xFactor / 2],
+      [0, yFactor, yFactor / 2],
+    ],
+    {
+      interpolationType,
+      borderType,
+      borderValue,
+      height,
+      width,
+    },
+  );
 }
 
+/**
+ * Verify that the resize options are valid.
+ * @param image - Image.
+ * @param options - Resize options.
+ * @returns Resize options.
+ */
 function checkOptions(
   image: Image,
-  options: IResizeOptions
+  options: ResizeOptions,
 ): { width: number; height: number; xFactor: number; yFactor: number } {
   const {
     width,
     height,
     xFactor,
     yFactor,
-    preserveAspectRatio = true
+    preserveAspectRatio = true,
   } = options;
 
   if (
@@ -69,8 +98,8 @@ function checkOptions(
     xFactor === undefined &&
     yFactor === undefined
   ) {
-    throw new Error(
-      'At least one of the width, height, xFactor or yFactor options must be passed'
+    throw new TypeError(
+      'at least one of the width, height, xFactor or yFactor options must be passed',
     );
   }
 
@@ -78,29 +107,24 @@ function checkOptions(
   let newHeight: number;
 
   const maybeWidth = getSize(width, xFactor, image.width, preserveAspectRatio);
+
   const maybeHeight = getSize(
     height,
     yFactor,
     image.height,
-    preserveAspectRatio
+    preserveAspectRatio,
   );
 
   if (maybeWidth === undefined) {
-    if (maybeHeight !== undefined) {
-      newWidth = Math.round(maybeHeight * (image.width / image.height));
-    } else {
-      throw new Error('UNREACHABLE');
-    }
+    assert(maybeHeight !== undefined);
+    newWidth = Math.round(maybeHeight * (image.width / image.height));
   } else {
     newWidth = maybeWidth;
   }
 
   if (maybeHeight === undefined) {
-    if (maybeWidth !== undefined) {
-      newHeight = Math.round(maybeWidth * (image.height / image.width));
-    } else {
-      throw new Error('UNREACHABLE');
-    }
+    assert(maybeWidth !== undefined);
+    newHeight = Math.round(maybeWidth * (image.height / image.width));
   } else {
     newHeight = maybeHeight;
   }
@@ -108,16 +132,24 @@ function checkOptions(
   return {
     width: newWidth,
     height: newHeight,
-    xFactor: xFactor ? xFactor : newWidth / image.width,
-    yFactor: yFactor ? yFactor : newHeight / image.height
+    xFactor: xFactor ?? newWidth / image.width,
+    yFactor: yFactor ?? newHeight / image.height,
   };
 }
 
+/**
+ * Compute automatic new size.
+ * @param sizeOpt - Size option.
+ * @param factor - Factor option.
+ * @param sizeImg - Size of the image.
+ * @param preserveAspectRatio - Whether to preserve the aspect ratio.
+ * @returns New size.
+ */
 function getSize(
   sizeOpt: number | undefined,
   factor: number | undefined,
   sizeImg: number,
-  preserveAspectRatio: boolean
+  preserveAspectRatio: boolean,
 ): number | undefined {
   if (sizeOpt === undefined) {
     if (factor !== undefined) {
@@ -126,7 +158,7 @@ function getSize(
       return sizeImg;
     }
   } else if (factor !== undefined) {
-    throw new Error('factor must not be passed with size');
+    throw new TypeError('factor and size cannot be passed together');
   } else {
     return sizeOpt;
   }