image-js 1.0.0-alpha.3 → 1.0.0

package/src/operations/grey.ts

@@ -0,0 +1,139 @@
+import type { Image } from '../Image.js';
+import { getClamp } from '../utils/clamp.js';
+import type { ImageColorModel } from '../utils/constants/colorModels.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+import { assert } from '../utils/validators/assert.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+import * as greyAlgorithms from './greyAlgorithms.js';
+
+export const GreyAlgorithm = {
+  LUMA_709: 'luma709',
+  LUMA_601: 'luma601',
+  MAX: 'max',
+  MIN: 'min',
+  AVERAGE: 'average',
+  MINMAX: 'minmax',
+  RED: 'red',
+  GREEN: 'green',
+  BLUE: 'blue',
+  BLACK: 'black',
+  CYAN: 'cyan',
+  MAGENTA: 'magenta',
+  YELLOW: 'yellow',
+  HUE: 'hue',
+  SATURATION: 'saturation',
+  LIGHTNESS: 'lightness',
+} as const satisfies Record<string, keyof typeof greyAlgorithms>;
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type GreyAlgorithm = (typeof GreyAlgorithm)[keyof typeof GreyAlgorithm];
+
+{
+  // Check that all the algorithms are in the enum.
+  const algos = new Set<string>(Object.values(GreyAlgorithm));
+  for (const algo of Object.keys(greyAlgorithms)) {
+    assert(
+      algos.has(algo),
+      `Grey algorithm ${algo} is missing in the GreyAlgorithm enum`,
+    );
+  }
+}
+
+/**
+ * Call back that converts the RGB channels to grey. It is clamped afterwards.
+ * @callback GreyAlgorithmCallback
+ * @param {number} red - Value of the red channel.
+ * @param {number} green - Value of the green channel.
+ * @param {number} blue - Value of the blue channel.
+ * @returns {number} Value of the grey channel.
+ */
+export type GreyAlgorithmCallback = (
+  red: number,
+  green: number,
+  blue: number,
+  image: Image,
+) => number;
+
+export interface GreyOptions {
+  /**
+   * Specify the grey algorithm to use.
+   * @default `'luma709'`
+   */
+  algorithm?: GreyAlgorithm | GreyAlgorithmCallback;
+  /**
+   * Specify wether to keep an alpha channel in the new image or not.
+   * @default `false`
+   */
+  keepAlpha?: boolean;
+  /**
+   * Specify wether to merge the alpha channel with the gray pixel or not.
+   * @default `true`
+   */
+  mergeAlpha?: boolean;
+  /**
+   * Image to which to output.
+   */
+  out?: Image;
+}
+
+/**
+ * Convert the current image to grayscale.
+ * The source image has to be RGB or RGBA.
+ * If there is an alpha channel you have to specify what to do:
+ * - keepAlpha :  keep the alpha channel, you will get a GREYA image.
+ * - mergeAlpha : multiply each pixel of the image by the alpha, you will get a GREY image.
+ * @param image - Original color image to convert to grey.
+ * @param options - The grey conversion options.
+ * @returns The resulting grey image.
+ */
+export function grey(image: Image, options: GreyOptions = {}): Image {
+  let { keepAlpha = false, mergeAlpha = true } = options;
+  const { algorithm = 'luma709' } = options;
+
+  checkProcessable(image, {
+    colorModel: ['RGB', 'RGBA'],
+  });
+
+  keepAlpha = keepAlpha && image.alpha;
+  mergeAlpha = mergeAlpha && image.alpha;
+  if (keepAlpha) {
+    mergeAlpha = false;
+  }
+
+  const newColorModel: ImageColorModel = keepAlpha ? 'GREYA' : 'GREY';
+
+  const newImage = getOutputImage(image, options, {
+    newParameters: { colorModel: newColorModel },
+  });
+
+  let method: GreyAlgorithmCallback;
+  if (typeof algorithm === 'function') {
+    method = algorithm;
+  } else {
+    method = greyAlgorithms[algorithm];
+  }
+
+  const clamp = getClamp(newImage);
+
+  for (let i = 0; i < image.size; i++) {
+    const red = image.getValueByIndex(i, 0);
+    const green = image.getValueByIndex(i, 1);
+    const blue = image.getValueByIndex(i, 2);
+    let newValue;
+    if (mergeAlpha) {
+      const alpha = image.getValueByIndex(i, 3);
+      newValue = clamp(
+        (method(red, green, blue, image) * alpha) / image.maxValue,
+      );
+    } else {
+      newValue = clamp(method(red, green, blue, image));
+      if (keepAlpha) {
+        const alpha = image.getValueByIndex(i, 3);
+        newImage.setValueByIndex(i, 1, alpha);
+      }
+    }
+    newImage.setValueByIndex(i, 0, newValue);
+  }
+
+  return newImage;
+}

