better docs and full sequence example

Author: jerch

README.md

@@ -1,38 +1,51 @@
 ## Sixel images in Javascript.
 
-SIXEL decoding / encoding library for node and the browser.
+SIXEL image decoding / encoding library for node and the browser.
+
 The library provides a class `SixelImage` with the following properties:
 
 - `constructor(fillColor: RGBA8888 = DEFAULT_BACKGROUND)`  
     Creates a new SIXEL image. The optional `fillColor` (default black) is used to fill
     "holey pixels" with a background color during pixel transfer in `toImageData`.
 
 - `width: number`  
-    Pixel width of the image. Updates during `write`.
+    Pixel width of the image. Updates during `write`. Other than stated in the SIXEL specification (DEC STD 070)
+    a width from raster attributes takes precedence, thus if a SIXEL data stream contains raster attributes
+    with a valid horizontal extend, width will always be set to this value, even for half transmitted images.
+    Also overlong sixel bands (a row of 6 vertical pixels) will be stripped to the raster attribute width.
+    (band data beyond width is not accessible anymore later on). If no raster attributes were transmitted
+    (used in earlier SIXEL variant) width will be set to the longest sixel band width found.
 
 - `height: number`  
-    Pixel height of the image. Updates during `write`.
+    Pixel height of the image. Updates during `write`. Height is either set from a valid vertical extend in
+    raster attributes, or grows with the number of sixel bands found in the data stream (number of bands * 6).
+    Raster attributes again have precedence over number of bands (band data beyond height is not
+    accessible anymore later on, also see `width`).
 
 - `fillColor: RGBA8888`  
-    Number respresenting the background fill color. The number depends on endianess of the architecture,
-    create it with `toRGBA8888(r, g, b, a)`.
+    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)`.
 
 - `write(data: UintTypedArray, start: number = 0, end: number = data.length): void`  
-    Writes SIXEL bytes to the image and updates the image data. This is done as a stream,
-    therefore it is possible to grab partly transmitted images (see browser example).
-    `data` can be any array like type with single bytes per index position.
+    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).
+    `data` can be any array like type with single byte values per index position.  
+    Note: Normally SIXEL data is embedded in a DCS escape sequence. To properly handle the full sequence with introducer
+    and finalizer you should to use an escape sequence parser (like `node-ansiparser` or the parser found in `xterm.js`).
+    The `write` method of `SixelImage` is only meant for the data part
+    (also see example `node_example_decode_full_sequence.js`).
 
 - `writeString(data: string, start: number = 0, end: number = data.length): void`  
     Same as `write` but with string data instead. For better performance use `write`.
 
 - `toImageData(target: Uint8ClampedArray, width: number, height: number, dx: number = 0, dy: number = 0, sx: number = 0, sy: number = 0, swidth: number = this.width, sheight: number = this.height, fillColor: RGBA8888 = this.fillColor): Uint8ClampedArray`  
-    Write pixel data to pixel array `target`. A pixel array can be obtained from `ImageData.data`, e.g. from a canvas.
+    Writes pixel data to pixel array `target`. A pixel array can be obtained from `ImageData.data`, e.g. from a canvas.
     `width` and `height` must contain the full dimension of the target. Use `dx`, `dy` (offset in target) and
     `sx`, `sy` (offset in source) and `swidth`, `sheight` (area in source) for cropping/clipping. `fillColor` has the same
     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`.
 
 - `toSixelBytes(cb: (chunk: Uint8Array) => void): void`  
-    Encodes image data as chunks of SIXEL bytes. `cb` will be called multiple times the SIXEL data in `chunk` until all image data was transmitted. `chunk` is borrowed, thus the data should be copied/written right away.  
+    Encodes image data as chunks of SIXEL bytes. `cb` will be called multiple times with SIXEL data in `chunk` until all image data was transmitted. `chunk` is borrowed, thus the data should be copied/written right away.  
     Note: The output contains only the SIXEL image data (no escape sequence introducer / finalizer).
 
 - `toSixelString(): string`  
