polish docs

Author: jerch

README.md

@@ -5,72 +5,65 @@ SIXEL image decoding / encoding library for node and the browser.
 
 ### Decoding
 
-For decoding the library provides two decoder classes with slightly different semantics.
+For decoding the library provides a stream decoder, that can either be used directly or with the convenient functions.
 
+- `decode(data: UintTypedArray | string, opts?: IDecoderOptions): IDecodeResult`  
+    Convenient function to decode the sixel data in `data`. Can be used for casual decoding and when you have the full image data at hand (not chunked). The function is actually a thin wrapper around the decoder, and spawns a new instance for every call.  
+    Returns the decoding result as `{width, height, data32}`.
 
-#### DefaultDecoder
+- `decodeAsync(data: UintTypedArray | string, opts?: IDecoderOptions): Promise<IDecodeResult>`  
+    Async version of `decode`. Use this one in browser main context.
 
-The `DefaultDecoder` is a general purpose decoder written in Typescript. It can decode level1 and level2
-SIXEL data with reasonable speed and without any further preparations. It currently only supports _printerMode_(_terminalMode_ with proper shared/private palette semantics is planned).
 
-Properties of `DefaultDecoder`:
+#### Decoder
 
-- `constructor(public fillColor: RGBA8888 = DEFAULT_BACKGROUND, public palette: RGBA8888[] = PALETTE_VT340_COLOR, public paletteLimit: number = 65536)`  
-    Creates a new SIXEL image. The optional `fillColor` (default black) is used to fill
-    "holey pixels" with a background color during pixel transfer in `toPixelData`. Set `palette` to the
-    terminal's default colors (defaults to 16 VT340 colors). `paletteLimit` can be used to restrict the color registers.
+The decoder uses webassembly for data decoding (see [/wasm](wasm/) for the webassembly parts), which gives a major performance improvement, compared to the old JS-based decoder.
 
-- `width: number`  
-    Pixel width of the image. Updates during `decode`. 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.
-    If no raster attributes were transmitted (used in earlier SIXEL variant) width will be set to the longest sixel band width found.
+Properties of `Decoder`:
 
-- `height: number`  
-    Pixel height of the image. Updates during `decode`. 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 (also see `width`).
+- `constructor(opts?: IDecoderOptions)`  
+    Creates a new decoder instance. Spawns the internal wasm part synchronously, which will work in nodejs or a web worker context, but not in the main context of all browsers. Use the promisified constructor function `DecoderAsync` there instead.  
+    Override default decoder options with `opts`. The options are used as default settings during image decoding and can be further overridden at individual images with `init`.
 
-- `realWidth: number`  
-    Other than `width` contains the real width of image data derived from longest SIXEL band found. For spec conform output use this.
+- `init(fillColor?: RGBA8888, palette?: Uint32Array, paletteLimit?: number, truncate?: boolean)`  
+    Initialize the decoder for the next image. This must be called before doing any decoding.  
+    The arguments can be used to override decoder default options. if omitted the default options will be used.
+    
+    The `palette` argument is somewhat special, as it respects a 3-way handling:
+    - explicitly set: applies values from your palette
+    - set to `undefined`: applies values from default decoder palette
+    - set to `null`: no palette changes applied (leaves color registers from previous decoding untouched)
 
-- `realHeight: number`  
-    Contains the real height of the image data, which might be greater or lesser than `height`. For spec conform output use this.
+    The `truncate` settings indicates, whether the decoder should limit image dimensions to found raster attributes. While this is not 100% spec-conform, it is what most people would expect and how modern sixel encoder will encode the data. Therefore is set by default.
 
-- `rasterWidth: number`  
-    Contains width from raster attributes. 0 if no raster attributes were found.
+- `decode(data: UintTypedArray, start: number = 0, end: number = data.length): void`  
+    Decode sixel data provided in `data` from `start` to `end` (exclusive). `data` must be a typed array containing single byte values at the index positions.  
+    The decoding is stream aware, thus can be fed with chunks of data until all image data was consumed.
 
-- `rasterHeight: number`  
-    Contains height from raster attributes. 0 if no raster attributes were found.
+- `decodeString(data: string, start: number = 0, end: number = data.length): void`  
+    Same as `decode`, but with string data. Do not use this method, if performance matters.
 
-- `rasterRatioNumerator: number` & `rasterRatioDenominator: number`  
-    Contains the pixel ratio numerator and denominator given by raster attributes. Note that `toPixelData` does not evaluate these settings and always assumes 1:1.
+- `release(): void`  
+    Release internally held image ressources to free memory. This may be needed after decoding a rather big image consuming a lot of memory. The decoder will not free the memory on its own, instead tries to re-use ressources for the next image by default. Also see below about memory handling.
 
