pngmint 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,32 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [1.0.0](https://github.com/Konvetto/pngmint/compare/v0.1.0...v1.0.0) (2026-11-21)
8
+
9
+
10
+ ### Miscellaneous Chores
11
+
12
+ * release 1.0.0 ([a097f03](https://github.com/Konvetto/pngmint/commit/a097f03e5dca2d89b05aa2d3ee2d437963afc2b3))
13
+
14
+ ## [0.1.0]
15
+
16
+ First public release, extracted from the Compress PNG engine of konvetto.com.
17
+
18
+ ### Added
19
+
20
+ - `quantize(rgba, width, height, options)`: straight RGBA in, indexed PNG out, with the palette,
21
+ the indices and the measured fit (`psnr`, `quality`, `exact`). Compression by the platform's
22
+ `CompressionStream` (no dependencies) or by the `deflate` option; `quantizeSync` for a
23
+ synchronous compressor such as fflate.
24
+ - `createPalette`, `applyPalette`, `encodeIndexedPng` and `encodeIndexedPngSync` for custom
25
+ pipelines.
26
+ - `presets.quality`, `presets.balanced`, `presets.small` and `presets.tiny`, the strength steps
27
+ used in production.
28
+ - Exact histogram up to 8192 colours, bucketed beyond; median cut with a linear weighted median;
29
+ k-means refinement; exact nearest-colour search with pruning; Floyd-Steinberg dithering on smooth
30
+ areas only; indexed PNG writer with 1, 2, 4 or 8 bits per pixel and a short tRNS.
31
+ - Input validation with `RangeError` and `TypeError`.
32
+ - Palette entries no pixel uses are dropped from the file.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Konvetto
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,395 @@
1
- # Temporary Holding Version
1
+ <a href="https://konvetto.com/images/compress-png"><img src="https://raw.githubusercontent.com/Konvetto/pngmint/main/.github/assets/social-preview.png" alt="pngmint: palette PNGs that stay sharp. Try it free on konvetto.com" width="100%"></a>
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # pngmint
4
+
5
+ **Palette PNGs that stay sharp. Pure TypeScript, zero dependencies, 5 kB, no wasm.**
6
+
7
+ [![npm](https://img.shields.io/npm/v/pngmint)](https://www.npmjs.com/package/pngmint)
8
+ [![bundle size](https://img.shields.io/bundlejs/size/pngmint?label=gzip)](https://bundlejs.com/?q=pngmint)
9
+ [![dependencies](https://img.shields.io/badge/dependencies-0-success)](./package.json)
10
+ [![license](https://img.shields.io/npm/l/pngmint)](./LICENSE)
11
+ [![CI](https://github.com/Konvetto/pngmint/actions/workflows/ci.yml/badge.svg)](https://github.com/Konvetto/pngmint/actions/workflows/ci.yml)
12
+
13
+ pngmint turns RGBA pixels into an indexed PNG with up to 256 colours: on the benchmark photos 2.7
14
+ to 6.4 times smaller than lossless PNG, depending on the preset, and a near-lossless file for
15
+ screenshots and flat art. It runs where your pixels already
16
+ are, in the browser, in a Web Worker, in Node, Deno or Bun, from one ES module with no
17
+ dependencies: the file is compressed by the platform's `CompressionStream`, or by any zlib
18
+ compressor you pass in.
19
+
20
+ > **Try it without installing anything:** the [Compress PNG](https://konvetto.com/images/compress-png)
21
+ > tool on Konvetto runs pngmint in your browser. No upload, no account, your file never leaves the
22
+ > tab.
23
+
24
+ ## Why pngmint
25
+
26
+ Measured on 14 public-domain images (photos, screenshots, illustrations, transparency) against
27
+ UPNG.js, image-q and libimagequant, all given the same pixels and the same colour count. Full
28
+ tables, method and the reproducible script are [below](#benchmarks).
29
+
30
+ - **Closest to the original at 256 colours**: on the five photos pngmint's PSNR is 0.7 dB above UPNG.js, 1.1 dB above image-q and 1.4 dB above libimagequant at 256 colours, and it is the closest of the four on 11 of 12 lossy images at 256 and on 12 of 13 at 128 colours.
31
+ - **Smallest files at 256 colours**: at 256 colours pngmint's photos are 2 percent smaller than UPNG.js and image-q and 17 percent smaller than libimagequant, with the default compressor and no hook.
32
+ - **Fast without wasm**: 1.7 to 2.7 times faster than the libimagequant wasm build and 10 to 15 times faster than image-q on photos; the fastest of the four on screenshots and illustrations at every colour count (UPNG.js is faster on photos).
33
+ - **Lossless when it can be**: an image with at most `maxColors` colours comes back pixel for
34
+ pixel, at the smallest bit depth PNG allows (1, 2, 4 or 8 bits).
35
+ - **Deterministic**: the palette and every pixel index are the same on every run and platform.
36
+ No random seeds, no timing, no threads. With a deterministic compressor (the `deflate` option,
37
+ see below) the file bytes are too.
38
+ - **Small**: zero dependencies, 14 kB minified, 5.7 kB gzipped, 5.2 kB brotli. Types included,
39
+ tree-shakeable, `sideEffects: false`.
40
+ - **Pluggable compression**: the file is deflated by the platform's `CompressionStream` out of
41
+ the box; pass fflate at level 9 through the `deflate` option for 1 to 3 percent smaller files,
42
+ identical bytes on every platform and a synchronous call. Three lines, see [Deflate](#deflate).
43
+
44
+ Where it loses, honestly: below 128 colours UPNG.js writes 8 to 22 percent smaller photo files because it does not dither (with visibly lower SSIM); libimagequant has the higher SSIM on photos at every colour count; and with the default compressor flat graphics come out 3 to 4 percent larger than UPNG.js and libimagequant, which the optional fflate hook recovers. Details in [Reading it](#reading-it).
45
+
46
+ ## Install
47
+
48
+ ```sh
49
+ npm install pngmint
50
+ ```
51
+
52
+ Node 20 or newer; any modern browser; Deno and Bun; ESM only. `quantize` returns a promise
53
+ because the default compressor, `CompressionStream`, is asynchronous. `quantizeSync` exists for
54
+ callers that pass their own synchronous compressor (see [Deflate](#deflate)).
55
+
56
+ ## Usage
57
+
58
+ ### Browser, from a canvas
59
+
60
+ ```ts
61
+ import { quantize, presets } from 'pngmint';
62
+
63
+ const canvas = document.querySelector('canvas')!;
64
+ const { data, width, height } = canvas
65
+ .getContext('2d')!
66
+ .getImageData(0, 0, canvas.width, canvas.height);
67
+
68
+ const result = await quantize(data, width, height, presets.balanced);
69
+ // result.png: Uint8Array of a complete PNG file
70
+ // result.colors, result.psnr, result.quality, result.exact
71
+
72
+ const blob = new Blob([result.png], { type: 'image/png' });
73
+ ```
74
+
75
+ ### In a Web Worker
76
+
77
+ The call is synchronous and CPU-bound (about a second for a 12 megapixel photo on a laptop), so
78
+ run it off the main thread:
79
+
80
+ ```ts
81
+ // worker.ts
82
+ import { quantize } from 'pngmint';
83
+ self.onmessage = async ({ data: { rgba, width, height, options } }) => {
84
+ const { png, colors } = await quantize(rgba, width, height, options);
85
+ self.postMessage({ png, colors }, [png.buffer]);
86
+ };
87
+
88
+ // main.ts
89
+ const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' });
90
+ worker.postMessage({ rgba: imageData.data, width, height, options: { maxColors: 128 } });
91
+ ```
92
+
93
+ ### Node, with a decoder
94
+
95
+ pngmint takes pixels, not files. Decode with whatever you have (sharp, pngjs, jpeg-js):
96
+
97
+ ```ts
98
+ import sharp from 'sharp';
99
+ import { writeFile } from 'node:fs/promises';
100
+ import { quantize, presets } from 'pngmint';
101
+
102
+ const { data, info } = await sharp('photo.jpg')
103
+ .ensureAlpha()
104
+ .raw()
105
+ .toBuffer({ resolveWithObject: true });
106
+ const { png, colors, psnr } = await quantize(
107
+ new Uint8Array(data),
108
+ info.width,
109
+ info.height,
110
+ presets.quality,
111
+ );
112
+ await writeFile('photo.png', png);
113
+ console.log(`${colors} colours, ${psnr.toFixed(1)} dB`);
114
+ ```
115
+
116
+ Input is straight (not premultiplied) RGBA, 4 bytes per pixel, as `getImageData` and every
117
+ decoder give it.
118
+
119
+ ### Lower-level API
120
+
121
+ ```ts
122
+ import { createPalette, applyPalette, encodeIndexedPng } from 'pngmint';
123
+
124
+ const { palette, transparentIndex } = createPalette(rgba, { maxColors: 64 }); // straight RGBA bytes
125
+ const indices = applyPalette(rgba, width, height, palette, { dither: 0.5, transparentIndex });
126
+ const png = await encodeIndexedPng(width, height, palette, indices);
127
+ ```
128
+
129
+ Use these to share one palette across several frames, to bring your own palette, or to write the
130
+ indices somewhere other than a PNG. `encodeIndexedPngSync` is the synchronous twin.
131
+
132
+ ### Deflate
133
+
134
+ The pixel rows are compressed by `CompressionStream('deflate')` by default: zero dependencies,
135
+ but asynchronous, at the engine's default level, and the bytes differ slightly between engines.
136
+ The `deflate` option takes any function from raw bytes to a zlib stream. With
137
+ [fflate](https://github.com/101arrowz/fflate) (8 kB) at level 9 the files are 2.5 percent smaller
138
+ on the benchmark set, the bytes are the same everywhere, and the synchronous variants work:
139
+
140
+ ```ts
141
+ import { zlibSync } from 'fflate';
142
+ import { quantizeSync, presets } from 'pngmint';
143
+
144
+ const deflate = (raw: Uint8Array) => zlibSync(raw, { level: 9 });
145
+ const { png } = quantizeSync(rgba, width, height, { ...presets.balanced, deflate });
146
+ ```
147
+
148
+ Measured on the benchmark set at the `quality` and `tiny` presets (same palette and indices, only the compressor differs; the times are one run on a busy laptop, read them as ratios):
149
+
150
+ | Compressor | Total size, 28 files | Relative | Deflate time |
151
+ | -------------------------------- | -------------------: | -------: | -----------: |
152
+ | fflate level 9 | 17.9 MB | 1.000 | 12.6 s |
153
+ | fflate level 6 | 18.1 MB | +1.3% | 6.6 s |
154
+ | CompressionStream (Node 26 zlib) | 18.4 MB | +2.5% | 5.0 s |
155
+
156
+ The gap is widest on tiny flat images (a 3.6 kB icon becomes 5.1 kB) and on screenshots (+6 to
157
+ 9 percent), smallest on photos (+1 to 3 percent). Konvetto passes fflate; the default is for
158
+ everyone who wants nothing else to install.
159
+
160
+ ## Options
161
+
162
+ `quantize(rgba, width, height, options?)` and `createPalette(rgba, options?)`:
163
+
164
+ | Option | Type | Default | What it does |
165
+ | ------------ | ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
166
+ | `maxColors` | 2 to 256 | 256 | Most palette entries. A fully transparent colour, when the image needs one, counts. |
167
+ | `minQuality` | number (dB) | off | Fewer colours while the fit stays above this. Measured like PSNR but against the image's own brightness range, so dark and pale images are judged fairly. 42 keeps screenshots lossless-looking; 32 is visibly reduced. |
168
+ | `dither` | 0 to 1 | 0 | Floyd-Steinberg error diffusion on smooth areas only (sky, skin, gradients). Edges and text are never dithered, nor is flat art or a palette that already fits above 42 dB. |
169
+ | `rounds` | integer | 2 | k-means rounds after median cut. 0 is plain median cut. |
170
+ | `deflate` | function | `CompressionStream` | Raw rows in, zlib stream out. Pixels never change, only size, time and whether `quantizeSync` is available. |
171
+
172
+ Presets, the strength steps used in production:
173
+
174
+ | Preset | maxColors | minQuality | dither | Typical use |
175
+ | ------------------ | --------: | ---------: | -----: | ------------------------------------------- |
176
+ | `presets.quality` | 256 | 42 | 0 | Screenshots stay exact, photos lose little. |
177
+ | `presets.balanced` | 128 | 38 | 0.4 | The default step on Konvetto. |
178
+ | `presets.small` | 64 | 35 | 0.65 | Thumbnails, previews. |
179
+ | `presets.tiny` | 32 | 32 | 0.6 | Icons, placeholders. |
180
+
181
+ The result of `quantize`:
182
+
183
+ | Field | Meaning |
184
+ | ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
185
+ | `png` | The file, `Uint8Array`. |
186
+ | `palette`, `indices`, `colors` | Straight RGBA palette (fully transparent first, then dark to light), one index per pixel, the palette size. |
187
+ | `transparentIndex` | The reserved fully transparent entry, or -1. |
188
+ | `psnr` | Standard PSNR of the palette fit, peak 255, before dithering. `Infinity` when lossless. |
189
+ | `quality` | The same fit against the image's brightness range: what `minQuality` compares with. |
190
+ | `exact` | True when every colour of the image is in the palette. |
191
+
192
+ Bad input throws `RangeError` or `TypeError` (wrong buffer length, sizes under 1 or over
193
+ 2^31 - 1, options out of range).
194
+
195
+ ## Benchmarks
196
+
197
+ Set: 14 public-domain and CC0 images listed in [`bench/images.json`](./bench/images.json) with
198
+ sources and licenses: three Kodak photos (0.4 MP), a 14 MP and a 7 MP photo, three screenshots,
199
+ three illustrations, two logos with transparency and one pixel-art sprite.
200
+
201
+ Reproduce it: `pnpm bench:images && pnpm bench` (about 15 minutes; `--only kodim` or
202
+ `--colors 256,64` for a quick look). Results land in `bench/out/results.md` and
203
+ `bench/out/results.json`, with every output file next to them; the committed copy is
204
+ [`bench/results.md`](./bench/results.md).
205
+
206
+ Method: every library gets the same decoded RGBA and the same colour count. pngmint runs as
207
+ installed, with no options beyond colours and dithering, so its files come from the default
208
+ `CompressionStream` compressor; the optional fflate hook appears only as its own, labelled row.
209
+ Each output is decoded
210
+ again with libvips and compared with the original: PSNR over premultiplied RGB (plus alpha when the
211
+ source has any), SSIM (grayscale, flattened over white), and wall time, median of 3 runs after a
212
+ warm-up, on an Apple Silicon laptop with Node 26. Lossless oxipng (level 2) is included as a size
213
+ reference only.
214
+
215
+ Contenders: UPNG.js 2.1.0, image-q 4.0.0 (wuquant palette, Floyd-Steinberg below 256 colours; it
216
+ has no PNG writer, so its pixels are written losslessly by pngmint), libimagequant through the
217
+ `imagequant` 0.1.2 wasm build (speed 4). libimagequant is GPL-3.0: it is a devDependency of the
218
+ benchmark and never part of this package.
219
+
220
+ ### Summary, other libraries relative to pngmint at the same colour count
221
+
222
+ Photos (5 images, 0.4 to 14 MP). Ratios are geometric means of (library / pngmint): a size ratio above 1.00 means the other library's file is larger, a time ratio above 1.00 means it is slower. PSNR and SSIM are mean differences (library minus pngmint): below 0 means pngmint is closer to the original. The last row of each group is pngmint's own output compressed through the optional `deflate` hook with fflate level 9, shown apart from the default.
223
+
224
+ | Colours | Library | Size ratio | PSNR diff (dB) | SSIM diff | Time ratio |
225
+ | ------: | --------------------------------------------- | ---------: | -------------: | --------: | ---------: |
226
+ | 256 | UPNG.js | 1.02 | -0.73 | -0.0015 | 0.88 |
227
+ | 256 | image-q | 1.02 | -1.13 | +0.0023 | 10.96 |
228
+ | 256 | libimagequant (wasm) | 1.17 | -1.44 | +0.0042 | 2.70 |
229
+ | 256 | pngmint with optional deflate hook (fflate 9) | 0.98 | +0.00 | +0.0000 | 1.38 |
230
+ | 128 | UPNG.js | 0.92 | -0.53 | -0.0068 | 0.62 |
231
+ | 128 | image-q | 1.08 | -1.71 | +0.0049 | 15.09 |
232
+ | 128 | libimagequant (wasm) | 1.10 | -1.13 | +0.0041 | 1.66 |
233
+ | 128 | pngmint with optional deflate hook (fflate 9) | 0.99 | +0.00 | +0.0000 | 1.46 |
234
+ | 64 | UPNG.js | 0.82 | -0.15 | -0.0140 | 0.84 |
235
+ | 64 | image-q | 1.00 | -1.33 | +0.0046 | 9.89 |
236
+ | 64 | libimagequant (wasm) | 1.05 | -0.83 | +0.0038 | 2.08 |
237
+ | 64 | pngmint with optional deflate hook (fflate 9) | 1.00 | +0.00 | +0.0000 | 1.55 |
238
+ | 32 | UPNG.js | 0.78 | -0.24 | -0.0237 | 0.87 |
239
+ | 32 | image-q | 0.97 | -1.46 | +0.0051 | 12.54 |
240
+ | 32 | libimagequant (wasm) | 1.06 | -0.70 | +0.0052 | 2.46 |
241
+ | 32 | pngmint with optional deflate hook (fflate 9) | 1.00 | +0.00 | +0.0000 | 1.76 |
242
+
243
+ Graphics (9 screenshots, illustrations, logos and pixel art) are a different story: at 256 colours most libraries are above 45 dB, several outputs are lossless, and the differences are in bytes, not in visible quality. There pngmint's default compressor is the weak spot (see [Deflate](#deflate)): UPNG.js and libimagequant write 3 to 4 percent smaller files on average, image-q 7 percent smaller, and the hook recovers 3 percent. Counting wins across all 14 images at the same colour count, pngmint is closer to the original (PSNR) than UPNG.js on 11 of 12 lossy cases at 256 colours and 12 of 13 at 128, than libimagequant on 11 of 12 and 13 of 13, and than image-q on every one.
244
+
245
+ ### With and without the deflate hook vs other libraries
246
+
247
+ Totals per colour count and group, so the two pngmint rows can be compared with each other and
248
+ with the rest. `pngmint` is the default install; `pngmint (fflate hook)` is the same palette and
249
+ pixels with the IDAT from fflate level 9 through the `deflate` option. Size and time are sums over
250
+ the group's images; PSNR and SSIM are means over the images where every library is lossy
251
+ (lossless outputs have no finite PSNR and are left out of the means).
252
+
253
+ | Colours | Group | Library | Size (kB) | Size vs default | PSNR (dB) | SSIM | Time (ms) | Time vs default |
254
+ | ------: | -------- | --------------------- | --------: | --------------: | --------: | -----: | --------: | --------------: |
255
+ | 256 | photos | pngmint | 9846.7 | 1.000 | 37.78 | 0.9926 | 3623 | 1.00 |
256
+ | 256 | photos | pngmint (fflate hook) | 9607.0 | 0.976 | 37.78 | 0.9926 | 4338 | 1.20 |
257
+ | 256 | photos | upng-js | 10014.4 | 1.017 | 37.04 | 0.9911 | 4429 | 1.22 |
258
+ | 256 | photos | image-q | 9941.8 | 1.010 | 36.65 | 0.9950 | 41120 | 11.35 |
259
+ | 256 | photos | libimagequant | 11769.8 | 1.195 | 36.34 | 0.9969 | 7927 | 2.19 |
260
+ | 256 | graphics | pngmint | 2067.7 | 1.000 | 58.81 | 0.9999 | 1191 | 1.00 |
261
+ | 256 | graphics | pngmint (fflate hook) | 2043.2 | 0.988 | 58.81 | 0.9999 | 1939 | 1.63 |
262
+ | 256 | graphics | upng-js | 2189.8 | 1.059 | 57.17 | 1.0000 | 2338 | 1.96 |
263
+ | 256 | graphics | image-q | 1983.0 | 0.959 | 48.08 | 0.9999 | 38347 | 32.21 |
264
+ | 256 | graphics | libimagequant | 2275.6 | 1.101 | 55.42 | 1.0000 | 2804 | 2.36 |
265
+ | 128 | photos | pngmint | 8706.2 | 1.000 | 35.27 | 0.9906 | 5066 | 1.00 |
266
+ | 128 | photos | pngmint (fflate hook) | 8637.6 | 0.992 | 35.27 | 0.9906 | 6073 | 1.20 |
267
+ | 128 | photos | upng-js | 7861.4 | 0.903 | 34.73 | 0.9838 | 4083 | 0.81 |
268
+ | 128 | photos | image-q | 9340.8 | 1.073 | 33.55 | 0.9954 | 71813 | 14.18 |
269
+ | 128 | photos | libimagequant | 9669.4 | 1.111 | 34.14 | 0.9946 | 6725 | 1.33 |
270
+ | 128 | graphics | pngmint | 1795.3 | 1.000 | 57.08 | 0.9999 | 1146 | 1.00 |
271
+ | 128 | graphics | pngmint (fflate hook) | 1781.8 | 0.992 | 57.08 | 0.9999 | 1862 | 1.63 |
272
+ | 128 | graphics | upng-js | 1832.3 | 1.021 | 56.49 | 0.9999 | 2728 | 2.38 |
273
+ | 128 | graphics | image-q | 1841.6 | 1.026 | 48.54 | 0.9999 | 59615 | 52.04 |
274
+ | 128 | graphics | libimagequant | 1942.1 | 1.082 | 55.07 | 1.0000 | 2929 | 2.56 |
275
+ | 64 | photos | pngmint | 7282.6 | 1.000 | 32.45 | 0.9864 | 4636 | 1.00 |
276
+ | 64 | photos | pngmint (fflate hook) | 7303.8 | 1.003 | 32.45 | 0.9864 | 5672 | 1.22 |
277
+ | 64 | photos | upng-js | 5994.1 | 0.823 | 32.30 | 0.9724 | 4027 | 0.87 |
278
+ | 64 | photos | image-q | 7340.8 | 1.008 | 31.12 | 0.9910 | 33873 | 7.31 |
279
+ | 64 | photos | libimagequant | 7850.7 | 1.078 | 31.62 | 0.9901 | 7012 | 1.51 |
280
+ | 64 | graphics | pngmint | 1511.1 | 1.000 | 52.65 | 0.9999 | 980 | 1.00 |
281
+ | 64 | graphics | pngmint (fflate hook) | 1516.3 | 1.003 | 52.65 | 0.9999 | 1488 | 1.52 |
282
+ | 64 | graphics | upng-js | 1521.3 | 1.007 | 51.97 | 0.9998 | 3054 | 3.11 |
283
+ | 64 | graphics | image-q | 1616.2 | 1.070 | 46.83 | 0.9999 | 31144 | 31.77 |
284
+ | 64 | graphics | libimagequant | 1616.6 | 1.070 | 51.94 | 1.0000 | 2512 | 2.56 |
285
+ | 32 | photos | pngmint | 5693.7 | 1.000 | 29.93 | 0.9758 | 4122 | 1.00 |
286
+ | 32 | photos | pngmint (fflate hook) | 5703.3 | 1.002 | 29.93 | 0.9758 | 5059 | 1.23 |
287
+ | 32 | photos | upng-js | 4655.8 | 0.818 | 29.69 | 0.9521 | 3694 | 0.90 |
288
+ | 32 | photos | image-q | 5563.3 | 0.977 | 28.47 | 0.9810 | 32054 | 7.78 |
289
+ | 32 | photos | libimagequant | 6146.2 | 1.079 | 29.22 | 0.9810 | 6686 | 1.62 |
290
+ | 32 | graphics | pngmint | 1334.0 | 1.000 | 47.66 | 0.9997 | 1435 | 1.00 |
291
+ | 32 | graphics | pngmint (fflate hook) | 1343.1 | 1.007 | 47.66 | 0.9997 | 2005 | 1.40 |
292
+ | 32 | graphics | upng-js | 1287.9 | 0.965 | 47.13 | 0.9996 | 3035 | 2.12 |
293
+ | 32 | graphics | image-q | 1364.6 | 1.023 | 44.49 | 0.9999 | 25812 | 17.99 |
294
+ | 32 | graphics | libimagequant | 1358.5 | 1.018 | 47.43 | 0.9999 | 2448 | 1.71 |
295
+
296
+ ### Reading it
297
+
298
+ - **At 256 colours pngmint is the most faithful of the four on photos**: 0.7 dB above UPNG.js, 1.1 dB above image-q, 1.4 dB above libimagequant, with files 2 percent smaller than UPNG.js and image-q and 17 percent smaller than libimagequant.
299
+ - **Below 128 colours UPNG.js writes smaller files** (8 percent at 128, 18 percent at 64, 22 percent at 32 on photos) because it does not dither; it pays with lower PSNR (0.2 to 0.5 dB) and clearly lower SSIM (-0.007 to -0.024, visible banding in skies and skin). Dial `dither` down to 0 if bytes matter more than banding and you get most of that back.
300
+ - **libimagequant has the best SSIM on photos at every colour count** (+0.004 to +0.005 over pngmint): its dithering covers the whole image with an adaptive strength, while pngmint dithers smooth areas only and clamps the carried error. Its PSNR is lower and its files 5 to 17 percent larger.
301
+ - **Speed**: UPNG.js is the fastest on photos (0.6 to 0.9 of pngmint's time); pngmint is 1.7 to 2.7 times faster than the libimagequant wasm build and 10 to 15 times faster than image-q. On graphics pngmint is the fastest of the four at every count (UPNG.js 2.2 to 3.4 times slower, libimagequant 1.9 to 2.8 times).
302
+ - **Lossless cases**: an image with at most 256 colours comes back pixel for pixel (`illustration-venn-diagram`, `pixelart-bird`). The file is then larger than oxipng's lossless output (151 kB against 128 kB), because oxipng tries PNG filters and a stronger deflate; pngmint writes rows unfiltered. If lossless size is the goal, run oxipng on the result.
303
+ - **Tiny files**: on a 1 MP icon with 9 colours the default compressor costs 1 kB (8.1 kB against 7.0 with the hook, 5.7 to 7.5 for the others). The hook closes that gap.
304
+
305
+ ### Every image at 256 colours
306
+
307
+ | Image | MP | pngmint kB | dB | ms | hook kB | UPNG.js kB | dB | ms | image-q kB | dB | ms | libimagequant kB | dB | ms | oxipng kB |
308
+ | ---------------------------- | ---: | ---------: | -------: | ---: | ------: | ---------: | ----: | ---: | ---------: | ----: | ----: | ---------------: | -------: | ---: | --------: |
309
+ | photo-kodim03-hats | 0.4 | 141.4 | 39.24 | 133 | 139.6 | 145.5 | 38.29 | 89 | 147.5 | 38.64 | 787 | 168.3 | 38.17 | 153 | 469.4 |
310
+ | photo-kodim15-face | 0.4 | 194.3 | 38.82 | 127 | 191.4 | 199.2 | 38.06 | 85 | 192.5 | 37.96 | 875 | 209.8 | 38.15 | 716 | 574.1 |
311
+ | photo-kodim23-parrots | 0.4 | 143.8 | 36.31 | 180 | 142.6 | 148.8 | 35.32 | 121 | 149.1 | 35.13 | 6479 | 175.5 | 35.06 | 1231 | 534.5 |
312
+ | photo-dordogne-14mp | 14.0 | 6196.4 | 36.05 | 2114 | 6020.3 | 6290.8 | 35.51 | 2683 | 6183.7 | 34.48 | 21998 | 7570.0 | 33.81 | 4017 | 16778.0 |
313
+ | photo-budapest-night-7mp | 7.2 | 3170.9 | 38.47 | 1070 | 3113.0 | 3230.2 | 38.03 | 1451 | 3269.0 | 37.04 | 10981 | 3646.3 | 36.49 | 1810 | 9478.3 |
314
+ | screenshot-wikipedia-history | 1.7 | 141.8 | 54.76 | 95 | 140.8 | 142.2 | 53.94 | 154 | 139.3 | 47.63 | 2473 | 145.8 | 53.66 | 152 | 276.0 |
315
+ | screenshot-wikidata-dialog | 3.1 | 83.3 | 64.53 | 94 | 80.2 | 84.3 | 63.83 | 242 | 78.5 | 48.24 | 4152 | 84.5 | 63.18 | 210 | 128.7 |
316
+ | screenshot-arc-browser | 4.7 | 363.4 | 52.02 | 275 | 375.2 | 466.0 | 51.47 | 524 | 363.4 | 47.27 | 6274 | 545.4 | 50.35 | 450 | 1067.7 |
317
+ | illustration-goyave | 2.2 | 197.6 | 51.24 | 166 | 194.1 | 198.0 | 50.73 | 161 | 194.2 | 46.39 | 3304 | 202.5 | 50.24 | 245 | 501.3 |
318
+ | illustration-village | 2.2 | 1002.0 | 42.82 | 363 | 975.9 | 1014.1 | 42.31 | 355 | 974.3 | 41.00 | 3511 | 1020.6 | 41.73 | 599 | 2559.5 |
319
+ | illustration-venn-diagram | 4.3 | 151.4 | lossless | 71 | 151.2 | 150.4 | 93.27 | 322 | 110.1 | 62.23 | 7131 | 142.4 | lossless | 801 | 127.5 |
320
+ | alpha-computer-icon | 1.0 | 8.1 | 87.54 | 24 | 7.0 | 7.5 | 78.06 | 269 | 5.7 | 52.00 | 4641 | 6.2 | 69.23 | 60 | 13.6 |
321
+ | alpha-wikiindaba-logo | 4.0 | 118.7 | 58.78 | 96 | 117.6 | 126.0 | 59.83 | 292 | 116.4 | 54.04 | 6493 | 127.0 | 59.56 | 269 | 292.8 |
322
+ | pixelart-bird | 0.3 | 1.3 | lossless | 7 | 1.1 | 1.3 | 71.24 | 19 | 1.1 | 61.81 | 366 | 1.2 | lossless | 19 | 1.1 |
323
+
324
+ Full per-image tables for 128, 64 and 32 colours and the presets are in
325
+ [`bench/results.md`](./bench/results.md).
326
+
327
+ ## How it works
328
+
329
+ 1. **Histogram.** Each distinct colour is counted once, premultiplied by alpha, so the hidden
330
+ colour of a transparent pixel never takes a palette slot. Fully transparent pixels become one
331
+ reserved entry. Up to 8192 colours the histogram is exact; beyond that colours are bucketed at
332
+ 6 bits per channel (4 for alpha) and each bucket remembers how far its pixels spread, so the
333
+ quality estimate stays honest.
334
+ 2. **Median cut.** The box with the most weighted error is split along its widest axis at the
335
+ weighted median, found in linear time from a 256-bin histogram rather than by sorting. Opaque
336
+ and see-through colours start in separate boxes, so an opaque pixel never turns slightly
337
+ transparent.
338
+ 3. **k-means.** Two rounds move each palette colour to the mean of the pixels it serves. Nearest
339
+ search is exact: it starts from the previous answer and drops a candidate as soon as its
340
+ partial distance is already worse.
341
+ 4. **Quality floor.** With `minQuality`, the palette is halved while a quick one-round palette
342
+ still holds the floor, then narrowed between the last size that held and the first that did
343
+ not.
344
+ 5. **Remap.** Without dithering every colour is matched exactly through a direct-mapped cache.
345
+ With dithering, Floyd-Steinberg error runs in serpentine order over smooth areas only; pixels
346
+ next to an edge (a luma or alpha step above 18) take their nearest colour and pass nothing on,
347
+ which keeps text crisp and files small. The carried error is clamped so colours far from every
348
+ palette entry do not turn into worms.
349
+ 6. **Write.** Palette entries no pixel uses are dropped. Entries are ordered fully transparent
350
+ first (a short tRNS), then dark to light (neighbouring indices stay close, which helps
351
+ deflate). Rows go unfiltered at the smallest bit depth that fits; IDAT comes from
352
+ `CompressionStream` or your `deflate` function.
353
+
354
+ ## Limits
355
+
356
+ - Palette PNG only. For photos where 256 colours are not enough, use WebP or AVIF; for lossless
357
+ PNG, use oxipng.
358
+ - CPU-bound and single-threaded (the promise only waits for the compressor). Put it in a worker
359
+ for anything above a megapixel.
360
+ - Memory: about 20 bytes per pixel on top of your input while it runs (the index array, the edge
361
+ map and the row buffer for deflate), plus up to 22 MB of fixed tables on large images.
362
+ - No APNG, no 16-bit input, no colour management: pixels in, pixels out, in whatever colour
363
+ space you gave them.
364
+ - The histogram is exact up to 8192 colours; a 20 000-colour screenshot is quantized from bucket
365
+ means, which is why a few screenshots lose 0.1 to 0.3 dB to libimagequant at 256 colours.
366
+
367
+ ## Used in production on Konvetto
368
+
369
+ pngmint is the engine behind the palette step of these free browser tools. They run the same code
370
+ you install from npm, in a Web Worker, and never upload your file:
371
+
372
+ - Compress PNG: [English](https://konvetto.com/images/compress-png),
373
+ [Polski](https://konvetto.com/pl/obrazy/kompresja-png),
374
+ [Deutsch](https://konvetto.com/de/bilder/png-komprimieren),
375
+ [Español](https://konvetto.com/es/imagenes/comprimir-png),
376
+ [Français](https://konvetto.com/fr/images/compresser-png)
377
+ - Compress image: [English](https://konvetto.com/images/compress-image),
378
+ [Polski](https://konvetto.com/pl/obrazy/zmniejsz-rozmiar-zdjecia),
379
+ [Deutsch](https://konvetto.com/de/bilder/bild-komprimieren),
380
+ [Español](https://konvetto.com/es/imagenes/comprimir-imagen),
381
+ [Français](https://konvetto.com/fr/images/compresser-image)
382
+
383
+ > **Try it free on Konvetto:** drop a PNG on [konvetto.com/images/compress-png](https://konvetto.com/images/compress-png),
384
+ > pick a strength, download. No install, no upload, runs in your browser.
385
+
386
+ ## License
387
+
388
+ MIT, Copyright (c) Konvetto. See [LICENSE](./LICENSE).
389
+
390
+ No runtime dependencies. The devDependencies of the tests and the benchmark include fflate
391
+ (MIT), libimagequant through `imagequant` (GPL-3.0), UPNG.js (MIT), image-q (MIT), ssim.js (MIT),
392
+ sharp (Apache-2.0) and @jsquash/oxipng (Apache-2.0); none of them ship in the package. Benchmark images are public domain or CC0, credited in
393
+ [`bench/images.json`](./bench/images.json).
394
+
395
+ Questions and security reports: hello@konvetto.com.
@@ -0,0 +1,147 @@
1
+ type Rgba = Uint8Array | Uint8ClampedArray;
2
+
3
+ /**
4
+ * Compresses raw scanlines into a zlib stream (RFC 1950, what IDAT holds). The built-in one is
5
+ * {@link nativeDeflate}; a caller may bring a stronger or synchronous one, such as fflate's
6
+ * `zlibSync(raw, { level: 9 })`.
7
+ */
8
+ type Deflate = (raw: Uint8Array) => Uint8Array | Promise<Uint8Array>;
9
+ /** The platform's `CompressionStream('deflate')`: zlib format at the engine's default level. */
10
+ declare function nativeDeflate(raw: Uint8Array): Promise<Uint8Array>;
11
+
12
+ /**
13
+ * Palette PNGs in pure TypeScript: histogram, median cut, k-means, selective dithering and an
14
+ * indexed PNG writer. With `minQuality` the palette gets as small as the image allows: a
15
+ * screenshot keeps a few colours, a photo gets up to `maxColors`. Quality is measured against
16
+ * the image's own range of brightness, so a dark or pale photo is not judged as if it used black
17
+ * to white.
18
+ */
19
+
20
+ /** Options shared by {@link quantize} and {@link createPalette}. */
21
+ interface PaletteOptions {
22
+ /** Most palette entries, 2 to 256. A fully transparent colour, when needed, counts. Default 256. */
23
+ maxColors?: number;
24
+ /**
25
+ * The least quality to keep, in dB: the palette gets fewer colours while it holds. Measured
26
+ * like PSNR but against the image's own range of brightness (see {@link QuantizeResult.quality}).
27
+ * Undefined (the default) keeps `maxColors`.
28
+ */
29
+ minQuality?: number;
30
+ /** k-means rounds for the final palette. 0 is plain median cut. Default 2. */
31
+ rounds?: number;
32
+ }
33
+ interface QuantizeOptions extends PaletteOptions {
34
+ /**
35
+ * 0 to 1: how much quantization error spreads to neighbouring pixels on smooth areas. Edges
36
+ * and text are never dithered, nor is an image with few colours or a palette that already
37
+ * fits well (quality above 42 dB). Default 0.
38
+ */
39
+ dither?: number;
40
+ /**
41
+ * The compressor for the pixel rows: raw bytes in, a zlib stream out. Default: the platform's
42
+ * `CompressionStream('deflate')`, which is asynchronous and compresses at the engine's default
43
+ * level (about 2.5% larger than fflate at level 9 on our set). Pass `(raw) => zlibSync(raw,
44
+ * { level: 9 })` from fflate for the smallest files, deterministic bytes and the synchronous
45
+ * variants.
46
+ */
47
+ deflate?: Deflate;
48
+ }
49
+ /** Options for {@link encodeIndexedPng} and {@link encodeIndexedPngSync}. */
50
+ interface EncodeOptions {
51
+ /** See {@link QuantizeOptions.deflate}. */
52
+ deflate?: Deflate;
53
+ }
54
+ interface PaletteResult {
55
+ /** Straight (not premultiplied) RGBA, 4 bytes per colour. Fully transparent first, then dark to light. */
56
+ palette: Uint8Array;
57
+ /** Number of colours in `palette`. */
58
+ colors: number;
59
+ /** Index of the fully transparent entry, or -1 when the image has no fully transparent pixel. */
60
+ transparentIndex: number;
61
+ /** Standard PSNR of the palette fit, in dB, peak 255: Infinity when every colour is kept. */
62
+ psnr: number;
63
+ /** The same fit measured against the image's own brightness range: what `minQuality` compares with. */
64
+ quality: number;
65
+ /** True when every colour of the image is in the palette (the output is lossless). */
66
+ exact: boolean;
67
+ }
68
+ interface QuantizeResult extends PaletteResult {
69
+ /** The indexed PNG file. */
70
+ png: Uint8Array;
71
+ width: number;
72
+ height: number;
73
+ /** One palette index per pixel, row by row. */
74
+ indices: Uint8Array;
75
+ }
76
+ /** Presets matching the strength steps of the Compress PNG tool on konvetto.com. */
77
+ declare const presets: {
78
+ /** Up to 256 colours while the fit stays above 42 dB; no dithering (it only added bytes here). */
79
+ readonly quality: {
80
+ readonly maxColors: 256;
81
+ readonly minQuality: 42;
82
+ readonly dither: 0;
83
+ };
84
+ /** Up to 128 colours while above 38 dB, light dithering on gradients. */
85
+ readonly balanced: {
86
+ readonly maxColors: 128;
87
+ readonly minQuality: 38;
88
+ readonly dither: 0.4;
89
+ };
90
+ /** Up to 64 colours while above 35 dB. */
91
+ readonly small: {
92
+ readonly maxColors: 64;
93
+ readonly minQuality: 35;
94
+ readonly dither: 0.65;
95
+ };
96
+ /** Up to 32 colours while above 32 dB. */
97
+ readonly tiny: {
98
+ readonly maxColors: 32;
99
+ readonly minQuality: 32;
100
+ readonly dither: 0.6;
101
+ };
102
+ };
103
+ /**
104
+ * PSNR of a squared error per pixel summed over `channels` (3 for an opaque image, 4 with
105
+ * alpha), against `peak`.
106
+ */
107
+ declare const psnrOf: (error: number, peak?: number, channels?: number) => number;
108
+ /**
109
+ * Builds a palette for an image without writing a file: for a custom pipeline (your own
110
+ * dithering, several images sharing one palette, an APNG) or just to inspect the fit.
111
+ * `rgba` is straight (not premultiplied) RGBA, 4 bytes per pixel, as a canvas gives it.
112
+ */
113
+ declare function createPalette(rgba: Rgba, options?: PaletteOptions): PaletteResult;
114
+ interface ApplyOptions {
115
+ /** 0 to 1: Floyd-Steinberg error diffusion on smooth areas only. Default 0. */
116
+ dither?: number;
117
+ /**
118
+ * Index of the palette entry every fully transparent pixel takes. Default: the entry
119
+ * nearest to transparent black.
120
+ */
121
+ transparentIndex?: number;
122
+ }
123
+ /**
124
+ * Maps every pixel to the nearest colour of a palette (straight RGBA, 4 bytes per colour, 1 to
125
+ * 256 colours), with optional dithering. Returns one index per pixel, row by row.
126
+ */
127
+ declare function applyPalette(rgba: Rgba, width: number, height: number, palette: Uint8Array, options?: ApplyOptions): Uint8Array;
128
+ /** Writes an indexed PNG from a palette (straight RGBA, 1 to 256 colours) and one index per pixel. */
129
+ declare function encodeIndexedPng(width: number, height: number, palette: Uint8Array, indices: Uint8Array, options?: EncodeOptions): Promise<Uint8Array>;
130
+ /** {@link encodeIndexedPng} with a synchronous `deflate` option (required). */
131
+ declare function encodeIndexedPngSync(width: number, height: number, palette: Uint8Array, indices: Uint8Array, options?: EncodeOptions): Uint8Array;
132
+ /**
133
+ * Quantizes straight RGBA pixels (as from `canvas.getImageData`) to an indexed PNG.
134
+ *
135
+ * An image with at most `maxColors` colours comes back lossless. With `minQuality` the palette
136
+ * shrinks while the quality holds. The result carries the file, the palette, the indices and
137
+ * the measured fit. The file is compressed with the platform's CompressionStream unless
138
+ * `options.deflate` brings another compressor.
139
+ */
140
+ declare function quantize(rgba: Rgba, width: number, height: number, options?: QuantizeOptions): Promise<QuantizeResult>;
141
+ /**
142
+ * {@link quantize} without a promise: needs a synchronous `deflate` option, such as fflate's
143
+ * `(raw) => zlibSync(raw, { level: 9 })`.
144
+ */
145
+ declare function quantizeSync(rgba: Rgba, width: number, height: number, options?: QuantizeOptions): QuantizeResult;
146
+
147
+ export { type ApplyOptions, type Deflate, type EncodeOptions, type PaletteOptions, type PaletteResult, type QuantizeOptions, type QuantizeResult, type Rgba, applyPalette, createPalette, encodeIndexedPng, encodeIndexedPngSync, nativeDeflate, presets, psnrOf, quantize, quantizeSync };