image-js 1.0.0-alpha.2 → 1.0.0

package/src/morphology/multipleFloodFill.ts

@@ -0,0 +1,135 @@
+import type { BitValue } from '../Mask.js';
+import { Mask } from '../Mask.js';
+import { maskToOutputMask } from '../utils/getOutputImage.js';
+import { assert } from '../utils/validators/assert.js';
+
+export interface MultipleFloodFillOptions {
+  /**
+   * Points from which to start the flood fill.
+   * @default `[0]`
+   */
+  startPixels?: Iterable<number>;
+  /**
+   * Initial value of the start pixel.
+   * @default `0`
+   */
+  startPixelValue?: BitValue;
+  /**
+   *  What value should the relevant pixels be set to?
+   * @default `1`
+   */
+  newPixelValue?: BitValue;
+  /**
+   * Consider pixels connected by corners?
+   * @default `false`
+   */
+  allowCorners?: boolean;
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Mask;
+}
+
+const MAX_ARRAY = 65536; // 65536 should be enough for most of the cases
+const toProcess = new Uint32Array(MAX_ARRAY);
+
+/**
+ * Set the pixels connected to the border of the mask to zero. You can chose to allow corner connection of not with the `allowCorners` option.
+ * @param mask - The mask to process.
+ * @param options - Clear border options.
+ * @returns The image with cleared borders.
+ */
+export function multipleFloodFill(
+  mask: Mask,
+  options: MultipleFloodFillOptions = {},
+): Mask {
+  const {
+    startPixels = [0],
+    startPixelValue = 0,
+    newPixelValue = 1,
+    allowCorners = false,
+  } = options;
+
+  const newMask = maskToOutputMask(mask, options, { clone: true });
+
+  const alreadyConsidered = Mask.createFrom(mask);
+
+  let from = 0;
+  let to = 0;
+
+  // const startPixelValue = mask.getBitByIndex(startPixels[0]);
+
+  // find relevant border pixels
+  for (const pixelIndex of startPixels) {
+    if (newMask.getBitByIndex(pixelIndex) === startPixelValue) {
+      toProcess[to++ % MAX_ARRAY] = pixelIndex;
+      alreadyConsidered.setBitByIndex(pixelIndex, 1);
+      newMask.setBitByIndex(pixelIndex, newPixelValue);
+    }
+  }
+
+  // find pixels connected to the border pixels
+  while (from < to) {
+    assert(to - from <= MAX_ARRAY);
+    const currentPixel = toProcess[from++ % MAX_ARRAY];
+    newMask.setBitByIndex(currentPixel, newPixelValue);
+
+    // check if pixel is on a border
+    const topBorder = currentPixel < mask.width;
+    const leftBorder = currentPixel % mask.width === 0;
+    const rightBorder = currentPixel % mask.width === mask.width - 1;
+    const bottomBorder = currentPixel > mask.size - mask.width;
+
+    // check neighbors
+
+    if (!bottomBorder) {
+      const bottom = currentPixel + mask.width;
+
+      addToProcess(bottom);
+    }
+    if (!leftBorder) {
+      const left = currentPixel - 1;
+      addToProcess(left);
+    }
+    if (!topBorder) {
+      const top = currentPixel - mask.width;
+      addToProcess(top);
+    }
+    if (!rightBorder) {
+      const right = currentPixel + 1;
+      addToProcess(right);
+    }
+    if (allowCorners) {
+      if (!topBorder) {
+        if (!leftBorder) {
+          const topLeft = currentPixel - mask.width - 1;
+          addToProcess(topLeft);
+        }
+        if (!rightBorder) {
+          const topRight = currentPixel - mask.width + 1;
+          addToProcess(topRight);
+        }
+      }
+      if (!bottomBorder) {
+        if (!leftBorder) {
+          const bottomLeft = currentPixel + mask.width - 1;
+          addToProcess(bottomLeft);
+        }
+        if (!rightBorder) {
+          const bottomRight = currentPixel + mask.width + 1;
+          addToProcess(bottomRight);
+        }
+      }
+    }
+  }
+
+  function addToProcess(pixel: number): void {
+    if (alreadyConsidered.getBitByIndex(pixel)) return;
+    if (newMask.getBitByIndex(pixel) === startPixelValue) {
+      toProcess[to++ % MAX_ARRAY] = pixel;
+      alreadyConsidered.setBitByIndex(pixel, 1);
+    }
+  }
+
+  return newMask;
+}

