image-js 1.0.0-alpha.3 → 1.1.0

package/src/utils/geometry/getCirclePoints.ts

@@ -0,0 +1,123 @@
+import { circle, line } from 'bresenham-zingl';
+
+import { deleteDuplicates } from '../../draw/utils/deleteDuplicates.js';
+import type { Point } from '../../geometry/index.js';
+
+import { sortByColumnRow } from './points.js';
+
+/**
+ * Get the coordinates of the points on a circle. The reference is the center of the circle.
+ * The first point is the right one and they are then sorted clockwise.
+ * @param radius - Radius of the circle.
+ * @returns The coordinates of the points on a circle of given diameter.
+ */
+export function getCirclePoints(radius: number): Point[] {
+  const circlePoints: Point[] = [];
+
+  circle(radius, radius, radius, (column: number, row: number) => {
+    circlePoints.push({ row: row - radius, column: column - radius });
+  });
+
+  const firstQuarter: Point[] = [];
+  const secondQuarter: Point[] = [];
+  const thirdQuarter: Point[] = [];
+  const fourthQuarter: Point[] = [];
+
+  for (let i = 0; i < circlePoints.length; i = i + 4) {
+    firstQuarter.push(circlePoints[i % circlePoints.length]);
+    secondQuarter.push(circlePoints[(i + 1) % circlePoints.length]);
+    thirdQuarter.push(circlePoints[(i + 2) % circlePoints.length]);
+    fourthQuarter.push(circlePoints[(i + 3) % circlePoints.length]);
+  }
+  return firstQuarter.concat(secondQuarter, thirdQuarter, fourthQuarter);
+}
+
+const zeroPoint: Point = { row: 0, column: 0 };
+
+/**
+ * Get the coordinates of the points in a circle of given radius. The points are sorted by column then row.
+ * @param radius - Radius of the circle.
+ * @param center - Center of the circle.
+ * @returns The coordinates of the points in a circle of given radius.
+ */
+export function getFilledCirclePoints(
+  radius: number,
+  center: Point = zeroPoint,
+): Point[] {
+  const circlePoints: Point[] = [];
+
+  if (radius === 0) {
+    return [center];
+  }
+  if (radius === 1) {
+    circlePoints.push(center);
+  }
+  circle(center.column, center.row, radius, (column: number, row: number) => {
+    circlePoints.push({ row, column });
+
+    if (column - 1 > center.column) {
+      circlePoints.push(
+        ...getLinePoints(
+          { row, column: column - 1 },
+          { row, column: center.column },
+        ),
+      );
+    } else if (column + 1 < center.column) {
+      circlePoints.push(
+        ...getLinePoints(
+          { row, column: column + 1 },
+          { row, column: center.column },
+        ),
+      );
+    }
+  });
+
+  const sorted = sortByColumnRow(circlePoints);
+
+  return deleteDuplicates(sorted);
+}
+
+/**
+ * Get the coordinates of the points on a line.
+ * @param from - Starting point.
+ * @param to - End point.
+ * @returns The coordinates of the points on the line.
+ */
+export function getLinePoints(from: Point, to: Point): Point[] {
+  const linePoints: Point[] = [];
+  line(
+    from.column,
+    from.row,
+    to.column,
+    to.row,
+    (column: number, row: number) => {
+      linePoints.push({
+        row,
+        column,
+      });
+    },
+  );
+
+  return linePoints;
+}
+
+/**
+ * Get the coordinates of the points that are on right, bottom, left and top at a given radius. The reference is the origin of the circle.
+ * First point is the most on the right, then points are in clockwise order.
+ * @param radius - Radius of the circle.
+ * @returns The coordinates of the compass points.
+ */
+export function getCompassPoints(radius: number): Point[] {
+  const circlePoints: Point[] = [];
+
+  circle(radius, radius, radius, (column: number, row: number) => {
+    circlePoints.push({ row: row - radius, column: column - radius });
+  });
+
+  return [
+    { row: 0, column: radius },
+    { row: radius, column: 0 },
+    { row: 0, column: -radius },
+    { row: -radius, column: 0 },
+  ];
+}

package/src/utils/geometry/index.ts

