image-js 1.0.0-alpha.3 → 1.1.0

package/src/roi/roi.types.ts

@@ -0,0 +1,23 @@
+import type { Point } from '../utils/geometry/points.js';
+
+export interface Ellipse {
+  center: {
+    column: number;
+    row: number;
+  };
+  majorAxis: { points: [Point, Point]; length: number; angle: number };
+
+  minorAxis: { points: [Point, Point]; length: number; angle: number };
+  surface: number;
+}
+
+export interface Border {
+  /**
+   * Refers  to the roiID of the contiguous ROI.
+   */
+  connectedID: number;
+  /**
+   * Length of the border with connectedID.
+   */
+  length: number;
+}

package/src/roi/utils/colorMaps/getBinaryMap.ts

@@ -0,0 +1,67 @@
+import type { RoiKind } from '../../getRois.js';
+import { hsvToRgb } from '../hsvToRgb.js';
+import { rgbToNumber } from '../rgbToNumber.js';
+
+// warning: the values in a uint32 array are flipped!! e.g. [0,0,0,1] becomes 0x01000000
+// the bits values are therefore in the following order: ABGR
+// index 32768 corresponds to the middle of the array
+
+export interface GetBinaryMapOptions {
+  /**
+   * Number of black ROIs.
+   */
+  nbNegative: number;
+  /**
+   * Number of white ID ROIs.
+   */
+  nbPositive: number;
+  /**
+   * Specify which ROIs to color.
+   * @default `'bw'`
+   */
+  roiKind?: RoiKind;
+  /**
+   * Hue of white ROIs.
+   * @default `120`
+   */
+  whiteHue?: number;
+  /**
+   * Hue of black ROIs.
+   * @default `0`
+   */
+  blackHue?: number;
+}
+
+/**
+ * Return a map where ROIs are red (negative) or green (positive) depending on the ROI index.
+ * @param options - Color maps options.
+ * @returns The colored map.
+ */
+export function getBinaryMap(options: GetBinaryMapOptions): Uint32Array {
+  const {
+    nbNegative,
+    nbPositive,
+    whiteHue = 120,
+    blackHue = 0,
+    roiKind = 'bw',
+  } = options;
+
+  const colorMap = new Uint32Array(nbNegative + nbPositive + 1);
+
+  // negative values
+  if (roiKind === 'bw' || roiKind === 'black') {
+    for (let i = -nbNegative; i < 0; i++) {
+      const hsv = [blackHue, 255, 255];
+      colorMap[i + nbNegative] = rgbToNumber(hsvToRgb(hsv));
+    }
+  }
+  if (roiKind === 'bw' || roiKind === 'white') {
+    // positive values
+    for (let i = 1; i <= nbPositive; i++) {
+      const hsv = [whiteHue, 255, 255];
+      colorMap[i + nbNegative] = rgbToNumber(hsvToRgb(hsv));
+    }
+  }
+
+  return colorMap;
+}

package/src/roi/utils/colorMaps/getRainbowMap.ts

@@ -0,0 +1,59 @@
+import { match } from 'ts-pattern';
+
+import type { RoiKind } from '../../getRois.js';
+import { hsvToRgb } from '../hsvToRgb.js';
+import { rgbToNumber } from '../rgbToNumber.js';
+
+export interface GetRainbowMapOptions {
+  /**
+   * Number of black ROIs.
+   */
+  nbNegative: number;
+  /**
+   * Number of white ID ROIs.
+   */
+  nbPositive: number;
+  /**
+   * Specify which ROIs to color.
+   * @default `'bw'`
+   */
+  roiKind?: RoiKind;
+}
+
+/**
+ * Return a map where ROIs are all different hues.
+ * @param options - Get temperature map options.
+ * @returns The colored map.
+ */
+export function getRainbowMap(options: GetRainbowMapOptions): Uint32Array {
+  const { nbNegative, nbPositive, roiKind = 'bw' } = options;
+
+  const colorMap = new Uint32Array(nbNegative + nbPositive + 1);
+
+  const hueRange = 360;
+
+  const step = match(roiKind)
+    .with('bw', () => hueRange / (nbNegative + nbPositive))
+    .with('black', () => hueRange / nbNegative)
+    .with('white', () => hueRange / nbPositive)
+    .exhaustive();
+
+  // negative values
+  let hue = 0;
+  if (roiKind === 'bw' || roiKind === 'black') {
+    for (let i = -nbNegative; i < 0; i++) {
+      const hsv = [hue, 255, 255];
+      colorMap[i + nbNegative] = rgbToNumber(hsvToRgb(hsv));
+      hue += step;
+    }
+  }
+  // positive values
+  if (roiKind === 'bw' || roiKind === 'white') {
+    for (let i = 1; i <= nbPositive; i++) {
+      const hsv = [hue, 255, 255];
+      colorMap[i + nbNegative] = rgbToNumber(hsvToRgb(hsv));
+      hue += step;
+    }
+  }
+  return colorMap;
+}

