@emdzej/itw-decoder 0.1.0 → 0.2.0

package/README.md

@@ -13,7 +13,7 @@ ITW is a proprietary image format used in BMW's Technical Information System (TI
 - **Subtype 0x0300** — Wavelet compression (biorthogonal wavelet transform, ~5:1–14:1 ratio)
 - **Subtype 0x0400** — Entropy compression (Huffman + RLE interleave)
 
-All images are 8-bit grayscale, typically 316×238 pixels.
+All images are 8-bit grayscale, typically 316×238 or 631×474 pixels.
 
 For a full technical description of the format and decoding algorithms see [`docs/HOW_IT_WORKS.md`](docs/HOW_IT_WORKS.md).
 
@@ -87,12 +87,14 @@ Tested against the full 47,660-file GRAFIK corpus:
 
 | Metric | Value |
 |--------|-------|
-| Success rate | **98.67%** (47,028 / 47,660) |
-| 0x0300 wavelet decoded | 35,117 |
+| Success rate | **99.66%** (47,498 / 47,660) |
+| 0x0300 wavelet decoded | 35,587 |
 | 0x0400 entropy decoded | 11,911 |
-| Failures | 632 — all genuinely malformed/truncated source files |
+| Failures | 162 — all genuinely malformed/truncated source files |
 
-The dominant failure reason is "wavelet payload overruns file" (470 truncated files), not decoder bugs.
+### Encoder bug: 256-byte payload length overrun
+
+586 wavelet (0x0300) files in the corpus declare a payload length exactly 256 bytes larger than the actual file data. This is a systematic bug in the original BMW ITW encoder — the payload data is complete, only the length field is wrong. The decoder tolerates this by allowing small overruns (up to 512 bytes) while still rejecting truly truncated files.
 
 ## Project structure
 
@@ -125,3 +127,13 @@ pnpm dev          # run via ts-node (no build step)
 ## License
 
 [PolyForm Noncommercial License 1.0.0](LICENSE) — free for personal, research, and noncommercial use; commercial use is not permitted.