@@ -0,0 +1 @@
+export * from './removeClosePoints.js';

package/src/utils/geometry/lines.ts

@@ -0,0 +1,26 @@
+import type { Point } from './points.js';
+
+export interface Line {
+  /**
+   * Line slope.
+   */
+  a: number;
+  /**
+   * Line y-intercept.
+   */
+  b: number;
+  /**
+   * Line is vertical.
+   */
+  vertical: boolean;
+}
+
+/**
+ * Compute the length of a segment defined by two points.
+ * @param p1 - First point.
+ * @param p2 - Second point.
+ * @returns Length of the segment.
+ */
+export function getLineLength(p1: Point, p2: Point): number {
+  return Math.hypot(p1.column - p2.column, p1.row - p2.row);
+}

package/src/utils/geometry/points.ts

@@ -0,0 +1,104 @@
+/**
+ * Coordinates of a point in an image with the top-left corner being the reference point. The point is a [column, row] array.
+ */
+export type ArrayPoint = [column: number, row: number];
+
+/**
+ * Coordinates of a point in an image with the top-left corner being the reference point.
+ */
+export interface Point {
+  /**
+   * Point row.
+   *
+   */
+  row: number;
+  /**
+   * Point column.
+   *
+   */
+  column: number;
+}
+
+/**
+ * Calculates a new point that is the difference p1 - p2.
+ * @param p1 - First point.
+ * @param p2 - Second Point.
+ * @returns Difference between the two points.
+ */
+export function difference(p1: Point, p2: Point): Point {
+  return { column: p1.column - p2.column, row: p1.row - p2.row };
+}
+
+/**
+ * Calculates a new point that is the sum p1 + p2.
+ * @param p1 - First point.
+ * @param p2 - Second Point.
+ * @returns Sum of the two points.
+ */
+export function sum(p1: Point, p2: Point): Point {
+  return { column: p1.column + p2.column, row: p1.row + p2.row };
+}
+
+/**
+ * Normalize a point (more precisely the vector from the origin to the point).
+ * @param point - Point to normalize.
+ * @returns - Normalized point.
+ */
+export function normalize(point: Point): Point {
+  const length = Math.hypot(point.column, point.row);
+  return { column: point.column / length, row: point.row / length };
+}
+
+/**
+ * Rotate an array of points by an angle in radians.
+ * The rotation is clockwise and the reference is (0,0).
+ * @param radians - Angle in radians.
+ * @param points - Source points.
+ * @returns The points after rotation.
+ */
+export function rotate(radians: number, points: readonly Point[]): Point[] {
+  const results: Point[] = [];
+  const cos = Math.cos(radians);
+  const sin = Math.sin(radians);
+  for (const point of points) {
+    results.push({
+      column: cos * point.column - sin * point.row,
+      row: sin * point.column + cos * point.row,
+    });
+  }
+  return results;
+}
+
+/**
+ * Dot product of 2 points assuming vectors starting from (0,0).
+ * @param p1 - First point.
+ * @param p2 - Second point.
+ * @returns Dot product between the two vectors.
+ */
+export function dot(p1: Point, p2: Point) {
+  return p1.column * p2.column + p1.row * p2.row;
+}
+
+/**
+ * Round the coordinates of the point.
+ * @param point - The point.
+ * @returns Rounded coordinates of the point.
+ */
+export function round(point: Point): Point {
+  return { column: Math.round(point.column), row: Math.round(point.row) };
+}
+
+/**
+ * Sort an array of points by column then row.
+ * @param points - Array of points to sort.
+ * @returns Sorted points.
+ */
+export function sortByColumnRow(points: Point[]): Point[] {
+  const sortedPoints = points.slice();
+  sortedPoints.sort((point1, point2) => {
+    if (point1.column < point2.column) return -1;
+    if (point1.column > point2.column) return 1;
+    return point1.row - point2.row;
+  });
+  return sortedPoints;
+}

package/src/utils/geometry/polygons.ts