@@ -45,7 +58,8 @@ The library provides a class `SixelImage` with the following properties:
     of `data`. Since SIXEL is a palette based image format, `palette` should contain the used colors in `data`.
     If no palette was given the colors will fallback to a 16 colors palette derived from VT340. This is most
     likely unwanted, also to avoid poor results in general use proper quantization/dithering and palette creation
-    before creating the SIXEL image. See `node_example_encode.js` for an example usage in conjunction with `rgbquant`.  
+    before creating the SIXEL image. See `node_example_encode.js` for an example usage in conjunction with `rgbquant`.
+    For transparency only an alpha value of 0 will be respected as fully transparent, other alpha values are set to fully opaque (255). Transparent pixels will be colored by the terminal later on depending on the `backgroundSelect` setting of the introducer.  
     Note: Some terminals have strict palette limitations (e.g. xterm is bound to 16 colors only in VT340 mode).
 
 - `static introducer(backgroundSelect: number = 0): string`  
@@ -54,30 +68,30 @@ The library provides a class `SixelImage` with the following properties:
     `backgroundSelect` is a hint for the terminal how to deal with uncolored pixels:
 
     - 0 - device default action (most terminals will apply background color)
-    - 1 - no action (no change to zero bit value grid positions)
-    - 2 - set to background color - zero bit value grid positions are set to background color (device dependent).
+    - 1 - no action (previous pixel value at output position should remain)
+    - 2 - set to background color (device dependent)
 
 - `static finalizer(): string`  
-    Finalizes the SIXEL escape sequence. Write this, when the SIXEL data stream has ended to restore
-    the terminal to normal operation. Note that a SIXEL escape sequences changes the operation mode
-    of a terminal, forgetting the finalizer might leave the terminal in an unrecoverable state.
+    Finalizes the SIXEL escape sequence. Write this, when the SIXEL data stream has ended.
+    Note that a SIXEL escape sequences changes the operation mode of a terminal,
+    forgetting the finalizer might leave the terminal in an unrecoverable state.
 
-Furthermore the library exposes two convenient functions to convert native RGBA colors:
+Furthermore the library exposes two convenient functions to convert to and from native RGBA colors:
 
 - `function toRGBA8888(r: number, g: number, b: number, a: number = 255): RGBA8888`  
-    Converts the RGB channels values to the native color type `RGBA8888`.
+    Converts the RGBA channel values to the native color type `RGBA8888`.
 
 - `function fromRGBA8888(color: RGBA8888): number[]`  
     Converts the native color to an array of [r, g, b, a].
 
 ### Installation
 Install the library with `npm install sixel`.
 
-### Demos and examples
+### Examples and browser demo
 See the example files for decoding/encoding in nodejs. Note that the examples and the browser demo are not part
 of the npm package, clone the repo and run `npm install` if you want to see them in action.
 
-Decoding can also be tested in the browser with `npm start` under `localhost:8080`.
+Decoding can also be tested in the browser after `npm start` under `localhost:8080`.
 
 ### Status
 Currently alpha, tests are yet to come.
@@ -86,3 +100,7 @@ Currently alpha, tests are yet to come.
 - tests
 - optimizations
 - more docs
