libimagequant — Image Quantization Library

Imagequant library converts RGBA images to palette-based 8-bit indexed images, including alpha component. It's ideal for generating tiny PNG images and nice-looking GIFs.

Image encoding/decoding isn't handled by the library itself, bring your own encoder. If you're looking for a command-line tool, see pngquant.

Getting started in C

This library can be used in C programs via imagequant-sys Rust package.

rustup update
git clone https://github.com/ImageOptim/libimagequant
cd imagequant-sys
cargo build --release
# makes target/release/libimagequant_sys.a

See the C library documentation for more details.

Getting started in Rust

Add to Cargo.toml:

rustup update
cargo add imagequant

See docs.rs for the library API documentation.

License

Libimagequant is dual-licensed:

• For Free/Libre Open Source Software it's available under GPL v3 or later with additional copyright notices for historical reasons.
• For use in closed-source software, AppStore distribution, and other non-GPL uses, you can obtain a commercial license. Feel free to ask kornel@pngquant.org for details and custom licensing terms if you need them.

Upgrading instructions

libimagequant v2 used to be a C library. libimagequant v4 is written entirely in Rust, but still exports the same C interface for C programs. You will need to install Rust 1.70+ to build it, and adjust your build commands. If you do not want to upgrade, you can keep using the C version of the library in the 2.x branch of the repo.

C static library users

Files for C/C++ are now in the imagequant-sys/ subdirectory, not in the root of the repo. There is no configure && make any more.

To build the library, install Rust via rustup, and run:

rustup update
cd imagequant-sys
cargo build --release

It produces target/release/libimagequant_sys.a static library. The API, ABI, and header files remain the same, so everything else should work the same. If you're building for macOS or iOS, see included xcodeproj file (add it as a subproject to yours).

If you're building for Android, run rustup target add aarch64-linux-android; cargo build --release --target aarch64-linux-android and use target/aarch64-linux-android/release/libimagequant_sys.a. Same for cross-compiling to other platforms. See rustup target list.

C dynamic library for package maintainers

If you're an application developer, please use the static linking option above — that option is much easier, and gives smaller executables.

The API and ABI of this library remains the same. It has the same sover, so it can be a drop-in replacement for the previous C version.

This library is now a typical Rust/Cargo library. If you want to set up off-line builds or override dependencies, it works the same as for every other Rust project. See Cargo docs for things like cargo fetch or cargo vendor (but I don't recommend vendoring).

If you want to build a dynamic library, but aren't bothered by soname and rpath being wrong, modify imagequant-sys/Cargo.toml and add "cdylib" to the existing crate-type property, and then cargo build --release will do its usual half-finished job and build target/release/libimagequant.{so,dylib,dll}.

Building with make

configure && make is gone. I hoped I could build a dynamic library just by wrapping the static library, but apparently that won't work, so I can't easily recreate the old make install. I wish there was a more standard and lightweight solution than using the cargo-c tool, so if you're good at wrangling linker flags and symbol visibility, please send pull requests.

Building with cargo-c

The cargo-c tool knows how to build and link so/dylib properly, and generates an accurate pkg-config file, so it's de-facto required for a correct system-wide install of a dynamic library.

rustup update
cd imagequant-sys
cargo install cargo-c
cargo cinstall --prefix=/usr/local --destdir=.

This makes Rust 1.70 and cargo-c package a build-time dependency. No runtime deps (apart from Cargo-internal ones). OpenMP has been dropped entirely.

Interaction with pngquant

pngquant v2 can use this library as a dynamic library. However, pngquant v4 does not support unbundling. It uses this library as a Cargo dependency via its Rust-native interface. The shared libimagequant library exports only a stable ABI for C programs, and this interface is not useful for Rust programs.

Upgrading for Rust users

If you've used the imagequant-sys crate, switch to the higher-level imagequant crate. The imagequant v4 is almost entirely backwards-compatible, with small changes that the Rust compiler will point out (e.g. changed use of c_int to u32). See docs. Please fix any deprecation warnings you may get, because the deprecated functions will be removed.

The openmp Cargo feature has been renamed to threads.

.new_image() can now take ownership of its argument to avoid copying. If you get an error that From<&Vec<RGBA>> is not implemented, then either don't pass by reference (moves, avoids copying), or call .as_slice() on it (to copy the pixels), or use .new_image_borrowed() method instead.

Threads support and WASM

By default, when the threads Cargo feature is enabled, this library uses multi-threading. Number of threads can be controlled via RAYON_NUM_THREADS environment variable.

Threads in WASM are experimental, and require special handling. If you're targeting WASM, you'll most likely want to disable threads.

To disable threads when using this library as a dependency, disable default features like this in Cargo.toml:

[dependencies]
imagequant = { version = "4.0", default-features = false }

When you compile the library directly, add --no-default-features flag instead.