image-js 0.0.0-next-e30968a2d8

package/src/Mask.ts

@@ -0,0 +1,476 @@
+import {
+  and,
+  AndOptions,
+  invert,
+  InvertOptions,
+  or,
+  OrOptions,
+  subtractImage,
+  SubtractImageOptions,
+} from './filters';
+import {
+  bottomHat,
+  BottomHatOptions,
+  clearBorder,
+  ClearBorderOptions,
+  close,
+  CloseOptions,
+  dilate,
+  DilateOptions,
+  ErodeOptions,
+  floodFill,
+  FloodFillOptions,
+  morphologicalGradient,
+  MorphologicalGradientOptions,
+  open,
+  OpenOptions,
+  topHat,
+  TopHatOptions,
+} from './morphology';
+import { erode } from './morphology/erode';
+import { boolToNumber } from './utils/boolToNumber';
+
+import { ImageColorModel, ColorDepth, colorModels, IJS, convertColor } from '.';
+
+export type BitValue = 1 | 0 | boolean;
+
+export interface MaskOptions {
+  /**
+   * Typed array holding the mask data.
+   */
+  data?: Uint8Array;
+}
+
+export interface MaskCreateFromOptions extends MaskOptions {
+  width?: number;
+  height?: number;
+}
+
+export class Mask {
+  /**
+   * The number of columns of the mask.
+   */
+  public readonly width: number;
+
+  /**
+   * The number of rows of the mask.
+   */
+  public readonly height: number;
+
+  /**
+   * The total number of bits in the mask (width × height).
+   */
+  public readonly size: number;
+
+  /**
+   * The number of bits per value in each channel (always 1).
+   */
+  public readonly depth: ColorDepth;
+
+  /**
+   * The color model of the mask (always BINARY).
+   */
+  public readonly colorModel: ImageColorModel;
+
+  /**
+   * The number of color channels in the image, excluding the alpha channel.
+   * (always 1)
+   */
+  public readonly components: number;
+
+  /**
+   * The number of channels in the mask, including the alpha channel.
+   * (always 1)
+   */
+  public readonly channels: number;
+
+  /**
+   * Specifying that the mask has no an alpha channel.
+   */
+  public readonly alpha: boolean;
+
+  /**
+   * The maximum value that a pixel channel can have.
+   */
+  public readonly maxValue: number;
+
+  /**
+   * Typed array holding the mask data.
+   */
+  private readonly data: Uint8Array;
+
+  /**
+   * Construct a new Mask knowing its dimensions.
+   *
+   * @param width - Image width.
+   * @param height - Image height.
+   * @param options - Image options.
+   */
+  public constructor(width: number, height: number, options: MaskOptions = {}) {
+    const { data } = options;
+
+    if (width < 1 || !Number.isInteger(width)) {
+      throw new RangeError(
+        `width must be an integer and at least 1. Received ${width}`,
+      );
+    }
+
+    if (height < 1 || !Number.isInteger(height)) {
+      throw new RangeError(
+        `height must be an integer and at least 1. Received ${height}`,
+      );
+    }
+
+    this.width = width;
+    this.height = height;
+    this.size = width * height;
+    this.depth = ColorDepth.UINT1;
+    this.colorModel = ImageColorModel.BINARY;
+
+    const colorModelDef = colorModels[this.colorModel];
+    this.components = colorModelDef.components;
+    this.alpha = colorModelDef.alpha;
+    this.channels = colorModelDef.channels;
+
+    this.maxValue = 1;
+
+    if (data === undefined) {
+      this.data = new Uint8Array(this.size);
+    } else {
+      const expectedLength = this.size * this.channels;
+      if (data.length !== expectedLength) {
+        throw new RangeError(
+          `incorrect data size: ${data.length}. Expected ${expectedLength}`,
+        );
+      }
+      this.data = data;
+    }
+  }
+
+  /**
+   * Create a new Mask based on the properties of an existing one.
+   *
+   * @param other - Reference Mask.
+   * @param options - Mask options.
+   * @returns New mask.
+   */
+  public static createFrom(
+    other: Mask | IJS,
+    options: MaskCreateFromOptions = {},
+  ): Mask {
+    const { width = other.width, height = other.height } = options;
+    return new Mask(width, height, options);
+  }
+
+  /**
+   * Create a copy of this mask.
+   *
+   * @returns The mask clone.
+   */
+  public clone(): Mask {
+    return Mask.createFrom(this, { data: this.data.slice() });
+  }
+
+  /**
+   * Get the value of a bit.
+   *
+   * @param row - Row index.
+   * @param column - Column index.
+   * @returns The bit value.
+   */
+  public getBit(row: number, column: number): number {
+    const index = row * this.width + column;
+    return this.data[index];
+  }
+
+  /**
+   * Set the value of a bit.
+   *
+   * @param row - Row index.
+   * @param column - Column index.
+   * @param value - New bit value.
+   */
+  public setBit(row: number, column: number, value: BitValue): void {
+    const index = row * this.width + column;
+    // @ts-expect-error: we know that value is a boolean
+    this.data[index] = value;
+  }
+
+  /**
+   * Get the value of a bit using index.
+   *
+   * @param index - Index of the pixel.
+   * @returns Value of the bit.
+   */
+  public getBitByIndex(index: number): number {
+    return this.data[index * this.channels];
+  }
+
+  /**
+   * Set the value of a bit using index.
+   *
+   * @param index - Index of the pixel.
+   * @param value - Value to set.
+   */
+  public setBitByIndex(index: number, value: BitValue): void {
+    let result = boolToNumber(value);
+    this.data[index * this.channels] = result;
+  }
+
+  /**
+   * Get the value of a bit. Function exists for compatibility with IJS.
+   *
+   * @param row - Row index.
+   * @param column - Column index.
+   * @param channel - Index of the channel, must be zero.
+   * @returns The bit value.
+   */
+  public getValue(row: number, column: number, channel: number): number {
+    checkChannel(channel);
+    return this.getBit(row, column);
+  }
+
+  /**
+   * Set the value of a bit. Function exists for compatibility with IJS.
+   *
+   * @param row - Row index.
+   * @param column - Column index.
+   * @param channel - Index of the channel, must be zero.
+   * @param value - New bit value.
+   */
+  public setValue(
+    row: number,
+    column: number,
+    channel: number,
+    value: BitValue,
+  ): void {
+    checkChannel(channel);
+    this.setBit(row, column, value);
+  }
+
+  /**
+   * Get the value of a bit using index. Function exists for compatibility with IJS.
+   *
+   * @param index - Index of the pixel.
+   * @param channel - Index of the channel, must be zero.
+   * @returns Value of the bit.
+   */
+  public getValueByIndex(index: number, channel: number): number {
+    checkChannel(channel);
+    return this.getBitByIndex(index);
+  }
+  /**
+   * Set the value of a bit using index. Function exists for compatibility with IJS.
+   *
+   * @param index - Index of the pixel.
+   * @param channel - Index of the channel, must be zero.
+   * @param value - Value to set.
+   */
+  public setValueByIndex(
+    index: number,
+    channel: number,
+    value: BitValue,
+  ): void {
+    checkChannel(channel);
+    this.setBitByIndex(index, value);
+  }
+
+  /**
+   * Return the raw mask data.
+   *
+   * @returns The raw data.
+   */
+  public getRawImage() {
+    return {
+      width: this.width,
+      height: this.height,
+      data: this.data,
+    };
+  }
+
+  public [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return `Mask {
+  width: ${this.width}
+  height: ${this.height}
+  data: ${printData(this)}
+}`;
+  }
+
+  /**
+   * Fill the mask with a value.
+   *
+   * @param value - Value of the bit.
+   * @returns The mask instance.
+   */
+  public fill(value: BitValue): this {
+    let result = boolToNumber(value);
+    this.data.fill(result);
+    return this;
+  }
+
+  public convertColor(colorModel: ImageColorModel): IJS {
+    return convertColor(this, colorModel);
+  }
+
+  // FILTERS
+  /**
+   * Invert the colors of the mask.
+   *
+   * @param options - Inversion options
+   * @returns The inverted mask.
+   */
+  public invert(options?: InvertOptions): Mask {
+    return invert(this, options);
+  }
+
+  /**
+   * Subtract other from a mask.
+   *
+   * @param other - Image to subtract
+   * @param options - Inversion options
+   * @returns The subtracted mask.
+   */
+  public subtractImage(other: Mask, options?: SubtractImageOptions): Mask {
+    return subtractImage(this, other, options);
+  }
+  /**
+   * Perform an AND operation on two masks.
+   *
+   * @param other - Second mask.
+   * @param options - And options.
+   * @returns AND of the two masks.
+   */
+  public and(other: Mask, options?: AndOptions): Mask {
+    return and(this, other, options);
+  }
+  /**
+   * Perform an OR operation on two masks.
+   *
+   * @param other - Second mask.
+   * @param options - And options.
+   * @returns OR of the two masks.
+   */
+  public or(other: Mask, options?: OrOptions): Mask {
+    return or(this, other, options);
+  }
+
+  // MORPHOLOGY
+  /**
+   * Erode a Mask.
+   *
+   * @param options - Erode options
+   * @returns The eroded mask.
+   */
+  public erode(options?: ErodeOptions): Mask {
+    return erode(this, options);
+  }
+
+  /**
+   * Dilate an image.
+   *
+   * @param options - Dilate options.
+   * @returns The dilated image.
+   */
+  public dilate(options?: DilateOptions): Mask {
+    return dilate(this, options);
+  }
+
+  /**
+   * Open an image.
+   *
+   * @param options - Open options.
+   * @returns The opened image.
+   */
+  public open(options?: OpenOptions): Mask {
+    return open(this, options);
+  }
+
+  /**
+   * Close an image.
+   *
+   * @param options - Close options.
+   * @returns The closed image.
+   */
+  public close(options?: CloseOptions): Mask {
+    return close(this, options);
+  }
+
+  /**
+   * Top hat of an image.
+   *
+   * @param options - Top hat options.
+   * @returns The top-hatted image.
+   */
+  public topHat(options?: TopHatOptions): Mask {
+    return topHat(this, options);
+  }
+
+  /**
+   * Bottom hat of an image.
+   *
+   * @param options - Bottom hat options.
+   * @returns The bottom-hatted image.
+   */
+  public bottomHat(options?: BottomHatOptions): Mask {
+    return bottomHat(this, options);
+  }
+
+  /**
+   * Apply morphological gradient to an image.
+   *
+   * @param options - Morphological gradient options.
+   * @returns The processed image.
+   */
+  public morphologicalGradient(options?: MorphologicalGradientOptions): Mask {
+    return morphologicalGradient(this, options);
+  }
+
+  /**
+   * Remove elements connected to the borders of an image.
+   *
+   * @param options - Clear border options.
+   * @returns The processed image.
+   */
+  public clearBorder(options?: ClearBorderOptions): Mask {
+    return clearBorder(this, options);
+  }
+  /**
+   * Fill holes in regions of interest.
+   *
+   * @param options - Flood fill options.
+   * @returns The filled mask.
+   */
+  public floodFill(options?: FloodFillOptions): Mask {
+    return floodFill(this, options);
+  }
+}
+
+/**
+ * Returns all values of a mask as a string.
+ *
+ * @param mask - Input mask.
+ * @returns Formatted string with all values of a mask.
+ */
+function printData(mask: Mask): string {
+  const result = [];
+  const padding = 2;
+  for (let i = 0; i < mask.height; i++) {
+    const line = [];
+    for (let j = 0; j < mask.width; j++) {
+      line.push(String(mask.getBit(i, j)).padStart(padding, ' '));
+    }
+    result.push(`[${line.join(' ')}]`);
+  }
+  return result.join('\n     ');
+}
+
+/**
+ * Verify the channel value of a mask
+ *
+ * @param channel - The channel value
+ */
+function checkChannel(channel: number) {
+  if (channel !== 0) {
+    throw new Error(`Channel value must be 0 on type Mask, got ${channel}.`);
+  }
+}