package/src/operations/greyAlgorithms.ts

@@ -0,0 +1,248 @@
+import type { Image } from '../Image.js';
+import { assert } from '../utils/validators/assert.js';
+
+/**
+ * Converts R, G and B values to a single value using Luma 709 standard({@link https://en.wikipedia.org/wiki/Luma_(video)}).
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @returns - Corresponding gray value.
+ */
+export function luma709(red: number, green: number, blue: number): number {
+  // sRGB
+  // return red * 0.2126 + green * 0.7152 + blue * 0.0722;
+  // Let's do a little trick ... in order not convert the integer to a double we do
+  // the multiplication with integer to reach a total of 32768 and then shift the bits
+  // of 15 to the right
+  // This does a Math.floor and may lead to small (max 1) difference
+  // Same result, > 10% faster on the full grey conversion
+  return (red * 6966 + green * 23436 + blue * 2366) >> 15;
+}
+/**
+ *  Converts R, G and B values to a single value using Luma 601 standard({@link https://en.wikipedia.org/wiki/Luma_(video)}).
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @returns - Corresponding gray value.
+ */
+export function luma601(red: number, green: number, blue: number): number {
+  // NTSC
+  // return this.red * 0.299 + green * 0.587 + blue * 0.114;
+  return (red * 9798 + green * 19235 + blue * 3735) >> 15;
+}
+/**
+ * Return the maximal value between red, green and blue.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @returns - Corresponding gray value.
+ */
+export function max(red: number, green: number, blue: number): number {
+  return Math.max(red, green, blue);
+}
+/**
+ * Return the minimal value between red, green and blue.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @returns - Corresponding gray value.
+ */
+export function min(red: number, green: number, blue: number): number {
+  return Math.min(red, green, blue);
+}
+/**
+ * Return the average of red, green and blue.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @returns - Corresponding gray value.
+ */
+export function average(red: number, green: number, blue: number): number {
+  return ((red + green + blue) / 3) >> 0;
+}
+/**
+ * Return the average between the max and min values of red, green and blue.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @returns - Corresponding gray value.
+ */
+export function minmax(red: number, green: number, blue: number): number {
+  return (Math.max(red, green, blue) + Math.min(red, green, blue)) / 2;
+}
+/**
+ * Return the red value.
+ * @param red - Red value of current pixel.
+ * @returns - Corresponding gray value.
+ */
+export function red(red: number): number {
+  return red;
+}
+/**
+ * Return the green value.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @returns - Corresponding gray value.
+ */
+export function green(red: number, green: number): number {
+  return green;
+}
+/**
+ * Return the blue value.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @returns - Corresponding gray value.
+ */
+export function blue(red: number, green: number, blue: number): number {
+  return blue;
+}
+/**
+ * Return the minimum of the inverses of red, green and blue.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @param image - Image to convert to grey.
+ * @returns - Corresponding gray value.
+ */
+export function black(
+  red: number,
+  green: number,
+  blue: number,
+  image: Image,
+): number {
+  return Math.min(
+    image.maxValue - red,
+    image.maxValue - green,
+    image.maxValue - blue,
+  );
+}
+/**
+ * Returns the cyan component of a pixel.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @param image - Image to convert to grey.
+ * @returns - Corresponding gray value.
+ */
+export function cyan(
+  red: number,
+  green: number,
+  blue: number,
+  image: Image,
+): number {
+  const blackColor = black(red, green, blue, image);
+  return (
+    ((image.maxValue - red - blackColor) / (1 - blackColor / image.maxValue)) >>
+    0
+  );
+}
+/**
+ * Returns the magenta component of a pixel.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @param image - Image to convert to grey.
+ * @returns - Corresponding gray value.
+ */
+export function magenta(
+  red: number,
+  green: number,
+  blue: number,
+  image: Image,
+): number {
+  const blackColor = black(red, green, blue, image);
+  return (
+    ((image.maxValue - green - blackColor) /
+      (1 - blackColor / image.maxValue)) >>
+    0
+  );
+}
+/**
+ * Returns the yellow component of a pixel.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @param image - Image to convert to grey.
+ * @returns - Corresponding gray value.
+ */
+export function yellow(
+  red: number,
+  green: number,
+  blue: number,
+  image: Image,
+): number {
+  const blackColor = black(red, green, blue, image);
+  return (
+    ((image.maxValue - blue - blackColor) /
+      (1 - blackColor / image.maxValue)) >>
+    0
+  );
+}
+/**
+ * Returns the hue of a pixel as a value between 0 and 255.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @param image - Source image for the RGB values.
+ * @returns - Hue of the pixel.
+ */
+export function hue(
+  red: number,
+  green: number,
+  blue: number,
+  image: Image,
+): number {
+  const minValue = min(red, green, blue);
+  const maxValue = max(red, green, blue);
+  if (maxValue === minValue) {
+    return 0;
+  }
+  let hue = 0;
+  const delta = maxValue - minValue;
+
+  if (maxValue === red) {
+    hue = (green - blue) / delta + (green < blue ? 6 : 0);
+  } else if (maxValue === green) {
+    hue = (blue - red) / delta + 2;
+  } else {
+    assert(maxValue === blue);
+    hue = (red - green) / delta + 4;
+  }
+
+  return ((hue / 6) * image.maxValue) >> 0;
+}
+
+/**
+ * Returns the saturation component of a pixel.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @param image - Source image for the RGB values.
+ * @returns - Saturation of the pixel.
+ */
+export function saturation(
+  red: number,
+  green: number,
+  blue: number,
+  image: Image,
+): number {
+  // from HSV model
+  const minValue = min(red, green, blue);
+  const maxValue = max(red, green, blue);
+  const delta = maxValue - minValue;
+  return maxValue === 0 ? 0 : (delta / maxValue) * image.maxValue;
+}
+
+/**
+ * Returns the lightness of a pixel.
+ * @param red - Red value of current pixel.
+ * @param green - Green value of current pixel.
+ * @param blue - Blue value of current pixel.
+ * @returns - Lightness of the pixel.
+ */
+export function lightness(red: number, green: number, blue: number): number {
+  const minValue = min(red, green, blue);
+  const maxValue = max(red, green, blue);
+  return (maxValue + minValue) / 2;
+}

