image-js 0.0.0-next-e30968a2d8

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './compute';
+export * from './filters';
+export * from './geometry';
+export * from './IJS';
+export * from './load';
+export * from './Mask';
+export * from './morphology';
+export * from './operations';
+export * from './save';

package/src/load/decode.ts

@@ -0,0 +1,33 @@
+import imageType from 'image-type';
+
+import { IJS } from '../IJS';
+
+import { decodeJpeg } from './decodeJpeg';
+import { decodePng } from './decodePng';
+import { decodeTiff } from './decodeTiff';
+
+/**
+ * Decode input data. Data format is automatically detected.
+ * Possible formats: png, jpeg and tiff.
+ *
+ * @param data - Data to decode.
+ * @returns The decoded image.
+ */
+export function decode(data: ArrayBufferView): IJS {
+  const typedArray = new Uint8Array(
+    data.buffer,
+    data.byteOffset,
+    data.byteLength,
+  );
+  const type = imageType(typedArray);
+  switch (type?.mime) {
+    case 'image/png':
+      return decodePng(typedArray);
+    case 'image/jpeg':
+      return decodeJpeg(typedArray);
+    case 'image/tiff':
+      return decodeTiff(typedArray);
+    default:
+      throw new Error('unrecognized data format');
+  }
+}

package/src/load/decodeJpeg.ts

@@ -0,0 +1,17 @@
+import { decode } from 'jpeg-js';
+
+import { IJS, ImageColorModel } from '../IJS';
+
+/**
+ * Decode a jpeg. See the jpeg-js npm module.
+ *
+ * @param buffer - The data to decode.
+ * @returns The decoded image.
+ */
+export function decodeJpeg(buffer: Uint8Array): IJS {
+  const jpeg = decode(buffer, { useTArray: true });
+  return new IJS(jpeg.width, jpeg.height, {
+    data: jpeg.data,
+    colorModel: ImageColorModel.RGBA,
+  });
+}

package/src/load/decodePng.ts

@@ -0,0 +1,78 @@
+import { decode, DecodedPng } from 'fast-png';
+
+import { IJS, ImageColorModel, ColorDepth } from '../IJS';
+
+/**
+ * Decode a PNG. See the fast-png npm module.
+ *
+ * @param buffer - The data to decode.
+ * @returns The decoded image.
+ */
+export function decodePng(buffer: Uint8Array): IJS {
+  const png = decode(buffer);
+
+  let colorModel: ImageColorModel;
+  const depth: ColorDepth =
+    png.depth === 16 ? ColorDepth.UINT16 : ColorDepth.UINT8;
+
+  if (png.palette) {
+    return loadPalettePng(png);
+  }
+
+  switch (png.channels) {
+    case 1:
+      colorModel = ImageColorModel.GREY;
+      break;
+    case 2:
+      colorModel = ImageColorModel.GREYA;
+      break;
+    case 3:
+      colorModel = ImageColorModel.RGB;
+      break;
+    case 4:
+      colorModel = ImageColorModel.RGBA;
+      break;
+    default:
+      throw new Error(`Unexpected number of channels: ${png.channels}`);
+  }
+  return new IJS(png.width, png.height, {
+    colorModel: colorModel,
+    depth,
+    data: png.data,
+  });
+}
+
+/**
+ * @param png
+ */
+function loadPalettePng(png: DecodedPng): IJS {
+  if (!png.palette) {
+    throw new Error(
+      'unexpected: there should be a palette when colourType is 3',
+    );
+  }
+  const pixels = png.width * png.height;
+  const data = new Uint8Array(pixels * 3);
+  const pixelsPerByte = 8 / png.depth;
+  const factor = png.depth < 8 ? pixelsPerByte : 1;
+  const mask = parseInt('1'.repeat(png.depth), 2);
+  let dataIndex = 0;
+
+  for (let i = 0; i < pixels; i++) {
+    const index = Math.floor(i / factor);
+    let value = png.data[index];
+    if (png.depth < 8) {
+      value =
+        (value >>> (png.depth * (pixelsPerByte - 1 - (i % pixelsPerByte)))) &
+        mask;
+    }
+    const paletteValue = png.palette[value];
+    data[dataIndex++] = paletteValue[0];
+    data[dataIndex++] = paletteValue[1];
+    data[dataIndex++] = paletteValue[2];
+  }
+
+  return new IJS(png.width, png.height, {
+    data,
+  });
+}

