feat: add multiply/divide functions (#459)

* feat: add multiply and divide functions

* feat: add divide function

* test: add testing cases

* test: add tests
close: #457

* refactor: change phrasing of tests and error

* fix: resolve conversations

* fix: default number of channels takes alpha into account

* test: refactor testing cases

* test: add testing of out and channels options

* feat: add functions as image methods

* docs: add comments about methods

* docs: minor fixes

* refactor: move divide and multiply functions to compare folder

* fix: add exports to pass typedoc errors

* refactor: refactor interfaces

* docs: fix typo

Author: EscapedGibbon

src/Image.ts

@@ -2,6 +2,8 @@ import { RgbColor } from 'colord';
 
 import { Mask } from './Mask';
 import { add, subtract, SubtractImageOptions } from './compare';
+import { divide, DivideOptions } from './compare/divide';
+import { multiply, MultiplyOptions } from './compare/multiply';
 import { median } from './compute';
 import { variance } from './compute/variance';
 import { correctColor } from './correctColor';
@@ -679,7 +681,24 @@ export class Image {
   public add(other: Image): Image {
     return add(this, other);
   }
-
+  /**
+   *  Multiply image pixels by a constant.
+   * @param value - Value which pixels will be multiplied to.
+   * @param options - Multiply options.
+   * @returns Multiplied image.
+   */
+  public multiply(value: number, options: MultiplyOptions = {}): Image {
+    return multiply(this, value, options);
+  }
+  /**
+   *  Divide image pixels by a constant.
+   * @param value - Value which pixels will be divided to.
+   * @param options - Divide options.
+   * @returns Divided image.
+   */
+  public divide(value: number, options: DivideOptions = {}): Image {
+    return divide(this, value, options);
+  }
   // COMPUTE
 
   public histogram(options?: HistogramOptions): Uint32Array {

src/compare/__tests__/divide.test.ts

@@ -0,0 +1,74 @@
+import { Image } from '../../Image';
+import { divide } from '../divide';
+
+test('divide by 2', () => {
+  let image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  image = divide(image, 2);
+  const result = testUtils.createRgbaImage([
+    [115, 40, 60, 127],
+    [50, 70, 6, 0],
+  ]);
+  expect(image).toStrictEqual(result);
+});
+
+test('error when dividing by 0', () => {
+  const image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  expect(() => {
+    divide(image, 0);
+  }).toThrow('Cannot divide by 0');
+});
+test('divide by decimal', () => {
+  let image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 4],
+  ]);
+  image = image.divide(0.25);
+  const result = testUtils.createRgbaImage([
+    [255, 255, 255, 255],
+    [255, 255, 52, 16],
+  ]);
+  expect(image).toStrictEqual(result);
+});
+test('divide by prime number', () => {
+  let image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  image = image.divide(7);
+  const result = testUtils.createRgbaImage([
+    [32, 11, 17, 36],
+    [14, 20, 1, 0],
+  ]);
+  expect(image).toStrictEqual(result);
+});
+test('testing channels option', () => {
+  let image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  image = image.divide(7, { channels: [0, 1, 3] });
+  const result = testUtils.createRgbaImage([
+    [32, 11, 120, 36],
+    [14, 20, 13, 0],
+  ]);
+  expect(image).toStrictEqual(result);
+});
+test('testing out option', () => {
+  const image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  const out = new Image(image.width, image.height, { colorModel: 'RGBA' });
+  image.divide(7, { out });
+  const result = testUtils.createRgbaImage([
+    [32, 11, 17, 36],
+    [14, 20, 1, 0],
+  ]);
+  expect(out).toStrictEqual(result);
+});

src/compare/__tests__/multiply.test.ts

