Normal Palette Batch CLI — experimental

Normal Palette Batch CLI — experimental

Apply one saved directional palette to a batch of existing normal-map PNGs.

Version 0.1.0, released 7 October 2026. An experimental, free command-line trial for technical game developers who already process multiple normal maps. Reuse a 2–64-color JSON palette across up to 12 images, with optional source Y inversion. This is a palette-finishing step; it does not generate normal maps.

What it does

- Matches each nontransparent pixel to the closest palette direction by normalized dot product.

- Preserves every decoded alpha byte, fully transparent pixels’ decoded RGB, and image dimensions.

- Writes new RGBA PNGs to a new output directory and reports decoded-pixel hashes in JSON.

Requirements and limits

- Node.js 24 and a trusted local filesystem supporting same-filesystem hard links. Verified on Linux with Node 24.19.0.

- No npm install, runtime package dependencies, paid API, or network calls. Node installation is separate.

- Non-interlaced 8-bit RGB/RGBA PNG only. No indexed, grayscale, 16-bit, APNG, or color-key transparency.

- Up to 16 MiB per PNG, 64 MiB per batch, 4,096 pixels per side, 4,194,304 pixels per image, and 12,582,912 pixels per batch. See README for full limits.

Read before trying

Use copies of assets. Existing output directories are refused. Publication to the output directory is not atomic; interruptions or crashes can leave partial output or staging files. PNG metadata, color profiles, compression, and original file bytes are not preserved. The preservation claims above concern decoded channels only.

No GUI or engine plugin is included. Windows, macOS, engine integration, and customer asset collections have not been validated. Automated checks are not a production-readiness guarantee.

Development, testing, and release copy used AI assistance.

Free trial. Payments and donations disabled. Feedback on real batch workflows is welcome.

Usage conditions: The included LICENSE.txt allows free personal and commercial image-processing use, source inspection, private backups, and local modifications for your own use. Image outputs can be used commercially subject to input rights, including outputs from the bundled synthetic examples, with no output attribution required. Tool redistribution and resale are prohibited except mandatory legal rights or separately authorized hosting-platform rights. Source-visible, not open source. See the included LICENSE.txt for the full conditions.

Download: normal-palette-batch-cli-0.1.0.zip

Synthetic example: encoded normal-map RGB before/after, not in-engine lighting. Same comparison image as the project cover.