+
+### References
+
+While being quite common in the DEC ecosystem in the 80s (even used for printer protocols), SIXEL references are very limited these days. The closest to a specification we have can be found in the Video Systems Reference Manual ([DEC STD 070](http://www.bitsavers.org/pdf/dec/standards/EL-SM070-00_DEC_STD_070_Video_Systems_Reference_Manual_Dec91.pdf#page=908), p. 908-933). Also see [Sixel Graphics](https://www.vt100.net/docs/vt3xx-gp/chapter14.html) on vt100.net, which gives a quick overview. For implementation this old usenet article "[All About SIXELs](https://www.digiater.nl/openvms/decus/vax90b1/krypton-nasa/all-about-sixels.text)" was very helpful.

node_example_decode_full_sequence.js

@@ -0,0 +1,81 @@
+const { SixelImage, toRGBA8888 } = require('./lib/index');
+const { createCanvas, createImageData } = require('canvas');
+const fs = require('fs');
+const open = require('open');
+const AnsiParser = require('node-ansiparser');
+
+
+/**
+ * Despite the other decode examples we use the normal testfiles here
+ * with full DCS sequences. For parsing of the escape sequence we can use `node-anisparser`.
+ * 
+ * Note that `node-ansiparser` works only with strings, thus we have to set 'utf-8' as file encoding
+ * (and use `SixelImage.writeString` later on). This will not work with all testfiles,
+ * some of them have 8bit control characters that get stripped with 'utf-8'.
+ */
+fs.readFile('testfiles/boticelli.six', 'utf-8', (err, data) => {
+  let image = null;
+
+  // terminal object needed for the sequence parser
+  // we are only interested in the DCS calls, thus skip the other methods
+  const terminal = {
+    // some background color
+    backgroundColor: toRGBA8888(255, 255, 0, 255),
+
+    // some state to determine whether DCS payload should go to sixel image
+    // the state is needed since the input might contain other non DCS sequences
+    // that should not be treated as SIXEL data
+    inSixel: false,
+
+    // inst_H: called whan a DCS sequence starts
+    inst_H(collected, params, flag) {
+      // q means incoming SIXEL DCS, thus create new SIXEL image
+      if (flag === 'q') {
+        // also eval params of the sequence, P2 is backgroundSelect
+        // if set to 1 we should set fillColor to 0 (leave transparent)
+        // else set to background color from the terminal
+        // hint: try changing the test file or the color to see the effect of this setting
+        image = new SixelImage(params[1] === 1 ? 0 : this.backgroundColor);
+        this.inSixel = true;
+      }
+    },
+
+    // inst_P: called for DCS payload chunks
+    inst_P(chunk) {
+      if (this.inSixel && image) {
+        image.writeString(chunk);
+      }
+    },
+
+    // inst_U: called when DCS sequence finishs
+    inst_U() {
+      if (this.inSixel) {
+        this.inSixel = false;
+
+        // we were actually in a SIXEL DCS sequence
+        // and have now all image data received, thus
+        // can continue image handling:
+
+        // transfer bitmap data to ImageData object
+        const imageData = createImageData(image.width, image.height);
+        image.toImageData(imageData.data, image.width, image.height);
+
+        // draw ImageData to canvas
+        const canvas = createCanvas(image.width, image.height);
+        const ctx = canvas.getContext('2d');
+        ctx.putImageData(imageData, 0, 0);
+
+        // write to some file and show it
+        const targetFile = __dirname + '/node_decode_full_sequence_output.png';
+        const out = fs.createWriteStream(targetFile);
+        const stream = canvas.createPNGStream();
+        stream.pipe(out);
+        out.on('finish', () => open(targetFile));
+      }
+    }
+  };
+
+  // create sequence parser and parse the file data
+  var parser = new AnsiParser(terminal);
+  parser.parse(data);
+})

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sixel",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Sixel image format for node and browser.",
   "main": "./lib/index.js",
   "scripts": {
@@ -28,6 +28,7 @@
     "chai": "^4.2.0",
     "http-server": "^0.11.1",
     "mocha": "^5.2.0",
+    "node-ansiparser": "^2.2.0",
     "open": "^6.4.0",
     "rgbquant": "^1.1.2",
     "ts-loader": "^5.3.3",

src/index.ts

@@ -334,6 +334,7 @@ class SixelBand {
     const end = this.width * 6;
     let lastCode = -1;
     let accu = 1;
+    // FIXME: avoid running beyond data.length (may happen if a single band is shorter than image width)
     for (let cursor = 0; cursor < end; cursor += 6) {
       let code = 0;
       for (let p = 0; p < 6; ++p) {