@@ -0,0 +1,32 @@
+import { getLineLength } from './lines.js';
+import type { Point } from './points.js';
+
+/**
+ * Compute the perimeter of a polygon.
+ * @param points - Array of polygon vertices.
+ * @returns The perimeter.
+ */
+export function getPolygonPerimeter(points: Point[]): number {
+  let perimeter = 0;
+  for (let i = 0; i < points.length; i++) {
+    perimeter += getLineLength(points[(i + 1) % points.length], points[i]);
+  }
+  return perimeter;
+}
+
+/**
+ * Compute the area of a polygon.
+ * Based on the algorithm described on
+ * @see {@link https://web.archive.org/web/20100405070507/http://valis.cs.uiuc.edu/~sariel/research/CG/compgeom/msg00831.html}
+ * @param points - Array of polygon vertices.
+ * @returns The area.
+ */
+export function getPolygonArea(points: Point[]): number {
+  let area = 0;
+  for (let current = 0; current < points.length; current++) {
+    const next = (current + 1) % points.length;
+    area += points[current].column * points[next].row;
+    area -= points[current].row * points[next].column;
+  }
+  return Math.abs(area / 2);
+}

package/src/utils/geometry/removeClosePoints.ts

@@ -0,0 +1,83 @@
+import type { Image } from '../../Image.js';
+
+import type { Point } from './points.js';
+
+export interface RemoveClosePointsOptions {
+  /**
+   * The minimum distance between points in the returned filtered points. If the distance is less or equal to 0, no point is removed.
+   * @default `0`
+   */
+  distance: number;
+  /**
+   * Shows what kind of extremum is being computed.
+   * @default `'maximum'`
+   */
+  kind: 'minimum' | 'maximum';
+  /**
+   * Channel number of an image where the extremum should be found.
+   * @default `0`
+   */
+  channel?: number;
+}
+/**
+ * Finds extreme values of an image which are not stacked together.
+ * @param points - Array of points that should be combined to improve.
+ * @param image - Image which extrema are calculated from.
+ * @param options - FilterPointsOptions
+ * @returns Array of Points.
+ */
+export function removeClosePoints(
+  points: Point[],
+  image: Image,
+  options: RemoveClosePointsOptions,
+) {
+  const distance = options?.distance || 0;
+  const kind = options?.kind || 'maximum';
+
+  if (options?.channel === undefined && image.channels > 1) {
+    throw new Error(
+      'image channel must be specified or image must have only one channel',
+    );
+  }
+  const channel = options?.channel || 0;
+  const isMax = kind === 'maximum';
+
+  const sortedPoints = points.slice();
+  sortedPoints.sort(getSort(image, channel, isMax));
+
+  if (distance > 0) {
+    for (let i = 0; i < sortedPoints.length; i++) {
+      for (let j = i + 1; j < sortedPoints.length; j++) {
+        if (
+          Math.hypot(
+            sortedPoints[i].column - sortedPoints[j].column,
+            sortedPoints[i].row - sortedPoints[j].row,
+          ) < distance
+        ) {
+          sortedPoints.splice(j, 1);
+          j--;
+        }
+      }
+    }
+  }
+
+  return sortedPoints;
+}
+
+function getSort(image: Image, channel: number, isDescending: boolean) {
+  if (isDescending) {
+    return function sortDescending(a: Point, b: Point) {
+      return (
+        image.getValue(b.column, b.row, channel) -
+        image.getValue(a.column, a.row, channel)
+      );
+    };
+  } else {
+    return function sortAscending(a: Point, b: Point) {
+      return (
+        image.getValue(a.column, a.row, channel) -
+        image.getValue(b.column, b.row, channel)
+      );
+    };
+  }
+}

package/src/utils/getDefaultColor.ts

@@ -0,0 +1,20 @@
+import { match } from 'ts-pattern';
+
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+
+/**
+ * Get the default color for a given color model.
+ * The color is black for images and 1 for masks.
+ * @param image - The used image.
+ * @returns Default color.
+ */
+export function getDefaultColor(image: Image | Mask): number[] {
+  return match(image.colorModel)
+    .with('GREY', () => [0])
+    .with('GREYA', () => [0, image.maxValue])
+    .with('RGB', () => [0, 0, 0])
+    .with('RGBA', () => [0, 0, 0, image.maxValue])
+    .with('BINARY', () => [1])
+    .exhaustive();
+}