package/src/load/decodeTiff.ts

@@ -0,0 +1,64 @@
+import { decode } from 'tiff';
+
+import { ImageColorModel } from '..';
+import { IJS } from '../IJS';
+
+type TiffIfd = ReturnType<typeof decode>[number];
+
+/**
+ * Decode a TIFF. See the tiff module.
+ *
+ * @param buffer - The data to decode.
+ * @returns The decoded image.
+ */
+export function decodeTiff(buffer: Uint8Array): IJS {
+  let result = decode(buffer);
+  return getImageFromIFD(result[0]);
+  // TODO: handle stacks (many IFDs)
+}
+
+/**
+ * Create image from a single IFD.
+ *
+ * @param ifd - The IFD.
+ * @returns The decoded image.
+ */
+function getImageFromIFD(ifd: TiffIfd): IJS {
+  if (ifd.type === 3) {
+    // Palette
+    const data = new Uint16Array(3 * ifd.width * ifd.height);
+    const palette = ifd.palette as [number, number, number][];
+    let ptr = 0;
+    for (let index of ifd.data) {
+      const color = palette[index];
+      data[ptr++] = color[0];
+      data[ptr++] = color[1];
+      data[ptr++] = color[2];
+    }
+    return new IJS(ifd.width, ifd.height, {
+      data: data,
+      // TODO: handle alpha properly
+      colorModel: ifd.alpha ? ImageColorModel.RGBA : ImageColorModel.RGB,
+      // TODO: handle other bit depths
+      depth: 16,
+      // TODO: implement metadata
+      //meta: getMetadata(ifd),
+    });
+  } else {
+    return new IJS(ifd.width, ifd.height, {
+      // TODO: handle float data
+      // @ts-expect-error float data not handled yet
+      data: ifd.data,
+      depth: ifd.bitsPerSample,
+      colorModel:
+        ifd.type === 2
+          ? ifd.alpha
+            ? ImageColorModel.RGBA
+            : ImageColorModel.RGB
+          : ifd.alpha
+          ? ImageColorModel.GREYA
+          : ImageColorModel.GREY,
+      // meta: getMetadata(ifd),
+    });
+  }
+}

package/src/load/index.ts

@@ -0,0 +1,7 @@
+export * from './decode';
+export * from './decodeJpeg';
+export * from './decodePng';
+export * from './decodeTiff';
+export * from './read';
+export * from './readCanvas';
+export * from './readImg';

package/src/load/read.ts

@@ -0,0 +1,27 @@
+import fs from 'fs';
+
+import { IJS } from '../IJS';
+
+import { decode } from './decode';
+
+/**
+ * Read an image from the disk.
+ * The file format is automatically selected based on the first few bytes.
+ *
+ * @param path - The path to the image.
+ * @returns IJS instance.
+ */
+export async function read(path: string | URL): Promise<IJS> {
+  const data = await fs.promises.readFile(path);
+  return decode(data);
+}
+
+/**
+ * Synchronous version of @see {@link read}.
+ *
+ * @param path - The path to the image.
+ * @returns IJS instance.
+ */
+export function readSync(path: string | URL): IJS {
+  return decode(fs.readFileSync(path));
+}

package/src/load/readCanvas.ts

@@ -0,0 +1,17 @@
+import { IJS, ImageColorModel } from '../IJS';
+
+export function readCanvas(canvas: HTMLCanvasElement): IJS {
+  const ctx = canvas.getContext('2d');
+  if (ctx === null) {
+    throw new Error('could not get context from canvas element');
+  }
+  const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+  return new IJS(imageData.width, imageData.height, {
+    data: new Uint8Array(
+      imageData.data.buffer,
+      imageData.data.byteOffset,
+      imageData.data.byteLength,
+    ),
+    colorModel: ImageColorModel.RGBA,
+  });
+}

package/src/load/readImg.ts