@@ -0,0 +1,64 @@
+import { Image } from '../../Image';
+
+test('multiply by 2', () => {
+  let image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  image = image.multiply(2);
+  const result = testUtils.createRgbaImage([
+    [255, 160, 240, 255],
+    [200, 255, 26, 2],
+  ]);
+  expect(image).toStrictEqual(result);
+});
+
+test('mulitply by 100', () => {
+  let image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  image = image.multiply(100);
+  const result = testUtils.createRgbaImage([
+    [255, 255, 255, 255],
+    [255, 255, 255, 100],
+  ]);
+  expect(image).toStrictEqual(result);
+});
+test('multiply by decimal', () => {
+  let image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  image = image.multiply(0.5);
+  const result = testUtils.createRgbaImage([
+    [115, 40, 60, 127],
+    [50, 70, 6, 0],
+  ]);
+  expect(image).toStrictEqual(result);
+});
+test('testing channels option', () => {
+  let image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  image = image.multiply(0.5, { channels: [0, 1] });
+  const result = testUtils.createRgbaImage([
+    [115, 40, 120, 255],
+    [50, 70, 13, 1],
+  ]);
+  expect(image).toStrictEqual(result);
+});
+test('testing out option', () => {
+  let image = testUtils.createRgbaImage([
+    [230, 80, 120, 255],
+    [100, 140, 13, 1],
+  ]);
+  const out = new Image(image.width, image.height, { colorModel: 'RGBA' });
+  image = image.multiply(0.5, { channels: [0, 1], out });
+  const result = testUtils.createRgbaImage([
+    [115, 40, 120, 255],
+    [50, 70, 13, 1],
+  ]);
+  expect(out).toStrictEqual(result);
+});

src/compare/divide.ts

@@ -0,0 +1,50 @@
+import { Image } from '../Image';
+import { getOutputImage } from '../utils/getOutputImage';
+import { validateChannels } from '../utils/validators/validators';
+
+export interface DivideOptions {
+  /**
+   * Channels where value will be divided.
+   * @default all channels
+   */
+  channels?: number[];
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Image;
+}
+
+/**
+ *
+ * Divides image pixels by a certain value.
+ * @param image - image to which division will be applied.
+ * @param value - Value by which each pixel will be divided.
+ * @param options - Divide options
+ * @returns image.
+ */
+export function divide(
+  image: Image,
+  value: number,
+  options: DivideOptions = {},
+) {
+  const {
+    channels = new Array(image.channels).fill(0).map((value, index) => index),
+  } = options;
+  validateChannels(channels, image);
+  if (value === 0) {
+    throw new TypeError(`Cannot divide by 0`);
+  }
+  const newImage = getOutputImage(image, options, { clone: true });
+  if (channels.length === 0) {
+    return newImage;
+  }
+  for (const channel of channels) {
+    for (let row = 0; row < newImage.height; row++) {
+      for (let column = 0; column < newImage.width; column++) {
+        const newIntensity = newImage.getValue(column, row, channel) / value;
+        newImage.setClampedValue(column, row, channel, newIntensity);
+      }
+    }
+  }
+  return newImage;
+}

src/compare/index.ts

@@ -4,3 +4,5 @@ export * from './computeRmse';
 export * from './computeSsim';
 export * from './subtract';
 export * from './add';
+export * from './divide';
+export * from './multiply';

src/compare/multiply.ts

@@ -0,0 +1,48 @@
+import { Image } from '../Image';
+import { getOutputImage } from '../utils/getOutputImage';
+import { validateChannels } from '../utils/validators/validators';
+
+export interface MultiplyOptions {
+  /**
+   * Channels where value will be multiplied.
+   * @default all channels
+   */
+  channels?: number[];
+  /**
+   * Image to which the resulting image has to be put.
+   */
+  out?: Image;
+}
+
+/**
+ *
+ * Multiplies points by a certain value.
+ * @param image - image to which multiplication will be applied.
+ * @param value - Value by which each pixel will be multiplied.
+ * @param options - Multiply options
+ * @returns image.
+ */
+export function multiply(
+  image: Image,
+  value: number,
+  options: MultiplyOptions = {},
+) {
+  const {
+    channels = new Array(image.channels).fill(0).map((value, index) => index),
+  } = options;
+  validateChannels(channels, image);
+
+  const newImage = getOutputImage(image, options, { clone: true });
+  if (channels.length === 0) {
+    return newImage;
+  }
+  for (const channel of channels) {
+    for (let row = 0; row < newImage.height; row++) {
+      for (let column = 0; column < newImage.width; column++) {
+        const newIntensity = newImage.getValue(column, row, channel) * value;
+        newImage.setClampedValue(column, row, channel, newIntensity);
+      }
+    }
+  }
+  return newImage;
+}