package/src/utils/getIndex.ts

@@ -0,0 +1,26 @@
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+
+export function getIndex(
+  column: number,
+  row: number,
+  image: Image,
+  channel: number,
+): number;
+export function getIndex(column: number, row: number, image: Mask): number;
+/**
+ * Compute the current pixel index based on the value coordinates.
+ * @param column - Column of the value.
+ * @param row - Row of the value.
+ * @param image - The image that is being processed.
+ * @param channel - Value channel.
+ * @returns The value index.
+ */
+export function getIndex(
+  column: number,
+  row: number,
+  image: Image | Mask,
+  channel = 0,
+): number {
+  return (row * image.width + column) * image.channels + channel;
+}

package/src/utils/getMinMax.ts

@@ -0,0 +1,27 @@
+import type { Image } from '../Image.js';
+
+/**
+ * Find the min and max values of each channel of the image.
+ * @param image - Image to process.
+ * @returns An object with arrays of the min and max values.
+ */
+export function getMinMax(image: Image): { min: number[]; max: number[] } {
+  const min = new Array(image.channels).fill(image.maxValue);
+  const max = new Array(image.channels).fill(0);
+
+  for (let row = 0; row < image.height; row++) {
+    for (let column = 0; column < image.width; column++) {
+      for (let channel = 0; channel < image.channels; channel++) {
+        const currentValue = image.getValue(column, row, channel);
+        if (currentValue < min[channel]) {
+          min[channel] = currentValue;
+        }
+        if (currentValue > max[channel]) {
+          max[channel] = currentValue;
+        }
+      }
+    }
+  }
+
+  return { min, max };
+}

package/src/utils/getOutputImage.ts

@@ -1,61 +1,178 @@
-import { Image, INewImageOptions } from '../Image';
+import type { CreateFromOptions } from '../Image.js';
+import { Image } from '../Image.js';
+import { Mask } from '../Mask.js';
 