@@ -0,0 +1,15 @@
+import { IJS } from '../IJS';
+
+import { readCanvas } from './readCanvas';
+
+export function readImg(img: CanvasImageSource): IJS {
+  const canvas = document.createElement('canvas');
+  canvas.width = img.width as number;
+  canvas.height = img.height as number;
+  const ctx = canvas.getContext('2d');
+  if (ctx === null) {
+    throw new Error('could not get context from canvas element');
+  }
+  ctx.drawImage(img, 0, 0);
+  return readCanvas(canvas);
+}

package/src/morphology/bottomHat.ts

@@ -0,0 +1,66 @@
+import { ColorDepth, IJS, Mask } from '..';
+import { subtractImage } from '../filters';
+import { checkKernel } from '../utils/checkKernel';
+import checkProcessable from '../utils/checkProcessable';
+
+export interface BottomHatOptions {
+  /**
+   * 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 bottomHat(image: IJS, options?: BottomHatOptions): IJS;
+export function bottomHat(image: Mask, options?: BottomHatOptions): Mask;
+/**
+ * This function is the black top hat (also called bottom hat).
+ * In mathematical morphology and digital image processing,
+ * top-hat transform is an operation that extracts small elements and details from given images.
+ * The black top-hat transform is defined dually as the difference between the closed and the input image.
+ * Top-hat transforms are used for various image processing tasks, such as feature extraction, background equalization,
+ * image enhancement, and others. (Wikipedia)
+ * http://docs.opencv.org/2.4/doc/tutorials/imgproc/opening_closing_hats/opening_closing_hats.html
+ *
+ * @param image - Image to process
+ * @param options - Bottom hat options
+ * @returns The bottom-hatted image
+ */
+export function bottomHat(
+  image: IJS | Mask,
+  options: BottomHatOptions = {},
+): IJS | Mask {
+  let {
+    kernel = [
+      [1, 1, 1],
+      [1, 1, 1],
+      [1, 1, 1],
+    ],
+    iterations = 1,
+  } = options;
+
+  if (image instanceof IJS) {
+    checkProcessable(image, 'bottomHat', {
+      bitDepth: [ColorDepth.UINT1, ColorDepth.UINT8, ColorDepth.UINT16],
+      components: 1,
+      alpha: false,
+    });
+  }
+
+  checkKernel(kernel, 'bottomHat');
+
+  let newImage = image;
+  for (let i = 0; i < iterations; i++) {
+    let openImage = newImage.close({ kernel });
+    newImage = subtractImage(openImage, newImage, { absolute: true });
+  }
+  return newImage;
+}

package/src/morphology/cannyEdgeDetector.ts

@@ -0,0 +1,214 @@
+import { IJS, ImageColorModel, Mask } from '..';
+import { GaussianBlurOptions } from '../filters';
+import checkProcessable from '../utils/checkProcessable';
+import { getIndex } from '../utils/getIndex';
+import { imageToOutputMask } from '../utils/getOutputImage';
+
+export interface CannyEdgeOptions {
+  /**
+   * Lower threshold of the gaussian blur (indicates the weak edges to discard).
+   *
+   * @default 0.04
+   */
+  lowThreshold?: number;
+  /**
+   * Higher threshold of the gaussian blur (indicates the strong edges to keep). Value must be between 0 and 1.
+   *
+   * @default 0.1
+   */
+  highThreshold?: number;
+  /**
+   * Standard deviation of the gaussian blur (sigma). Value must be between 0 and 1.
+   *
+   * @default { sigma: 1 }
+   */
+  gaussianBlurOptions?: GaussianBlurOptions;
+  /**
+   * Enable/ disable hysteresis steps.
+   *
+   * @default true
+   */
+  hysteresis?: boolean;
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Mask;
+}
+
+const kernelX = [
+  [-1, 0, +1],
+  [-2, 0, +2],
+  [-1, 0, +1],
+];
+
+const kernelY = [
+  [-1, -2, -1],
+  [0, 0, 0],
+  [+1, +2, +1],
+];
+
+/**
+ * Apply Canny edge detection to an image.
+ *
+ * @param image - Image to process.
+ * @param options - Canny edge detection options.
+ * @returns The processed image.
+ */
+export function cannyEdgeDetector(
+  image: IJS,
+  options: CannyEdgeOptions = {},
+): Mask {
+  const {
+    hysteresis = true,
+    lowThreshold = 0.04,
+    highThreshold = 0.1,
+    gaussianBlurOptions = { sigma: 1 },
+  } = options;
+
+  const minValue = lowThreshold * image.maxValue;
+  const maxValue = highThreshold * image.maxValue;
+
+  checkProcessable(image, 'cannyEdgeDetector', {
+    colorModel: ImageColorModel.GREY,
+  });
+
+  const width = image.width;
+  const height = image.height;
+
+  const blurred = image.gaussianBlur(gaussianBlurOptions);
+
+  const gradientX = blurred.rawDirectConvolution(kernelY);
+  const gradientY = blurred.rawDirectConvolution(kernelX);
+
+  let gradient = new Float64Array(image.size);
+  for (let i = 0; i < image.size; i++) {
+    gradient[i] = Math.hypot(gradientX[i], gradientY[i]);
+  }
+
+  let nonMaxSuppression = new Float64Array(image.size);
+  let edges = new Float64Array(image.size);
+
+  const finalImage = imageToOutputMask(image, options);
+
+  // Non-Maximum suppression
+  for (let column = 1; column < width - 1; column++) {
+    for (let row = 1; row < height - 1; row++) {
+      const currentGradientX = gradientX[getIndex(row, column, 0, image)];
+      const currentGradientY = gradientY[getIndex(row, column, 0, image)];
+      let direction = getDirection(currentGradientX, currentGradientY);
+      const currentGradient = gradient[getIndex(row, column, 0, image)];
+      if (
+        // horizontal
+        (direction === 0 &&
+          currentGradient >= gradient[getIndex(row - 1, column, 0, image)] &&
+          currentGradient >= gradient[getIndex(row + 1, column, 0, image)]) ||
+        // upward slope
+        (direction === 1 &&
+          currentGradient >=
+            gradient[getIndex(row - 1, column - 1, 0, image)] &&
+          currentGradient >=
+            gradient[getIndex(row + 1, column + 1, 0, image)]) ||
+        // vertical
+        (direction === 2 &&
+          currentGradient >= gradient[getIndex(row, column - 1, 0, image)] &&
+          currentGradient >= gradient[getIndex(row, column + 1, 0, image)]) ||
+        // downward slope
+        (direction === 3 &&
+          currentGradient >=
+            gradient[getIndex(row + 1, column - 1, 0, image)] &&
+          currentGradient >= gradient[getIndex(row - 1, column + 1, 0, image)])
+      ) {
+        // pixels to remove from the final image
+        nonMaxSuppression[getIndex(row, column, 0, image)] = currentGradient;
+      }
+    }
+  }
+
+  for (let i = 0; i < width * height; ++i) {
+    let currentNms = nonMaxSuppression[i];
+    let currentEdge = 0;
+    if (currentNms > maxValue) {
+      currentEdge++;
+      finalImage.setBitByIndex(i, 1);
+    }
+    if (currentNms > minValue) {
+      currentEdge++;
+    }
+
+    edges[i] = currentEdge;
+  }
+
+  // Hysteresis: first pass
+  if (hysteresis) {
+    let currentPixels: number[][] = [];
+    for (let column = 1; column < width - 1; ++column) {
+      for (let row = 1; row < height - 1; ++row) {
+        if (edges[getIndex(row, column, 0, image)] !== 1) {
+          continue;
+        }
+
+        outer: for (
+          let hystColumn = column - 1;
+          hystColumn < column + 2;
+          ++hystColumn
+        ) {
+          for (let hystRow = row - 1; hystRow < row + 2; ++hystRow) {
+            if (edges[getIndex(hystRow, hystColumn, 0, image)] === 2) {
+              currentPixels.push([column, row]);
+              finalImage.setValue(row, column, 0, 1);
+              break outer;
+            }
+          }
+        }
+      }
+    }
+
+    // Hysteresis: second pass
+    while (currentPixels.length > 0) {
+      let newPixels = [];
+      for (let currentPixel of currentPixels) {
+        for (let j = -1; j < 2; ++j) {
+          for (let k = -1; k < 2; ++k) {
+            if (j === 0 && k === 0) {
+              continue;
+            }
+            let row = currentPixel[0] + j;
+            let column = currentPixel[1] + k;
+            if (
+              // there could be an error here
+              edges[getIndex(row, column, 0, image)] === 1 &&
+              finalImage.getValue(row, column, 0) === 0
+            ) {
+              newPixels.push([row, column]);
+              finalImage.setValue(row, column, 0, 1);
+            }
+          }
+        }
+      }
+      currentPixels = newPixels;
+    }
+  }
+
+  return finalImage;
+
+  /* Function for debug
+  import { Matrix } from 'ml-matrix';
+
+  function printArray(array: Float64Array): void {
+    // @ts-expect-error: only for debug
+    const matrix = Matrix.from1DArray(height, width, array);
+    console.log(matrix);
+  }
+  */
+}
+
+/**
+ * Return a 0 to 3 value indicating the four main directions (horizontal, upward diagonal, vertical, downward diagonal).
+ *
+ * @param x - The x coordinate
+ * @param y - The y coordinate
+ * @returns The direction as a 0 to 4 value.
+ */
+export function getDirection(x: number, y: number): number {
+  return (Math.round(Math.atan2(y, x) * (4 / Math.PI)) + 4) % 4;
+}

package/src/morphology/clearBorder.ts

@@ -0,0 +1,116 @@
+import { Mask } from '..';
+import { borderIterator } from '../utils/borderIterator';
+import { maskToOutputMask } from '../utils/getOutputImage';
+
+export interface ClearBorderOptions {
+  /**
+   * 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 Uint16Array(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 image - The mask to process.
+ * @param options - Clear border options.
+ * @returns The image with cleared borders.
+ */
+export function clearBorder(
+  image: Mask,
+  options: ClearBorderOptions = {},
+): Mask {
+  let { allowCorners = false } = options;
+
+  // toProcess.fill(0);
+
+  let newImage = maskToOutputMask(image, options, { clone: true });
+
+  const maxValue = image.maxValue;
+
+  let from = 0;
+  let to = 0;
+
+  // find relevant border pixels
+  for (let pixelIndex of borderIterator(image)) {
+    if (newImage.getBitByIndex(pixelIndex) === maxValue) {
+      toProcess[to++ % MAX_ARRAY] = pixelIndex;
+      newImage.setBitByIndex(pixelIndex, 0);
+    }
+  }
+
+  // find pixels connected to the border pixels
+  while (from < to) {
+    const currentPixel = toProcess[from++ % MAX_ARRAY];
+    newImage.setBitByIndex(currentPixel, 0);
+    if (to - from > MAX_ARRAY) {
+      throw new Error(
+        'clearBorder: could not process image, overflow in the data processing array.',
+      );
+    }
+
+    // check if pixel is on a border
+    const topBorder = currentPixel < image.width;
+    const leftBorder = currentPixel % image.width === 0;
+    const rightBorder = currentPixel % image.width === image.width - 1;
+    const bottomBorder = currentPixel > image.size - image.width;
+
+    // check neighbours
+
+    if (!bottomBorder) {
+      const bottom = currentPixel + image.width;
+      addToProcess(bottom);
+    }
+    if (!leftBorder) {
+      const left = currentPixel - 1;
+      addToProcess(left);
+    }
+    if (!topBorder) {
+      const top = currentPixel - image.width;
+      addToProcess(top);
+    }
+    if (!rightBorder) {
+      const right = currentPixel + 1;
+      addToProcess(right);
+    }
+    if (allowCorners) {
+      if (!topBorder) {
+        if (!leftBorder) {
+          const topLeft = currentPixel - image.width - 1;
+          addToProcess(topLeft);
+        }
+        if (!rightBorder) {
+          const topRight = currentPixel - image.width + 1;
+          addToProcess(topRight);
+        }
+      }
+      if (!bottomBorder) {
+        if (!leftBorder) {
+          const bottomLeft = currentPixel + image.width - 1;
+          addToProcess(bottomLeft);
+        }
+        if (!rightBorder) {
+          const bottomRight = currentPixel + image.width + 1;
+          addToProcess(bottomRight);
+        }
+      }
+    }
+  }
+
+  return newImage;
+
+  function addToProcess(pixel: number): void {
+    if (newImage.getBitByIndex(pixel) === image.maxValue) {
+      toProcess[to++ % MAX_ARRAY] = pixel;
+    }
+  }
+}