package/src/operations/index.ts

@@ -1,5 +1,16 @@
-export * from './convertColor';
-export * from './convertDepth';
-export * from './merge';
-export * from './split';
-export * from './threshold';
+export * from './convertColor.js';
+export * from './convertBitDepth.js';
+export * from './extract.js';
+export * from './merge.js';
+export * from './split.js';
+export * from './threshold.js';
+export * from './grey.js';
+export * from './copyTo.js';
+export * from './crop.js';
+export * from './cropAlpha.js';
+export * from './cropRectangle.js';
+export * from './operations.types.js';
+export * from './paintMaskOnImage.js';
+export * from './paintMaskOnMask.js';
+export * from './correctBackground.js';
+export * from './extendBorders.js';

package/src/operations/merge.ts

@@ -1,48 +1,64 @@
-import { Image, ImageKind } from '../Image';
+import { Image } from '../Image.js';
+import type { ImageColorModel } from '../utils/constants/colorModels.js';
 
 /**
  * Inverse of split. Merges multiple single-channel images into one.
- * @param images An array of single-channel images
+ * @param images - An array of single-channel images.
+ * @returns The merged image.
  */
 export function merge(images: Image[]): Image {
   const channels = images.length;
 
-  let kind: ImageKind;
-  if (channels === 2) {
-    kind = ImageKind.GREYA;
-  } else if (channels === 3) {
-    kind = ImageKind.RGB;
-  } else if (channels === 4) {
-    kind = ImageKind.RGBA;
-  } else {
-    throw new RangeError(
-      `merge expects an array of two to four images. Got ${channels}`
-    );
+  let colorModel: ImageColorModel;
+  switch (channels) {
+    case 2: {
+      colorModel = 'GREYA';
+      break;
+    }
+    case 3: {
+      colorModel = 'RGB';
+      break;
+    }
+    case 4: {
+      colorModel = 'RGBA';
+      break;
+    }
+    default: {
+      throw new RangeError(
+        `merge expects an array of two to four images. Received ${channels}`,
+      );
+    }
   }
 
   const first = images[0];
   if (first.channels !== 1) {
-    throw new Error(`each image must have one channel. Got ${first.channels}`);
+    throw new RangeError(
+      `each image must have one channel. Received ${first.channels}`,
+    );
   }
   for (let i = 1; i < channels; i++) {
     const img = images[i];
     if (img.channels !== 1) {
-      throw new Error(`each image must have one channel. Got ${img.channels}`);
+      throw new RangeError(
+        `each image must have one channel. Received ${img.channels}`,
+      );
     }
     if (
       img.width !== first.width ||
       img.height !== first.height ||
-      img.depth !== first.depth
+      img.bitDepth !== first.bitDepth
     ) {
-      throw new Error('all images must have the same width, height and depth');
+      throw new RangeError(
+        'all images must have the same width, height and bitDepth',
+      );
     }
   }
 
-  const newImage = Image.createFrom(first, { kind });
+  const newImage = Image.createFrom(first, { colorModel });
   for (let c = 0; c < channels; c++) {
     const img = images[c];
-    for (let i = 0; i < newImage.data.length; i += channels) {
-      newImage.data[i + c] = img.data[i / channels];
+    for (let i = 0; i < newImage.size; i++) {
+      newImage.setValueByIndex(i, c, img.getValueByIndex(i, 0));
     }
   }
 

package/src/operations/operations.types.ts

@@ -0,0 +1,6 @@
+export interface CropAlphaOptions {
+  /**
+   * Threshold from which rows and columns should be kept.
+   */
+  threshold?: number;
+}

package/src/operations/paintMaskOnImage.ts

@@ -0,0 +1,111 @@
+import type { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import type { Point } from '../utils/geometry/points.js';
+import { getDefaultColor } from '../utils/getDefaultColor.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+import { setBlendedPixel } from '../utils/setBlendedPixel.js';
+import { checkPointIsInteger } from '../utils/validators/checkPointIsInteger.js';
+
+export interface PaintMaskOnImageOptions {
+  /**
+   * Top-left corner of the mask relative to a parent image.
+   * @default `{row: 0, column: 0}`
+   */
+  origin?: Point;
+  /**
+   * Color with which to blend the image pixel.
+   * @default Opaque black.
+   */
+  color?: Array<number | null>;
+  /**
+   * Whether the given color should be blended with the original pixel.
+   * @default `true`
+   */
+  blend?: boolean;
+  /**
+   * Image to which to output.
+   */
+  out?: Image;
+}
+
+/**
+ * Paint a mask onto an image and the given position and with the given color.
+ * @param image - Image on which to paint the mask.
+ * @param mask - Mask to paint on the image.
+ * @param options - Paint mask options.
+ * @returns The painted image.
+ */
+export function paintMaskOnImage(
+  image: Image,
+  mask: Mask,
+  options: PaintMaskOnImageOptions = {},
+): Image {
+  const {
+    origin = { row: 0, column: 0 },
+    color = getDefaultColor(image),
+    blend = true,
+  } = options;
+  const { column, row } = origin;
+
+  if (color.length !== image.channels) {
+    throw new RangeError('the given color is not compatible with the image');
+  }
+
+  checkPointIsInteger(origin, 'Origin');
+
+  const result = getOutputImage(image, options, { clone: true });
+  if (blend) {
+    checkColorIsNumberArray(color);
+
+    for (
+      let currentRow = Math.max(row, 0);
+      currentRow < Math.min(mask.height + row, image.height);
+      currentRow++
+    ) {
+      for (
+        let currentColumn = Math.max(column, 0);
+        currentColumn < Math.min(mask.width + column, image.width);
+        currentColumn++
+      ) {
+        if (mask.getBit(currentColumn - column, currentRow - row)) {
+          setBlendedPixel(result, currentColumn, currentRow, color);
+        }
+      }
+    }
+  } else {
+    for (
+      let currentRow = Math.max(row, 0);
+      currentRow < Math.min(mask.height + row, image.height);
+      currentRow++
+    ) {
+      for (
+        let currentColumn = Math.max(column, 0);
+        currentColumn < Math.min(mask.width + column, image.width);
+        currentColumn++
+      ) {
+        if (mask.getBit(currentColumn - column, currentRow - row)) {
+          for (let channel = 0; channel < image.channels; channel++) {
+            const currentValue = color[channel];
+            if (typeof currentValue === 'number') {
+              result.setValue(currentColumn, currentRow, channel, currentValue);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+function checkColorIsNumberArray(
+  color: Array<number | null>,
+): asserts color is number[] {
+  for (const channel of color) {
+    if (typeof channel !== 'number') {
+      throw new TypeError(
+        'cannot have null channels in color if blend is true',
+      );
+    }
+  }
+}

package/src/operations/paintMaskOnMask.ts

@@ -0,0 +1,59 @@
+import type { BitValue, Mask } from '../Mask.js';
+import type { Point } from '../utils/geometry/points.js';
+import { maskToOutputMask } from '../utils/getOutputImage.js';
+import { checkPointIsInteger } from '../utils/validators/checkPointIsInteger.js';
+
+export interface PaintMaskOnMaskOptions {
+  /**
+   * Top-left corner of the mask relative to a parent image.
+   * @default `{row: 0, column: 0}`
+   */
+  origin?: Point;
+  /**
+   * Value with which to set the pixel.
+   * @default `1`
+   */
+  value?: BitValue;
+  /**
+   * Mask to which to output.
+   */
+  out?: Mask;
+}
+
+/**
+ * Paint a mask onto an image and the given position and with the given color.
+ * @param image - Image on which to paint the mask.
+ * @param mask - Mask to paint on the image.
+ * @param options - Paint mask options.
+ * @returns The painted image.
+ */
+export function paintMaskOnMask(
+  image: Mask,
+  mask: Mask,
+  options: PaintMaskOnMaskOptions = {},
+): Mask {
+  const { origin = { row: 0, column: 0 }, value = 1 } = options;
+  const { column, row } = origin;
+
+  checkPointIsInteger(origin, 'Origin');
+
+  const result = maskToOutputMask(image, options, { clone: true });
+
+  for (
+    let currentRow = Math.max(row, 0);
+    currentRow < Math.min(mask.height + row, image.height);
+    currentRow++
+  ) {
+    for (
+      let currentColumn = Math.max(column, 0);
+      currentColumn < Math.min(mask.width + column, image.width);
+      currentColumn++
+    ) {
+      if (mask.getBit(currentColumn - column, currentRow - row)) {
+        result.setBit(currentColumn, currentRow, value);
+      }
+    }
+  }
+
+  return result;
+}

package/src/operations/split.ts

@@ -1,11 +1,18 @@
-import { Image, ImageKind } from '../Image';
+import { Image } from '../Image.js';
 
+/**
+ * Create an array of single-channel images based on a multi-channel image.
+ * @param image - The image with many channels.
+ * @returns Array of single-channel images.
+ */
 export function split(image: Image): Image[] {
   const result = [];
   for (let c = 0; c < image.channels; c++) {
-    const channel = Image.createFrom(image, { kind: ImageKind.GREY });
-    for (let i = 0; i < channel.data.length; i++) {
-      channel.data[i] = image.data[i * image.channels + c];
+    const channel = Image.createFrom(image, {
+      colorModel: 'GREY',
+    });
+    for (let i = 0; i < channel.size; i++) {
+      channel.setValueByIndex(i, 0, image.getValueByIndex(i, c));
     }
     result.push(channel);
   }