-export interface IOutOptions {
+import { copyData } from './copyData.js';
+
+export interface OutOptions {
   /**
    * Image to use as the output.
    * The image must have compatible properties or the method will throw.
    */
-  out?: Image;
+  out?: Image | Mask;
 }
 
-interface IOutInternalOptions {
+type NewImageParameters = Omit<CreateFromOptions, 'data'>;
+
+interface OutInternalOptions {
   /**
    * Parameters that will be combined with the ones from
-   * thisImage`.
+   * `thisImage`.
+   */
+  newParameters?: NewImageParameters;
+  /**
+   * Specify if the values of the original image should be cloned.
    */
-  newParameters?: INewImageOptions;
+  clone?: boolean;
 }
 
 /**
  * Use this function to support getting the output image of an algorithm from
  * user-supplied options.
- * @private
  * @param thisImage - Current image on which the algorithm is applied.
  * @param options - Options object received by the algorithm.
  * @param internalOptions - Some additional private options.
+ * @returns The output image.
  */
 export function getOutputImage(
   thisImage: Image,
-  options: IOutOptions = {},
-  internalOptions: IOutInternalOptions = {}
+  options: OutOptions = {},
+  internalOptions: OutInternalOptions = {},
 ): Image {
   const { out } = options;
-  const { newParameters } = internalOptions;
+  const { newParameters, clone } = internalOptions;
+  if (out === undefined) {
+    if (clone) {
+      return thisImage.clone();
+    } else {
+      return Image.createFrom(thisImage, newParameters);
+    }
+  } else {
+    if (!(out instanceof Image)) {
+      throw new TypeError('out must be an Image');
+    }
+    const requirements: NewImageParameters = {
+      width: thisImage.width,
+      height: thisImage.height,
+      bitDepth: thisImage.bitDepth,
+      colorModel: thisImage.colorModel,
+      ...newParameters,
+    };
+    checkRequirements(requirements, out);
+    if (clone && thisImage !== out) {
+      copyData(thisImage, out);
+    }
+    return out;
+  }
+}
+
+/**
+ * Use this function to support getting the output image of an algorithm from
+ * user-supplied options when the input is a mask.
+ * @param mask - Current mask on which the algorithm is applied.
+ * @param options - Options object received by the algorithm.
+ * @returns The output image.
+ */
+export function maskToOutputImage(mask: Mask, options: OutOptions = {}): Image {
+  const { out } = options;
+
   if (out === undefined) {
-    return Image.createFrom(thisImage, newParameters);
+    return Image.createFrom(mask, {
+      colorModel: 'GREY',
+    });
   } else {
     if (!(out instanceof Image)) {
-      throw new TypeError('out must be an Image object');
-    }
-    const requirements: INewImageOptions = Object.assign(
-      {
-        width: thisImage.width,
-        height: thisImage.height,
-        depth: thisImage.depth,
-        kind: thisImage.kind
-      },
-      newParameters
-    );
-    type keys = keyof typeof requirements;
-    for (const property in requirements) {
-      const prop = property as keys;
-      if (out[prop] !== requirements[prop]) {
-        throw new RangeError(
-          `cannot use out. Its ${property} property must be ${
-            requirements[prop]
-          }. Found ${out[prop]}`
-        );
-      }
+      throw new TypeError('out must be an Image');
+    }
+    const requirements: NewImageParameters = {
+      width: mask.width,
+      height: mask.height,
+      bitDepth: 8,
+      colorModel: 'GREY',
+    };
+    checkRequirements(requirements, out);
+    return out;
+  }
+}
+
+/**
+ * Use this function to support getting the output mask of an algorithm from
+ * user-supplied options when the input is an image.
+ * @param image - Current image on which the algorithm is applied.
+ * @param options - Options object received by the algorithm.
+ * @returns The output mask.
+ */
+export function imageToOutputMask(
+  image: Image,
+  options: OutOptions = {},
+): Mask {
+  const { out } = options;
+  if (out === undefined) {
+    return Mask.createFrom(image);
+  } else {
+    if (!(out instanceof Mask)) {
+      throw new TypeError('out must be a Mask');
+    }
+    const requirements: NewImageParameters = {
+      width: image.width,
+      height: image.height,
+      bitDepth: 1,
+      colorModel: 'BINARY',
+    };
+    checkRequirements(requirements, out);
+    return out;
+  }
+}
+
+function checkRequirements<ReqType extends object>(
+  requirements: ReqType,
+  out: ReqType,
+): void {
+  type Keys = keyof ReqType;
+  for (const property in requirements) {
+    const prop = property as Keys;
+    if (out[prop] !== requirements[prop]) {
+      throw new RangeError(
+        `cannot use out image. Its ${property} property must be ${requirements[prop]}. Received ${out[prop]}`,
+      );
+    }
+  }
+}
+
+/**
+ * Use this function to support getting the output mask of an algorithm from
+ * user-supplied options when the input is an mask.
+ * @param mask - Current mask on which the algorithm is applied.
+ * @param options - Options object received by the algorithm.
+ * @param internalOptions - Additional private options.
+ * @returns The output mask.
+ */
+export function maskToOutputMask(
+  mask: Mask,
+  options: OutOptions = {},
+  internalOptions: OutInternalOptions = {},
+): Mask {
+  const { out } = options;
+  const { newParameters, clone } = internalOptions;
+  if (out === undefined) {
+    if (clone) {
+      return mask.clone();
+    } else {
+      return Mask.createFrom(mask, newParameters);
+    }
+  } else {
+    if (!(out instanceof Mask)) {
+      throw new TypeError('out must be a Mask');
+    }
+    const requirements: NewImageParameters = {
+      width: mask.width,
+      height: mask.height,
+      bitDepth: 1,
+      colorModel: 'BINARY',
+    };
+    checkRequirements(requirements, out);
+    if (clone && mask !== out) {
+      copyData(mask, out);
     }
     return out;
   }

package/src/utils/getRadius.ts

@@ -0,0 +1,11 @@
+/**
+ * Compute the radius of the circle of given size.
+ * @param size - Size of the circle.
+ * @returns The radius.
+ */
+export function getRadius(size: number): number {
+  if (size % 2 !== 1 || size < 0) {
+    throw new RangeError('size must be positive and odd');
+  }
+  return (size - 1) / 2;
+}