Quantizr

将RGBA图像转换为8位调色板图像的快速库。用Rust编写；可在C程序中使用。

Rust中使用

添加到Cargo.toml

[dependencies]
quantizr = "1.4.0"

有关库API文档，请参阅docs.rs。还可以查看示例代码目录。

C中使用

安装

Quantizr是用Rust编写的，因此您需要先安装它。还需要cargo-c。然后只需运行

cargo cinstall --release

用法

#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);

使用直方图

有时需要为多个图像（如动画帧）生成单个调色板。在这种情况下，您可以使用直方图API

#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);

与libvips一起使用

libvips 8.13+ 首先支持Quantizr。

Quantizr 1.3+ 不能与libvips的早期版本一起使用。如果您想使用Quantizr与libvips的早期版本一起使用，请使用Quantizr 1.2并遵循说明。

作者

Sergey "DarthSim" Alexandrovich

许可证

Quantizr受MIT许可证的许可。

请参阅LICENSE以获取完整的许可证文本。