fix: correct level default options and rename autoLevel to increaseContrast (#409)

Closes: #166

level now has default options which will increase the constrast

BREAKING CHANGE: renamed autoLevel to increaseContrast

Author: opatiny

src/Image.ts

@@ -43,8 +43,8 @@ import {
   InvertOptions,
   level,
   LevelOptions,
-  autoLevel,
-  AutoLevelOptions,
+  increaseContrast,
+  IncreaseContrastOptions,
   pixelate,
   PixelateOptions,
   medianFilter,
@@ -938,12 +938,12 @@ export class Image {
   }
 
   /**
-   * Enhance the contrast of an image by spanning each channel on the range [0, image.maxValue].
-   * @param options - Enhance contrast options.
+   * Increase the contrast of an image by spanning each channel on the range [0, image.maxValue].
+   * @param options - Increase contrast options.
    * @returns The enhanced image.
    */
-  public autoLevel(options: AutoLevelOptions = {}): Image {
-    return autoLevel(this, options);
+  public increaseContrast(options: IncreaseContrastOptions = {}): Image {
+    return increaseContrast(this, options);
   }
 
   /**

src/filters/__tests__/__image_snapshots__/auto-level-test-ts-bigger-image-1-snap.png

@@ -1,4 +1,4 @@
-import { autoLevel } from '../autoLevel';
+import { increaseContrast } from '../increaseContrast';
 
 test('3x1 rgba image, custom output min and max', () => {
   const image = testUtils.createRgbaImage([
@@ -7,7 +7,7 @@ test('3x1 rgba image, custom output min and max', () => {
     [255, 200, 0, 50],
   ]);
 
-  const result = autoLevel(image);
+  const result = increaseContrast(image);
 
   expect(result).toMatchImageData([
     [0, 0, 0, 50],
@@ -23,7 +23,7 @@ test('3x1 rgba image, uniform = true, image should not change', () => {
     [255, 200, 0, 50],
   ]);
 
-  const result = autoLevel(image, { uniform: true });
+  const result = increaseContrast(image, { uniform: true });
 
   expect(result).toMatchImage(image);
 });
@@ -35,7 +35,7 @@ test('3x1 rgb image, uniform = true', () => {
     [200, 200, 0],
   ]);
 
-  const result = autoLevel(image, { uniform: true });
+  const result = increaseContrast(image, { uniform: true });
   expect(result).toMatchImageData([
     [0, 127, 0],
     [191, 191, 0],
@@ -45,15 +45,15 @@ test('3x1 rgb image, uniform = true', () => {
 
 test('1x3 grey image', () => {
   const image = testUtils.createGreyImage([[50, 100]]);
-  expect(autoLevel(image)).toMatchImageData([[0, 255]]);
+  expect(increaseContrast(image)).toMatchImageData([[0, 255]]);
 });
 
 test('alpha should not be modified', () => {
   const image = testUtils.createGreyaImage([
     [50, 100],
     [100, 50],
   ]);
-  expect(autoLevel(image)).toMatchImageData([
+  expect(increaseContrast(image)).toMatchImageData([
     [0, 100],
     [255, 50],
   ]);
@@ -65,7 +65,7 @@ test('out option', () => {
     [30, 40],
     [60, 70],
   ]);
-  const result = autoLevel(image, { out: image });
+  const result = increaseContrast(image, { out: image });
   expect(result).toMatchImageData([
     [0, 10],
     [127, 40],
@@ -75,6 +75,6 @@ test('out option', () => {
 });
 
 test('bigger image', () => {
-  const image = testUtils.load('featureMatching/id-crops/crop1.png');
-  expect(autoLevel(image)).toMatchImageSnapshot();
+  const image = testUtils.load('featureMatching/id-crops/crop2.png');
+  expect(increaseContrast(image)).toMatchImageSnapshot();
 });

src/filters/__tests__/__image_snapshots__/increase-contrast-test-ts-bigger-image-1-snap.png

@@ -1,16 +1,25 @@
-test('1x1 rgba image, default options', () => {
-  const image = testUtils.createRgbaImage([[100, 0, 0, 50]]);
-  expect(image.level()).toMatchImage(image);
+test('3x1 rgba image, default options', () => {
+  // should span contrast on the whole range
+  const image = testUtils.createRgbaImage([
+    [1, 0, 1, 50],
+    [2, 2, 0, 50],
+    [3, 1, 0, 50],
+  ]);
+  expect(image.level()).toMatchImageData([
+    [0, 0, 255, 50],
+    [127, 255, 0, 50],
+    [255, 127, 0, 50],
+  ]);
 });
 
 test('1x1 rgba image, out to itself', () => {
-  const image = testUtils.createRgbaImage([[100, 0, 0, 50]]);
+  const image = testUtils.createRgbaImage([[100, 50, 0, 50]]);
   expect(image.level({ out: image })).toBe(image);
 });
 
-test('1x1 greya image, default options', () => {
+test('1x4 greya image, default options', () => {
   const image = testUtils.createRgbaImage([[100, 50, 0, 50]]);
-  expect(image.level()).toMatchImage(image);
+  expect(image.level()).toMatchImageData([[0, 0, 0, 50]]);
 });
 
 test('3x1 rgba image, custom input min and max', () => {
@@ -29,12 +38,12 @@ test('3x1 rgba image, custom input min and max', () => {
 test('3x1 rgba image, custom output min and max', () => {
   const image = testUtils.createRgbaImage([
     [0, 0, 0, 50],
-    [127, 0, 0, 50],
+    [127, 1, 0, 50],
     [255, 0, 0, 50],
   ]);
   expect(image.level({ outputMin: 100, outputMax: 150 })).toMatchImageData([
     [100, 100, 100, 50],
-    [124, 100, 100, 50],
+    [124, 150, 100, 50],
     [150, 100, 100, 50],
   ]);
 });

src/filters/__tests__/autoLevel.test.ts renamed to src/filters/__tests__/increaseContrast.test.ts

@@ -2,7 +2,7 @@ import { Image } from '../Image';
 import { ImageColorModel } from '../utils/constants/colorModels';
 import checkProcessable from '../utils/validators/checkProcessable';
 
-export interface AutoLevelOptions {
+export interface IncreaseContrastOptions {
   /**
    * Image to which to output.
    */
@@ -15,12 +15,16 @@ export interface AutoLevelOptions {
 }
 
 /**
- * Enhance the contrast of an image by spanning each channel on the range [0, image.maxValue].
+ * 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 - Enhance contrast options.
+ * @param options - Increase contrast options.
  * @returns The enhanced image.
  */
-export function autoLevel(image: Image, options: AutoLevelOptions = {}): Image {
+export function increaseContrast(
+  image: Image,
+  options: IncreaseContrastOptions = {},
+): Image {
   const { uniform = false } = options;
   checkProcessable(image, {
     bitDepth: [8, 16],

src/filters/__tests__/level.test.ts

@@ -2,7 +2,7 @@ export * from './and';
 export * from './blur';
 export * from './convolution';
 export * from './derivativeFilter';
-export * from './autoLevel';
+export * from './increaseContrast';
 export * from './gaussianBlur';
 export * from './gradientFilter';
 export * from './hypotenuse';

src/filters/autoLevel.ts renamed to src/filters/increaseContrast.ts

@@ -12,22 +12,22 @@ export interface LevelOptions {
    */
   channels?: number[];
   /**
-   * Minimal input value.
-   * @default `0`
+   * Input lower bound.
+   * @default `image.minMax().min`
    */
   inputMin?: number | number[];
   /**
-   * Maximal input value.
-   * @default `image.maxValue`
+   * Input upper bound.
+   * @default `image.minMax().min`
    */
   inputMax?: number | number[];
   /**
-   * Minimal output value.
+   * output lower bound.
    * @default `0`
    */
   outputMin?: number | number[];
   /**
-   * Maximal output value.
+   * Output upper bound.
    * @default `image.maxValue`
    */
   outputMax?: number | number[];
@@ -43,15 +43,16 @@ export interface LevelOptions {
 }
 
 /**
- * Level the image using the optional input and output value. This function allows you to enhance the image's contrast.
+ * 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 = 0,
-    inputMax = image.maxValue,
+    inputMin = minMax.min,
+    inputMax = minMax.max,
     outputMin = 0,
     outputMax = image.maxValue,
     gamma = 1,
@@ -86,11 +87,13 @@ export function level(image: Image, options: LevelOptions = {}) {
           inputMin[channel],
         );
 
-        const ratio = clamp(
+        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]) +