Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/darthsim/quantizr
Fast library for converting RGBA images to 8-bit palette images. Written in Rust; can be used in C programs
https://github.com/darthsim/quantizr
image palette quantization rust
Last synced: 3 months ago
JSON representation
Fast library for converting RGBA images to 8-bit palette images. Written in Rust; can be used in C programs
- Host: GitHub
- URL: https://github.com/darthsim/quantizr
- Owner: DarthSim
- License: mit
- Created: 2020-03-08T11:37:46.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-18T14:16:03.000Z (about 1 year ago)
- Last Synced: 2024-08-09T12:28:17.776Z (6 months ago)
- Topics: image, palette, quantization, rust
- Language: Rust
- Homepage:
- Size: 81.1 KB
- Stars: 16
- Watchers: 5
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Quantizr
[](https://crates.io/crates/quantizr) [](https://docs.rs/quantizr)
Fast library for converting RGBA images to 8-bit palette images. Written in Rust; can be used in C programs.
## Using with Rust
Add to Cargo.toml:
```toml
[dependencies]
quantizr = "1.4.0"
```
See [docs.rs](https://docs.rs/quantizr) for the library API documentation. Also, check out [examples](examples) directory for example code.
## Using with C
### Installation
Quantizr written in Rust, so you need to [install it](https://www.rust-lang.org/tools/install) first. Also, you need [cargo-c](https://github.com/lu-zero/cargo-c#installation). Then simply run:
```bash
cargo cinstall --release
```
### Usage
```c
#include "quantizr.h"
uint8_t *image_data;
int32_t image_width;
int32_t image_height;
QuantizrOptions *opts;
QuantizrImage *img;
QuantizrResult *res;
QuantizrPalette *pal;
QuantizrError err;
size_t out_buffer_length = width * height;
uint8_t *out_buffer = (uint8_t*)malloc(out_buffer_length);
// Load image data and get its dimensions. `load_image` is not a part of Quantizr
load_image(&data, &width, &height);
// Create new image object.
// You're responsible for freeing it when the work is done (see below).
// image_data is unsigned char array with raw RGBA pixels.
img = quantizr_create_image_rgba(image_data, image_width, image_height);
// Create new Quantizr options.
// You're responsible for freeing it when the work is done (see below).
opts = quantizr_new_options();
// (optional) Set desired number of colors. The default number is 256.
// This function returns QUANTIZR_VALUE_OUT_OF_RANGE if provided number is less than 2 or
// greater than 255.
err = quantizr_set_max_colors(opts, 128);
if (err != QuantizrOk) {
// handle error...
}
// Quantize image.
// This function returns quantization result, which you're responsible to free when
// the work is done (see below).
res = quantizr_quantize(img, opts);
// Set dithering level for the future remapping. The default level is 1.0.
// This function returns QUANTIZR_VALUE_OUT_OF_RANGE if provided level is less than 0.0 or
// greater than 1.0.
err = quantizr_set_dithering_level(res, 0.8);
if (err != QuantizrOk) {
// handle error...
}
// Write quantized image in the provided buffer.
// The buffer should be prealocated and be large enough to fit entire image (width*height bytes).
// This function returns QUANTIZR_BUFFER_TOO_SMALL if the buffer is not large enough.
err = quantizr_remap(res, img, out_buffer, out_buffer_length);
if (err != QuantizrOk) {
// handle error...
}
// Fetch palette from the quantization result.
// Fetched pallette is read-only. You should not modify or free it.
// pal->count is a number of colors in the palette.
// pal->entries is an array of colors.
// pal->entries[i].r, pal->entries[i].g, pal->entries[i].b, and pal->entries[i].a are color channels
// of palette colors.
pal = quantizr_get_palette(res);
// Save the resulting image. `save_image` is not a part of Quantizr
save_image(pal, out_buffer, out_buffer_length, image_width, image_height);
// Cleanup. Free quantization result, image, and options.
quantizr_free_result(res);
quantizr_free_image(img);
quantizr_free_options(opts);
```
### Using histogram
Sometimes it's necessary to generate a single palette for multiple images like animation frames. In this case, you can use histogram API:
```c
#include "quantizr.h"
uint8_t *image_data;
int32_t image_width;
int32_t image_height;
QuantizrOptions *opts;
QuantizrImage *img;
QuantizrResult *res;
QuantizrPalette *pal;
QuantizrError err;
size_t out_buffer_length = width * height;
uint8_t *out_buffer = (uint8_t*)malloc(out_buffer_length);
// Create new histogram.
// You're responsible for freeing it when the work is done (see below).
QuantizrHistogram *hist = quantizr_create_histogram();
// Load image data and get its dimensions. `load_image` is not a part of Quantizr
load_image(&data, &width, &height);
// Create new image object.
// You're responsible for freeing it when the work is done (see below).
// image_data is unsigned char array with raw RGBA pixels.
img = quantizr_create_image_rgba(image_data, image_width, image_height);
// Add the image to the histogram.
// You can repeat these two steps multiple times to add multiple images to the histogram.
quantizr_histogram_add_image(hist, image);
// Create new Quantizr options.
// You're responsible for freeing it when the work is done (see below).
opts = quantizr_new_options();
// (optional) Set desired number of colors. The default number is 256.
// This function returns QUANTIZR_VALUE_OUT_OF_RANGE if provided number is less than 2 or
// greater than 255.
err = quantizr_set_max_colors(opts, 128);
if (err != QuantizrOk) {
// handle error...
}
// Quantize histogram.
// This function returns quantization result, which you're responsible to free when
// the work is done (see below).
QuantizrResult *res = quantizr_quantize_histogram(hist, opts);
// Set dithering level for the future remapping. The default level is 1.0.
// This function returns QUANTIZR_VALUE_OUT_OF_RANGE if provided level is less than 0.0 or
// greater than 1.0.
err = quantizr_set_dithering_level(res, 0.8);
if (err != QuantizrOk) {
// handle error...
}
// Write quantized image in the provided buffer.
// The buffer should be prealocated and be large enough to fit entire image (width*height bytes).
// This function returns QUANTIZR_BUFFER_TOO_SMALL if the buffer is not large enough.
err = quantizr_remap(res, img, out_buffer, out_buffer_length);
if (err != QuantizrOk) {
// handle error...
}
// Fetch palette from the quantization result.
// Fetched pallette is read-only. You should not modify or free it.
// pal->count is a number of colors in the palette.
// pal->entries is an array of colors.
// pal->entries[i].r, pal->entries[i].g, pal->entries[i].b, and pal->entries[i].a are color channels
// of palette colors.
pal = quantizr_get_palette(res);
// Save the resulting image. `save_image` is not a part of Quantizr
save_image(pal, out_buffer, out_buffer_length, image_width, image_height);
// Cleanup. Free quantization result, image, and options.
quantizr_free_result(res);
quantizr_free_histogram(hist);
quantizr_free_image(img);
quantizr_free_options(opts);
```
## Using with [libvips](https://github.com/libvips/libvips)
libvips 8.13+ has first-class support of Quantizr.
Quantizr 1.3+ can't be used with earlier versions of libvips. If you want to use Quantizr with an earlier version of libvips, use Quantizr 1.2 and follow [the instructions](https://github.com/DarthSim/quantizr/tree/v1.2.0#using-with-libvips).
## Author
Sergey "[DarthSim](https://github.com/DarthSim)" Alexandrovich
## License
Quantizr is licensed under the MIT license.
See LICENSE for the full license text.