image-js 1.0.0-alpha.3 → 1.0.0

package/src/filters/flip.ts

@@ -0,0 +1,35 @@
+import type { Image } from '../Image.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+
+import flipX from './flipX.js';
+import flipY from './flipY.js';
+
+export interface FlipOptions {
+  /**
+   * Image to which the resulting image has to be put.
+   * @default `'horizontal'`
+   */
+  axis?: 'horizontal' | 'vertical' | 'both';
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Image;
+}
+
+/**
+ * Apply a flip filter to an image.
+ * @param image - Image to process.
+ * @param options - Flip options.
+ * @returns - The processed image.
+ */
+export function flip(image: Image, options: FlipOptions = {}): Image {
+  const { axis = 'horizontal' } = options;
+  const newImage = getOutputImage(image, options, { clone: true });
+  if (axis === 'horizontal') {
+    return flipX(newImage);
+  } else if (axis === 'vertical') {
+    return flipY(newImage);
+  } else {
+    return flipY(flipX(newImage));
+  }
+}

package/src/filters/flipX.ts

@@ -0,0 +1,32 @@
+import type { Image } from '../Image.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+/**
+ * Apply a flipX filter to an image.
+ * @param image - Image to process.
+ * @returns The processed image.
+ */
+export default function flipX(image: Image): Image {
+  checkProcessable(image, {
+    bitDepth: [8, 16],
+  });
+  for (let row = 0; row < image.height; row++) {
+    for (let column = 0; column < Math.floor(image.width / 2); column++) {
+      const currentCol = column;
+      const oppositeCol = image.width - column - 1;
+
+      for (let channel = 0; channel < image.channels; channel++) {
+        const tmp = image.getValue(currentCol, row, channel);
+        image.setValue(
+          currentCol,
+          row,
+          channel,
+          image.getValue(oppositeCol, row, channel),
+        );
+        image.setValue(oppositeCol, row, channel, tmp);
+      }
+    }
+  }
+
+  return image;
+}

package/src/filters/flipY.ts

@@ -0,0 +1,34 @@
+import type { Image } from '../Image.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+/**
+ * Apply a flipY filter to an image.
+ * @param image - Image to process.
+ * @returns The processed image.
+ */
+export default function flipY(image: Image): Image {
+  checkProcessable(image, {
+    bitDepth: [8, 16],
+  });
+
+  for (let row = 0; row < Math.floor(image.height / 2); row++) {
+    for (let column = 0; column < image.width; column++) {
+      const currentRow = row;
+      const oppositeRow = image.height - row - 1;
+
+      for (let channel = 0; channel < image.channels; channel++) {
+        const tmp = image.getValue(column, currentRow, channel);
+        image.setValue(
+          column,
+          currentRow,
+
+          channel,
+          image.getValue(column, oppositeRow, channel),
+        );
+        image.setValue(column, oppositeRow, channel, tmp);
+      }
+    }
+  }
+
+  return image;
+}

package/src/filters/gaussianBlur.ts

@@ -1,61 +1,104 @@
-import { BorderType } from '../types';
-import { Image } from '../Image';
+import type { Image } from '../Image.js';
+import { getRadius } from '../utils/getRadius.js';
+import type { BorderType } from '../utils/interpolateBorder.js';
 
-import { separableConvolution } from './convolution';
+import { separableConvolution } from './convolution.js';
 
