image-js 1.0.0-alpha.2 → 1.0.0

package/src/utils/interpolateBorder.ts

@@ -1,51 +1,204 @@
-import { BorderType } from '../types';
+import { match } from 'ts-pattern';
 
-export function interpolateBorder(
+import type { Image } from '../Image.js';
+
+import type { BorderInterpolationFunction } from './utils.types.js';
+
+export const BorderType = {
+  CONSTANT: 'constant',
+  REPLICATE: 'replicate',
+  REFLECT: 'reflect',
+  WRAP: 'wrap',
+  REFLECT_101: 'reflect101',
+} as const;
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type BorderType = (typeof BorderType)[keyof typeof BorderType];
+
+/**
+ * Pick the border interpolation algorithm.
+ * The different algorithms are illustrated here:
+ * @see {@link https://vovkos.github.io/doxyrest-showcase/opencv/sphinx_rtd_theme/enum_cv_BorderTypes.html}
+ * @param type - The border type.
+ * @param value - A pixel value if BorderType.CONSTANT is used.
+ * @returns The border interpolation function.
+ */
+export function getBorderInterpolation(
+  type: BorderType,
+  value: number,
+): BorderInterpolationFunction {
+  return match(type)
+    .with('constant', () => getInterpolateConstant(value))
+    .with('replicate', () => interpolateReplicate)
+    .with('reflect', () => interpolateReflect)
+    .with('reflect101', () => interpolateReflect101)
+    .with('wrap', () => interpolateWrap)
+    .exhaustive();
+}
+
+function checkRange(point: number, length: number): void {
+  if (point <= 0 - length || point >= length + length - 1) {
+    throw new RangeError('border must be smaller than the original image');
+  }
+}
+
+function getInterpolateConstant(value: number): BorderInterpolationFunction {
+  return function interpolateConstant(
+    column: number,
+    row: number,
+    channel: number,
+    image: Image,
+  ): number {
+    const newColumn = interpolateConstantPoint(column, image.width);
+    const newRow = interpolateConstantPoint(row, image.height);
+    if (newColumn === -1 || newRow === -1) {
+      return value;
+    }
+    return image.getValue(newColumn, newRow, channel);
+  };
+}
+
+/**
+ * Interpolate using a constant point.
+ * @param point - The point to interpolate.
+ * @param length  - The length of the image.
+ * @returns The interpolated point.
+ */
+export function interpolateConstantPoint(
   point: number,
   length: number,
-  type: BorderType
 ): number {
   if (point >= 0 && point < length) {
     return point;
   }
-  if (type === BorderType.CONSTANT) {
-    return -1;
+  return -1;
+}
+
+function interpolateReplicate(
+  column: number,
+  row: number,
+  channel: number,
+  image: Image,
+): number {
+  return image.getValue(
+    interpolateReplicatePoint(column, image.width),
+    interpolateReplicatePoint(row, image.height),
+    channel,
+  );
+}
+
+/**
+ * Interpolate by replicating the border.
+ * @param point - The point to interpolate.
+ * @param length - The length of the image.
+ * @returns The interpolated point.
+ */
+export function interpolateReplicatePoint(
+  point: number,
+  length: number,
+): number {
+  if (point >= 0 && point < length) {
+    return point;
   }
-  if (point > 0 - length && point < length + length - 1) {
-    if (type === BorderType.REPLICATE) {
-      if (point < 0) {
-        return 0;
-      } else {
-        return length - 1;
-      }
-    }
-    if (type === BorderType.REFLECT) {
-      if (point < 0) {
-        return -1 - point;
-      } else {
-        return length + length - 1 - point;
-      }
-    }
-    if (type === BorderType.WRAP) {
-      if (point < 0) {
-        return length + point;
-      } else {
-        return point - length;
-      }
-    }
-    if (type === BorderType.REFLECT_101) {
-      if (point < 0) {
-        return 0 - point;
-      } else {
-        return length + length - 2 - point;
-      }
-    }
-    throw new Error(
-      `interpolateBorder cannot be used with border type ${type}`
-    );
+  checkRange(point, length);
+  if (point < 0) {
+    return 0;
+  } else {
+    return length - 1;
+  }
+}
+
+function interpolateReflect(
+  column: number,
+  row: number,
+  channel: number,
+  image: Image,
+): number {
+  return image.getValue(
+    interpolateReflectPoint(column, image.width),
+    interpolateReflectPoint(row, image.height),
+    channel,
+  );
+}
+
+/**
+ * Interpolate by reflecting the border.
+ * @param point - The point to interpolate.
+ * @param length - The length of the image.
+ * @returns The interpolated point.
+ */
+export function interpolateReflectPoint(point: number, length: number): number {
+  if (point >= 0 && point < length) {
+    return point;
+  }
+  checkRange(point, length);
+  if (point < 0) {
+    return -1 - point;
+  } else {
+    return length + length - 1 - point;
+  }
+}
+
+function interpolateWrap(
+  column: number,
+  row: number,
+  channel: number,
+  image: Image,
+): number {
+  return image.getValue(
+    interpolateWrapPoint(column, image.width),
+    interpolateWrapPoint(row, image.height),
+    channel,
+  );
+}
+
+/**
+ * Interpolate by wrapping the border.
+ * @param point - The point to interpolate.
+ * @param length - The length of the image.
+ * @returns The interpolated point.
+ */
+export function interpolateWrapPoint(point: number, length: number): number {
+  if (point >= 0 && point < length) {
+    return point;
+  }
+  checkRange(point, length);
+  if (point < 0) {
+    return length + point;
+  } else {
+    return point - length;
+  }
+}
+
+function interpolateReflect101(
+  column: number,
+  row: number,
+  channel: number,
+  image: Image,
+): number {
+  return image.getValue(
+    interpolateReflect101Point(column, image.width),
+    interpolateReflect101Point(row, image.height),
+    channel,
+  );
+}
+
+/**
+ * Interpolate by reflecting the border.
+ * @param point - The point to interpolate.
+ * @param length - The length of the image.
+ * @returns The interpolated point.
+ */
+export function interpolateReflect101Point(
+  point: number,
+  length: number,
+): number {
+  if (point >= 0 && point < length) {
+    return point;
+  }
+  checkRange(point, length);
+  if (point < 0) {
+    return 0 - point;
   } else {
-    throw new RangeError(
-      'interpolateBorder only supports borders smaller than the original image'
-    );
+    return length + length - 2 - point;
   }
 }

package/src/utils/interpolatePixel.ts

@@ -1,45 +1,180 @@
-import { Image } from '../Image';
-import { BorderType, InterpolationType } from '../types';
+import { match } from 'ts-pattern';
 
-import { interpolateBorder } from './interpolateBorder';
+import type { Image } from '../Image.js';
+
+import { round } from './round.js';
+import type {
+  BorderInterpolationFunction,
+  ClampFunction,
+} from './utils.types.js';
+
+export const InterpolationType = {
+  NEAREST: 'nearest',
+  BILINEAR: 'bilinear',
+  BICUBIC: 'bicubic',
+} as const;
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type InterpolationType =
+  (typeof InterpolationType)[keyof typeof InterpolationType];
 
 type InterpolationFunction = (
   image: Image,
-  x: number,
-  y: number,
+  column: number,
+  row: number,
   channel: number,
-  borderType: BorderType,
-  borderValue: number
+  intepolateBorder: BorderInterpolationFunction,
+  clamp: ClampFunction,
 ) => number;
 
+/**
+ * Get the interpolation function based on its name.
+ * @param interpolationType - Specified interpolation type.
+ * @returns The interpolation function.
+ */
 export function getInterpolationFunction(
-  interpolationType: InterpolationType
+  interpolationType: InterpolationType,
 ): InterpolationFunction {
-  switch (interpolationType) {
-    case InterpolationType.NEAREST: {
-      return interpolateNearest;
-    }
-    default: {
-      throw new Error(`interpolation ${interpolationType} not implemented`);
-    }
+  return match(interpolationType)
+    .with('nearest', () => interpolateNearest)
+    .with('bilinear', () => interpolateBilinear)
+    .with('bicubic', () => interpolateBicubic)
+    .exhaustive();
+}
+
+/**
+ * Interpolate using nearest neighbor.
+ * @param image - The image to interpolate.
+ * @param column - Column index.
+ * @param row - Row index.
+ * @param channel - Channel index.
+ * @param interpolateBorder - Border interpolation function.
+ * @returns The interpolated value.
+ */
+function interpolateNearest(
+  image: Image,
+  column: number,
+  row: number,
+  channel: number,
+  interpolateBorder: BorderInterpolationFunction,
+): number {
+  column = Math.round(column);
+  row = Math.round(row);
+
+  return interpolateBorder(column, row, channel, image);
+}
+
+/**
+ * Interpolate using bilinear interpolation.
+ * @param image - The image to interpolate.
+ * @param column - Column index.
+ * @param row - Row index.
+ * @param channel - Channel index.
+ * @param interpolateBorder - Border interpolation function.
+ * @returns The interpolated value.
+ */
+function interpolateBilinear(
+  image: Image,
+  column: number,
+  row: number,
+  channel: number,
+  interpolateBorder: BorderInterpolationFunction,
+): number {
+  const px0 = Math.floor(column);
+  const py0 = Math.floor(row);
+
+  const px1 = px0 + 1;
+  const py1 = py0 + 1;
+
+  if (px1 < image.width && py1 < image.height && px0 >= 0 && py0 >= 0) {
+    const vx0y0 = image.getValue(px0, py0, channel);
+    const vx1y0 = image.getValue(px1, py0, channel);
+    const vx0y1 = image.getValue(px0, py1, channel);
+    const vx1y1 = image.getValue(px1, py1, channel);
+
+    const r1 = (px1 - column) * vx0y0 + (column - px0) * vx1y0;
+    const r2 = (px1 - column) * vx0y1 + (column - px0) * vx1y1;
+    return round((py1 - row) * r1 + (row - py0) * r2);
+  } else {
+    const vx0y0 = interpolateBorder(px0, py0, channel, image);
+    const vx1y0 = interpolateBorder(px1, py0, channel, image);
+    const vx0y1 = interpolateBorder(px0, py1, channel, image);
+    const vx1y1 = interpolateBorder(px1, py1, channel, image);
+
+    const r1 = (px1 - column) * vx0y0 + (column - px0) * vx1y0;
+    const r2 = (px1 - column) * vx0y1 + (column - px0) * vx1y1;
+    return round((py1 - row) * r1 + (row - py0) * r2);
   }
 }
 
-export function interpolateNearest(
+/**
+ * Interpolate using bicubic interpolation.
+ * @param image - The image to interpolate.
+ * @param column - Column index.
+ * @param row - Row index.
+ * @param channel - Channel index.
+ * @param interpolateBorder - Border interpolation function.
+ * @param clamp - Clamp function.
+ * @returns The interpolated value.
+ */
+function interpolateBicubic(
   image: Image,
-  x: number,
-  y: number,
+  column: number,
+  row: number,
   channel: number,
-  borderType: BorderType,
-  borderValue: number
+  interpolateBorder: BorderInterpolationFunction,
+  clamp: ClampFunction,
 ): number {
-  x = Math.round(x);
-  y = Math.round(y);
+  const px1 = Math.floor(column);
+  const py1 = Math.floor(row);
 
-  const px = interpolateBorder(x, image.width, borderType);
-  const py = interpolateBorder(y, image.height, borderType);
-  if (px < 0 || py < 0) {
-    return borderValue;
+  if (px1 === column && py1 === row) {
+    return interpolateBorder(px1, py1, channel, image);
   }
-  return image.getValue(py, px, channel);
+
+  const xNorm = column - px1;
+  const yNorm = row - py1;
+
+  const vx0y0 = interpolateBorder(px1 - 1, py1 - 1, channel, image);
+  const vx1y0 = interpolateBorder(px1, py1 - 1, channel, image);
+  const vx2y0 = interpolateBorder(px1 + 1, py1 - 1, channel, image);
+  const vx3y0 = interpolateBorder(px1 + 2, py1 - 1, channel, image);
+  const v0 = cubic(vx0y0, vx1y0, vx2y0, vx3y0, xNorm);
+
+  const vx0y1 = interpolateBorder(px1 - 1, py1, channel, image);
+  const vx1y1 = interpolateBorder(px1, py1, channel, image);
+  const vx2y1 = interpolateBorder(px1 + 1, py1, channel, image);
+  const vx3y1 = interpolateBorder(px1 + 2, py1, channel, image);
+  const v1 = cubic(vx0y1, vx1y1, vx2y1, vx3y1, xNorm);
+
+  const vx0y2 = interpolateBorder(px1 - 1, py1 + 1, channel, image);
+  const vx1y2 = interpolateBorder(px1, py1 + 1, channel, image);
+  const vx2y2 = interpolateBorder(px1 + 1, py1 + 1, channel, image);
+  const vx3y2 = interpolateBorder(px1 + 2, py1 + 1, channel, image);
+  const v2 = cubic(vx0y2, vx1y2, vx2y2, vx3y2, xNorm);
+
+  const vx0y3 = interpolateBorder(px1 - 1, py1 + 2, channel, image);
+  const vx1y3 = interpolateBorder(px1, py1 + 2, channel, image);
+  const vx2y3 = interpolateBorder(px1 + 1, py1 + 2, channel, image);
+  const vx3y3 = interpolateBorder(px1 + 2, py1 + 2, channel, image);
+  const v3 = cubic(vx0y3, vx1y3, vx2y3, vx3y3, xNorm);
+
+  return round(clamp(cubic(v0, v1, v2, v3, yNorm)));
+}
+
+/**
+ * Cubic function.
+ * @param a - First value.
+ * @param b - Second value.
+ * @param c - Third value.
+ * @param d - Fourth value.
+ * @param x - X value.
+ * @returns The interpolated value.
+ */
+function cubic(a: number, b: number, c: number, d: number, x: number): number {
+  return (
+    b +
+    0.5 *
+      x *
+      (c - a + x * (2 * a - 5 * b + 4 * c - d + x * (3 * (b - c) + d - a)))
+  );
 }

package/src/utils/round.ts

@@ -1,11 +1,16 @@
-const { isInteger } = Number;
-
+/**
+ * Round a pixel value.
+ * @param value - Value of the pixel.
+ * @returns The rounded value.
+ */
 export function round(value: number): number {
-  if (isInteger(value)) {
-    return value;
+  const integer = Math.trunc(value);
+  const decimal = value - integer;
+  if (decimal < 0.5) {
+    return integer;
+  } else if (decimal > 0.5) {
+    return integer + 1;
+  } else {
+    return integer % 2 === 0 ? integer : integer + 1;
   }
-  if (value % 0.5 !== 0) {
-    return Math.round(value);
-  }
-  return Math.floor(value) % 2 === 0 ? Math.floor(value) : Math.ceil(value);
 }

package/src/utils/sampleBackgroundPoints.ts

@@ -0,0 +1,84 @@
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import type { Point } from '../geometry/index.js';
+
+interface SampleBackgroundPointsOptions {
+  /**
+   * Mask to sample points from. If mask is undefined, all the points
+   * of the grid are taken as background.
+   */
+  mask?: Mask;
+  /**
+   * Number of rows in the grid.
+   * @default `10`
+   */
+  gridHeight?: number;
+  /**
+   * Number of columns in the grid.
+   * @default `10`
+   */
+  gridWidth?: number;
+  /**
+   * The kind of background to sample.
+   * @default `'black'`
+   */
+  kind?: 'black' | 'white';
+}
+/**
+ * Applies the grid that samples points that belong to background.
+ * @param image - Image to sample points from.
+ * @param options - SampleBackgroundPointsOptions.
+ * @returns Array of points.
+ */
+export function sampleBackgroundPoints(
+  image: Image,
+  options: SampleBackgroundPointsOptions = {},
+) {
+  const { mask, kind = 'black', gridHeight = 10, gridWidth = 10 } = options;
+  const background: Point[] = [];
+  const verticalSpread = Math.floor(image.height / gridHeight);
+  const horizontalSpread = Math.floor(image.width / gridWidth);
+  if (verticalSpread <= 0) {
+    throw new RangeError(
+      `The grid has bigger height than the image. Grid's height:${gridHeight}`,
+    );
+  }
+  if (horizontalSpread <= 0) {
+    throw new RangeError(
+      `The grid has bigger width than the image. Grid's width: ${gridWidth}`,
+    );
+  }
+  if (mask) {
+    const backgroundValue = kind === 'black' ? 0 : 1;
+    for (
+      let row = Math.floor(verticalSpread / 2);
+      row < image.height - Math.floor(verticalSpread / 2);
+      row += verticalSpread
+    ) {
+      for (
+        let column = Math.floor(horizontalSpread / 2);
+        column < image.width - Math.floor(horizontalSpread / 2);
+        column += horizontalSpread
+      ) {
+        if (mask.getBit(column, row) === backgroundValue) {
+          background.push({ column, row });
+        }
+      }
+    }
+  } else {
+    for (
+      let row = Math.floor(verticalSpread / 2);
+      row < image.height - Math.floor(verticalSpread / 2);
+      row += verticalSpread
+    ) {
+      for (
+        let column = Math.floor(horizontalSpread / 2);
+        column < image.width - Math.floor(horizontalSpread / 2);
+        column += horizontalSpread
+      ) {
+        background.push({ column, row });
+      }
+    }
+  }
+  return background;
+}

package/src/utils/setBlendedPixel.ts

@@ -0,0 +1,54 @@
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+
+import { getDefaultColor } from './getDefaultColor.js';
+import { assert } from './validators/assert.js';
+
+/**
+ * Blend the given pixel with the pixel at the specified location in the image.
+ * @param image - The image with which to blend.
+ * @param column - Column of the target pixel.
+ * @param row - Row of the target pixel.
+ * @param color - Color with which to blend the image pixel. @default `'Opaque black'`.
+ */
+
+export function setBlendedPixel(
+  image: Image | Mask,
+  column: number,
+  row: number,
+  color?: number[],
+) {
+  color = color ?? getDefaultColor(image);
+
+  if (!image.alpha) {
+    image.setPixel(column, row, color);
+  } else {
+    assert(image instanceof Image);
+
+    const sourceAlpha = color.at(-1) as number;
+
+    if (sourceAlpha === image.maxValue) {
+      image.setPixel(column, row, color);
+      return;
+    }
+
+    const targetAlpha = image.getValue(column, row, image.channels - 1);
+
+    const newAlpha =
+      sourceAlpha + targetAlpha * (1 - sourceAlpha / image.maxValue);
+
+    image.setValue(column, row, image.channels - 1, newAlpha);
+
+    for (let component = 0; component < image.components; component++) {
+      const sourceComponent = color[component];
+      const targetComponent = image.getValue(column, row, component);
+
+      const newComponent =
+        (sourceComponent * sourceAlpha +
+          targetComponent * targetAlpha * (1 - sourceAlpha / image.maxValue)) /
+        newAlpha;
+
+      image.setValue(column, row, component, newComponent);
+    }
+  }
+}

package/src/utils/setBlendedVisiblePixel.ts

@@ -0,0 +1,22 @@
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+
+import { setBlendedPixel } from './setBlendedPixel.js';
+
+/**
+ * Blend the given pixel with the pixel at the specified location in the image if the pixel is in image's bounds.
+ * @param image - The image with which to blend.
+ * @param column - Column of the target pixel.
+ * @param row - Row of the target pixel.
+ * @param color - Color with which to blend the image pixel. @default `'Opaque black'`.
+ */
+export function setBlendedVisiblePixel(
+  image: Image | Mask,
+  column: number,
+  row: number,
+  color?: number[],
+) {
+  if (column >= 0 && column < image.width && row >= 0 && row < image.height) {
+    setBlendedPixel(image, column, row, color);
+  }
+}

package/src/utils/surroundingPixels.ts

@@ -0,0 +1,14 @@
+/**
+ * Coordinates of the surrounding pixels relative to the current pixel.
+ * First pixel is the one on the right, then they are in clockwise order.
+ */
+export const surroundingPixels = [
+  { row: 0, column: 1 },
+  { row: 1, column: 1 },
+  { row: 1, column: 0 },
+  { row: 1, column: -1 },
+  { row: 0, column: -1 },
+  { row: -1, column: -1 },
+  { row: -1, column: 0 },
+  { row: -1, column: 1 },
+];

package/src/utils/utils.types.ts

@@ -0,0 +1,32 @@
+import type { Image } from '../Image.js';
+
+export type ClampFunction = (value: number) => number;
+
+export interface GetGaussianPointsOptions {
+  /**
+   * Number of points to generate.
+   * @default `1024`
+   */
+  nbPoints?: number;
+  /**
+   * Seed of the gaussian distribution for the x coordinates.
+   * @default `0`
+   */
+  xSeed?: number;
+  /**
+   * Seed of the gaussian distribution for the y coordinates.
+   * @default `1`
+   */
+  ySeed?: number;
+  /**
+   * The standard deviation for the gaussian distribution.
+   */
+  sigma?: number;
+}
+
+export type BorderInterpolationFunction = (
+  column: number,
+  row: number,
+  channel: number,
+  image: Image,
+) => number;