package/src/roi/utils/colorMaps/getSaturationMap.ts

@@ -0,0 +1,70 @@
+import type { RoiKind } from '../../getRois.js';
+import { hsvToRgb } from '../hsvToRgb.js';
+import { rgbToNumber } from '../rgbToNumber.js';
+
+export interface GetSaturationMapOptions {
+  /**
+   * Number of black ROIs.
+   */
+  nbNegative: number;
+  /**
+   * Number of white ID ROIs.
+   */
+  nbPositive: number;
+  /**
+   * Specify which ROIs to color.
+   * @default `'bw'`
+   */
+  roiKind?: RoiKind;
+  /**
+   * Hue of white ROIs.
+   *  @default `0`
+   */
+  whiteHue?: number;
+  /**
+   * Hue of black ROIs.
+   * @default `240`
+   */
+  blackHue?: number;
+}
+
+/**
+ * Return a map where ROIs are different shades of red (positive) or blue (negative) depending on the ROI index. It it the saturation of the HSV color model that is varied.
+ * @param options - Get temperature map options.
+ * @returns The colored map.
+ */
+export function getSaturationMap(
+  options: GetSaturationMapOptions,
+): Uint32Array {
+  const {
+    nbNegative,
+    nbPositive,
+    roiKind = 'bw',
+    whiteHue = 0,
+    blackHue = 240,
+  } = options;
+
+  const colorMap = new Uint32Array(nbNegative + nbPositive + 1);
+
+  const range = 255 - 63; // saturation range for good contrast
+  const negativeStep = range / nbNegative;
+  const positiveStep = range / nbPositive;
+
+  // negative values
+  let counter = 0;
+  if (roiKind === 'bw' || roiKind === 'black') {
+    for (let i = -nbNegative; i < 0; i++) {
+      const hsv = [blackHue, 255 - counter++ * negativeStep, 255];
+      colorMap[i + nbNegative] = rgbToNumber(hsvToRgb(hsv));
+    }
+  }
+  // positive values
+  counter = 0;
+  if (roiKind === 'bw' || roiKind === 'white') {
+    for (let i = 1; i <= nbPositive; i++) {
+      const hsv = [whiteHue, 255 - counter++ * positiveStep, 255];
+      colorMap[i + nbNegative] = rgbToNumber(hsvToRgb(hsv));
+    }
+  }
+  return colorMap;
+}

package/src/roi/utils/getColorMap.ts

@@ -0,0 +1,46 @@
+import { match } from 'ts-pattern';
+
+import type { RoisColorMode } from '../colorRois.js';
+import type { RoiKind } from '../getRois.js';
+
+import { getBinaryMap } from './colorMaps/getBinaryMap.js';
+import { getRainbowMap } from './colorMaps/getRainbowMap.js';
+import { getSaturationMap } from './colorMaps/getSaturationMap.js';
+
+export interface GetColorMapOptions {
+  /**
+   * Number of black ROIs.
+   */
+  nbNegative: number;
+  /**
+   * Number of white ID ROIs.
+   */
+  nbPositive: number;
+  /**
+   * Specify the mode: what colors to use in the color map.
+   * @default `'binary'`
+   */
+  mode?: RoisColorMode;
+
+  /**
+   * Specify which ROIs to color.
+   * @default `'bw'`
+   */
+  roiKind?: RoiKind;
+}
+
+/**
+ * Return a map of 32 bits integers corresponding to the colors of each ROI.
+ * @param options - Get color map options.
+ * @returns The color map.
+ */
+export function getColorMap(options: GetColorMapOptions): Uint32Array {
+  const { mode = 'binary' } = options;
+  options = { roiKind: 'bw', ...options };
+
+  return match(mode)
+    .with('binary', () => getBinaryMap(options))
+    .with('saturation', () => getSaturationMap(options))
+    .with('rainbow', () => getRainbowMap(options))
+    .exhaustive();
+}

package/src/roi/utils/hsvToRgb.ts

