Stack: add sum and histogram (#420)

opatiny · web-flow · commit f37d4e4267c4 · 2023-12-15T15:02:57.000+01:00
* feat: basic Stack API * feat(Stack): implement constructor Closes: #413 * feat(Stack): implement functions to get values * feat(Stack): implement minImage * feat(Stack): implement maxImage * feat(Stack): implement iterator * test(Stack): add min and max image tests * feat(Stack): implement getStackFromFolder for debug * fix(Stack): enhance Stack properties * feat(Stack): implement map and filter * feat(Stack): implement meanImage Closes: #414 * feat(Stack): implement medianImage * test: enhance stack coverage * test: fix test after merge * chore: fix eslint errors * feat(Stack): implement sum * feat(Stack): implement histogram Closes: #418 * refactor: move stack functions to subfolder * test: fix images path * fix: add check to sum * fix(stack): max nb of images for sum
diff --git a/src/Stack.ts b/src/Stack.ts
@@ -1,10 +1,13 @@
 import { BitDepth } from 'fast-png';
 
 import { Image } from './Image';
-import { maxImage } from './stack/maxImage';
-import { meanImage } from './stack/meanImage';
-import { medianImage } from './stack/medianImage';
-import { minImage } from './stack/minImage';
+import { HistogramOptions } from './compute';
+import { histogram } from './stack/compute/histogram';
+import { maxImage } from './stack/compute/maxImage';
+import { meanImage } from './stack/compute/meanImage';
+import { medianImage } from './stack/compute/medianImage';
+import { minImage } from './stack/compute/minImage';
+import { sum } from './stack/compute/sum';
 import {
   checkImagesValid,
   verifySameDimensions,
@@ -64,7 +67,7 @@ export class Stack {
   }
 
   /**
-   * Clone a stack.
+   * Clone a stack. The images are a copy of the original images.
    * @returns A new stack with the same images.
    */
   public clone(): Stack {
@@ -157,10 +160,22 @@ export class Stack {
   }
 
   /**
-   * Get the global histogram of the stack.
+   * Return a 16 bits depth image containing the sum values of all the images in the stack for
+   * each pixel.
+   * @returns The sum image.
    */
-  // public getHistogram(): Uint32Array {}
+  public sum(): Image {
+    return sum(this);
+  }
 
+  /**
+   * Get the sum of all the histograms of the stack's images. If no channel is specified in the options, the images must be GREY.
+   * @param options - Histogram options.
+   * @returns The histogram of the stack.
+   */
+  public histogram(options: HistogramOptions = {}): Uint32Array {
+    return histogram(this, options);
+  }
   /**
    * Align all the images of the stack on the image at the given index.
    * @param refIndex - The index of the reference image.
diff --git a/src/stack/compute/__tests__/__image_snapshots__/max-image-test-ts-more-complex-stack-1-snap.png b/src/stack/compute/__tests__/__image_snapshots__/max-image-test-ts-more-complex-stack-1-snap.png
diff --git a/src/stack/compute/__tests__/__image_snapshots__/mean-image-test-ts-more-complex-stack-1-snap.png b/src/stack/compute/__tests__/__image_snapshots__/mean-image-test-ts-more-complex-stack-1-snap.png
diff --git a/src/stack/compute/__tests__/__image_snapshots__/median-image-test-ts-more-complex-stack-1-snap.png b/src/stack/compute/__tests__/__image_snapshots__/median-image-test-ts-more-complex-stack-1-snap.png
diff --git a/src/stack/compute/__tests__/__image_snapshots__/min-image-test-ts-more-complex-stack-1-snap.png b/src/stack/compute/__tests__/__image_snapshots__/min-image-test-ts-more-complex-stack-1-snap.png
diff --git a/src/stack/compute/__tests__/__image_snapshots__/sum-test-ts-more-complex-stack-1-snap.png b/src/stack/compute/__tests__/__image_snapshots__/sum-test-ts-more-complex-stack-1-snap.png
diff --git a/src/stack/compute/__tests__/histogram.test.ts b/src/stack/compute/__tests__/histogram.test.ts
@@ -0,0 +1,48 @@
+import { Stack } from '../../../Stack';
+
+test('two grey images, bitsDepth = 8', () => {
+  const image = testUtils.createGreyImage([[1, 2, 3, 4]]);
+  const stack = new Stack([image, image]);
+
+  const histogram = stack.histogram();
+
+  expect(histogram).toHaveLength(256);
+  expect(histogram.subarray(0, 5)).toStrictEqual(
+    new Uint32Array([0, 2, 2, 2, 2]),
+  );
+});
+
+test('two grey images, bitsDepth = 16', () => {
+  const image1 = testUtils.createGreyImage([[1, 2, 3, 4]]);
+  const image2 = testUtils.createGreyImage([[4, 5, 6, 7]]);
+  const stack = new Stack([image1, image2]);
+
+  const histogram = stack.histogram();
+
+  expect(histogram).toHaveLength(256);
+  expect(histogram.subarray(0, 8)).toStrictEqual(
+    new Uint32Array([0, 1, 1, 1, 2, 1, 1, 1]),
+  );
+});
+
+test('two RGB images, channel = 2', () => {
+  const image1 = testUtils.createRgbImage([[1, 2, 0]]);
+  const image2 = testUtils.createRgbImage([[4, 5, 1]]);
+  const stack = new Stack([image1, image2]);
+
+  const histogram = stack.histogram({ channel: 2 });
+
+  expect(histogram).toHaveLength(256);
+  expect(histogram.subarray(0, 2)).toStrictEqual(new Uint32Array([1, 1]));
+});
+
+test('two grey images, slots = 2', () => {
+  const image1 = testUtils.createGreyImage([[1, 200, 3, 150]]);
+  const image2 = testUtils.createGreyImage([[200, 5, 190, 7]]);
+  const stack = new Stack([image1, image2]);
+
+  const histogram = stack.histogram({ slots: 2 });
+
+  expect(histogram).toHaveLength(2);
+  expect(histogram).toStrictEqual(new Uint32Array([4, 4]));
+});
diff --git a/src/stack/compute/__tests__/maxImage.test.ts b/src/stack/compute/__tests__/maxImage.test.ts
@@ -1,8 +1,8 @@
 import { join } from 'node:path';
 
-import { Image } from '../../Image';
-import { Stack } from '../../Stack';
-import { getStackFromFolder } from '../utils/getStackFromFolder';
+import { Image } from '../../../Image';
+import { Stack } from '../../../Stack';
+import { getStackFromFolder } from '../../utils/getStackFromFolder';
 
 test('2 grey images', () => {
   const image1 = testUtils.createGreyImage([[1, 2, 3, 4]]);
@@ -18,7 +18,7 @@ test('2 grey images', () => {
 });
 
 test('more complex stack', () => {
-  const folder = join(__dirname, '../../../test/img/correctColor');
+  const folder = join(__dirname, '../../../../test/img/correctColor');
   const stack = getStackFromFolder(folder);
 
   expect(stack.maxImage()).toMatchImageSnapshot();
diff --git a/src/stack/compute/__tests__/meanImage.test.ts b/src/stack/compute/__tests__/meanImage.test.ts
@@ -1,8 +1,8 @@
 import { join } from 'node:path';
 
-import { Image } from '../../Image';
-import { Stack } from '../../Stack';
-import { getStackFromFolder } from '../utils/getStackFromFolder';
+import { Image } from '../../../Image';
+import { Stack } from '../../../Stack';
+import { getStackFromFolder } from '../../utils/getStackFromFolder';
 
 test('2 grey images', () => {
   const image1 = testUtils.createGreyImage([[1, 2, 3, 4]]);
@@ -31,7 +31,7 @@ test('2 RGB images', () => {
 });
 
 test('more complex stack', () => {
-  const folder = join(__dirname, '../../../test/img/correctColor');
+  const folder = join(__dirname, '../../../../test/img/correctColor');
   const stack = getStackFromFolder(folder);
   expect(stack.meanImage()).toMatchImageSnapshot();
 });
diff --git a/src/stack/compute/__tests__/medianImage.test.ts b/src/stack/compute/__tests__/medianImage.test.ts
@@ -1,8 +1,8 @@
 import { join } from 'node:path';
 
-import { Image } from '../../Image';
-import { Stack } from '../../Stack';
-import { getStackFromFolder } from '../utils/getStackFromFolder';
+import { Image } from '../../../Image';
+import { Stack } from '../../../Stack';
+import { getStackFromFolder } from '../../utils/getStackFromFolder';
 
 test('3 grey images', () => {
   const image1 = testUtils.createGreyImage([[1, 2, 3, 4]]);
@@ -33,7 +33,7 @@ test('3 RGB images', () => {
 });
 
 test('more complex stack', () => {
-  const folder = join(__dirname, '../../../test/img/correctColor');
+  const folder = join(__dirname, '../../../../test/img/correctColor');
   const stack = getStackFromFolder(folder);
   expect(stack.medianImage()).toMatchImageSnapshot();
 });
diff --git a/src/stack/compute/__tests__/minImage.test.ts b/src/stack/compute/__tests__/minImage.test.ts
@@ -1,8 +1,8 @@
 import { join } from 'node:path';
 
-import { Image } from '../../Image';
-import { Stack } from '../../Stack';
-import { getStackFromFolder } from '../utils/getStackFromFolder';
+import { Image } from '../../../Image';
+import { Stack } from '../../../Stack';
+import { getStackFromFolder } from '../../utils/getStackFromFolder';
 
 test('simple images', () => {
   const image1 = testUtils.createGreyImage([[1, 2, 3, 4]]);
@@ -31,7 +31,7 @@ test('2 RGB images', () => {
 });
 
 test('more complex stack', () => {
-  const folder = join(__dirname, '../../../test/img/correctColor');
+  const folder = join(__dirname, '../../../../test/img/correctColor');
   const stack = getStackFromFolder(folder);
   expect(stack.minImage()).toMatchImageSnapshot();
 });
diff --git a/src/stack/compute/__tests__/sum.test.ts b/src/stack/compute/__tests__/sum.test.ts
@@ -0,0 +1,52 @@
+import { join } from 'node:path';
+
+import { Image } from '../../../Image';
+import { Stack } from '../../../Stack';
+import { getStackFromFolder } from '../../utils/getStackFromFolder';
+
+test('2 grey images', () => {
+  const image1 = testUtils.createGreyImage([[1, 2, 3, 4]]);
+  const image2 = testUtils.createGreyImage([[4, 3, 2, 1]]);
+  const stack = new Stack([image1, image2]);
+  const sum = stack.sum();
+
+  expect(sum).toBeInstanceOf(Image);
+  expect(sum.bitDepth).toBe(16);
+  expect(sum).toMatchImageData([[5, 5, 5, 5]]);
+});
+
+test('2 RGB images', () => {
+  const image1 = testUtils.createRgbImage([[1, 2, 3]]);
+  const image2 = testUtils.createRgbImage([[5, 6, 7]]);
+  const stack = new Stack([image1, image2]);
+  const sum = stack.sum();
+
+  expect(sum).toMatchImageData([[6, 8, 10]]);
+});
+
+test('more complex stack', () => {
+  const folder = join(__dirname, '../../../../test/img/correctColor');
+  const stack = getStackFromFolder(folder);
+  expect(stack.sum()).toMatchImageSnapshot();
+});
+
+test('should throw if 16 bits depth', () => {
+  const data = new Uint16Array([1, 2, 3, 4]);
+  const image1 = new Image(4, 1, { data, bitDepth: 16, colorModel: 'GREY' });
+  const image2 = new Image(4, 1, { data, bitDepth: 16, colorModel: 'GREY' });
+  const stack = new Stack([image1, image2]);
+
+  expect(() => {
+    return stack.sum();
+  }).toThrow('image bitDepth must be 8 to apply this algorithm');
+});
+
+test('should throw if too many images in stack', () => {
+  const image1 = testUtils.createGreyImage([[1, 2, 3, 4]]);
+  const images = new Array(500).fill(image1);
+  const stack = new Stack(images);
+
+  expect(() => {
+    return stack.sum();
+  }).toThrow('Maximal valid stack size is 257');
+});
diff --git a/src/stack/compute/histogram.ts b/src/stack/compute/histogram.ts
@@ -0,0 +1,26 @@
+import { Stack } from '../../Stack';
+import { HistogramOptions } from '../../compute';
+import { checkProcessable } from '../utils/checkProcessable';
+
+/**
+ * Get the sum of all the histograms of the stack's images. If no channel is specified in the options, the images must be GREY.
+ * @param stack - Stack to process.
+ * @param options - Histogram options.
+ * @returns The histogram of the stack.
+ */
+export function histogram(
+  stack: Stack,
+  options: HistogramOptions,
+): Uint32Array {
+  checkProcessable(stack, { bitDepth: [8, 16] });
+  const { slots = 2 ** stack.bitDepth, channel = 0 } = options;
+  const result = new Uint32Array(slots);
+  for (let i = 0; i < stack.size; i++) {
+    const image = stack.getImage(i);
+    const histogram = image.histogram({ channel, slots });
+    for (const [index, value] of histogram.entries()) {
+      result[index] += value;
+    }
+  }
+  return result;
+}
diff --git a/src/stack/compute/index.ts b/src/stack/compute/index.ts
@@ -1,4 +1,6 @@
+export * from './histogram';
 export * from './maxImage';
-export * from './minImage';
 export * from './meanImage';
 export * from './medianImage';
+export * from './minImage';
+export * from './sum';
diff --git a/src/stack/compute/maxImage.ts b/src/stack/compute/maxImage.ts
@@ -1,7 +1,6 @@
-import { Image } from '../Image';
-import { Stack } from '../Stack';
-
-import { checkProcessable } from './utils/checkProcessable';
+import { Image } from '../../Image';
+import { Stack } from '../../Stack';
+import { checkProcessable } from '../utils/checkProcessable';
 
 /**
  *  Returns a new image with the maximum values of each pixel from the stack.
diff --git a/src/stack/compute/meanImage.ts b/src/stack/compute/meanImage.ts
@@ -1,7 +1,7 @@
-import { Image } from '../Image';
-import { Stack } from '../Stack';
+import { Image } from '../../Image';
+import { Stack } from '../../Stack';
 
-import { checkProcessable } from './utils/checkProcessable';
+import { checkProcessable } from '../utils/checkProcessable';
 
 /**
  *  Returns a new image with the average values of each pixel of the images of the stack.
diff --git a/src/stack/compute/medianImage.ts b/src/stack/compute/medianImage.ts
@@ -1,10 +1,10 @@
 // @ts-expect-error: median-quisckselect has no types
 import quickMedian from 'median-quickselect';
 
-import { Image } from '../Image';
-import { Stack } from '../Stack';
+import { Image } from '../../Image';
+import { Stack } from '../../Stack';
 
-import { checkProcessable } from './utils/checkProcessable';
+import { checkProcessable } from '../utils/checkProcessable';
 
 /**
  *  Returns a new image with the median values of each pixel of the images of the stack.
diff --git a/src/stack/compute/minImage.ts b/src/stack/compute/minImage.ts
@@ -1,7 +1,7 @@
-import { Image } from '../Image';
-import { Stack } from '../Stack';
+import { Image } from '../../Image';
+import { Stack } from '../../Stack';
 
-import { checkProcessable } from './utils/checkProcessable';
+import { checkProcessable } from '../utils/checkProcessable';
 
 /**
  *  Returns a new image with the minimum values of each pixel from the stack.
diff --git a/src/stack/compute/sum.ts b/src/stack/compute/sum.ts
@@ -0,0 +1,37 @@
+import { Image } from '../../Image';
+import { Stack } from '../../Stack';
+import { checkProcessable } from '../utils/checkProcessable';
+
+/**
+ *  Returns a new 16 bits depth image with the sum of each pixel of the images of the stack.
+ * @param stack - Stack to process.
+ * @returns The sum image.
+ */
+export function sum(stack: Stack): Image {
+  checkProcessable(stack, { sameDimensions: true, bitDepth: 8 });
+  // Because 255*257 = 2**16 - 1
+  if (stack.size > 257) {
+    throw new Error('Maximal valid stack size is 257');
+  }
+  const image = stack.getImage(0);
+  const dataSize = image.size * stack.channels;
+  const sum = new Uint16Array(dataSize).fill(0);
+
+  for (let i = 0; i < stack.size; i++) {
+    for (let j = 0; j < image.size; j++) {
+      for (let channel = 0; channel < stack.channels; channel++) {
+        sum[j * stack.channels + channel] += stack.getValueByIndex(
+          i,
+          j,
+          channel,
+        );
+      }
+    }
+  }
+
+  return new Image(image.width, image.height, {
+    data: sum,
+    colorModel: stack.colorModel,
+    bitDepth: 16,
+  });
+}
