multiple changes:

- add DEFAULT_FOREGROUND color in Color.ts
- removed DimensionDecoder (now part of wasm code)
- removed SixelDecoderL2 (now part of wasm code)
- fix prolly undefined palette color in encoder
- wasm decoder:
  - changed to handle only one band at a time
  - static fixed memory with upper max band width
  - optimize with bulk-memory
  - added normal M1 for level 1 images or non truncating
  - cleanup emscripten install & wam build scripts
  - python wasmer example
  - wasm-simd proof of concept implementation
- moved WasmDecoder.ts to Decoder.ts
- Decoder.ts prepared as new main decoder
- convenient decode functions
- add new decoder to benchmarks
- cleanup imports/export in index.ts
- better build scripts:
  - remove the need for json imports
  - add UMD/ESM bundles for browser/webpack

Author: jerch

.gitignore

@@ -6,5 +6,7 @@
 /.nyc_output
 /benchmark
 /.vscode
-/wasm/sixel.wasm
-/src/wasm.json
+/wasm/decoder.wasm
+/wasm/settings.json
+/src/wasm.ts
+/emsdk

.npmignore

@@ -16,3 +16,5 @@ src/*.benchmark.*
 src/*.test.*
 img2sixel.js
 .vscode
+lib-esm
+emsdk

README.md

@@ -73,19 +73,6 @@ Properties of `DefaultDecoder`:
     meaning as in the constructor, explicit setting it to 0 will leave non encoded pixels unaltered (pixels, that were not colored in the SIXEL data). This can be used for a transparency like effect (background/previous pixel value will remain). Returns the altered `target`.
 
 
-#### WasmDecoder
-
-The `WasmDecoder` is a level 2 only decoder written in C and compiled to WebAssembly. While it can decode image data much faster (see benchmarks below), it imposes several usage restrictions:
-
-- limited to 1536 x 1536 pixels and 4096 palette colors (compile time settings)
-- level 2 only, needs proper pixel dimensions (can be obtained from raster attributes with `DimensionDecoder`)
-- always truncates images to pixel dimensions (not spec conform)
-
-Other than the default decoder, `WasmDecoder` is meant to be re-used with follow-up images, which lowers the need to spawn webassembly instances.
-
-TODO: document properties + canUsewasm + DimensionDecoder
-
-
 ### Encoding
 
 For encoding the library provides the following properties:
@@ -194,8 +181,169 @@ Results:
 TODO...
 
 
+
+### Decoder usage
+
+For casual usage and when you have the full image data at hand,
+you can use the convenient functions `decode` or `decodeAsync`.
+
+_Example (Typescript):_
+```typescript
+import { decode, decodeAsync, ISixelDecoderOptions } from 'sixel';
+
+// some options
+const OPTIONS: ISixelDecoderOptions = {
+    memoryLimit: 65536 * 256, // limit pixel memory to 16 MB (2048 x 2048 pixels)
+    ...
+};
+
+// in nodejs or web worker context
+const result = decode(some_data, OPTIONS);
+someRawImageAction(result.data32, result.width, result.height);
+
+// in browser main context
+decodeAsync(some_data, OPTIONS)
+  .then(result => someRawImageAction(result.data32, result.width, result.height));
+```
+
+These functions are much easier to use than the stream decoder,
+but come with a performance penalty of ~25% due to bootstrapping into
+the wasm module everytime. Do not use them, if you have multiple images to decode.
+Also they cannot be used for chunked data.
+
+For more advanced use cases with multiple images or chunked data,
+use the stream decoder directly.
+
+_Example (Typescript):_
+```typescript
+import { Decoder, DecoderAsync, ISixelDecoderOptions } from 'sixel';
+
+// some options
+const OPTIONS: ISixelDecoderOptions = {
+    memoryLimit: 65536 * 256, // limit pixel memory to 16 MB (2048 x 2048 pixels)
+    ...
+};
+
+// in nodejs or web worker context
+const decoder = new Decoder(OPTIONS);
+// in browser main context
+const decoder = DecoderAsync(OPTIONS);
+
+for (image of images) {
+    // initialize for next image with defaults
+    // for a more terminal like behavior you may want to override default settings
+    // with init arguments, e.g. set fillColor to BG color / reflect palette changes
+    decoder.init();
+
+    // for every incoming chunk call decode
+    for (chunk of image.data_chunks) {
+        decoder.decode(chunk);
+        // optional: check your memory limits
+        if (decoder.memoryUsage > YOUR_LIMIT) {
+        // the decoder is meant to be resilient for exceptional conditions
+        // and can be re-used after calling .release (if not, please file a bug)
+        // (for simplicity example exists whole loop)
+        decoder.release();
+        throw new Error('dont like your data, way too big');
+        }
+        // optional: grab partial data (useful for slow transmission)
+        somePartialRawImageAction(decoder.data32, decoder.width, decoder.height);
+    }
+
+    // image finished, grab pixels and dimensions
+    someRawImageAction(decoder.data32, decoder.width, decoder.height);
+
+    // optional: release held pixel memory
+    decoder.release();
+}
+```
+
+
+__Note on decoder memory handling__
+
+The examples above all contain some sort of memory limit notions. This is needed,
+because sixel image data does not strictly announce dimensions upfront,
+instead incoming data may implicitly expand image dimensions. While the decoder already
+limits the max width of an image with a compile time setting,
+there is no good way to limit the height of an image (can run "forever").
+
+To not run into out of memory issues the decoder respects an upper memory limit for the pixel array.
+The default limit is set rather high (hardcoded to 128 MB) and can be adjusted in the decoder options
+as `memoryLimit` in bytes. You should always adjust that value to your needs.
+
+During chunk decoding the memory usage can be tracked with `memoryUsage`. Other than `memoryLimit`,
+this value also accounts the static memory taken by the wasm module, thus is slightly higher and
+closer to the real usage of the decoder. Note that the decoder will try to pre-allocate the pixel array,
+if it can derive the dimensions early, thus `memoryUsage` might not change anymore for subsequent
+chunks after an initial jump. If re-allocation is needed during decoding, the decoder will hold up to twice
+of `memoryLimit` for a short amount of time.
+
+During decoding the decoder will throw an error, if the needed pixel memory exceeds `memoryLimit`.
+
+Between multiple images the decoder will not free the pixel memory of the previous image.
+This is an optimization to lower allocation and GC pressure of the decoder.
+Call `release` after decoding to explicitly free the pixel memory.
+
+Rules of thumb regarding memory:
+- set `memoryLimit` to a more realistic value, e.g. 64MB for 4096 x 4096 pixels
+- conditionally call `release` after image decoding, e.g. check if  `memoryUsage` stays within your expectations
+- under memory pressure set `memoryLimit` rather low, always call `release`
+
+
+### Encoder usage
+
+TODO...
+
+
+### Package format and browser bundles
+
+The node package comes as CommonJS and can be used as usual.
+An ESM package version is planned for a later release.
+
+For easier usage in the browser the package contains several prebuilt bundles under `/dist`:
+- decode - color functions, default palettes and decoder
+- encode - color functions, default palettes and encoder
+- full - full package containing all definitions.
+
+The browser bundles come in UMD and ESM flavors. Note that the UMD bundles export
+the symbols under `sixel`.
+
+Some usage examples:
+- vanilla usage with UMD version:
+  ```html
+  <script nomodule src="/path/to/decode.umd.js"></script>
+  ...
+  <script>
+    sixel.decodeAsync(some_data)
+      .then(result => someRawImageAction(result.data32, result.width, result.height));
+  </script>
+  ```
+- ESM example:
+  ```html
+  <script type="module">
+    import { decodeAsync } from '/path/to/decode.esm.js';
+
+    decodeAsync(some_data)
+      .then(result => someRawImageAction(result.data32, result.width, result.height));
+
+    // or with on-demand importing:
+    import('/path/to/decode.esm.js')
+      .then(m => m.decodeAsync(some_data))
+      .then(result => someRawImageAction(result.data32, result.width, result.height));
+  </script>
+  ```
+- web worker example:
+  ```js
+  importScripts('/path/to/decode.umd.js');
+
+  // in web worker we are free to use the sync variants:
+  const result = sixel.decode(some_data);
+  someRawImageAction(result.data32, result.width, result.height);
+  ```
+
+
 ### Status
-Currently beta, still more tests to come.
+Currently beta, still more tests to come. Also the API might still change.
 
 
 ### References

bin/install_emscripten.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+if [ -d emsdk ]; then
+  exit 0
+fi
+
+# pull emscripten on fresh checkout
+echo "Fetching emscripten..."
+
+git clone https://github.com/emscripten-core/emsdk.git
+cd emsdk
+
+# wasm module is only tested with 2.0.25, install by default
+./emsdk install 2.0.25
+./emsdk activate 2.0.25
+
+cd ..

bin/wrap_wasm.js

@@ -0,0 +1,12 @@
+const fs = require('fs');
+const LIMITS = require('../wasm/settings.json');
+
+const file = `
+export const LIMITS = {
+  CHUNK_SIZE: ${LIMITS.CHUNK_SIZE},
+  PALETTE_SIZE: ${LIMITS.PALETTE_SIZE},
+  MAX_WIDTH: ${LIMITS.MAX_WIDTH},
+  BYTES: '${fs.readFileSync('wasm/decoder.wasm').toString('base64')}'
+};
+`;
+fs.writeFileSync('src/wasm.ts', file);

index.html

@@ -60,32 +60,21 @@
   Reencoded with img2sixel:<br>
   <canvas id="output2" style="border: 1px solid black"></canvas>
   <script src="/dist/bundle.js"></script>
+  <script src="/dist/decode.umd.js"></script>
+  
   <script id="sampsa" type="application/json"></script>
   <script>
 
 let drawHandle = null;
 let imgS = null;
 let imgWasm = null;
 let wasmDecoder = null;
-sixel.WasmDecoderAsync().then(dec => wasmDecoder = dec);
-
-function decodeWasm(bytes) {
-  const start = new Date();
-  const dim = new sixel.DimensionDecoder().decode(bytes);
-  console.log('L2 attrs:', dim);
-  if (sixel.canUseWasm(dim.width, dim.height, 4096)) {
-    wasmDecoder.init(
-      dim.width,
-      dim.height,
-      sixel.toRGBA8888(...hexColorToRGB(document.getElementById('fillColor').value))  
-    );
-    wasmDecoder.decode(bytes);
-  }
-  drawImageL2(wasmDecoder.data32, wasmDecoder.width, wasmDecoder.height);
-  console.log('L2 conversion:', (new Date()) - start);
-}
+sixel.DecoderAsync().then(dec => wasmDecoder = dec);
 
-function drawImageL2(data, width, height) {
+function drawImageWasm() {
+  const data = wasmDecoder.data32;
+  const width = wasmDecoder.width;
+  const height = wasmDecoder.height;
   if (!height || !width) {
     return;
   }
@@ -172,25 +161,31 @@
 
   // create image
   const img = new sixel.SixelDecoder();
+  wasmDecoder.init(sixel.toRGBA8888(...hexColorToRGB(document.getElementById('fillColor').value)));
   imgS = img;
 
   // read in
   let start;
   if (s === 'wiki') {
     start = new Date();
-    img.decodeString('#0;2;0;0;0#1;2;100;100;0#2;2;0;100;0#1~~@@vv@@~~@@~~~~@@vv@@~~@@~~~~@@vv@@~~@@~~$#2??}}GG}}??}}????}}GG}}??}}????}}GG}}??}}??-#1!14!14!14@');
+            img.decodeString('#0;2;0;0;0#1;2;100;100;0#2;2;0;100;0#1~~@@vv@@~~@@~~~~@@vv@@~~@@~~~~@@vv@@~~@@~~$#2??}}GG}}??}}????}}GG}}??}}????}}GG}}??}}??$-#1!14!14!14A');
+    wasmDecoder.decodeString('#0;2;0;0;0#1;2;100;100;0#2;2;0;100;0#1~~@@vv@@~~@@~~~~@@vv@@~~@@~~~~@@vv@@~~@@~~$#2??}}GG}}??}}????}}GG}}??}}????}}GG}}??}}??$-#1!42A');
   } else {
     const response = await fetch('/testfiles/' + s);
     const bytes = new Uint8Array(await response.arrayBuffer());
-    decodeWasm(bytes);
+    //decodeWasm(bytes);
     start = new Date();
     if (document.getElementById('slow').checked) {
-      let localHandle = drawHandle = setInterval(() => drawImage(img), 100);
+      let localHandle = drawHandle = setInterval(() => {
+        drawImage(img);
+        drawImageWasm();
+      }, 100);
       let i = 0;
       const endTens = bytes.length - (bytes.length % 10);
       while (i < endTens) {
         if (drawHandle !== localHandle) return;
         img.decode(bytes, i, i + 10);
+        wasmDecoder.decode(bytes, i, i + 10);
         document.getElementById('stats').innerText = 'width: ' + img.width + '\nheight: ' + img.height;
         document.getElementById('swidth').value = img.width;
         document.getElementById('sheight').value = img.height;
@@ -199,10 +194,33 @@
       }
       if (bytes.length % 10) {
         img.decode(bytes, endTens, bytes.length);
+        wasmDecoder.decode(bytes, endTens, bytes.length);
+        //decodeWasm(bytes.subarray(endTens, endTens + bytes.length));
       }
       clearInterval(drawHandle);
     } else {
       img.decode(bytes);
+      decodeWasm(bytes);
+      wasmDecoder.decode(bytes);
+
+      //import('/dist/decode.es6.js').then(m => m.sixelDecodeAsync(bytes)).then(r => {
+      ////sixel_new.sixelDecodeAsync(bytes).then(r => {
+      //  console.log(r);
+      //  const data = r.data32;
+      //  const width = r.width;
+      //  const height = r.height;
+      //  if (!height || !width) {
+      //    return;
+      //  }
+      //  const canvas = document.getElementById('output_wasm');
+      //  const ctx = canvas.getContext('2d');
+      //  // resize canvas to show full image
+      //  canvas.width = width;
+      //  canvas.height = height;
+      //  const target = new ImageData(width, height);
+      //  new Uint32Array(target.data.buffer).set(data);
+      //  ctx.putImageData(target, 0, 0);
+      //});
     }
   }
   document.getElementById('stats').innerText = 'width: ' + img.width + '\nheight: ' + img.height;
@@ -215,6 +233,7 @@
   // output
   start = new Date();
   drawImage(img);
+  //drawImageWasm();
   console.log('output to canvas time', (new Date()) - start);
 }
 

package.json

@@ -12,7 +12,10 @@
     "prepublish": "npm run tsc",
     "coverage": "nyc --reporter=lcov --reporter=text --reporter=html npm test",
     "benchmark": "xterm-benchmark $*",
-    "build-wasm": "bash -c wasm/build.sh"
+    "build-wasm": "bin/install_emscripten.sh && cd wasm && ./build.sh && cd .. && node bin/wrap_wasm.js",
+    "bundle": "tsc --project tsconfig.esm.json && webpack",
+    "clean": "rm -rf lib lib-esm dist src/wasm.ts wasm/decoder.wasm wasm/settings.json",
+    "build-all": "npm run build-wasm && npm run tsc && npm run bundle"
   },
   "keywords": [
     "sixel",
@@ -25,23 +28,23 @@
   },
   "author": "Joerg Breitbart <j.breitbart@netzkolchose.de>",
   "license": "MIT",
-  "dependencies": {},
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "^1.0.1",
-    "@types/mocha": "^8.2.2",
-    "@types/node": "^14.17.3",
+    "@types/mocha": "^9.0.0",
+    "@types/node": "^14.17.12",
     "canvas": "^2.8.0",
-    "http-server": "^0.12.3",
-    "mocha": "^9.0.1",
+    "http-server": "^13.0.1",
+    "mocha": "^9.1.0",
     "node-ansiparser": "^2.2.0",
     "nyc": "^15.1.0",
     "open": "^8.2.1",
     "rgbquant": "^1.1.2",
+    "source-map-loader": "^3.0.0",
     "source-map-support": "^0.5.19",
-    "ts-loader": "^9.2.3",
-    "ts-node": "^10.0.0",
+    "ts-loader": "^9.2.5",
+    "ts-node": "^10.2.1",
     "tslint": "^6.1.3",
-    "typescript": "^4.3.4",
+    "typescript": "^4.4.2",
     "webpack": "^5.40.0",
     "webpack-cli": "^4.7.2",
     "xterm-benchmark": "^0.2.1"