-interface IGaussianBlurBaseOptions {
-  size: number;
+interface GaussianBlurBaseOptions {
+  /**
+   * Specify how the borders should be handled.
+   * @default `'reflect101'`
+   */
   borderType?: BorderType;
+  /**
+   * Image to which the resulting image has to be put.
+   */
   out?: Image;
 }
 
-export interface IGaussianBlurSigmaOptions extends IGaussianBlurBaseOptions {
+export interface GaussianBlurSigmaOptions extends GaussianBlurBaseOptions {
+  /**
+   * The standard deviation. Specifies the width of the gaussian function in the case where it is the same for x and y.
+   */
   sigma: number;
+  /**
+   * Size of the kernel.
+   * @default `2 * Math.ceil(2 * sigma) + 1`
+   */
+  size?: number;
 }
 
-export interface IGaussianBlurXYOptions extends IGaussianBlurBaseOptions {
+export interface GaussianBlurXYOptions extends GaussianBlurBaseOptions {
+  /**
+   * The standard deviation for the x axis. Specifies the width of the gaussian function along x.
+   */
   sigmaX: number;
+  /**
+   * The standard deviation for the y axis. Specifies the width of the gaussian function along y.
+   */
   sigmaY: number;
+  /**
+   * Size of the X axis kernel.
+   * @default `2 * Math.ceil(2 * sigmaX) + 1`
+   */
+  sizeX?: number;
+  /**
+   * Size of the Y axis kernel.
+   * @default `2 * Math.ceil(2 * sigmaY) + 1`
+   */
+  sizeY?: number;
 }
 
 export type GaussianBlurOptions =
-  | IGaussianBlurSigmaOptions
-  | IGaussianBlurXYOptions;
-
-function getRadius(size: number): number {
-  if (size % 2 !== 1 || size < 0) {
-    throw new Error('gaussian blur size must be positive and odd');
-  }
-  return (size - 1) / 2;
-}
+  | GaussianBlurSigmaOptions
+  | GaussianBlurXYOptions;
 
+/**
+ * Apply a gaussian filter to an image.
+ * @param image - Image to blur.
+ * @param options - Gaussian blur options.
+ * @returns The blurred image.
+ */
 export function gaussianBlur(
   image: Image,
-  options: GaussianBlurOptions
+  options: GaussianBlurOptions,
 ): Image {
   if ('sigma' in options) {
-    const { size, sigma } = options;
+    const { sigma, size = getSize(sigma), borderType } = options;
     const radius = getRadius(size);
     const kernel = getKernel(radius, sigma);
     return separableConvolution(image, kernel, kernel, {
-      borderType: options.borderType
+      borderType,
     });
-  } else {
-    getRadius(options.size);
-    const { sigmaX, sigmaY } = options;
-    const radius = getRadius(options.size);
-    const kernelX = getKernel(radius, sigmaX);
-    const kernelY = getKernel(radius, sigmaY);
+  } else if ('sigmaX' in options && 'sigmaY' in options) {
+    const {
+      sigmaX,
+      sigmaY,
+      sizeX = getSize(sigmaX),
+      sizeY = getSize(sigmaY),
+      borderType,
+    } = options;
+
+    const radiusX = getRadius(sizeX);
+    const radiusY = getRadius(sizeY);
+
+    const kernelX = getKernel(radiusX, sigmaX);
+    const kernelY = getKernel(radiusY, sigmaY);
     return separableConvolution(image, kernelX, kernelY, {
-      borderType: options.borderType
+      borderType,
     });
+  } else {
+    throw new TypeError(
+      'you must either define sigma or sigmaX and sigmaY in the options argument',
+    );
   }
 }
 
 function getKernel(radius: number, sigma: number): number[] {
   const n = radius * 2 + 1;
   const kernel = new Array(n);
-  const sigmaX = sigma ? sigma : ((n - 1) * 0.5 - 1) * 0.3 + 0.8;
+  // TODO: check if sigma can really be 0 or undefined.
+  const sigmaX = sigma || ((n - 1) * 0.5 - 1) * 0.3 + 0.8;
   const scale2X = -0.5 / (sigmaX * sigmaX);
   let sum = 0;
   for (let i = 0; i < n; i++) {
@@ -70,3 +113,7 @@ function getKernel(radius: number, sigma: number): number[] {
   }
   return kernel;
 }
+
+function getSize(sigma: number): number {
+  return 2 * Math.ceil(2 * sigma) + 1;
+}

package/src/filters/gradientFilter.ts

@@ -0,0 +1,103 @@
+import type { BitDepth } from '../Image.js';
+import { Image } from '../Image.js';
+import type { BorderType } from '../utils/interpolateBorder.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface GradientFilterBaseOptions {
+  /**
+   * Specify how the borders should be handled.
+   * @default `'replicate'`
+   */
+  borderType?: BorderType;
+  /**
+   * Value of the border if BorderType is 'constant'.
+   * @default `0`
+   */
+  borderValue?: number;
+  /**
+   * Specify the bit depth of the resulting image.
+   * @default `image.bitDepth`
+   */
+  bitDepth?: BitDepth;
+}
+
+export interface GradientFilterXOptions extends GradientFilterBaseOptions {
+  /**
+   * Kernel along x axis.
+   */
+  kernelX: number[][];
+}
+export interface GradientFilterYOptions extends GradientFilterBaseOptions {
+  /**
+   * Kernel along y axis.
+   */
+  kernelY: number[][];
+}
+
+export interface GradientFilterXYOptions extends GradientFilterBaseOptions {
+  /**
+   * Kernel along x axis.
+   */
+  kernelX: number[][];
+  /**
+   * Kernel along y axis.
+   */
+  kernelY: number[][];
+}
+
+export type GradientFilterOptions =
+  | GradientFilterXOptions
+  | GradientFilterYOptions
+  | GradientFilterXYOptions;
+
+/**
+ * Apply a gradient filter to an image.
+ * @param image - The image to process.
+ * @param options - Gradient filter options.
+ * @returns The gradient image.
+ */
+export function gradientFilter(
+  image: Image,
+  options: GradientFilterOptions,
+): Image {
+  const { borderType = 'replicate', borderValue = 0 } = options;
+
+  checkProcessable(image, {
+    bitDepth: [8, 16],
+    colorModel: 'GREY',
+  });
+
+  if ('kernelX' in options && 'kernelY' in options) {
+    const { kernelX, kernelY } = options;
+    const gradientX = image.rawDirectConvolution(kernelX, {
+      borderType,
+      borderValue,
+    });
+
+    const gradientY = image.rawDirectConvolution(kernelY, {
+      borderType,
+      borderValue,
+    });
+
+    const gradient = new Image(image.width, image.height, {
+      colorModel: 'GREY',
+    });
+
+    for (let i = 0; i < image.size; i++) {
+      gradient.setValueByIndex(i, 0, Math.hypot(gradientX[i], gradientY[i]));
+    }
+    return gradient;
+  } else if ('kernelX' in options) {
+    return image.directConvolution(options.kernelX, {
+      borderType,
+      borderValue,
+    });
+  } else if ('kernelY' in options) {
+    return image.directConvolution(options.kernelY, {
+      borderType,
+      borderValue,
+    });
+  } else {
+    throw new TypeError(`kernelX and KernelY are not defined`);
+  }
+}

package/src/filters/hypotenuse.ts

@@ -0,0 +1,62 @@
+import type { Image } from '../Image.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+import { validateChannels } from '../utils/validators/validators.js';
+
+export interface HypotenuseOptions {
+  /**
+   * To which channels to apply the filter. By default all but alpha.
+   */
+  channels?: number[];
+}
+
+/**
+ * Calculate a new image that is the hypotenuse between the current image and the otherImage.
+ * @param image - First image to process.
+ * @param otherImage - Second image.
+ * @param options - Hypotenuse options.
+ * @returns Hypotenuse of the two images.
+ */
+export function hypotenuse(
+  image: Image,
+  otherImage: Image,
+  options: HypotenuseOptions = {},
+): Image {
+  const {
+    channels = new Array(image.components).fill(0).map((value, index) => index),
+  } = options;
+
+  checkProcessable(image, {
+    bitDepth: [8, 16],
+  });
+
+  if (image.width !== otherImage.width || image.height !== otherImage.height) {
+    throw new RangeError('both images must have the same size');
+  }
+  if (
+    image.alpha !== otherImage.alpha ||
+    image.bitDepth !== otherImage.bitDepth
+  ) {
+    throw new RangeError('both images must have the same alpha and bitDepth');
+  }
+  if (image.channels !== otherImage.channels) {
+    throw new RangeError('both images must have the same number of channels');
+  }
+
+  validateChannels(channels, image);
+
+  const newImage = getOutputImage(image, {}, { clone: true });
+
+  for (const channel of channels) {
+    for (let i = 0; i < image.size; i++) {
+      const value = Math.hypot(
+        image.getValueByIndex(i, channel),
+        otherImage.getValueByIndex(i, channel),
+      );
+
+      newImage.setValueByIndex(i, channel, Math.min(value, newImage.maxValue));
+    }
+  }
+
+  return newImage;
+}

package/src/filters/increaseContrast.ts

@@ -0,0 +1,69 @@
+import type { Image } from '../Image.js';
+import { ImageColorModel } from '../utils/constants/colorModels.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+
+export interface IncreaseContrastOptions {
+  /**
+   * Image to which to output.
+   */
+  out?: Image;
+  /**
+   * Level all channels uniformly in order to preserve the color balance.
+   * @default false
+   */
+  uniform?: boolean;
+}
+
+/**
+ * Increase the contrast of an image by spanning each channel on the range [0, image.maxValue].
+ * This algorithm is based on the level algorithm.
+ * @param image - The image to enhance.
+ * @param options - Increase contrast options.
+ * @returns The enhanced image.
+ */
+export function increaseContrast(
+  image: Image,
+  options: IncreaseContrastOptions = {},
+): Image {
+  const { uniform = false } = options;
+  checkProcessable(image, {
+    bitDepth: [8, 16],
+  });
+  const minMax = image.minMax();
+
+  let min: number | number[] = minMax.min;
+  let max: number | number[] = minMax.max;
+
+  if (uniform) {
+    let maxDiffIndex = -1;
+    let previousDiff = -1;
+    for (let i = 0; i < minMax.max.length; i++) {
+      const difference = minMax.max[i] - minMax.min[i];
+      if (difference > previousDiff) {
+        maxDiffIndex = i;
+        previousDiff = difference;
+      }
+    }
+    min = minMax.min[maxDiffIndex];
+    max = minMax.max[maxDiffIndex];
+  }
+
+  let channels: number[] = new Array(image.components)
+    .fill(0)
+    .map((value, index) => index);
+
+  if (image.colorModel === ImageColorModel.GREYA) {
+    channels = [0];
+  } else if (image.colorModel === ImageColorModel.RGBA) {
+    channels = [0, 1, 2];
+  }
+
+  return image.level({
+    inputMin: min,
+    inputMax: max,
+    outputMin: 0,
+    outputMax: image.maxValue,
+    channels,
+    ...options,
+  });
+}

package/src/filters/index.ts

@@ -1,4 +1,14 @@
-export * from './invert';
-export * from './gaussianBlur';
-export * from './convolution';
-export * from './blur';
+export * from './and.js';
+export * from './blur.js';
+export * from './convolution.js';
+export * from './derivativeFilter.js';
+export * from './increaseContrast.js';
+export * from './gaussianBlur.js';
+export * from './gradientFilter.js';
+export * from './hypotenuse.js';
+export * from './invert.js';
+export * from './level.js';
+export * from './or.js';
+export * from './flip.js';
+export * from './medianFilter.js';
+export * from './pixelate.js';

package/src/filters/invert.ts

@@ -1,19 +1,50 @@
-import { Image } from '../Image';
-import { getOutputImage } from '../utils/getOutputImage';
+import { Image } from '../Image.js';
+import type { Mask } from '../Mask.js';
+import { copyAlpha } from '../operations/index.js';
+import { getOutputImage, maskToOutputMask } from '../utils/getOutputImage.js';
 
-export interface IInvertOptions {
-  out?: Image;
+export interface InvertOptions {
+  /**
+   * Image to which the inverted image has to be put.
+   */
+  out?: Image | Mask;
 }
 
+export function invert(image: Image, options?: InvertOptions): Image;
+export function invert(image: Mask, options?: InvertOptions): Mask;
 /**
- * Invert the colors of an image.
+ * Invert the components of an image.
  * @param image - The image to invert.
+ * @param options - Invert options.
+ * @returns The inverted image.
  */
-export function invert(image: Image, options?: IInvertOptions): Image {
-  const newImage = getOutputImage(image, options);
-  const { maxValue } = newImage;
-  for (let i = 0; i < newImage.data.length; i++) {
-    newImage.data[i] = maxValue - image.data[i];
+export function invert(
+  image: Image | Mask,
+  options?: InvertOptions,
+): Image | Mask {
+  if (image instanceof Image) {
+    const newImage = getOutputImage(image, options);
+    if (image.alpha) {
+      copyAlpha(image, newImage);
+    }
+
+    const { maxValue, size } = newImage;
+    for (let i = 0; i < size; i++) {
+      for (let component = 0; component < image.components; component++) {
+        newImage.setValueByIndex(
+          i,
+          component,
+          maxValue - image.getValueByIndex(i, component),
+        );
+      }
+    }
+    return newImage;
+  } else {
+    const newImage = maskToOutputMask(image, options);
+
+    for (let i = 0; i < newImage.size; i++) {
+      newImage.setBitByIndex(i, !image.getBitByIndex(i));
+    }
+    return newImage;
   }
-  return newImage;
 }

package/src/filters/level.ts

@@ -0,0 +1,131 @@
+import type { Image } from '../Image.js';
+import { getClamp } from '../utils/clamp.js';
+import { getOutputImage } from '../utils/getOutputImage.js';
+import checkProcessable from '../utils/validators/checkProcessable.js';
+import { validateChannels } from '../utils/validators/validators.js';
+
+export interface LevelOptions {
+  /**
+   * Specify which channels should be processed. To process the alpha as well,
+   * specify the channels as [0,1,2,3] for RGBA images and [0,1] for GREYA.
+   * @default All components of the image the image (no alpha).
+   */
+  channels?: number[];
+  /**
+   * Input lower bound.
+   * @default `image.minMax().min`
+   */
+  inputMin?: number | number[];
+  /**
+   * Input upper bound.
+   * @default `image.minMax().min`
+   */
+  inputMax?: number | number[];
+  /**
+   * output lower bound.
+   * @default `0`
+   */
+  outputMin?: number | number[];
+  /**
+   * Output upper bound.
+   * @default `image.maxValue`
+   */
+  outputMax?: number | number[];
+  /**
+   * Specifies the shape of the curve connecting the two points.
+   *  @default `1`
+   */
+  gamma?: number | number[];
+  /**
+   * Image to which to output.
+   */
+  out?: Image;
+}
+
+/**
+ * Level the image using the optional input and output value. The default options allow to increase the image's contrast.
+ * @param image - Image to process.
+ * @param options - Level options.
+ * @returns The levelled image.
+ */
+export function level(image: Image, options: LevelOptions = {}) {
+  const minMax = image.minMax();
+  let {
+    inputMin = minMax.min,
+    inputMax = minMax.max,
+    outputMin = 0,
+    outputMax = image.maxValue,
+    gamma = 1,
+  } = options;
+  const {
+    channels = new Array(image.components).fill(0).map((value, index) => index),
+  } = options;
+
+  validateChannels(channels, image);
+
+  checkProcessable(image, {
+    bitDepth: [8, 16],
+  });
+
+  const newImage = getOutputImage(image, options, { clone: true });
+
+  const clamp = getClamp(image);
+
+  inputMin = getValueArray(inputMin, image.channels);
+  inputMax = getValueArray(inputMax, image.channels);
+  outputMin = getValueArray(outputMin, image.channels);
+  outputMax = getValueArray(outputMax, image.channels);
+  gamma = getValueArray(gamma, image.channels);
+
+  for (let row = 0; row < image.height; row++) {
+    for (let column = 0; column < image.width; column++) {
+      for (const channel of channels) {
+        const currentValue = image.getValue(column, row, channel);
+
+        const clamped = Math.max(
+          Math.min(currentValue, inputMax[channel]),
+          inputMin[channel],
+        );
+
+        let ratio = clamp(
+          (clamped - inputMin[channel]) /
+            (inputMax[channel] - inputMin[channel]),
+        );
+
+        if (Number.isNaN(ratio)) ratio = 0;
+
+        const result = clamp(
+          ratio ** (1 / gamma[channel]) *
+            (outputMax[channel] - outputMin[channel]) +
+            outputMin[channel],
+        );
+
+        newImage.setValue(column, row, channel, result);
+      }
+    }
+  }
+  return newImage;
+}
+
+/**
+ * Get an array with correct values for each channel to process.
+ * @param value - Number or array to transform to the final array.
+ * @param imageChannels - Number of channels processed in the level function.
+ * @returns Array of values for each channel.
+ */
+function getValueArray(
+  value: number | number[],
+  imageChannels: number,
+): number[] {
+  if (Array.isArray(value)) {
+    if (value.length === imageChannels) {
+      return value;
+    } else {
+      throw new RangeError(
+        'array length is not compatible with channel option',
+      );
+    }
+  } else {
+    return new Array(imageChannels).fill(value);
+  }
+}