package/src/morphology/open.ts

@@ -0,0 +1,62 @@
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import { checkKernel } from '../utils/validators/checkKernel.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface OpenOptions {
+  /**
+   * 3x3 matrix. The kernel can only have ones and zeros.
+   * Accessing a value: kernel[row][column].
+   * @default `[[1, 1, 1], [1, 1, 1], [1, 1, 1]]`
+   */
+  kernel?: number[][];
+  /**
+   * Number of iterations of the algorithm.
+   * @default `1`
+   */
+  iterations?: number;
+}
+
+export function open(image: Image, options?: OpenOptions): Image;
+export function open(image: Mask, options?: OpenOptions): Mask;
+/**
+ * In mathematical morphology, opening is the dilation of the erosion of a set A by a structuring element B.
+ * Together with closing, the opening serves in computer vision and image processing as a basic workhorse of morphological noise removal.
+ * Opening removes small objects from the foreground (usually taken as the bright pixels) of an image,
+ * placing them in the background, while closing removes small holes in the foreground, changing small islands of background into foreground. (Wikipedia)
+ * @see {@link http://docs.opencv.org/2.4/doc/tutorials/imgproc/opening_closing_hats/opening_closing_hats.html}
+ * @param image - Image to process.
+ * @param options - Open options.
+ * @returns The opened image.
+ */
+export function open(
+  image: Image | Mask,
+  options: OpenOptions = {},
+): Image | Mask {
+  const {
+    kernel = [
+      [1, 1, 1],
+      [1, 1, 1],
+      [1, 1, 1],
+    ],
+    iterations = 1,
+  } = options;
+
+  if (image instanceof Image) {
+    checkProcessable(image, {
+      bitDepth: [1, 8, 16],
+      components: 1,
+      alpha: false,
+    });
+  }
+
+  checkKernel(kernel);
+
+  let newImage = image;
+  for (let i = 0; i < iterations; i++) {
+    newImage = newImage.erode({ kernel });
+    newImage = newImage.dilate({ kernel });
+  }
+
+  return newImage;
+}

package/src/morphology/solidFill.ts

@@ -0,0 +1,29 @@
+import type { Mask } from '../Mask.js';
+import { maskToOutputMask } from '../utils/getOutputImage.js';
+
+export interface SolidFillOptions {
+  /**
+   * Consider pixels connected by corners?
+   * @default `false`
+   */
+  allowCorners?: boolean;
+  /**
+   * Image to which the inverted image has to be put.
+   */
+  out?: Mask;
+}
+
+/**
+ * Fill holes in regions of interest.
+ * @param mask - Mask to process.
+ * @param options - Flood fill options.
+ * @returns The filled mask.
+ */
+export function solidFill(mask: Mask, options: SolidFillOptions = {}): Mask {
+  const { allowCorners = false } = options;
+
+  const newImage = maskToOutputMask(mask, options, { clone: true });
+  const inverted = mask.invert();
+  const cleared = inverted.clearBorder({ allowCorners });
+  return newImage.or(cleared, { out: newImage });
+}

package/src/morphology/topHat.ts

