first unit tests:

jerch · jerch · commit 7608bb4d0d97 · 2019-10-13T19:43:34.000+02:00
- test native color conversion
- decode parser transition tests
- sanitze color handling: clamp to 100%, always convert to positive ints
- memoryUsage property (a way to determine incoming sxiel stream going
overboard and to restrict decoding to certain memory limits)
diff --git a/README.md b/README.md
@@ -26,6 +26,10 @@ The library provides a class `SixelImage` with the following properties:
     Number respresenting the background fill color. A value of 0 will leave background pixels untouched.
     The number depends on endianess of the architecture, create it with `toRGBA8888(r, g, b, a)`.
 
+- `memoryUsage: number`  
+    Get current memory usage of the image data in bytes. Can be used to restrict image handling if memory is limited.  
+    Note: This only accounts the image pixel data storage, the real value will be slightly higher due to some JS object overhead.
+
 - `write(data: UintTypedArray, start: number = 0, end: number = data.length): void`  
     Decodes SIXEL bytes and updates the image data. This is done as a stream,
     therefore it is possible to grab partly transmitted images (see "Simulate slow chunks" in browser example).
diff --git a/src/index.test.ts b/src/index.test.ts
@@ -0,0 +1,226 @@
+import { assert } from 'chai';
+import { SixelImage, fromRGBA8888, toRGBA8888 } from './index';
+
+const BIG_ENDIAN = new Uint8Array(new Uint32Array([0xFF000000]).buffer)[0] === 0xFF;
+
+describe('RGBA8888 native colors', () => {
+  describe('toRGBA888', () => {
+    it('conversions', () => {
+      assert.equal(toRGBA8888(0, 0, 0, 0), 0);
+      assert.equal(toRGBA8888(0, 0, 0, 255), BIG_ENDIAN ? 0x000000FF : 0xFF000000);
+      assert.equal(toRGBA8888(0, 0, 255, 0), BIG_ENDIAN ? 0x0000FF00 : 0x00FF0000);
+      assert.equal(toRGBA8888(0, 255, 0, 0), BIG_ENDIAN ? 0x00FF0000 : 0x0000FF00);
+      assert.equal(toRGBA8888(255, 0, 0, 0), BIG_ENDIAN ? 0xFF000000 : 0x000000FF);
+    });
+    it('alpha defaults to 255', () => {
+      assert.equal(toRGBA8888(0, 0, 0), toRGBA8888(0, 0, 0, 255));
+      assert.equal(toRGBA8888(0, 0, 255), toRGBA8888(0, 0, 255, 255));
+      assert.equal(toRGBA8888(0, 255, 0), toRGBA8888(0, 255, 0, 255));
+      assert.equal(toRGBA8888(255, 0, 0), toRGBA8888(255, 0, 0, 255));
+      assert.equal(toRGBA8888(0, 255, 255), toRGBA8888(0, 255, 255, 255));
+      assert.equal(toRGBA8888(255, 0, 255), toRGBA8888(255, 0, 255, 255));
+      assert.equal(toRGBA8888(255, 255, 0), toRGBA8888(255, 255, 0, 255));
+      assert.equal(toRGBA8888(255, 255, 255), toRGBA8888(255, 255, 255, 255));
+    });
+    it('should only return unsigned', () => {
+      // test only for r and a here (g/b dont add to significant bit)
+      for (let r = 0; r <= 0xFF; ++r) {
+        for (let a = 0; a <= 0xFF; ++a) {
+          const color = toRGBA8888(r, 0, 0, a);
+          assert.equal(color >= 0, true);
+        }
+      }
+    });
+    it('handled signed channel values', () => {
+      assert.equal(toRGBA8888(-8, -50, -100, -127), toRGBA8888(-8 >>> 0, -50 >>> 0, -100 >>> 0, -127 >>> 0));
+    });
+    it('strip channel values to 8 bit (not clamping)', () => {
+      assert.equal(toRGBA8888(0x1234, 0x5678, 0xabcd, 0xef11), BIG_ENDIAN ? 0x3478cd11 : 0x11cd7834);
+    });
+  });
+  describe('fromRGBA8888', () => {
+    it('conversions', () => {
+      assert.deepEqual(fromRGBA8888(0), [0, 0, 0, 0]);
+      assert.deepEqual(fromRGBA8888(0x000000FF), BIG_ENDIAN ? [0, 0, 0, 255] : [255, 0, 0, 0]);
+      assert.deepEqual(fromRGBA8888(0x0000FF00), BIG_ENDIAN ? [0, 0, 255, 0] : [0, 255, 0, 0]);
+      assert.deepEqual(fromRGBA8888(0x00FF0000), BIG_ENDIAN ? [0, 255, 0, 0] : [0, 0, 255, 0]);
+      assert.deepEqual(fromRGBA8888(0xFF000000), BIG_ENDIAN ? [255, 0, 0, 0] : [0, 0, 0, 255]);
+    });
+    it('should only create unsigned channel values', () => {
+      assert.deepEqual(fromRGBA8888(-1), [255, 255, 255, 255]);
+      // 2 complement: -0xedcba988 ==> 0x12345678 (newDigit = 15 - digit; result + 1)
+      assert.deepEqual(fromRGBA8888(-0xedcba988), BIG_ENDIAN ? [0x12, 0x34, 0x56, 0x78] : [0x78, 0x56, 0x34, 0x12]);
+    });
+    it('strip values to 32bit', () => {
+      assert.deepEqual(fromRGBA8888(0x1234567890), BIG_ENDIAN ? [0x12, 0x34, 0x56, 0x78] : [0x90, 0x78, 0x56, 0x34])
+    });
+  });
+})
+
+describe('SixelImage', () => {
+  let img: SixelImage;
+  beforeEach(() => {
+    img = new SixelImage();
+  });
+  describe('empty data', () => {
+    it('width/height are 0', () => {
+      assert.equal(img.width, 0);
+      assert.equal(img.height, 0);
+    });
+    it('toSixel methods should not produce any data', () => {
+      assert.doesNotThrow(() => img.toSixelBytes(c => { throw Error('should not have been called'); }));
+      assert.equal(img.toSixelString(), '');
+    });
+    it('toImageData does not throw or alter target', () => {
+      const target = new Uint8ClampedArray(256 * 4);
+      target.fill(10);
+      assert.doesNotThrow(() => img.toImageData(target, 16, 16));
+      assert.deepEqual(target, (new Uint8ClampedArray(256 * 4)).fill(10));
+    });
+  });
+  describe('decode parser', () => {
+    describe('state transitions', () => {
+      it('DATA -> DATA', () => {
+        // excluded chars leading to other states
+        const except = [33, 34, 35];
+        const input = new Uint8Array(10);
+        for (let i = 0; i < 256; ++i) {
+          if (~except.indexOf(i)) continue;
+          input[0] = i;
+          img.write(input, 0, 1);
+          assert.equal((img as any)._currentState, 0);  // 0 == DATA
+        }
+      });
+      it('DATA -> COMPRESSION', () => {
+        const input = new Uint8Array(10);
+        input[0] = 33;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 1);    // 1 == COMPRESSION
+      });
+      it('DATA -> ATTR', () => {
+        const input = new Uint8Array(10);
+        input[0] = 34;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 2);    // 2 == ATTR
+      });
+      it('DATA -> COLOR', () => {
+        const input = new Uint8Array(10);
+        input[0] = 35;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 3);    // 3 == COLOR
+      });
+      it('COMPRESSION -> COMPRESSION', () => {
+        (img as any)._currentState = 1;
+        const input = new Uint8Array(10);
+        for (let i = 0; i < 256; ++i) {
+          if (63 <= i && i <= 126) continue;
+          input[0] = i;
+          img.write(input, 0, 1);
+          assert.equal((img as any)._currentState, 1);
+        }
+      });
+      it('COMPRESSION -> DATA', () => {
+        (img as any)._currentState = 1;
+        const input = new Uint8Array(10);
+        for (let i = 63; i < 127; ++i) {
+          input[0] = i;
+          img.write(input, 0, 1);
+          assert.equal((img as any)._currentState, 0);
+          (img as any)._currentState = 1;
+        }
+      });
+      it('ATTR -> ATTR', () => {
+        // excluded chars leading to other states
+        const except = [33, 35, 36, 45];
+        const input = new Uint8Array(10);
+        (img as any)._currentState = 2;
+        for (let i = 0; i < 256; ++i) {
+          if (~except.indexOf(i)) continue;
+          if (63 <= i && i <= 126) continue;
+          input[0] = i;
+          img.write(input, 0, 1);
+          assert.equal((img as any)._currentState, 2);
+          (img as any)._currentState = 2;
+        }
+      });
+      it('ATTR -> DATA', () => {
+        (img as any)._currentState = 2;
+        const input = new Uint8Array(10);
+        for (let i = 63; i < 127; ++i) {
+          input[0] = i;
+          img.write(input, 0, 1);
+          assert.equal((img as any)._currentState, 0);
+          (img as any)._currentState = 2;
+        }
+        (img as any)._currentState = 2;
+        input[0] = 36;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 0);
+        (img as any)._currentState = 2;
+        input[0] = 45;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 0);
+      });
+      it('ATTR -> COMPRESSION', () => {
+        (img as any)._currentState = 2;
+        const input = new Uint8Array(10);
+        input[0] = 33;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 1);    // 1 == COMPRESSION
+      });
+      it('ATTR -> COLOR', () => {
+        (img as any)._currentState = 2;
+        const input = new Uint8Array(10);
+        input[0] = 35;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 3);    // 3 == COLOR
+      });
+      it('COLOR -> COLOR', () => {
+        // excluded chars leading to other states
+        const except = [33, 34, 36, 45];
+        const input = new Uint8Array(10);
+        (img as any)._currentState = 3;
+        for (let i = 0; i < 256; ++i) {
+          if (~except.indexOf(i)) continue;
+          if (63 <= i && i <= 126) continue;
+          input[0] = i;
+          img.write(input, 0, 1);
+          assert.equal((img as any)._currentState, 3);
+          (img as any)._currentState = 3;
+        }
+      });
+      it('COLOR -> DATA', () => {
+        (img as any)._currentState = 3;
+        const input = new Uint8Array(10);
+        for (let i = 63; i < 127; ++i) {
+          input[0] = i;
+          img.write(input, 0, 1);
+          assert.equal((img as any)._currentState, 0);
+          (img as any)._currentState = 3;
+        }
+        (img as any)._currentState = 3;
+        input[0] = 36;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 0);
+        (img as any)._currentState = 3;
+        input[0] = 45;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 0);
+      });
+      it('COLOR -> COMPRESSION', () => {
+        (img as any)._currentState = 3;
+        const input = new Uint8Array(10);
+        input[0] = 33;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 1);    // 1 == COMPRESSION
+      });
+      it('COLOR -> ATTR', () => {
+        (img as any)._currentState = 3;
+        const input = new Uint8Array(10);
+        input[0] = 34;
+        img.write(input, 0, 1);
+        assert.equal((img as any)._currentState, 2);    // 2 == ATTR
+      });
+    });
+  });
+});
diff --git a/src/index.ts b/src/index.ts
@@ -137,14 +137,14 @@ function hlsToRgb(h: number, l: number, s: number): RGBA8888 {
   }
 
   return (BIG_ENDIAN)