+
+## Right to Repair
+
+The [Right to Repair](https://repair.eu) movement advocates for consumers' ability to fix the products they own — from electronics to vehicles — without being locked out by manufacturers through proprietary tools, paywalled documentation, or artificial restrictions.
+
+**I build these tools because I believe repair is a fundamental right, not a privilege.**
+
+Too often, service manuals, diagnostic software, and technical documentation are kept behind closed doors — unavailable to individuals even when they're willing to pay. This wasn't always the case. Products once shipped with schematics and repair guides as standard. The increasing complexity of modern technology doesn't change the fact that capable people exist who can — and should be allowed to — use that information.
+
+These projects exist to preserve access to technical knowledge and ensure that owners aren't left at the mercy of vendors who may discontinue support, charge prohibitive fees, or simply refuse service.

package/dist/decode0300.js

@@ -7,6 +7,7 @@
  * https://polyformproject.org/licenses/noncommercial/1.0.0
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._internals = void 0;
 exports.decode0300 = decode0300;
 const zlib_1 = require("zlib");
 const itw_1 = require("./itw");
@@ -22,8 +23,8 @@ const DAT_004ed118 = 0x80; // int:    extra bits flag mask
 const DAT_004ed11c = 5; // int:    buffer size multiplier
 // ─── Cursor: tracks read position into the payload ─────────────────────────
 class Cursor {
-    constructor(buf, offset) {
-        this.buf = buf;
+    constructor(input, offset) {
+        this.buf = (0, itw_1.toBuffer)(input);
         this.pos = offset;
     }
     readByte() {
@@ -32,12 +33,16 @@ class Cursor {
         return this.buf[this.pos++];
     }
     readBE16() {
-        const v = (0, itw_1.readBE16)(this.buf, this.pos);
+        if (this.pos + 2 > this.buf.length)
+            throw new itw_1.ITWError("cursor overrun (BE16)");
+        const v = this.buf.readUInt16BE(this.pos);
         this.pos += 2;
         return v;
     }
     readBE32() {
-        const v = (0, itw_1.readBE32From2BE16)(this.buf, this.pos);
+        if (this.pos + 4 > this.buf.length)
+            throw new itw_1.ITWError("cursor overrun (BE32)");
+        const v = this.buf.readUInt32BE(this.pos);
         this.pos += 4;
         return v;
     }
@@ -1203,10 +1208,17 @@ function decode0300(buf, payloadOffset, width, height, opts) {
     // Read BE32 payload length, then the payload starts after it
     if (payloadOffset + 4 > buf.length)
         throw new itw_1.ITWError("missing wavelet length");
-    const payloadLen = (0, itw_1.readBE32From2BE16)(buf, payloadOffset);
+    const b = (0, itw_1.toBuffer)(buf);
+    const payloadLen = b.readUInt32BE(payloadOffset);
     const payloadStart = payloadOffset + 4;
-    if (payloadStart + payloadLen > buf.length)
-        throw new itw_1.ITWError("wavelet payload overruns file");
+    // Tolerate declared payload length exceeding file size — 586 files in the BMW TIS
+    // corpus have a payload length exactly 256 bytes larger than the actual file data.
+    // This is a systematic encoder bug; the actual wavelet data fits within the file.
+    if (payloadStart + payloadLen > buf.length) {
+        const over = (payloadStart + payloadLen) - buf.length;
+        if (over > 512)
+            throw new itw_1.ITWError("wavelet payload overruns file by " + over + " bytes");
+    }
     // Build Fischer tables
     const baseTable = buildBaseTable(); // cumulative counts — used to build diff table
     const diffTable = buildDiffTable(baseTable); // exact counts T(q,m) — used by fischerDecode for unranking
@@ -1378,3 +1390,26 @@ function decode0300(buf, payloadOffset, width, height, opts) {
     }
     return { width, height, pixels };
 }
+/** @internal — exported for testing only */
+exports._internals = {
+    deriveMirror,
+    buildFilterCoeffs,
+    initFilters,
+    buildBaseTable,
+    buildDiffTable,
+    buildRankTable,
+    tableLookup,
+    fischerDecode,
+    splitEvenOdd,
+    calcBandSize,
+    levelScaleFactor,
+    q15ToFloat,
+    hexToFloat,
+    polyphaseConvolve1D,
+    matrixCreate,
+    matrixGet,
+    matrixSet,
+    edgeExtend,
+    Cursor,
+    Bitstream,
+};

package/dist/decode0400.js

@@ -51,7 +51,8 @@ class IntStack {
     }
 }
 // ─── FUN_004b5a40: Read payload tables from buffer ──────────────────
-function readTables(buf, off) {
+function readTables(input, off) {
+    const buf = (0, itw_1.toBuffer)(input);
     const intArr = new IntStack(); // DAT_00580020
     const tableB = new ByteStack(); // DAT_00580014
     const tableC = new ByteStack(); // DAT_0058001c
@@ -71,7 +72,7 @@ function readTables(buf, off) {
     // len1 = FUN_004b5750(param_1) → BE32 via two BE16
     if (p + 4 > buf.length)
         throw new itw_1.ITWError("missing len1");
-    const len1 = (0, itw_1.readBE32From2BE16)(buf, p);
+    const len1 = buf.readUInt32BE(p);
     p += 4;
     if (p + len1 > buf.length)
         throw new itw_1.ITWError("payload length exceeds file size at table B");
@@ -81,7 +82,7 @@ function readTables(buf, off) {
     // len2 = FUN_004b5750(param_1) → BE32 via two BE16
     if (p + 4 > buf.length)
         throw new itw_1.ITWError("missing len2");
-    const len2 = (0, itw_1.readBE32From2BE16)(buf, p);
+    const len2 = buf.readUInt32BE(p);
     p += 4;
     if (p + len2 > buf.length)
         throw new itw_1.ITWError("payload length exceeds file size at table C");

package/dist/itw.js

@@ -8,9 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ITWError = void 0;
-exports.readBE16 = readBE16;
-exports.readBE32From2BE16 = readBE32From2BE16;
-exports.readLE32 = readLE32;
+exports.toBuffer = toBuffer;
 exports.parseHeader = parseHeader;
 class ITWError extends Error {
     constructor(message) {
@@ -19,36 +17,22 @@ class ITWError extends Error {
     }
 }
 exports.ITWError = ITWError;
-function readBE16(buf, off) {
-    if (off + 2 > buf.length)
-        throw new ITWError(`readBE16 out of range @${off}`);
-    return (buf[off] << 8) | buf[off + 1];
+/** Ensure we have a Buffer (wraps plain Uint8Array if needed). */
+function toBuffer(buf) {
+    return Buffer.isBuffer(buf) ? buf : Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength);
 }
-function readBE32From2BE16(buf, off) {
-    const hi = readBE16(buf, off);
-    const lo = readBE16(buf, off + 2);
-    return (hi << 16) | lo;
-}
-function readLE32(buf, off) {
-    if (off + 4 > buf.length)
-        throw new ITWError(`readLE32 out of range @${off}`);
-    return buf[off] | (buf[off + 1] << 8) | (buf[off + 2] << 16) | (buf[off + 3] << 24);
-}
-function parseHeader(buf) {
-    // Header layout (from Ghidra FUN_004b5680 + FUN_004b5780):
-    //   6 x BE16 in FUN_004b5680: magic(2), magic(2), version, width, height, bpp
-    //   1 x BE16 in FUN_004b5780: subtype
-    // Total = 7 x BE16 = 14 bytes
-    if (buf.length < 14)
+function parseHeader(input) {
+    if (input.length < 14)
         throw new ITWError("file too small for header");
-    const magic = String.fromCharCode(buf[0], buf[1], buf[2], buf[3]);
+    const buf = toBuffer(input);
+    const magic = buf.toString('ascii', 0, 4);
     if (magic !== "ITW_")
         throw new ITWError("bad magic");
-    const version = readBE16(buf, 4);
-    const width = readBE16(buf, 6);
-    const height = readBE16(buf, 8);
-    const bpp = readBE16(buf, 0x0a);
-    const subtype = readBE16(buf, 0x0c);
+    const version = buf.readUInt16BE(4);
+    const width = buf.readUInt16BE(6);
+    const height = buf.readUInt16BE(8);
+    const bpp = buf.readUInt16BE(0x0a);
+    const subtype = buf.readUInt16BE(0x0c);
     if (version !== 0x0100 && version !== 0x0200)
         throw new ITWError(`unsupported version 0x${version.toString(16)}`);
     if (subtype !== 0x0300 && subtype !== 0x0400)

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@emdzej/itw-decoder",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "commonjs",
   "description": "Decode BMW TIS .ITW proprietary image files to PNG",
   "license": "PolyForm-Noncommercial-1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/emdzej/itw-decoder"
+  },
   "main": "dist/index.js",
   "bin": {
     "itw-decode": "dist/index.js"
@@ -11,12 +15,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "ts-node src/index.ts",
-    "decode": "ts-node src/index.ts"
-  },
   "dependencies": {
     "commander": "^14.0.3",
     "pngjs": "^7.0.0"
@@ -25,6 +23,15 @@
     "@types/node": "^20.11.0",
     "@types/pngjs": "^6.0.4",
     "ts-node": "^10.9.2",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "decode": "ts-node src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}