@@ -0,0 +1,62 @@
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import { subtract } from '../compare/index.js';
+import { checkKernel } from '../utils/validators/checkKernel.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface TopHatOptions {
+  /**
+   * 3x3 matrix. The kernel can only have ones and zeros.
+   * Accessing a value: kernel[row][column].
+   * @default `[[1, 1, 1], [1, 1, 1], [1, 1, 1]]`
+   */
+  kernel?: number[][];
+  /**
+   * Number of iterations of the algorithm.
+   * @default `1`
+   */
+  iterations?: number;
+}
+
+export function topHat(image: Image, options?: TopHatOptions): Image;
+export function topHat(image: Mask, options?: TopHatOptions): Mask;
+/**
+ * This function is the white top hat (also called top hat). In mathematical morphology and digital image processing,
+ * top-hat transform is an operation that extracts small elements and details from given images.
+ * The white top-hat transform is defined as the difference between the input image and its opening by some structuring element.
+ * Top-hat transforms are used for various image processing tasks, such as feature extraction, background equalization, image enhancement, and others. (Wikipedia)
+ * @see {@link http://docs.opencv.org/2.4/doc/tutorials/imgproc/opening_closing_hats/opening_closing_hats.html}
+ * @param image - Image to process.
+ * @param options - Top hat options.
+ * @returns The top-hatted image.
+ */
+export function topHat(
+  image: Image | Mask,
+  options: TopHatOptions = {},
+): Image | Mask {
+  const {
+    kernel = [
+      [1, 1, 1],
+      [1, 1, 1],
+      [1, 1, 1],
+    ],
+    iterations = 1,
+  } = options;
+
+  if (image instanceof Image) {
+    checkProcessable(image, {
+      bitDepth: [1, 8, 16],
+      components: 1,
+      alpha: false,
+    });
+  }
+
+  checkKernel(kernel);
+
+  let newImage = image;
+  for (let i = 0; i < iterations; i++) {
+    const openImage = newImage.open({ kernel });
+    newImage = subtract(openImage, newImage, { absolute: true });
+  }
+  return newImage;
+}

package/src/operations/convertBitDepth.ts

@@ -0,0 +1,74 @@
+import type { BitDepth, Image } from '../Image.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+
+export interface ConvertBitDepthOptions {
+  /**
+   * Image to which to output.
+   */
+  out?: Image;
+}
+
+/**
+ * Convert the bit depth of an image.
+ * @param image - Image to convert.
+ * @param newBitDepth - Bit depth to convert to.
+ * @param options - Convert bit depth options.
+ * @returns Converted image.
+ */
+export function convertBitDepth(
+  image: Image,
+  newBitDepth: BitDepth,
+  options: ConvertBitDepthOptions = {},
+): Image {
+  if (image.bitDepth === newBitDepth) {
+    return getOutputImage(image, options, { clone: true });
+  }
+
+  if (newBitDepth !== 8 && newBitDepth !== 16) {
+    throw new RangeError(
+      `This image bit depth is not supported: ${newBitDepth}`,
+    );
+  }
+  // Get the output image first - this handles the out option
+  const newImage = getOutputImage(image, options, {
+    clone: false,
+    newParameters: {
+      bitDepth: newBitDepth,
+      colorModel: image.colorModel,
+    },
+  });
+
+  return newBitDepth === 8
+    ? convertToUint8(image, newImage)
+    : convertToUint16(image, newImage);
+}
+
+/**
+ * Convert bit depth to 16 bits.
+ * @param image - Image to convert.
+ * @param targetImage - Target image to write to.
+ * @returns Converted image.
+ */
+function convertToUint16(image: Image, targetImage: Image): Image {
+  for (let i = 0; i < image.size; i++) {
+    for (let j = 0; j < targetImage.channels; j++) {
+      targetImage.setValueByIndex(i, j, image.getValueByIndex(i, j) << 8);
+    }
+  }
+  return targetImage;
+}
+
+/**
+ * Convert bit depth to 8 bits.
+ * @param image - Image to convert.
+ * @param targetImage - Target image to write to.
+ * @returns Converted image.
+ */
+function convertToUint8(image: Image, targetImage: Image): Image {
+  for (let i = 0; i < image.size; i++) {
+    for (let j = 0; j < targetImage.channels; j++) {
+      targetImage.setValueByIndex(i, j, image.getValueByIndex(i, j) >> 8);
+    }
+  }
+  return targetImage;
+}