@@ -0,0 +1,61 @@
+export interface HsvColor {
+  h: number;
+  s: number;
+  v: number;
+}
+export interface RgbColor {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/**
+ * Convert HSV (hue, saturation, value) color code to RGB.
+ * - Hue: angle in the color wheel (from red to purple), in range 0-359.
+ * - Saturation: how strong the color is (from white to bright color), in range 0-255.
+ * - Value: basically the brightness (from black to intense color), in range 0-255.
+ * @param hsv - The HSV color.
+ * @returns The RGB color.
+ */
+export function hsvToRgb(hsv: number[]): Uint8Array {
+  const h = hsv[0];
+  const s = hsv[1] / 255;
+  const v = hsv[2] / 255;
+  const C = s * v;
+  const X = C * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = v - C;
+
+  let r, g, b;
+
+  if (h >= 0 && h < 60) {
+    r = C;
+    g = X;
+    b = 0;
+  } else if (h >= 60 && h < 120) {
+    r = X;
+    g = C;
+    b = 0;
+  } else if (h >= 120 && h < 180) {
+    r = 0;
+    g = C;
+    b = X;
+  } else if (h >= 180 && h < 240) {
+    r = 0;
+    g = X;
+    b = C;
+  } else if (h >= 240 && h < 300) {
+    r = X;
+    g = 0;
+    b = C;
+  } else {
+    r = C;
+    g = 0;
+    b = X;
+  }
+
+  const rgb = new Uint8Array(3);
+  rgb[0] = (r + m) * 255;
+  rgb[1] = (g + m) * 255;
+  rgb[2] = (b + m) * 255;
+  return rgb;
+}

package/src/roi/utils/rgbToNumber.ts

@@ -0,0 +1,8 @@
+/**
+ * Convert RGB array to 32 bits number where alpha is set to 255.
+ * @param rgb - The RGB color array.
+ * @returns 32 bits number encoding RGBA color.
+ */
+export function rgbToNumber(rgb: Uint8Array): number {
+  return 0xff000000 + (rgb[2] << 16) + (rgb[1] << 8) + rgb[0];
+}

package/src/roi/waterShed.ts

@@ -0,0 +1,146 @@
+import PriorityQueue from 'js-priority-queue';
+
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import { getExtrema } from '../compute/index.js';
+import type { Point } from '../geometry/index.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+import { RoiMapManager } from './RoiMapManager.js';
+
+/**
+ * Point interface that is used in the queue data structure.
+ */
+interface PointWithIntensity {
+  /**
+   * @param row - Row of a point.
+   */
+  row: number;
+  /**
+   * @param column - Column of a point.
+   */
+  column: number;
+  /**
+   * @param intensity - Value of a point.
+   */
+  intensity: number;
+}
+
+export interface WaterShedOptions {
+  /**
+   * @param points - Points which should be filled by watershed filter.
+   * @default - minimum points from getExtrema() function.
+   */
+  points?: Point[];
+  /**
+   * @param mask - A binary image, the same size as the image. The algorithm will fill only if the current pixel in the binary mask is not null.
+   * @default undefined
+   */
+  mask?: Mask;
+  /**
+   * @param threshold - Limit of filling. Maximum value that pixel can have.
+   * @default 1
+   */
+  threshold?: number;
+}
+/**
+ * This method allows to create a ROIMap using the water shed algorithm. By default this algorithm
+ * will fill the holes and therefore the lowest value of the image (black zones).
+ * If no points are given, the function will look for all the minimal points.
+ * If no mask is given the algorithm will completely fill the image.
+ * Please take care about the value that has be in the mask ! In order to be coherent with the expected mask,
+ * meaning that if it is a dark zone, the mask will be dark the normal behavior to fill a zone
+ * is that the mask pixel is clear (value of 0) !
+ * If you are looking for 'maxima' the image must be inverted before applying the algorithm
+ * @param image - Image that the filter will be applied to.
+ * @param options - WaterShedOptions
+ * @returns RoiMapManager
+ */
+export function waterShed(
+  image: Image,
+  options: WaterShedOptions,
+): RoiMapManager {
+  let { points } = options;
+  const { mask, threshold = 1 } = options;
+  const currentImage = image;
+  checkProcessable(image, {
+    bitDepth: [8, 16],
+    components: 1,
+  });
+
+  const fillMaxValue = threshold * image.maxValue;
+
+  // WaterShed is done from points in the image. We can either specify those points in options,
+  // or it is gonna take the minimum locals of the image by default.
+  if (!points) {
+    points = getExtrema(image, {
+      kind: 'minimum',
+      mask,
+    });
+  }
+
+  const maskExpectedValue = 0;
+
+  const data = new Int32Array(currentImage.size);
+  const width = currentImage.width;
+  const height = currentImage.height;
+  const toProcess = new PriorityQueue({
+    comparator: (a: PointWithIntensity, b: PointWithIntensity) =>
+      a.intensity - b.intensity,
+    strategy: PriorityQueue.BinaryHeapStrategy,
+  });
+  for (let i = 0; i < points.length; i++) {
+    const index = points[i].column + points[i].row * width;
+    data[index] = -i - 1;
+    const intensity = currentImage.getValueByIndex(index, 0);
+    if (intensity <= fillMaxValue) {
+      toProcess.queue({
+        column: points[i].column,
+        row: points[i].row,
+        intensity,
+      });
+    }
+  }
+  const dxs = [1, 0, -1, 0, 1, 1, -1, -1];
+  const dys = [0, 1, 0, -1, 1, -1, 1, -1];
+  // Then we iterate through each points
+
+  while (toProcess.length > 0) {
+    const currentPoint = toProcess.dequeue();
+    const currentValueIndex = currentPoint.column + currentPoint.row * width;
+    for (let dir = 0; dir < 4; dir++) {
+      const newX = currentPoint.column + dxs[dir];
+      const newY = currentPoint.row + dys[dir];
+      if (newX >= 0 && newY >= 0 && newX < width && newY < height) {
+        const currentNeighbourIndex = newX + newY * width;
+        if (
+          !mask ||
+          mask.getBitByIndex(currentNeighbourIndex) === maskExpectedValue
+        ) {
+          const intensity = currentImage.getValueByIndex(
+            currentNeighbourIndex,
+            0,
+          );
+          if (intensity <= fillMaxValue && data[currentNeighbourIndex] === 0) {
+            data[currentNeighbourIndex] = data[currentValueIndex];
+            toProcess.queue({
+              column: currentPoint.column + dxs[dir],
+              row: currentPoint.row + dys[dir],
+              intensity,
+            });
+          }
+        }
+      }
+    }
+  }
+  const nbNegative = points.length;
+  const nbPositive = 0;
+
+  return new RoiMapManager({
+    data,
+    nbPositive,
+    nbNegative,
+    width: image.width,
+    height: image.height,
+  });
+}

package/src/save/encode.ts

@@ -1,55 +1,53 @@
-import { Image } from '../Image';
+import { P, match } from 'ts-pattern';
 
-import { encodePng, IEncodePngOptions } from './encodePng';
-import { encodeJpeg, IEncodeJpegOptions } from './encodeJpeg';
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
 
-export enum ImageFormat {
-  png = 'png',
-  jpg = 'jpg',
-  jpeg = 'jpeg'
-}
+import { encodeBmp } from './encodeBmp.js';
+import type { EncodeJpegOptions } from './encodeJpeg.js';
+import { encodeJpeg } from './encodeJpeg.js';
+import type { EncodePngOptions } from './encodePng.js';
+import { encodePng } from './encodePng.js';
+
+export const ImageFormat = {
+  PNG: 'png',
+  JPG: 'jpg',
+  JPEG: 'jpeg',
+  BMP: 'bmp',
+} as const;
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type ImageFormat = (typeof ImageFormat)[keyof typeof ImageFormat];
 
-export interface IEncodeOptionsPng {
-  format: ImageFormat.png;
-  encoderOptions?: IEncodePngOptions;
+export interface EncodeOptionsPng {
+  format: 'png';
+  encoderOptions?: EncodePngOptions;
 }
-export interface IEncodeOptionsJpeg {
-  format: ImageFormat.jpg | ImageFormat.jpeg;
-  encoderOptions?: IEncodeJpegOptions;
+export interface EncodeOptionsJpeg {
+  format: 'jpg' | 'jpeg';
+  encoderOptions?: EncodeJpegOptions;
 }
+export interface EncodeOptionsBmp {
+  format: 'bmp';
+}
+export const defaultPng: EncodeOptionsPng = { format: 'png' };
 
-const defaultPng: IEncodeOptionsPng = { format: ImageFormat.png };
-
-/**
- * Encodes the image to an output format.
- * Defaults to PNG.
- * @param image - Image to encode.
- */
-export function encode(image: Image): Uint8Array;
-/**
- * Encodes the image to PNG.
- * @param image - Image to encode.
- * @param options - Format and options passed to the PNG encoder.
- */
-export function encode(image: Image, options: IEncodeOptionsPng): Uint8Array;
 /**
- * Encodes the image to JPEG.
+ * Encodes the image to the specified format
  * @param image - Image to encode.
- * @param options - Format and options passed to the JPEG encoder.
+ * @param options - Format and options passed to the encoder.
+ * @returns The encoded image.
  */
-export function encode(image: Image, options: IEncodeOptionsJpeg): Uint8Array;
 export function encode(
-  image: Image,
-  options: IEncodeOptionsPng | IEncodeOptionsJpeg = defaultPng
+  image: Image | Mask,
+  options: EncodeOptionsBmp | EncodeOptionsPng | EncodeOptionsJpeg = defaultPng,
 ): Uint8Array {
-  if (options.format === ImageFormat.png) {
-    return encodePng(image, options.encoderOptions);
-  } else if (
-    options.format === ImageFormat.jpg ||
-    options.format === ImageFormat.jpeg
-  ) {
-    return encodeJpeg(image, options.encoderOptions);
-  } else {
-    throw new RangeError(`unknown format: ${options.format}`);
-  }
+  return match(options)
+    .with({ format: 'png' }, (options) =>
+      encodePng(image, options.encoderOptions),
+    )
+    .with({ format: P.union('jpg', 'jpeg') }, (options) =>
+      encodeJpeg(image, options.encoderOptions),
+    )
+    .with({ format: 'bmp' }, () => encodeBmp(image))
+    .exhaustive();
 }

package/src/save/encodeBmp.ts

@@ -0,0 +1,31 @@
+import * as bmp from 'fast-bmp';
+
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+
+/**
+ * Creates a BMP buffer from a mask.
+ * @param image - The mask instance.
+ * @returns The buffer.
+ */
+export function encodeBmp(image: Image | Mask) {
+  if (image instanceof Image) {
+    return bmp.encode({
+      width: image.width,
+      height: image.height,
+      components: image.components,
+      bitsPerPixel: image.channels * image.bitDepth,
+      channels: image.channels,
+      data: image.getRawImage().data,
+    });
+  } else {
+    return bmp.encode({
+      width: image.width,
+      height: image.height,
+      components: 1,
+      bitsPerPixel: 1,
+      channels: 1,
+      data: image.getRawImage().data,
+    });
+  }
+}

package/src/save/encodeDataURL.ts

@@ -0,0 +1,25 @@
+import { encode as uint8encode } from 'uint8-base64';
+
+import type { Image } from '../Image.js';
+
+import type {
+  EncodeOptionsBmp,
+  EncodeOptionsJpeg,
+  EncodeOptionsPng,
+} from './encode.js';
+import { defaultPng, encode } from './encode.js';
+/**
+ * Converts image into Data URL string.
+ * @param image - Image to get base64 encoding from.
+ * @param options - Encoding options.
+ * @returns base64 string.
+ */
+export function encodeDataURL(
+  image: Image,
+  options: EncodeOptionsBmp | EncodeOptionsPng | EncodeOptionsJpeg = defaultPng,
+) {
+  const buffer = encode(image, options);
+  const base64 = uint8encode(buffer);
+  const base64Data = new TextDecoder().decode(base64);
+  return `data:image/${options.format};base64,${base64Data}`;
+}

package/src/save/encodeJpeg.ts

@@ -1,26 +1,35 @@
 import { encode } from 'jpeg-js';
 
-import { Image, ImageKind, ColorDepth } from '../Image';
+import type { Image } from '../Image.js';
+import { Mask } from '../Mask.js';
 
-export interface IEncodeJpegOptions {
+export interface EncodeJpegOptions {
+  /**
+   * Defines jpeg quality. Integer value between 1 and 100%, 100% being the best quality.
+   * @default `50`
+   */
   quality?: number;
 }
 
+/**
+ * Creates a JPEG buffer from an image.
+ * @param image - The image instance.
+ * @param options - JPEG encoding options.
+ * @returns The buffer.
+ */
 export function encodeJpeg(
-  image: Image,
-  options: IEncodeJpegOptions = {}
+  image: Image | Mask,
+  options: EncodeJpegOptions = {},
 ): Uint8Array {
   const { quality = 50 } = options;
-
-  if (image.kind !== ImageKind.RGBA) {
-    image = image.convertColor(ImageKind.RGBA);
+  if (image.colorModel !== 'RGBA' || image instanceof Mask) {
+    image = image.convertColor('RGBA');
   }
-  if (image.depth !== ColorDepth.UINT8) {
-    image = image.convertDepth(ColorDepth.UINT8);
+  if (image.bitDepth !== 8) {
+    image = image.convertBitDepth(8);
   }
 
-  // Image data after depth conversion will always be UInt8Array
-  // @ts-ignore
-  const buffer = encode(image, quality).data;
-  return new Uint8Array(buffer, buffer.byteOffset, buffer.byteLength);
+  // Image data after bit depth conversion will always be UInt8Array.
+  const buffer = encode(image.getRawImage(), quality).data;
+  return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
 }