@emdzej/itw-decoder 0.1.0

package/LICENSE

@@ -0,0 +1,118 @@
+PolyForm Noncommercial License 1.0.0
+
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+Acceptance
+
+In order to get any license under these terms, you must agree to them as
+both strict obligations and conditions to all your licenses.
+
+Copyright License
+
+The licensor grants you a copyright license for the software to do
+everything you might do with the software that would otherwise infringe
+the licensor's copyright in it for any permitted purpose. However, you
+may only distribute the software according to Distribution License and
+make changes or new works based on the software according to Changes and
+New Works License.
+
+Distribution License
+
+The licensor grants you an additional copyright license to distribute
+copies of the software. Your license to distribute covers distributing
+the software with changes and new works permitted by Changes and New
+Works License.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of the software
+from you also gets a copy of these terms or the URL for them above, as
+well as copies of any plain-text lines beginning with Required Notice:
+that the licensor provided with the software. For example:
+
+  Required Notice: Copyright Marek Jaskolski (https://github.com/emdzej)
+
+Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes
+and new works based on the software for any permitted purpose.
+
+Patent License
+
+The licensor grants you a patent license for the software that covers
+patent claims the licensor can license, or becomes able to license, that
+you would infringe by using the software.
+
+Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of
+public knowledge, personal study, private entertainment, hobby projects,
+amateur pursuits, or religious observance, without any anticipated
+commercial application, is use for a permitted purpose.
+
+Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public
+research organization, public safety or health organization,
+environmental protection organization, or government institution is use
+for a permitted purpose regardless of the source of funding or
+obligations resulting from the funding.
+
+Fair Use
+
+You may have "fair use" rights for the software under the law. These
+terms do not limit them.
+
+No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your
+licenses to anyone else, or prevent the licensor from granting licenses
+to anyone else. These terms do not imply any other licenses.
+
+Patent Defense
+
+If you make any written claim that the software infringes or contributes
+to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a
+claim, your patent license ends immediately for work on behalf of your
+company.
+
+Violations
+
+The first time you are notified in writing that you have violated any of
+these terms, or done anything with the software not covered by your
+licenses, your licenses can nonetheless continue if you come into full
+compliance with these terms, and take practical steps to correct past
+violations, within 32 days of receiving notice. Otherwise, all your
+licenses end immediately.
+
+No Liability
+
+As far as the law allows, the software comes as is, without any warranty
+or condition, and the licensor will not be liable to you for any damages
+arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+Definitions
+
+The licensor is the individual or entity offering these terms, and the
+software is the software the licensor makes available under these terms.
+
+You refers to the individual or entity agreeing to these terms.
+
+Your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control
+over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+Your licenses are all the licenses granted to you for the software under
+these terms.
+
+Use means anything you do with the software requiring one of your
+licenses.

package/README.md

@@ -0,0 +1,127 @@
+# @emdzej/itw-decoder
+
+TypeScript CLI decoder for BMW TIS `.ITW` proprietary image files. Converts proprietary ITW images to standard PNG format.
+
+[![CI](https://github.com/emdzej/itw-decoder/actions/workflows/ci.yml/badge.svg)](https://github.com/emdzej/itw-decoder/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@emdzej/itw-decoder)](https://www.npmjs.com/package/@emdzej/itw-decoder)
+[![License: PolyForm Noncommercial 1.0.0](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-blue)](LICENSE)
+
+## What is ITW?
+
+ITW is a proprietary image format used in BMW's Technical Information System (TIS) software for storing technical illustrations (wiring diagrams, exploded views, etc.). The format supports two compression codecs:
+
+- **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.
+
+For a full technical description of the format and decoding algorithms see [`docs/HOW_IT_WORKS.md`](docs/HOW_IT_WORKS.md).
+
+## Installation
+
+### Global (recommended for CLI use)
+
+```bash
+npm install -g @emdzej/itw-decoder
+```
+
+### Local / development
+
+```bash
+pnpm install
+```
+
+## Usage
+
+```
+Usage: itw-decode [options] <input>
+
+Decode BMW TIS .ITW proprietary image files to PNG
+
+Arguments:
+  input                  path to the .ITW file to decode
+
+Options:
+  -V, --version          output the current version
+  -o, --output <file>    output PNG path (default: <input>.png in cwd)
+  -d, --dir <directory>  output directory, keeps auto-derived filename (default: cwd)
+  -h, --help             display help for command
+```
+
+### Examples
+
+```bash
+# Decode — output defaults to ./26.png
+itw-decode samples/1/03/95/26.ITW
+
+# Explicit output path
+itw-decode samples/1/03/95/26.ITW -o out/diagram.png
+
+# Write to a directory, keep original filename
+itw-decode samples/1/03/95/26.ITW -d out/
+```
+
+> **Note:** `-o` and `-d` are independent; `-o` takes full precedence when both are supplied.
+
+### Dev (without global install)
+
+```bash
+./node_modules/.bin/ts-node src/index.ts samples/1/03/95/26.ITW -o output.png
+```
+
+## Bulk testing
+
+To test against a full GRAFIK corpus directory:
+
+```bash
+# First 100 files
+./node_modules/.bin/ts-node bulk_test.ts /path/to/GRAFIK --limit 100
+
+# All files
+./node_modules/.bin/ts-node bulk_test.ts /path/to/GRAFIK
+```
+
+## Test results
+
+Tested against the full 47,660-file GRAFIK corpus:
+
+| Metric | Value |
+|--------|-------|
+| Success rate | **98.67%** (47,028 / 47,660) |
+| 0x0300 wavelet decoded | 35,117 |
+| 0x0400 entropy decoded | 11,911 |
+| Failures | 632 — all genuinely malformed/truncated source files |
+
+The dominant failure reason is "wavelet payload overruns file" (470 truncated files), not decoder bugs.
+
+## Project structure
+
+```
+src/
+  itw.ts          — Header parsing, shared types (ITWHeader, DecodeResult, ITWError), endian helpers
+  decode0300.ts   — Wavelet codec (biorthogonal wavelet transform, ~1518 lines)
+  decode0400.ts   — Entropy codec (Huffman + RLE interleave)
+  png.ts          — Grayscale→RGBA conversion, PNG writer (pngjs)
+  index.ts        — CLI entry point (commander.js)
+docs/
+  HOW_IT_WORKS.md — Complete decoder specification (format to reimplement in any language)
+  findings.md     — Raw reverse-engineering notes, Ghidra function table, lessons learned
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [`docs/HOW_IT_WORKS.md`](docs/HOW_IT_WORKS.md) | Complete, language-agnostic decoder specification — header layout, both codecs, filter derivation, Fischer coding, polyphase convolution, all constants |
+| [`docs/findings.md`](docs/findings.md) | Reverse-engineering notes — Ghidra function addresses, all 9 bugs found and fixed, x87 FPU pitfalls |
+
+## Building
+
+```bash
+pnpm build        # tsc → dist/
+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.