package/src/operations/convertColor.ts

@@ -1,109 +1,186 @@
-import { Image, ImageKind } from '../Image';
-import { getOutputImage } from '../utils/getOutputImage';
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import type { ImageColorModel } from '../utils/constants/colorModels.js';
+import { getOutputImage, maskToOutputImage } from '../utils/getOutputImage.js';
 
-export interface IConvertColorOptions {
+export interface ConvertColorOptions {
+  /**
+   * Image to which to output.
+   */
   out?: Image;
 }
 
+/**
+ * Convert image to a different color model.
+ * @param image - Image to convert.
+ * @param colorModel - New color model.
+ * @param options - Convert color options.
+ * @returns The converted image.
+ */
 export function convertColor(
-  image: Image,
-  kind: ImageKind,
-  options: IConvertColorOptions = {}
+  image: Image | Mask,
+  colorModel: ImageColorModel,
+  options: ConvertColorOptions = {},
 ): Image {
-  const canConvert = new Map([
-    [ImageKind.GREY, [ImageKind.GREYA, ImageKind.RGB, ImageKind.RGBA]],
-    [ImageKind.GREYA, [ImageKind.GREY, ImageKind.RGB, ImageKind.RGBA]],
-    [ImageKind.RGB, [ImageKind.GREYA, ImageKind.GREY, ImageKind.RGBA]],
-    [ImageKind.RGBA, [ImageKind.GREYA, ImageKind.GREY, ImageKind.RGB]]
+  const canConvert = new Map<ImageColorModel, ImageColorModel[]>([
+    ['GREY', ['GREYA', 'RGB', 'RGBA']],
+    ['GREYA', ['GREY', 'RGB', 'RGBA']],
+    ['RGB', ['GREY', 'GREYA', 'RGBA']],
+    ['RGBA', ['GREY', 'GREYA', 'RGB']],
+    ['BINARY', ['GREY', 'RGB', 'RGBA']],
   ]);
 
-  if (image.kind === kind) {
-    throw new Error(`Cannot convert color, image is already ${kind}`);
+  if (image.colorModel === colorModel && colorModel !== 'BINARY') {
+    return getOutputImage(
+      image as Image,
+      { out: options.out },
+      { clone: true },
+    );
   }
 
-  const canConvertTo = canConvert.get(image.kind);
-  if (!canConvertTo || !canConvertTo.includes(kind)) {
-    throw new Error(`conversion from ${image.kind} to ${kind} not implemented`);
+  const canConvertTo = canConvert.get(image.colorModel);
+  if (!canConvertTo?.includes(colorModel)) {
+    throw new RangeError(
+      `conversion from ${image.colorModel} to ${colorModel} not implemented`,
+    );
   }
 
-  const output = getOutputImage(image, options, {
-    newParameters: { kind }
-  });
+  if (image instanceof Image) {
+    const output = getOutputImage(image, options, {
+      newParameters: { colorModel },
+    });
 
-  if (image.kind === ImageKind.GREY || image.kind === ImageKind.GREYA) {
-    convertGreyToAny(image, output);
-  }
+    if (image.colorModel === 'GREY' || image.colorModel === 'GREYA') {
+      convertGreyToAny(image, output);
+    }
 
-  if (image.kind === ImageKind.RGB || image.kind === ImageKind.RGBA) {
-    if (kind === ImageKind.RGB || kind === ImageKind.RGBA) {
-      convertRgbToRgb(image, output);
-    } else {
-      // GREYA or GREY
-      convertRgbToGrey(image, output);
+    if (image.colorModel === 'RGB' || image.colorModel === 'RGBA') {
+      if (colorModel === 'RGB' || colorModel === 'RGBA') {
+        convertRgbToRgb(image, output);
+      } else {
+        // GREYA or GREY
+        convertRgbToGrey(image, output);
+      }
     }
-  }
 
-  if (!image.alpha && output.alpha) {
-    output.fillAlpha(output.maxValue);
-  }
+    if (!image.alpha && output.alpha) {
+      output.fillAlpha(output.maxValue);
+    }
 
-  if (image.alpha && output.alpha) {
-    copyAlpha(image, output);
+    if (image.alpha && output.alpha) {
+      copyAlpha(image, output);
+    }
+    return output;
+  } else if (colorModel === 'GREY') {
+    const output = maskToOutputImage(image, options);
+    convertBinaryToGrey(image, output);
+    return output;
+  } else {
+    const img = new Image(image.width, image.height, {
+      colorModel,
+    });
+    convertBinaryToRgb(image, img);
+    return img;
   }
-
-  return output;
 }
 
-function copyAlpha(source: Image, dest: Image): void {
+/**
+ * Copy alpha channel of source to dest.
+ * @param source - Source image.
+ * @param dest - Destination image.
+ */
+export function copyAlpha(source: Image, dest: Image): void {
+  if (source.size !== dest.size) {
+    throw new RangeError('source and destination have different sizes');
+  }
   if (!source.alpha) {
-    throw new Error('source image does not have alpha');
+    throw new RangeError('source image does not have alpha');
   }
   if (!dest.alpha) {
-    throw new Error('destination does not have alpha');
+    throw new RangeError('destination does not have alpha');
   }
 
-  for (
-    let i = dest.channels - 1, j = source.channels - 1;
-    i < dest.data.length;
-    i += dest.channels, j += source.channels
-  ) {
-    dest.data[i] = source.data[j];
+  for (let i = 0; i < dest.size; i++) {
+    dest.setValueByIndex(
+      i,
+      dest.channels - 1,
+      source.getValueByIndex(i, source.channels - 1),
+    );
   }
 }
 
+/**
+ * Convert grey image to other color model.
+ * @param image - Image to convert.
+ * @param newImage - Converted image.
+ */
 function convertGreyToAny(image: Image, newImage: Image): void {
-  for (
-    let i = 0, iNew = 0;
-    i < image.data.length;
-    i += image.channels, iNew += newImage.channels
-  ) {
+  for (let i = 0; i < image.size; i++) {
     for (let j = 0; j < newImage.components; j++) {
-      newImage.data[iNew + j] = image.data[i];
+      newImage.setValueByIndex(i, j, image.getValueByIndex(i, 0));
     }
   }
 }
 
+/**
+ * Convert RGB image to RGB. Allows to use convert with an RGB target whatever the image color model is.
+ * @param image - Image to convert.
+ * @param newImage - Converted image.
+ */
 function convertRgbToRgb(image: Image, newImage: Image): void {
-  for (
-    let i = 0, iNew = 0;
-    i < image.data.length;
-    i += image.channels, iNew += newImage.channels
-  ) {
+  for (let i = 0; i < image.size; i++) {
     for (let j = 0; j < 3; j++) {
-      newImage.data[iNew + j] = image.data[i + j];
+      newImage.setValueByIndex(i, j, image.getValueByIndex(i, j));
     }
   }
 }
 
+/**
+ * Convert RGB image to GREY.
+ * @param image - Image to convert.
+ * @param newImage - Converted image.
+ */
 function convertRgbToGrey(image: Image, newImage: Image): void {
-  for (
-    let i = 0, iNew = 0;
-    i < image.data.length;
-    i += image.channels, iNew += newImage.channels
-  ) {
-    const r = image.data[i];
-    const g = image.data[i + 1];
-    const b = image.data[i + 2];
-    newImage.data[iNew] = Math.round(0.299 * r + 0.587 * g + 0.114 * b);
+  for (let i = 0; i < image.size; i++) {
+    const r = image.getValueByIndex(i, 0);
+    const g = image.getValueByIndex(i, 1);
+    const b = image.getValueByIndex(i, 2);
+    newImage.setValueByIndex(
+      i,
+      0,
+      Math.round(0.299 * r + 0.587 * g + 0.114 * b),
+    );
+  }
+}
+
+/**
+ * Convert Mask to GREY.
+ * @param mask - Mask to convert.
+ * @param newImage - Converted image.
+ */
+export function convertBinaryToGrey(mask: Mask, newImage: Image): void {
+  for (let i = 0; i < mask.size; i++) {
+    newImage.setValueByIndex(
+      i,
+      0,
+      mask.getBitByIndex(i) ? newImage.maxValue : 0,
+    );
+  }
+}
+
+/**
+ * Convert mask to RGB or RGBA.
+ * @param mask - Mask to convert.
+ * @param newImage - Converted image.
+ */
+export function convertBinaryToRgb(mask: Mask, newImage: Image): void {
+  const black = new Array(newImage.components).fill(0);
+  const white = new Array(newImage.components).fill(newImage.maxValue);
+  if (newImage.alpha) {
+    black.push(newImage.maxValue);
+    white.push(newImage.maxValue);
+  }
+  for (let i = 0; i < mask.size; i++) {
+    newImage.setPixelByIndex(i, mask.getBitByIndex(i) ? white : black);
   }
 }

package/src/operations/copyTo.ts

@@ -0,0 +1,79 @@
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import type { Point } from '../geometry/index.js';
+import { getOutputImage, maskToOutputMask } from '../utils/getOutputImage.js';
+import { setBlendedPixel } from '../utils/setBlendedPixel.js';
+import { checkPointIsInteger } from '../utils/validators/checkPointIsInteger.js';
+
+export interface CopyToOptions<OutType> {
+  /**
+   * Origin for the crop relative to the top-left corner of the image.
+   * @default `{row: 0, column: 0}`
+   */
+  origin?: Point;
+  /**
+   * Image to which to output.
+   */
+  out?: OutType;
+}
+
+export function copyTo(
+  source: Image,
+  target: Image,
+  options?: CopyToOptions<Image>,
+): Image;
+export function copyTo(
+  source: Mask,
+  target: Mask,
+  options?: CopyToOptions<Mask>,
+): Mask;
+/**
+ * Copy the image to another one by specifying the location in the target image.
+ * If the source image exceeds the boundaries of the target image, the excess pixels
+ * are ignored. The result image will have the same dimensions as the target image.
+ * @param source - The source image.
+ * @param target - The target image.
+ * @param options - Options.
+ * @returns The target with the source copied to it.
+ */
+export function copyTo(
+  source: Image | Mask,
+  target: Image | Mask,
+  options: CopyToOptions<Image | Mask> = {},
+): Image | Mask {
+  const { origin = { column: 0, row: 0 } } = options;
+  const { column, row } = origin;
+
+  if (source.colorModel !== target.colorModel) {
+    throw new RangeError('source and target must have the same color model');
+  }
+
+  checkPointIsInteger(origin, 'Origin');
+
+  let result: Image | Mask;
+  if (target instanceof Image) {
+    result = getOutputImage(target, options, { clone: true });
+  } else {
+    result = maskToOutputMask(target, options, { clone: true });
+  }
+
+  for (
+    let currentRow = Math.max(row, 0);
+    currentRow < Math.min(source.height + row, target.height);
+    currentRow++
+  ) {
+    for (
+      let currentColumn = Math.max(column, 0);
+      currentColumn < Math.min(source.width + column, target.width);
+      currentColumn++
+    ) {
+      const sourcePixel = source.getPixel(
+        currentColumn - column,
+        currentRow - row,
+      );
+      setBlendedPixel(result, currentColumn, currentRow, sourcePixel);
+    }
+  }
+
+  return result;
+}