libimgquant 3.0.0__tar.gz
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.
- libimgquant-3.0.0/BENCHMARKS.md +95 -0
- libimgquant-3.0.0/CHANGELOG.md +147 -0
- libimgquant-3.0.0/Cargo.lock +572 -0
- libimgquant-3.0.0/Cargo.toml +65 -0
- libimgquant-3.0.0/LICENSE +26 -0
- libimgquant-3.0.0/NOTICE +16 -0
- libimgquant-3.0.0/PKG-INFO +192 -0
- libimgquant-3.0.0/README.md +439 -0
- libimgquant-3.0.0/THIRD-PARTY-LICENSES.txt +707 -0
- libimgquant-3.0.0/examples/animated_gif.rs +339 -0
- libimgquant-3.0.0/libimgquant/__init__.py +77 -0
- libimgquant-3.0.0/libimgquant/_libimgquant.pyi +112 -0
- libimgquant-3.0.0/libimgquant/py.typed +0 -0
- libimgquant-3.0.0/pyproject.toml +66 -0
- libimgquant-3.0.0/python/.gitignore +8 -0
- libimgquant-3.0.0/python/Cargo.lock +292 -0
- libimgquant-3.0.0/python/Cargo.toml +32 -0
- libimgquant-3.0.0/python/README.md +150 -0
- libimgquant-3.0.0/python/THIRD-PARTY-LICENSES.txt +707 -0
- libimgquant-3.0.0/python/src/lib.rs +345 -0
- libimgquant-3.0.0/python/tests/conftest.py +53 -0
- libimgquant-3.0.0/python/tests/test_png.py +157 -0
- libimgquant-3.0.0/python/tests/test_quantize.py +204 -0
- libimgquant-3.0.0/src/attr.rs +577 -0
- libimgquant-3.0.0/src/blur.rs +289 -0
- libimgquant-3.0.0/src/dithermap.rs +131 -0
- libimgquant-3.0.0/src/error.rs +34 -0
- libimgquant-3.0.0/src/hist.rs +1200 -0
- libimgquant-3.0.0/src/histogram.rs +416 -0
- libimgquant-3.0.0/src/image.rs +503 -0
- libimgquant-3.0.0/src/kmeans.rs +445 -0
- libimgquant-3.0.0/src/lib.rs +229 -0
- libimgquant-3.0.0/src/mediancut/improved.rs +644 -0
- libimgquant-3.0.0/src/mediancut/moments.rs +578 -0
- libimgquant-3.0.0/src/mediancut.rs +683 -0
- libimgquant-3.0.0/src/nearest/exact.rs +315 -0
- libimgquant-3.0.0/src/nearest/reference.rs +207 -0
- libimgquant-3.0.0/src/nearest/tests.rs +277 -0
- libimgquant-3.0.0/src/nearest/vp.rs +602 -0
- libimgquant-3.0.0/src/nearest.rs +49 -0
- libimgquant-3.0.0/src/pal.rs +313 -0
- libimgquant-3.0.0/src/png_io.rs +499 -0
- libimgquant-3.0.0/src/quant.rs +642 -0
- libimgquant-3.0.0/src/remap.rs +718 -0
- libimgquant-3.0.0/src/reorder.rs +356 -0
- libimgquant-3.0.0/src/rng.rs +63 -0
- libimgquant-3.0.0/tests/api.rs +278 -0
- libimgquant-3.0.0/tests/common/mod.rs +85 -0
- libimgquant-3.0.0/tests/golden.rs +240 -0
- libimgquant-3.0.0/tests/histogram.rs +336 -0
- libimgquant-3.0.0/tests/png_io.rs +318 -0
- libimgquant-3.0.0/tests/quantize.rs +305 -0
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Benchmarks
|
|
2
|
+
|
|
3
|
+
The measurements behind the comparison in the [README](README.md#comparison): libimgquant 3
|
|
4
|
+
(`Profile::Improved`) against its own port of libimagequant 2.4.1 (`Profile::Compat`) and,
|
|
5
|
+
for reference only, against imagequant 4.4.1.
|
|
6
|
+
|
|
7
|
+
## Test set
|
|
8
|
+
|
|
9
|
+
22 PNG images, 18.5 megapixels in total: photos, paintings, textures, sprites with alpha, UI
|
|
10
|
+
screenshots, flat art, noise and an already paletted image. It is a private set of images
|
|
11
|
+
under mixed licenses, so the images are not part of the repository; any directory of PNG
|
|
12
|
+
files can be measured the same way. All settings are at 256 colors, measured with
|
|
13
|
+
libimgquant 3.0.0 on 2026-10-22.
|
|
14
|
+
|
|
15
|
+
## How it was measured
|
|
16
|
+
|
|
17
|
+
- **Metrics:** SSIMULACRA 2.1 (higher is better), butteraugli 3-norm and CIEDE2000 (lower is
|
|
18
|
+
better). Images with alpha are scored over a dark and a light background, keeping the
|
|
19
|
+
worse score.
|
|
20
|
+
- **PNG size:** the smaller of an unfiltered and a filtered encoding, with the smallest bit
|
|
21
|
+
depth and a trimmed tRNS chunk (as described under
|
|
22
|
+
[PNG files](README.md#png-files)), applied to every library alike.
|
|
23
|
+
- **Time:** the best of 2 runs on 14 threads.
|
|
24
|
+
- **Peak memory:** the largest heap growth during one image's `new_image_borrowed`,
|
|
25
|
+
`quantize` and `remapped` calls (or the same calls of imagequant), the maximum over the 22
|
|
26
|
+
images, counted with a tracking allocator in the comparison program. The caller's input
|
|
27
|
+
pixels are borrowed and not counted; the returned indices are.
|
|
28
|
+
|
|
29
|
+
imagequant 4.4.1 (the newest GPL libimagequant release when measured) is shown for reference
|
|
30
|
+
only. It was run as a black box through its public API in a one-off comparison program,
|
|
31
|
+
which also measured every peak-memory figure. That program is not published; imagequant is
|
|
32
|
+
not part of this project, and none of its code is used here.
|
|
33
|
+
|
|
34
|
+
## Results
|
|
35
|
+
|
|
36
|
+
| Speed, dithering | Library | Time | Peak memory | SSIMULACRA2 | butteraugli | CIEDE2000 | PNG size |
|
|
37
|
+
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
38
|
+
| 3, none | **libimgquant 3** | **1.39 s** | **83 MB** | **88.30** | **0.708** | **0.527** | **3.54 MB** |
|
|
39
|
+
| 3, none | 2.4.1 port (`Compat`) | 4.73 s | 87 MB | 86.43 | 0.864 | 0.548 | 3.77 MB |
|
|
40
|
+
| 3, none | imagequant 4.4.1 (GPL) | 1.44 s | 88 MB | 87.38 | 0.799 | 0.535 | 3.89 MB |
|
|
41
|
+
| 3, full | **libimgquant 3** | **1.54 s** | **83 MB** | **88.78** | **0.665** | **0.532** | **3.64 MB** |
|
|
42
|
+
| 3, full | imagequant 4.4.1 (GPL) | 1.95 s | 88 MB | 88.12 | 0.735 | 0.546 | 4.14 MB |
|
|
43
|
+
| 1, full | **libimgquant 3** | **1.74 s** | **83 MB** | **88.89** | **0.663** | **0.530** | **3.64 MB** |
|
|
44
|
+
| 1, full | imagequant 4.4.1 (GPL) | 2.68 s | 88 MB | 88.36 | 0.684 | 0.542 | 4.07 MB |
|
|
45
|
+
| 10, full | **libimgquant 3** | **0.56 s** | **9 MB** | **87.37** | **0.894** | 0.687 | 4.15 MB |
|
|
46
|
+
| 10, full | imagequant 4.4.1 (GPL) | 1.01 s | 69 MB | 86.78 | 0.916 | **0.672** | **4.14 MB** |
|
|
47
|
+
| 10, none | **libimgquant 3** | 0.48 s | **9 MB** | **86.61** | **0.971** | 0.632 | 3.74 MB |
|
|
48
|
+
| 10, none | imagequant 4.4.1 (GPL) | **0.43 s** | 69 MB | 85.61 | 1.060 | **0.619** | **3.72 MB** |
|
|
49
|
+
|
|
50
|
+
**Against the 2.4.1 port** (measured at speed 3 without dithering): version 3 is 3.4 times
|
|
51
|
+
as fast, better on all three metrics and 6% smaller.
|
|
52
|
+
|
|
53
|
+
**Against imagequant 4.4.1:**
|
|
54
|
+
|
|
55
|
+
- **Speeds 1 and 3:** version 3 is about as fast without dithering and 1.3–1.5 times as fast
|
|
56
|
+
with it, better on all three metrics, 9–12% smaller, and uses less memory.
|
|
57
|
+
- **Speed 10:**
|
|
58
|
+
- **Better:** SSIMULACRA2, butteraugli, and 7× less memory. With dithering, it is also
|
|
59
|
+
1.8 times as fast.
|
|
60
|
+
- **About equal:** file size.
|
|
61
|
+
- **Worse:** CIEDE2000 is about 2% behind. Without dithering it is about 10% slower; v4's
|
|
62
|
+
own time varied by about as much between runs.
|
|
63
|
+
- **Why sizes are equal at speed 10:** palette reordering is skipped at speeds 8–10. It
|
|
64
|
+
would make files 7% smaller but costs about 20% of the time there.
|
|
65
|
+
|
|
66
|
+
## One palette for many images
|
|
67
|
+
|
|
68
|
+
`examples/animated_gif.rs` builds one palette for all frames with a `Histogram` and writes
|
|
69
|
+
an animated GIF. GIF has a single transparent index and no partial alpha, so the example
|
|
70
|
+
makes pixels with alpha below 128 transparent and the rest opaque. `--compare` prints each
|
|
71
|
+
frame's PSNR with the shared palette, with the first frame's palette and with a palette of
|
|
72
|
+
its own:
|
|
73
|
+
|
|
74
|
+
- **Six unrelated test images as frames** (490x490 crops): 40.4 dB with the shared palette
|
|
75
|
+
against 34.9 dB with the first frame's (49.0 dB with a palette each, but a 58% larger GIF).
|
|
76
|
+
- **The example's synthetic animation of similar frames:** 52.7 dB against 52.5 dB (53.5 dB
|
|
77
|
+
each).
|
|
78
|
+
|
|
79
|
+
## Reproducing
|
|
80
|
+
|
|
81
|
+
[`tools/iqeval`](tools/iqeval/README.md) measures the time, quality and PNG-size columns of
|
|
82
|
+
the libimgquant rows on any directory of PNG files; the imagequant rows and peak memory come
|
|
83
|
+
from the unpublished comparison program. It is an unpublished workspace member with its own
|
|
84
|
+
dependencies and MSRV (1.89). It reads PNG files, so the reference images are exact, and it
|
|
85
|
+
times only `new_image_borrowed`, `quantize`, `set_dithering_level` and `remapped`:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
# speed 3 (the default); add --speed 1 or --speed 10 for the other rows
|
|
89
|
+
cargo run --release -p iqeval -- path/to/pngs --profile both --repeat 2 --dither 1 --save s3d1.tsv
|
|
90
|
+
cargo run --release -p iqeval -- path/to/pngs --profile both --repeat 2 --dither 0 --save s3d0.tsv
|
|
91
|
+
cargo run --release -p iqeval -- --diff old.tsv new.tsv
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`--profile both` runs `Improved` and `Compat` interleaved and prints the change per image and
|
|
95
|
+
per metric. See [tools/iqeval/README.md](tools/iqeval/README.md) for all options and metrics.
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to libimgquant are listed here. Versions follow
|
|
4
|
+
[Semantic Versioning](https://semver.org/). Version 3.0.0 is the first release; it is
|
|
5
|
+
compared with libimagequant 2.4.1, the BSD-licensed C library it is based on.
|
|
6
|
+
|
|
7
|
+
## 3.0.0 (2026-11-18)
|
|
8
|
+
|
|
9
|
+
### Overview
|
|
10
|
+
|
|
11
|
+
- **Pure Rust:** a rewrite of libimagequant 2.4.1 (tag `2.4.1`, commit
|
|
12
|
+
`976e021cda07c14cd36630f611a5a6eb2cafc28e`) in Rust, `#![forbid(unsafe_code)]`, with no C
|
|
13
|
+
code, no build script and no FFI. Dependencies: `rgb`, `rayon` for the optional
|
|
14
|
+
`threads` feature (on by default) and `png` for the optional `png` feature. MSRV 1.85.
|
|
15
|
+
- **License:** BSD-2-Clause, plus Jef Poskanzer's original permissive notice. No code from
|
|
16
|
+
libimagequant 2.5 or later (GPL-3) was used. `LICENSE` has the BSD-2-Clause text and
|
|
17
|
+
`NOTICE` the provenance and Poskanzer's notice; every crate, wheel, sdist and the npm
|
|
18
|
+
package ships both.
|
|
19
|
+
- **Two profiles:** `Profile::Improved` (the default) uses the new algorithms below.
|
|
20
|
+
`Profile::Compat` reproduces 2.4.1 step by step, including its mixed `f32`/`f64`
|
|
21
|
+
arithmetic, apart from the bug fixes below; golden-hash tests freeze its output.
|
|
22
|
+
|
|
23
|
+
### New algorithms (`Profile::Improved`)
|
|
24
|
+
|
|
25
|
+
- **Color difference:** an OKLab-shaped opponent matrix (lightness and two chroma axes) on
|
|
26
|
+
2.4.1's internal gamma, keeping its premultiplied alpha and black/white blending.
|
|
27
|
+
- **Median cut:** splits along the principal axis at the error-optimal point, and splits
|
|
28
|
+
the box with the largest error first.
|
|
29
|
+
- **Refinement:** weighted Hartigan moves after the k-means (Lloyd) iterations.
|
|
30
|
+
- **Nearest color:** an exact search with a switching triangle-inequality search.
|
|
31
|
+
- **Dithering:** serpentine Floyd-Steinberg in parallel 64-row strips with warm-up rows;
|
|
32
|
+
seamless and deterministic.
|
|
33
|
+
- **Palette order:** colors that touch in the image get adjacent indices (speeds 1-7), which
|
|
34
|
+
makes filtered PNGs smaller. Translucent entries still come first.
|
|
35
|
+
- **Speed presets:** fewer repeated median cuts and k-means iterations.
|
|
36
|
+
|
|
37
|
+
On the project's private 22-image test set at speed 3 without dithering (measured on
|
|
38
|
+
2026-10-22), the default profile takes 1.39 s against 4.73 s for the 2.4.1 port, scores
|
|
39
|
+
better on SSIMULACRA2, butteraugli and CIEDE2000, and gives 6% smaller PNGs (BENCHMARKS.md).
|
|
40
|
+
|
|
41
|
+
### Faster in both profiles (output unchanged)
|
|
42
|
+
|
|
43
|
+
- The 2.4.1 nearest-color search is vectorized and prunes with the triangle inequality.
|
|
44
|
+
- With the `threads` feature, the histogram, contrast maps, pixel conversion, k-means
|
|
45
|
+
iterations, remapping and dither map run in parallel. Parallel sums use fixed work
|
|
46
|
+
chunks, so output does not depend on the number of threads.
|
|
47
|
+
|
|
48
|
+
### Rust API
|
|
49
|
+
|
|
50
|
+
- `Attributes`, `Image` and `QuantizationResult` replace `liq_attr`, `liq_image` and
|
|
51
|
+
`liq_result`; errors are `Result<_, Error>`.
|
|
52
|
+
- Images from owned or borrowed pixels (with or without a stride), separate rows, or a row
|
|
53
|
+
callback.
|
|
54
|
+
- Remapping into a new buffer (`remapped`), a contiguous buffer (`remap_into`) or separate
|
|
55
|
+
rows (`remap_rows`); one result can remap several images, each with the palette fitted to
|
|
56
|
+
it, which `remapped` returns.
|
|
57
|
+
- Log callbacks are closures.
|
|
58
|
+
- `Histogram`: one palette for several images (animation frames, sprite sheets). Images are
|
|
59
|
+
added with `add_image`, weighted as `quantize` weights a single image (contrast maps, each
|
|
60
|
+
color limited to a tenth of the image's area); colors with pixel counts with
|
|
61
|
+
`add_colors` (`HistogramEntry`); fixed colors with `add_fixed_color`. `quantize` returns a
|
|
62
|
+
result that remaps every image to exactly the same palette. All colors must have one
|
|
63
|
+
gamma. The result is the same for any number of threads.
|
|
64
|
+
- Feature `png` (off by default): the `png_io` module decodes any PNG to RGBA with its gamma
|
|
65
|
+
and ICC profile (`decode`), writes palette PNGs with the smallest bit depth, a trimmed tRNS
|
|
66
|
+
chunk and the smaller of an unfiltered and a filtered encoding (`encode_indexed`), and
|
|
67
|
+
converts a PNG in one call (`compress_png`), keeping the gamma and ICC profile.
|
|
68
|
+
`encode_indexed` takes the gAMA and iCCP chunks to write as a `PngMetadata`, which
|
|
69
|
+
`DecodedPng::metadata()` copies from a decoded file. The command-line tool uses it.
|
|
70
|
+
- `decode` and untrusted files: images over `i32::MAX` pixels are rejected before anything
|
|
71
|
+
is allocated, the pixels are allocated fallibly and filled as rows are decoded, and
|
|
72
|
+
images with too little image data for their size fail before their pixels are allocated.
|
|
73
|
+
The png crate's own buffers keep its 64 MiB limit. Only RGB ICC profiles are written (PNG
|
|
74
|
+
allows no other kind on palette images).
|
|
75
|
+
- Every public type implements `Debug`; `Image` and `QuantizationResult` show their size
|
|
76
|
+
and settings, not their pixels.
|
|
77
|
+
- `examples/animated_gif.rs`: PNG frames (or a synthetic animation) to an animated GIF with
|
|
78
|
+
one palette, using `Histogram` and the `gif` crate (a development dependency only).
|
|
79
|
+
|
|
80
|
+
### C API (`libimgquant-capi`, new crate)
|
|
81
|
+
|
|
82
|
+
- `libimgquant.h` with every function, type and constant of the libimagequant 2.4.1 header.
|
|
83
|
+
Programs written for 2.4.x need only a new include and `-limgquant`.
|
|
84
|
+
- Builds a shared and a static library; `cargo cinstall` (cargo-c) installs the header and
|
|
85
|
+
a `libimgquant.pc` pkg-config file.
|
|
86
|
+
- Additions: `liq_set_profile`/`liq_get_profile` with `LIQ_HAS_PROFILES`, and a declared
|
|
87
|
+
`liq_version()`. `LIQ_VERSION` is 30000.
|
|
88
|
+
- `liq_get_palette` returns one stable pointer per result, valid until
|
|
89
|
+
`liq_result_destroy`; in 2.4.1 an old pointer could dangle after remapping.
|
|
90
|
+
- `liq_image_create_rgba` returns NULL when the image can't be created; 2.4.1 wrote through
|
|
91
|
+
a NULL pointer.
|
|
92
|
+
|
|
93
|
+
### Command-line tool (`imgquant`, new crate)
|
|
94
|
+
|
|
95
|
+
- A pngquant-style command-line tool built on the library: `cargo install imgquant`.
|
|
96
|
+
- pngquant's options: number of colors, `--quality`, `--speed` (1-11; 11 is the same as
|
|
97
|
+
10), `--nofs`/`--ordered`/`--floyd`, `--posterize`, `--ext`, `-o`, `--force`,
|
|
98
|
+
`--skip-if-larger`, `--strip`, `--transbug`, `-v`/`-q`; plus `--profile` and `--threads`.
|
|
99
|
+
`--ordered` is the same as `--nofs`, since there is no ordered dithering.
|
|
100
|
+
- pngquant's exit codes: 99 when the minimum quality can't be reached, 98 when the result
|
|
101
|
+
would be larger (`--skip-if-larger`), 15 when the output exists without `--force`. With
|
|
102
|
+
standard output as the output, 98 and 99 write the input there unchanged.
|
|
103
|
+
- Reads every PNG color type and bit depth, keeps the input's gamma and ICC profile
|
|
104
|
+
(`--strip` drops the ICC profile), writes the smallest bit depth and the smaller of an
|
|
105
|
+
unfiltered and a filtered encoding, and writes files atomically. Reads standard input and
|
|
106
|
+
writes standard output with `-`.
|
|
107
|
+
- Prebuilt binaries for Linux (static musl builds for x86_64 and aarch64), Windows (x64) and
|
|
108
|
+
macOS (arm64, x86_64) are attached to the GitHub release; `cargo binstall imgquant`
|
|
109
|
+
installs them.
|
|
110
|
+
|
|
111
|
+
### npm package (`libimgquant`, new, `wasm/`)
|
|
112
|
+
|
|
113
|
+
- WebAssembly build for browsers and Node.js 18+, with TypeScript types and no
|
|
114
|
+
dependencies: `quantize`, `compressPng` (PNG in, smaller indexed PNG out) and
|
|
115
|
+
`quantizeFrames` (one palette for many frames). About 480 KB `.wasm`, 190 KB gzipped.
|
|
116
|
+
`compressPng` keeps the input's gamma and ICC profile.
|
|
117
|
+
|
|
118
|
+
### Python package (`libimgquant`, new, `python/`)
|
|
119
|
+
|
|
120
|
+
- PyO3 bindings with stable-ABI wheels for CPython 3.9+: `quantize`, `compress_png`,
|
|
121
|
+
`quantize_frames` and the Pillow helper `quantize_image`. Accepts bytes, bytearray,
|
|
122
|
+
memoryview and numpy arrays; releases the GIL while working; raises
|
|
123
|
+
`QualityTooLowError` when the minimum quality can't be reached. `compress_png` keeps the
|
|
124
|
+
input's gamma and ICC profile.
|
|
125
|
+
- The wheels and the sdist include `THIRD-PARTY-LICENSES.txt`, the licenses of the Rust
|
|
126
|
+
crates compiled into the extension.
|
|
127
|
+
|
|
128
|
+
### Bug fixes (both profiles)
|
|
129
|
+
|
|
130
|
+
- **Edge map:** high-contrast pixels no longer get garbage values (2.4.1 converted negative
|
|
131
|
+
floats to bytes with undefined behavior).
|
|
132
|
+
- **Large images:** images over about 4 megapixels get correct contrast maps (2.4.1 reused
|
|
133
|
+
one row buffer for three rows, so it saw no vertical edges and shifted the map by a row).
|
|
134
|
+
- **Median cut:** deep recursion, which could overflow the stack on large images with many
|
|
135
|
+
near-identical colors, is now iterative.
|
|
136
|
+
- **Out-of-bounds reads** in rare edge cases are replaced with safe behavior.
|
|
137
|
+
- **Settings:** `set_dithering_level` validates the new value instead of the previous one,
|
|
138
|
+
and `set_output_gamma` no longer returns a palette rounded with the previous gamma.
|
|
139
|
+
|
|
140
|
+
### Deterministic output
|
|
141
|
+
|
|
142
|
+
- Dithering noise comes from the crate's own seeded generator (the lagged-Fibonacci
|
|
143
|
+
algorithm of GNU `random()`) instead of the global `rand()`.
|
|
144
|
+
- Sorting uses a fixed tie order instead of the platform's `qsort` order, and histogram
|
|
145
|
+
hashing is little-endian on every platform.
|
|
146
|
+
- So output is identical on every platform. The dither map threshold is speed 5 in every
|
|
147
|
+
build; 2.4.1 raised it to 7 in OpenMP builds.
|