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.
Files changed (52) hide show
  1. libimgquant-3.0.0/BENCHMARKS.md +95 -0
  2. libimgquant-3.0.0/CHANGELOG.md +147 -0
  3. libimgquant-3.0.0/Cargo.lock +572 -0
  4. libimgquant-3.0.0/Cargo.toml +65 -0
  5. libimgquant-3.0.0/LICENSE +26 -0
  6. libimgquant-3.0.0/NOTICE +16 -0
  7. libimgquant-3.0.0/PKG-INFO +192 -0
  8. libimgquant-3.0.0/README.md +439 -0
  9. libimgquant-3.0.0/THIRD-PARTY-LICENSES.txt +707 -0
  10. libimgquant-3.0.0/examples/animated_gif.rs +339 -0
  11. libimgquant-3.0.0/libimgquant/__init__.py +77 -0
  12. libimgquant-3.0.0/libimgquant/_libimgquant.pyi +112 -0
  13. libimgquant-3.0.0/libimgquant/py.typed +0 -0
  14. libimgquant-3.0.0/pyproject.toml +66 -0
  15. libimgquant-3.0.0/python/.gitignore +8 -0
  16. libimgquant-3.0.0/python/Cargo.lock +292 -0
  17. libimgquant-3.0.0/python/Cargo.toml +32 -0
  18. libimgquant-3.0.0/python/README.md +150 -0
  19. libimgquant-3.0.0/python/THIRD-PARTY-LICENSES.txt +707 -0
  20. libimgquant-3.0.0/python/src/lib.rs +345 -0
  21. libimgquant-3.0.0/python/tests/conftest.py +53 -0
  22. libimgquant-3.0.0/python/tests/test_png.py +157 -0
  23. libimgquant-3.0.0/python/tests/test_quantize.py +204 -0
  24. libimgquant-3.0.0/src/attr.rs +577 -0
  25. libimgquant-3.0.0/src/blur.rs +289 -0
  26. libimgquant-3.0.0/src/dithermap.rs +131 -0
  27. libimgquant-3.0.0/src/error.rs +34 -0
  28. libimgquant-3.0.0/src/hist.rs +1200 -0
  29. libimgquant-3.0.0/src/histogram.rs +416 -0
  30. libimgquant-3.0.0/src/image.rs +503 -0
  31. libimgquant-3.0.0/src/kmeans.rs +445 -0
  32. libimgquant-3.0.0/src/lib.rs +229 -0
  33. libimgquant-3.0.0/src/mediancut/improved.rs +644 -0
  34. libimgquant-3.0.0/src/mediancut/moments.rs +578 -0
  35. libimgquant-3.0.0/src/mediancut.rs +683 -0
  36. libimgquant-3.0.0/src/nearest/exact.rs +315 -0
  37. libimgquant-3.0.0/src/nearest/reference.rs +207 -0
  38. libimgquant-3.0.0/src/nearest/tests.rs +277 -0
  39. libimgquant-3.0.0/src/nearest/vp.rs +602 -0
  40. libimgquant-3.0.0/src/nearest.rs +49 -0
  41. libimgquant-3.0.0/src/pal.rs +313 -0
  42. libimgquant-3.0.0/src/png_io.rs +499 -0
  43. libimgquant-3.0.0/src/quant.rs +642 -0
  44. libimgquant-3.0.0/src/remap.rs +718 -0
  45. libimgquant-3.0.0/src/reorder.rs +356 -0
  46. libimgquant-3.0.0/src/rng.rs +63 -0
  47. libimgquant-3.0.0/tests/api.rs +278 -0
  48. libimgquant-3.0.0/tests/common/mod.rs +85 -0
  49. libimgquant-3.0.0/tests/golden.rs +240 -0
  50. libimgquant-3.0.0/tests/histogram.rs +336 -0
  51. libimgquant-3.0.0/tests/png_io.rs +318 -0
  52. 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.