refactor: rename depth to bitDepth and improve some error messages (#298)

Closes: #280

Author: targos

src/Image.ts

@@ -76,7 +76,7 @@ import {
 import {
   convertColor,
   ConvertColorOptions,
-  convertDepth,
+  convertBitDepth,
   copyTo,
   CopyToOptions,
   crop,
@@ -106,7 +106,7 @@ export type ImageDataArray = Uint8Array | Uint16Array | Uint8ClampedArray;
 /**
  * Bit depth of the image (nb of bits that encode each value in the image).
  */
-export type ColorDepth = 1 | 8 | 16;
+export type BitDepth = 1 | 8 | 16;
 
 export const ImageCoordinates = {
   CENTER: 'center',
@@ -125,7 +125,7 @@ export interface ImageOptions {
    *
    * @default `8`.
    */
-  depth?: ColorDepth;
+  bitDepth?: BitDepth;
 
   /**
    * Typed array holding the image data.
@@ -173,7 +173,7 @@ export class Image {
   /**
    * The number of bits per value in each channel.
    */
-  public readonly depth: ColorDepth;
+  public readonly bitDepth: BitDepth;
 
   /**
    * The color model of the image.
@@ -222,7 +222,7 @@ export class Image {
     options: ImageOptions = {},
   ) {
     const {
-      depth = 8,
+      bitDepth = 8,
       data,
       colorModel = 'RGB',
       origin = { row: 0, column: 0 },
@@ -243,7 +243,7 @@ export class Image {
     this.width = width;
     this.height = height;
     this.size = width * height;
-    this.depth = depth;
+    this.bitDepth = bitDepth;
     this.colorModel = colorModel;
     this.origin = origin;
 
@@ -252,21 +252,21 @@ export class Image {
     this.alpha = colorModelDef.alpha;
     this.channels = colorModelDef.channels;
 
-    this.maxValue = 2 ** depth - 1;
+    this.maxValue = 2 ** bitDepth - 1;
 
     if (data === undefined) {
       this.data = createPixelArray(
         this.size,
         this.channels,
         this.alpha,
-        this.depth,
+        this.bitDepth,
         this.maxValue,
       );
     } else {
-      if (depth === 8 && data instanceof Uint16Array) {
-        throw new Error(`depth is ${depth} but data is Uint16Array`);
-      } else if (depth === 16 && data instanceof Uint8Array) {
-        throw new Error(`depth is ${depth} but data is Uint8Array`);
+      if (bitDepth === 8 && data instanceof Uint16Array) {
+        throw new Error(`bitDepth is ${bitDepth} but data is Uint16Array`);
+      } else if (bitDepth === 16 && data instanceof Uint8Array) {
+        throw new Error(`bitDepth is ${bitDepth} but data is Uint8Array`);
       }
       const expectedLength = this.size * this.channels;
       if (data.length !== expectedLength) {
@@ -290,14 +290,14 @@ export class Image {
     options: CreateFromOptions = {},
   ): Image {
     const { width = other.width, height = other.height } = options;
-    let depth: ColorDepth;
+    let bitDepth: BitDepth;
     if (other instanceof Image) {
-      depth = other.depth;
+      bitDepth = other.bitDepth;
     } else {
-      depth = 8;
+      bitDepth = 8;
     }
     return new Image(width, height, {
-      depth,
+      bitDepth,
       colorModel: other.colorModel,
       origin: other.origin,
       ...options,
@@ -458,7 +458,7 @@ export class Image {
       height: this.height,
       data: this.data,
       channels: this.channels,
-      depth: this.depth,
+      bitDepth: this.bitDepth,
     };
   }
 
@@ -472,7 +472,7 @@ export class Image {
     return `Image {
   width: ${this.width}
   height: ${this.height}
-  depth: ${this.depth}
+  bitDepth: ${this.bitDepth}
   colorModel: ${this.colorModel}
   channels: ${this.channels}
   data: ${dataString}
@@ -577,7 +577,7 @@ export class Image {
    * Get the coordinates of a point in the image. The reference is the top-left corner.
    *
    * @param coordinates - The point for which you want the coordinates.
-   * @param round - Should the coordinates be rounded? This is useful when you want the center of the image.
+   * @param round - Whether the coordinates should be rounded. This is useful when you want the center of the image.
    * @returns Coordinates of the point in the format [column, row].
    */
   public getCoordinates(coordinates: ImageCoordinates, round = false): Point {
@@ -766,8 +766,8 @@ export class Image {
     return convertColor(this, colorModel, options);
   }
 
-  public convertDepth(newDepth: ColorDepth): Image {
-    return convertDepth(this, newDepth);
+  public convertBitDepth(newDepth: BitDepth): Image {
+    return convertBitDepth(this, newDepth);
   }
 
   public grey(options?: GreyOptions): Image {
@@ -1054,28 +1054,28 @@ export class Image {
  * @param size - Number of pixels.
  * @param channels - Number of channels.
  * @param alpha - Specify if there is alpha channel.
- * @param depth - Number of bits per channel.
+ * @param bitDepth - Number of bits per channel.
  * @param maxValue - Maximal acceptable value for the channels.
  * @returns The new pixel array.
  */
 function createPixelArray(
   size: number,
   channels: number,
   alpha: boolean,
-  depth: ColorDepth,
+  bitDepth: BitDepth,
   maxValue: number,
 ): ImageDataArray {
   const length = channels * size;
   let arr;
-  switch (depth) {
+  switch (bitDepth) {
     case 8:
       arr = new Uint8Array(length);
       break;
     case 16:
       arr = new Uint16Array(length);
       break;
     default:
-      throw new Error(`unexpected color depth: ${depth}`);
+      throw new Error(`unexpected bitDepth: ${bitDepth}`);
   }
 
   // Alpha channel is 100% by default.
@@ -1096,7 +1096,7 @@ function createPixelArray(
  */
 function printData(img: Image): string {
   const result = [];
-  const padding = img.depth === 8 ? 3 : 5;
+  const padding = img.bitDepth === 8 ? 3 : 5;
 
   for (let row = 0; row < img.height; row++) {
     const currentRow = [];

src/Mask.ts

@@ -1,4 +1,4 @@
-import { ColorDepth, Image } from './Image';
+import { BitDepth, Image } from './Image';
 import { subtract, SubtractImageOptions } from './compare';
 import {
   drawLineOnMask,
@@ -100,7 +100,7 @@ export class Mask {
   /**
    * The number of bits per value in each channel (always 1).
    */
-  public readonly depth: ColorDepth;
+  public readonly bitDepth: BitDepth;
 
   /**
    * The color model of the mask (always BINARY).
@@ -164,7 +164,7 @@ export class Mask {
     this.width = width;
     this.height = height;
     this.size = width * height;
-    this.depth = 1;
+    this.bitDepth = 1;
     this.colorModel = 'BINARY';
     this.origin = origin;
 

src/__tests__/Image.test.ts

@@ -9,7 +9,7 @@ describe('create new images', () => {
       width: 10,
       height: 20,
       size: 200,
-      depth: 8,
+      bitDepth: 8,
       colorModel: 'RGB',
       components: 3,
       channels: 3,
@@ -20,12 +20,12 @@ describe('create new images', () => {
   });
 
   it('should create a 16-bit image', () => {
-    const img = new Image(10, 20, { depth: 16 });
+    const img = new Image(10, 20, { bitDepth: 16 });
     expect(img).toMatchObject({
       width: 10,
       height: 20,
       size: 200,
-      depth: 16,
+      bitDepth: 16,
       colorModel: 'RGB',
       components: 3,
       channels: 3,
@@ -38,7 +38,7 @@ describe('create new images', () => {
   it('should create a grey image with alpha', () => {
     const img = new Image(10, 20, { colorModel: 'GREYA' });
     expect(img).toMatchObject({
-      depth: 8,
+      bitDepth: 8,
       colorModel: 'GREYA',
       components: 1,
       channels: 2,
@@ -78,33 +78,33 @@ describe('create new images', () => {
 
   it('should throw on wrong data size', () => {
     const data = new Uint16Array(2);
-    expect(() => new Image(2, 2, { data, depth: 16 })).toThrow(
+    expect(() => new Image(2, 2, { data, bitDepth: 16 })).toThrow(
       /incorrect data size: 2. Expected 12/,
     );
   });
 
   it('should throw on wrong bit depth', () => {
     // @ts-expect-error we want to test the error.
-    expect(() => new Image(1, 1, { depth: 20 })).toThrow(
-      /unexpected color depth: 20/,
+    expect(() => new Image(1, 1, { bitDepth: 20 })).toThrow(
+      /unexpected bitDepth: 20/,
     );
   });
-  it('should throw depth 8 but data 16', () => {
+  it('should throw with bit depth 8 but data 16', () => {
     const data = new Uint16Array([1, 2, 3, 4]);
     expect(() => new Image(2, 2, { colorModel: 'GREY', data })).toThrow(
-      'depth is 8 but data is Uint16Array',
+      'bitDepth is 8 but data is Uint16Array',
     );
   });
-  it('should throw depth 16 but data 8', () => {
+  it('should throw with bit depth 16 but data 8', () => {
     const data = new Uint8Array([1, 2, 3, 4]);
     expect(
       () =>
         new Image(2, 2, {
           colorModel: 'GREY',
-          depth: 16,
+          bitDepth: 16,
           data,
         }),
-    ).toThrow('depth is 16 but data is Uint8Array');
+    ).toThrow('bitDepth is 16 but data is Uint8Array');
   });
 });
 

src/__tests__/Mask.test.ts

@@ -10,7 +10,7 @@ describe('create new masks', () => {
       width: 10,
       height: 20,
       size: 200,
-      depth: 1,
+      bitDepth: 1,
       colorModel: 'BINARY',
       components: 1,
       channels: 1,

src/__tests__/__snapshots__/Image.test.ts.snap

@@ -4,7 +4,7 @@ exports[`check custom inspect with image too large 1`] = `
 "Image {
   width: 25
   height: 25
-  depth: 8
+  bitDepth: 8
   colorModel: GREYA
   channels: 2
   data: [...]
@@ -15,7 +15,7 @@ exports[`check custom inspect, GREYA image 1`] = `
 "Image {
   width: 2
   height: 2
-  depth: 8
+  bitDepth: 8
   colorModel: GREYA
   channels: 2
   data: {
@@ -31,7 +31,7 @@ exports[`check custom inspect, RGB image 1`] = `
 "Image {
   width: 1
   height: 2
-  depth: 8
+  bitDepth: 8
   colorModel: RGB
   channels: 3
   data: {

src/compare/__tests__/computeSsim.test.ts

@@ -112,8 +112,8 @@ test('windowSize too large error', async () => {
   const other = image;
   expect(() => {
     computeSsim(image, other, { windowSize: 5 });
-  }).toThrow('ssim: windowSize cannot exceed image dimensions');
+  }).toThrow('windowSize cannot exceed image dimensions');
   expect(() => {
     computeSsim(image, other, { windowSize: 20 });
-  }).toThrow('ssim: windowSize cannot exceed image dimensions');
+  }).toThrow('windowSize cannot exceed image dimensions');
 });

src/compare/__tests__/subtract.test.ts

@@ -55,7 +55,7 @@ test('different alpha should throw', async () => {
   const other = testUtils.createRgbImage([[1, 1, 1, 5, 5, 5, 10, 10, 10]]);
   expect(() => {
     image.subtract(other);
-  }).toThrow(`subtract: both images must have the same alpha and depth`);
+  }).toThrow(`subtract: both images must have the same alpha and bitDepth`);
 });
 
 test('different number of channels should throw', async () => {

src/compare/computeSsim.ts

@@ -53,7 +53,7 @@ export function computeSsim(
 
   if (windowSize) {
     if (windowSize > image.width || windowSize > image.height) {
-      throw new Error('ssim: windowSize cannot exceed image dimensions');
+      throw new Error('windowSize cannot exceed image dimensions');
     }
   } else {
     windowSize = Math.min(11, image.height, image.width);

src/draw/__tests__/drawCircleOnImage.test.ts

@@ -117,7 +117,7 @@ test('negative radius error', () => {
     image.drawCircle(center, radius, {
       color: [1],
     });
-  }).toThrow('drawCircle: circle radius must be positive');
+  }).toThrow('circle radius must be positive');
 });
 test('non-integer radius error', () => {
   const image = testUtils.createGreyImage([
@@ -131,7 +131,7 @@ test('non-integer radius error', () => {
     image.drawCircle(center, radius, {
       color: [1],
     });
-  }).toThrow('drawCircle: radius must be an integer');
+  }).toThrow('circle radius must be an integer');
 });
 
 test('draw grey filled circle, radius=0', () => {

src/draw/drawCircleOnImage.ts

@@ -54,12 +54,13 @@ export function drawCircleOnImage(
   });
 
   if (!Number.isInteger(radius)) {
-    throw new Error('drawCircle: radius must be an integer');
+    throw new Error('circle radius must be an integer');
   }
 
   if (radius < 0) {
-    throw new Error('drawCircle: circle radius must be positive');
+    throw new Error('circle radius must be positive');
   }
+
   if (radius === 0) {
     newImage.setVisiblePixel(center.column, center.row, color);
     return newImage;