-- `fillColor: RGBA8888`  
-    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)`.
+- `data32: Uint32Array`  
+    Getter of the pixel data as 32-bit data (RGBA8888). The pixel array will always be sized as full image of the currently reported `width` and `height` dimensions (with `fillColor` applied). Note that the array is only borrowed in most cases and you may want to copy it before doing further processing.  
+    It is possible to grab the pixels of partially transmitted images during chunk decoding. Here image dimensions may not be final yet and keep shifting until all data was processed.
 
-- `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.
+- `width: number` 
+    Reports the current width of the current image. For `truncate=true` this may report the raster width, if a valid raster attribute was found. Otherwise reports rightmost band cursor advance seen so far. 
 
-- `decode(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).
-    `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`).
-    Note that this method is only meant for the data part of a SIXEL sequence (also see example `node_example_decode_full_sequence.js`).
+- `height: number`  
+    Reports the current height of the current image. Note that for `trancate=true` this may report the raster height, if a valid raster attribute was found. Otherwise reports the height in multiple of 6 pixels (seen sixel bands).
 
-- `decodeString(data: string, start: number = 0, end: number = data.length): void`  
-    Same as `decode` but with string data instead. For better performance use `decode`.
+- `memoryUsage: number`  
+    Reports the current memory usage of the decoder for wasm module memory and allocated pixel buffer.
 
-- `toPixelData(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`  
-    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`.
+- `properties: IDecoderProperties`  
+    Reports various properties of the current decoder state.
+
+- `palette: Uint32Array`  
+    Returns the currently loaded palette (borrowed).
 
 
 ### Encoding
@@ -104,27 +97,30 @@ For encoding the library provides the following properties:
 
 ### Convenient Properties
 
-Furthermore the library exposes some convenient properties:
+Furthermore the library exposes some general purpose properties:
 
 - `function toRGBA8888(r: number, g: number, b: number, a: number = 255): 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].
 
-- `PALETTE_VT340_COLOR: RGBA8888[]`  
-    16 color palette of VT340.
+- `PALETTE_VT340_COLOR: Uint32Array`  
+    16 color palette of VT340 (as `RGBA8888`).
 
-- `PALETTE_VT340_GREY: RGBA8888[]`  
-    16 monochrome palette of VT340.
+- `PALETTE_VT340_GREY: Uint32Array`  
+    16 monochrome palette of VT340 (as `RGBA8888`).
 
-- `PALETTE_ANSI_256: RGBA8888[]`  
-    256 ANSI color palette derived from xterm.
+- `PALETTE_ANSI_256: Uint32Array`  
+    256 ANSI color palette derived from xterm (as `RGBA8888`).
 
 
 ### Installation
 Install the library with `npm install sixel`.
 
+For direct usage in the browser, see under "browser bundles" below.
+
+
 ### Examples and browser demo
 See the example files in `/examples` 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.
@@ -136,7 +132,8 @@ Encoding can be tested in a SIXEL capable terminal with `img2sixel.js`, e.g.
 $> node img2sixel.js -p16 http://leeoniya.github.io/RgbQuant.js/demo/img/bluff.jpg
 ```
 
-## Benchmarks
+
+### Benchmarks
 Performance is measured for typical actions based on 9-bit palette image:
 ![test image](palette.png "test image")
 
@@ -147,39 +144,39 @@ Results:
    Context "./lib/index.benchmark.js"
       Context "testimage"
          Context "pixel transfer"
-            Case "toPixelData - with fillColor" : 20 runs - average runtime: 1.42 ms
-            Case "toPixelData - without fillColor" : 20 runs - average runtime: 1.12 ms
+            Case "toPixelData - with fillColor" : 20 runs - average runtime: 1.38 ms
+            Case "toPixelData - without fillColor" : 20 runs - average runtime: 1.06 ms
          Context "decode (DefaultDecoder)"
-            Case "decode" : 20 runs - average runtime: 4.34 ms
-            Case "decodeString" : 20 runs - average runtime: 4.62 ms
-            Case "decode + pixel transfer" : 20 runs - average runtime: 3.39 ms
+            Case "decode" : 20 runs - average runtime: 4.15 ms
+            Case "decodeString" : 20 runs - average runtime: 5.18 ms
+            Case "decode + pixel transfer" : 20 runs - average runtime: 3.17 ms
          Context "decode (WasmDecoder)"
-            Case "decode" : 20 runs - average runtime: 1.35 ms
-            Case "decodeString" : 20 runs - average runtime: 1.81 ms
+            Case "decode" : 20 runs - average runtime: 1.27 ms
+            Case "decodeString" : 20 runs - average runtime: 1.66 ms
          Context "encode"
-            Case "sixelEncode" : 20 runs - average runtime: 25.10 ms
-      Context "decode - testfiles (DefaultDecoder)"
-         Case "test1_clean.sixel" : 20 runs - average runtime: 16.75 ms
-         Case "test1_clean.sixel" : 20 runs - average throughput: 37.70 MB/s
-         Case "test2_clean.sixel" : 20 runs - average runtime: 7.23 ms
-         Case "test2_clean.sixel" : 20 runs - average throughput: 45.48 MB/s
-         Case "sampsa_reencoded_clean.six" : 20 runs - average runtime: 16.53 ms
-         Case "sampsa_reencoded_clean.six" : 20 runs - average throughput: 39.57 MB/s
-         Case "FullHD 12bit noise" : 20 runs - average runtime: 228.52 ms
-         Case "FullHD 12bit noise" : 20 runs - average throughput: 67.84 MB/s
-      Context "decode - testfiles (WasmDecoder)"
-         Case "test1_clean.sixel" : 20 runs - average runtime: 9.99 ms
-         Case "test1_clean.sixel" : 20 runs - average throughput: 61.25 MB/s
-         Case "test2_clean.sixel" : 20 runs - average runtime: 4.16 ms
-         Case "test2_clean.sixel" : 20 runs - average throughput: 76.79 MB/s
-         Case "sampsa_reencoded_clean.six" : 20 runs - average runtime: 10.54 ms
-         Case "sampsa_reencoded_clean.six" : 20 runs - average throughput: 61.23 MB/s
-         Case "FullHD 12bit noise" : 20 runs - average runtime: 100.77 ms
-         Case "FullHD 12bit noise" : 20 runs - average throughput: 153.86 MB/s
+            Case "sixelEncode" : 20 runs - average runtime: 22.23 ms
+      Context "decode - testfiles (SixelDecoder - old decoder)"
+         Case "test1_clean.sixel" : 20 runs - average runtime: 15.64 ms
+         Case "test1_clean.sixel" : 20 runs - average throughput: 41.48 MB/s
+         Case "test2_clean.sixel" : 20 runs - average runtime: 6.53 ms
+         Case "test2_clean.sixel" : 20 runs - average throughput: 48.90 MB/s
+         Case "sampsa_reencoded_clean.six" : 20 runs - average runtime: 15.23 ms
+         Case "sampsa_reencoded_clean.six" : 20 runs - average throughput: 42.46 MB/s
+         Case "FullHD 12bit noise" : 20 runs - average runtime: 215.23 ms
+         Case "FullHD 12bit noise" : 20 runs - average throughput: 72.03 MB/s
+      Context "decode - testfiles (Decoder - new decoder)"
+         Case "test1_clean.sixel" : 20 runs - average runtime: 4.30 ms
+         Case "test1_clean.sixel" : 20 runs - average throughput: 138.79 MB/s
+         Case "test2_clean.sixel" : 20 runs - average runtime: 2.25 ms
+         Case "test2_clean.sixel" : 20 runs - average throughput: 140.65 MB/s
+         Case "sampsa_reencoded_clean.six" : 20 runs - average runtime: 4.40 ms
+         Case "sampsa_reencoded_clean.six" : 20 runs - average throughput: 147.16 MB/s
+         Case "FullHD 12bit noise" : 20 runs - average runtime: 48.82 ms
+         Case "FullHD 12bit noise" : 20 runs - average throughput: 317.88 MB/s
+         Case "640x480 9bit tiles" : 20 runs - average runtime: 0.65 ms
+         Case "640x480 9bit tiles" : 20 runs - average throughput: 154.89 MB/s
 ```
-`WasmDecoder` is roughly 1.5x - 2.3x faster than `DefaultDecoder`.
-TODO...
-
+Note that the new decoder is roughly 3-4 times faster than the old one. Therefore the old decoder will be removed with one of the next releases.
 
 
 ### Decoder usage
@@ -271,8 +268,8 @@ To not run into out of memory issues the decoder respects an upper memory limit
 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
+During chunk decoding the memory usage can be further tracked with `memoryUsage`. Other than `memoryLimit`,
+this value also accounts the static memory taken by the wasm instance, 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
@@ -281,7 +278,7 @@ 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.
+This is an optimization to lower allocation and GC pressure.
 Call `release` after decoding to explicitly free the pixel memory.
 
 Rules of thumb regarding memory:
@@ -290,23 +287,17 @@ Rules of thumb regarding memory:
 - 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.
+An ESM package version for nodejs 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`.
+The browser bundles come in UMD and ESM flavors. At the current stage the ESM builds are mostly untested (treat them as alpha, bug reports are more than welcome). Note that the UMD bundles export the symbols under the name `sixel`.
 
 Some usage examples:
 - vanilla usage with UMD version:
@@ -343,8 +334,10 @@ Some usage examples:
 
 
 ### Status
-Currently beta, still more tests to come. Also the API might still change.
+Beta.
 
+Automatically tested on nodejs 12, 14 and 16.
+Manually tested on recent versions of Chrome, Firefox and Webkit.
 
 ### References
 

wasm/README.md

@@ -1,6 +1,7 @@
 
 ## Sixel band decoder
 
+
 __Features__:
 - written in C
 - allocation free (single instance static memory)
@@ -153,6 +154,6 @@ There are probably more deviations from the SIXEL spec not listed here.
 - undecided: establish some real height accounting for M1
 
 
-### State
+### Status
 
-Alpha, still way to go.
+Beta. The code is tested with unit/regression tests from the JS integration.