image-js 1.0.0-alpha.3 → 1.0.0

package/src/utils/interpolateBorder.ts

@@ -1,62 +1,71 @@
-import { BorderType } from '../types';
-import { Image } from '../Image';
+import { match } from 'ts-pattern';
 
-export type BorderInterpolationFunction = (
-  x: number,
-  y: number,
-  channel: number,
-  image: Image
-) => number;
+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
+  value: number,
 ): BorderInterpolationFunction {
-  switch (type) {
-    case BorderType.CONSTANT:
-      return getInterpolateConstant(value);
-    case BorderType.REPLICATE:
-      return interpolateReplicate;
-    case BorderType.REFLECT:
-      return interpolateReflect;
-    case BorderType.REFLECT_101:
-      return interpolateReflect101;
-    case BorderType.WRAP:
-      return interpolateWrap;
-    default:
-      throw new Error(
-        `interpolateBorder cannot be used with border type ${type}`
-      );
-  }
+  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(
-      'interpolateBorder only supports borders smaller than the original image'
-    );
+    throw new RangeError('border must be smaller than the original image');
   }
 }
 
 function getInterpolateConstant(value: number): BorderInterpolationFunction {
   return function interpolateConstant(
-    x: number,
-    y: number,
+    column: number,
+    row: number,
     channel: number,
-    image: Image
+    image: Image,
   ): number {
-    const newX = interpolateConstantPoint(x, image.width);
-    const newY = interpolateConstantPoint(y, image.height);
-    if (newX === -1 || newY === -1) {
+    const newColumn = interpolateConstantPoint(column, image.width);
+    const newRow = interpolateConstantPoint(row, image.height);
+    if (newColumn === -1 || newRow === -1) {
       return value;
     }
-    return image.getValue(newY, newX, channel);
+    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
+  length: number,
 ): number {
   if (point >= 0 && point < length) {
     return point;
@@ -65,21 +74,27 @@ export function interpolateConstantPoint(
 }
 
 function interpolateReplicate(
-  x: number,
-  y: number,
+  column: number,
+  row: number,
   channel: number,
-  image: Image
+  image: Image,
 ): number {
   return image.getValue(
-    interpolateReplicatePoint(y, image.height),
-    interpolateReplicatePoint(x, image.width),
-    channel
+    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
+  length: number,
 ): number {
   if (point >= 0 && point < length) {
     return point;
@@ -93,18 +108,24 @@ export function interpolateReplicatePoint(
 }
 
 function interpolateReflect(
-  x: number,
-  y: number,
+  column: number,
+  row: number,
   channel: number,
-  image: Image
+  image: Image,
 ): number {
   return image.getValue(
-    interpolateReflectPoint(y, image.height),
-    interpolateReflectPoint(x, image.width),
-    channel
+    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;
@@ -118,18 +139,24 @@ export function interpolateReflectPoint(point: number, length: number): number {
 }
 
 function interpolateWrap(
-  x: number,
-  y: number,
+  column: number,
+  row: number,
   channel: number,
-  image: Image
+  image: Image,
 ): number {
   return image.getValue(
-    interpolateWrapPoint(y, image.height),
-    interpolateWrapPoint(x, image.width),
-    channel
+    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;
@@ -143,21 +170,27 @@ export function interpolateWrapPoint(point: number, length: number): number {
 }
 
 function interpolateReflect101(
-  x: number,
-  y: number,
+  column: number,
+  row: number,
   channel: number,
-  image: Image
+  image: Image,
 ): number {
   return image.getValue(
-    interpolateReflect101Point(y, image.height),
-    interpolateReflect101Point(x, image.width),
-    channel
+    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
+  length: number,
 ): number {
   if (point >= 0 && point < length) {
     return point;

package/src/utils/interpolatePixel.ts

@@ -1,95 +1,138 @@
-import { Image } from '../Image';
-import { InterpolationType } from '../types';
+import { match } from 'ts-pattern';
 
-import { BorderInterpolationFunction } from './interpolateBorder';
-import { round } from './round';
-import { ClampFunction } from './clamp';
+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,
   intepolateBorder: BorderInterpolationFunction,
-  clamp: ClampFunction
+  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;
-    }
-    case InterpolationType.BILINEAR: {
-      return interpolateBilinear;
-    }
-    case InterpolationType.BICUBIC: {
-      return interpolateBicubic;
-    }
-    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,
-  x: number,
-  y: number,
+  column: number,
+  row: number,
   channel: number,
-  interpolateBorder: BorderInterpolationFunction
+  interpolateBorder: BorderInterpolationFunction,
 ): number {
-  x = Math.round(x);
-  y = Math.round(y);
+  column = Math.round(column);
+  row = Math.round(row);
 
-  return interpolateBorder(x, y, channel, image);
+  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,
-  x: number,
-  y: number,
+  column: number,
+  row: number,
   channel: number,
-  interpolateBorder: BorderInterpolationFunction
+  interpolateBorder: BorderInterpolationFunction,
 ): number {
-  const px0 = Math.floor(x);
-  const py0 = Math.floor(y);
-
-  if (px0 === x && py0 === y) {
-    return interpolateBorder(px0, py0, channel, image);
-  }
+  const px0 = Math.floor(column);
+  const py0 = Math.floor(row);
 
   const px1 = px0 + 1;
   const py1 = py0 + 1;
 
-  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 - x) * vx0y0 + (x - px0) * vx1y0;
-  const r2 = (px1 - x) * vx0y1 + (x - px0) * vx1y1;
-  return round((py1 - y) * r1 + (y - py0) * r2);
+  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);
+  }
 }
 
+/**
+ * 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,
   interpolateBorder: BorderInterpolationFunction,
-  clamp: ClampFunction
+  clamp: ClampFunction,
 ): number {
-  const px1 = Math.floor(x);
-  const py1 = Math.floor(y);
+  const px1 = Math.floor(column);
+  const py1 = Math.floor(row);
 
-  if (px1 === x && py1 === y) {
+  if (px1 === column && py1 === row) {
     return interpolateBorder(px1, py1, channel, image);
   }
 
-  const xNorm = x - px1;
-  const yNorm = y - py1;
+  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);
@@ -118,13 +161,20 @@ function interpolateBicubic(
   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.0 * a - 5.0 * b + 4.0 * c - d + x * (3.0 * (b - c) + d - a)))
+      (c - a + x * (2 * a - 5 * b + 4 * c - d + x * (3 * (b - c) + d - a)))
   );
 }

package/src/utils/round.ts

@@ -1,6 +1,16 @@
+/**
+ * Round a pixel value.
+ * @param value - Value of the pixel.
+ * @returns The rounded value.
+ */
 export function round(value: number): number {
-  if (value % 0.5 !== 0) {
-    return Math.round(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;
   }
-  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;