-    ? Math.round(r * 255) << 24 | Math.round(g * 255) << 16 | Math.round(b * 255) << 8 | 0xFF   // RGBA32
-    : 0xFF000000 | Math.round(b * 255) << 16 | Math.round(g * 255) << 8 | Math.round(r * 255);  // ABGR32
+    ? (Math.round(r * 255) << 24 | Math.round(g * 255) << 16 | Math.round(b * 255) << 8 | 0xFF) >>> 0   // RGBA32
+    : (0xFF000000 | Math.round(b * 255) << 16 | Math.round(g * 255) << 8 | Math.round(r * 255)) >>> 0;  // ABGR32
 }
 
 function normalizeRGB(r: number, g: number, b: number): RGBA8888 {
   return (BIG_ENDIAN)
-    ? Math.round(r / 100 * 255) << 24 | Math.round(g / 100 * 255) << 16 | Math.round(b / 100 * 255) << 8 | 0xFF   // RGBA32
-    : 0xFF000000 | Math.round(b / 100 * 255) << 16 | Math.round(g / 100 * 255) << 8 | Math.round(r / 100 * 255);  // ABGR32
+    ? (Math.round(r / 100 * 255) << 24 | Math.round(g / 100 * 255) << 16 | Math.round(b / 100 * 255) << 8 | 0xFF) >>> 0   // RGBA32
+    : (0xFF000000 | Math.round(b / 100 * 255) << 16 | Math.round(g / 100 * 255) << 8 | Math.round(r / 100 * 255)) >>> 0;  // ABGR32
 }
 
 function normalizeHLS(h: number, l: number, s: number): RGBA8888 {
@@ -188,6 +188,13 @@ class SixelBand {
     this.data = new Uint32Array(length * 6);
   }
 
+  /**
+   * Get current memory usage of the band.
+   */
+  public get memUsage(): number {
+    return this.data.length * 4;
+  }
+
   /**
    * Add a sixel to the band.
    * Called by the parser for any data byte of the sixel stream.
@@ -464,7 +471,7 @@ const SIXEL_TABLE = (() => {
   // default transition for all states
   for (state in states) {
     // Note: ignore never changes state
-    table.addMany(r(0x00, 0x80), state, SixelAction.IGNORE, state);
+    table.addMany(r(0x00, 0x100), state, SixelAction.IGNORE, state);
   }
   // DATA state
   table.addMany(r(63, 127), SixelState.DATA, SixelAction.DRAW, SixelState.DATA);
@@ -648,6 +655,16 @@ export class SixelImage {
     return this._width || Math.max.apply(null, this._bands.map(el => el.width)) | 0;
   }
 
+  /**
+   * Get current memory usage of the image data in bytes.
+   * Can be used to restrict image handling if memory is limited.
+   * Note: This only accounts the image pixel data storage, the real value
+   * will be slightly higher due to some JS object overhead.
+   */
+  public get memUsage(): number {
+    return this._bands.reduce((accu, cur) => accu + cur.memUsage, 0);
+  }
+
   /**
    * Write SIXEL string data to the image.
    */
@@ -671,8 +688,8 @@ export class SixelImage {
     let params = this._params;
 
     for (let i = start; i < end; ++i) {
-      const code = data[i];
-      const transition = SIXEL_TABLE.table[currentState << 8 | (code < 0x7F ? code : 0xFF)];
+      const code = data[i] & 0xFF;
+      const transition = SIXEL_TABLE.table[currentState << 8 | (code < 0x7F ? code : 0xFF)] | 0;
       switch (transition >> 4) {
         case SixelAction.DRAW:
           dataStart = (~dataStart) ? dataStart : i;
@@ -736,11 +753,19 @@ export class SixelImage {
           if (currentState === SixelState.COLOR) {
             if (params.length >= 5) {
               if (params[1] === 1) {
-                // HLS color
-                this._colors[params[0]] = color = normalizeHLS(params[2], params[3], params[4]);
+                // HLS color, angle as mod 260, LS in % clamped to 100
+                this._colors[params[0]] = color = normalizeHLS(
+                  params[2] % 360,
+                  Math.min(params[3], 100),
+                  Math.min(params[4], 100)
+                );
               } else if (params[1] === 2) {
-                // RGB color
-                this._colors[params[0]] = color = normalizeRGB(params[2], params[3], params[4]);
+                // RGB color in %, clamped to 100
+                this._colors[params[0]] = color = normalizeRGB(
+                  Math.min(params[2], 100),
+                  Math.min(params[3], 100),
+                  Math.min(params[4], 100)
+                );
               }
             } else if (params.length === 1) {
               color = this._colors[params[0]] || this._colors[0];
@@ -854,6 +879,11 @@ export class SixelImage {
    * @param cb  callback to process a single SIXEL chunk (borrowed)
    */
   public toSixelBytes(cb: (chunk: Uint8Array) => void): void {
+    // exit early if we have no image data
+    if (!this.width || !this.height) {
+      return;
+    }
+
     // prepare chunk buffer
     if (!this._chunk || this._chunk.length < this.width + 100) {
       this._chunk = new Uint8Array(this.width + 100);