package/src/compute/histogram.ts

@@ -0,0 +1,39 @@
+import { IJS } from '../IJS';
+import { validateChannel } from '../utils/validators';
+
+export interface HistogramOptions {
+  /**
+   * The channel for which to compute the histogram.
+   * If it is unspecified, the image must have one channel or the method will
+   * throw an error.
+   *
+   * @default 0
+   */
+  channel?: number;
+}
+
+/**
+ * Returns a histogram of pixel intensities.
+ *
+ * @param image - The original image.
+ * @param options - Histogram options.
+ * @returns - The histogram.
+ */
+export function histogram(
+  image: IJS,
+  options: HistogramOptions = {},
+): Uint32Array {
+  let { channel } = options;
+  if (typeof channel !== 'number') {
+    if (image.channels !== 1) {
+      throw new Error('channel option is mandatory for multi-channel images');
+    }
+    channel = 0;
+  }
+  validateChannel(channel, image);
+  const hist = new Uint32Array(image.maxValue + 1);
+  for (let i = 0; i < image.size; i++) {
+    hist[image.getValueByIndex(i, channel)]++;
+  }
+  return hist;
+}

package/src/compute/index.ts

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

package/src/filters/and.ts

@@ -0,0 +1,34 @@
+import { Mask } from '..';
+import { maskToOutputMask } from '../utils/getOutputImage';
+
+export interface AndOptions {
+  /**
+   * Image to which the inverted image has to be put.
+   */
+  out?: Mask;
+}
+
+/**
+ * Perform an AND operation on two masks.
+ *
+ * @param mask - First mask.
+ * @param otherMask - Second mask.
+ * @param options - And options.
+ * @returns AND of the two masks.
+ */
+export function and(mask: Mask, otherMask: Mask, options?: AndOptions): Mask {
+  const newMask = maskToOutputMask(mask, options);
+
+  if (mask.width !== otherMask.width || mask.height !== otherMask.height) {
+    throw new Error('and: 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/blur.ts

@@ -0,0 +1,49 @@
+import { IJS } from '../IJS';
+import { BorderType } from '../utils/interpolateBorder';
+
+import { separableConvolution } from './convolution';
+
+export interface BlurOptions {
+  /**
+   * Width of the blurring matrix, must be an odd integer.
+   */
+  width: number;
+  /**
+   * Height of the blurring matrix, must be an odd integer.
+   */
+  height: number;
+  /**
+   * Explicit how to handle the borders.
+   *
+   * @default BorderType.REFLECT_101
+   */
+  borderType?: BorderType;
+  /**
+   * Value of the border if BorderType is CONSTANT.
+   *
+   * @default 0
+   */
+  borderValue?: number;
+  /**
+   * Image to which to output.
+   */
+  out?: IJS;
+}
+
+/**
+ * Blur an image. The pixel in the center becomes an average of the surrounding ones.
+ *
+ * @param image - Image to blur.
+ * @param options - Blur options
+ * @returns The blurred image.
+ */
+export function blur(image: IJS, options: BlurOptions): IJS {
+  const { width, height } = options;
+  const kernelX = new Array(width).fill(1);
+  const kernelY = new Array(height).fill(1);
+
+  return separableConvolution(image, kernelX, kernelY, {
+    normalize: true,
+    ...options,
+  });
+}