Imagequant

https://docs.rs/imagequant
Admin
Imagequant is a Rust library that converts RGBA images to 8-bit indexed color with alpha channel...
Tokens:69,279
Snippets:410
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Imagequant Library Initialization

Source: https://docs.rs/imagequant

This snippet demonstrates how to start the imagequant library by creating a new handle for configuration.

```APIDOC
## Function: new

### Description
Start here: creates new handle for library configuration.

### Method
(Not applicable, this is a library function)

### Endpoint
(Not applicable, this is a library function)

### Parameters
(No specific parameters mentioned for `new` in the provided text)

### Request Example
(Not applicable, this is a library function)

### Response
(No specific response details mentioned for `new` in the provided text)
```

--------------------------------

### imagequant::new

Source: https://docs.rs/imagequant/latest/imagequant

Initializes a new handle for library configuration, serving as the starting point for the quantization process.

```APIDOC
## FUNCTION new

### Description
Creates a new handle for library configuration. This is the entry point for using the imagequant library.

### Returns
- **Attributes** - A handle containing the starting point and settings for the quantization process.
```

--------------------------------

### Implement BuildHasher for U32Hasher

Source: https://docs.rs/imagequant/latest/src/imagequant/hist.rs.html

Provides a deterministic hasher for color hash maps. Requires no setup.

```rust
impl std::hash::BuildHasher for U32Hasher {
    type Hasher = Self;

    #[inline(always)]
    fn build_hasher(&self) -> Self {
        Self(0)
    }
}
```

--------------------------------

### Attributes Struct

Source: https://docs.rs/imagequant/latest/imagequant/struct.Attributes.html

The Attributes struct serves as the starting point and holds the settings for the image quantization process.

```APIDOC
## Struct Attributes

### Description
Starting point and settings for the quantization process.

```rust
pub struct Attributes { /* private fields */ }
```
```

--------------------------------

### Get Dynamic Rows Iterator (Prepared)

Source: https://docs.rs/imagequant/latest/src/imagequant/rows.rs.html

Returns a dynamic iterator over the image rows after ensuring the iterator is prepared. This method calls `prepare_iter` internally. Requires a mutable temporary RGBA row buffer.

```rust
pub fn rows_iter(&mut self, temp_row: &mut [MaybeUninit<RGBA>]) -> Result<DynamicRowsIter<'_, 'pixels, 'rows>, Error> {
        self.prepare_iter(temp_row, true)?;
        Ok(DynamicRowsIter {
            temp_f_row: self.temp_f_row_for_iter()?,
            px: self,
        })
    }
```

--------------------------------

### Get Type ID

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Gets the `TypeId` of the `QuantizationResult` instance. This is part of the `Any` trait implementation.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Get Palette

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Returns a reference to the final palette. It is recommended to get the palette from the `remapped()` call for potentially better results.

```rust
pub fn palette(&mut self) -> &[RGBA]
```

--------------------------------

### Configure ImageQuant Settings and Callbacks

Source: https://docs.rs/imagequant/latest/src/imagequant/lib.rs.html

Shows how to configure speed, quality, and posterization limits, and set custom log and progress callback functions. Callbacks allow for external monitoring and control during quantization.

```rust
let width = 10usize;
let height = 10usize;
let mut fakebitmap = vec![RGBA::new(255, 255, 255, 255); width * height];

fakebitmap[0].r = 0x55;
fakebitmap[0].g = 0x66;
fakebitmap[0].b = 0x77;

// Configure the library
let mut liq = Attributes::new();
liq.set_speed(5).unwrap();
liq.set_quality(70, 99).unwrap();
liq.set_min_posterization(1).unwrap();
assert_eq!(1, liq.min_posterization());
liq.set_min_posterization(0).unwrap();

use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering::SeqCst;
use std::sync::Arc;

let log_called = Arc::new(AtomicBool::new(false));
let log_called2 = log_called.clone();
liq.set_log_callback(move |_attr, _msg| {
    log_called2.store(true, SeqCst);
});

let prog_called = Arc::new(AtomicBool::new(false));
let prog_called2 = prog_called.clone();
liq.set_progress_callback(move |_perc| {
    prog_called2.store(true, SeqCst);
    ControlFlow::Continue
});

// Describe the bitmap
let img = &mut liq.new_image(&fakebitmap[..], width, height, 0.0).unwrap();

// The magic happens in quantize()
let mut res = match liq.quantize(img) {
```

--------------------------------

### Get Final Palette as Vec

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Returns a `Vec<RGBA>` copy of the final palette. It's generally more efficient to get the palette directly from the `remapped()` call if possible.

```rust
pub fn palette_vec(&mut self) -> Vec<RGBA> {
        let pal = self.palette();
        let mut out: Vec<RGBA> = Vec::new();
        if out.try_reserve_exact(pal.len()).is_ok() {
            out.extend_from_slice(pal);
        }
        out
    }
```

--------------------------------

### Initialize imagequant configuration

Source: https://docs.rs/imagequant/latest/imagequant/fn.new.html

Creates a new handle for library configuration. Returns an Attributes instance.

```rust
pub fn new() -> Attributes
```

--------------------------------

### Get Image Height

Source: https://docs.rs/imagequant/latest/imagequant/struct.Image.html

Returns the height of the image in pixels.

```rust
pub const fn height(&self) -> usize
```

--------------------------------

### Retrieve Basic Configuration Settings

Source: https://docs.rs/imagequant/latest/src/imagequant/attr.rs.html

Simple getters for speed and maximum color count settings.

```rust
pub fn speed(&self) -> u32 {
        self.speed.into()
    }
```

```rust
pub fn max_colors(&self) -> u32 {
        self.max_colors.into()
    }
```

--------------------------------

### Get Image Width

Source: https://docs.rs/imagequant/latest/imagequant/struct.Image.html

Returns the width of the image in pixels.

```rust
pub const fn width(&self) -> usize
```

--------------------------------

### Get row count

Source: https://docs.rs/imagequant/latest/src/imagequant/seacow.rs.html

Returns the number of rows currently managed by the structure.

```rust
#[must_use]
    pub(crate) fn len(&mut self) -> usize {
        self.rows.borrow_mut().len()
    }
```

--------------------------------

### Configuration and Utility Methods

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Methods for managing progress callbacks, palette information, and quantization attributes.

```APIDOC
## set_progress_callback

### Description
Sets a callback function to track progress during processing.

### Parameters
- **callback** (Fn(f32) -> ControlFlow) - Required - Callback function that receives progress percentage.

## palette_vec

### Description
Returns a copy of the final palette.

### Response
- **Vec<RGBA>** - The palette colors.

## from_palette

### Description
Creates a quantization result from a fixed palette.

### Parameters
- **attr** (&Attributes) - Required - Quantization attributes.
- **palette** (&[RGBA]) - Required - The source palette.
- **gamma** (f64) - Required - Gamma value (0. for sRGB).

### Response
- **Result<Self, Error>** - Returns the initialized quantization result.
```

--------------------------------

### GET /quantization_quality

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Retrieves the estimated quality of the input image after remapping to the current palette.

```APIDOC
## GET /quantization_quality

### Description
Returns a number between 0-100 guessing how nice the input image will look if remapped to the current palette.

### Method
GET

### Response
#### Success Response (200)
- **quality** (u8) - Quality score (0-100).
```

--------------------------------

### Initialize ImageQuant Library

Source: https://docs.rs/imagequant/latest/src/imagequant/lib.rs.html

Creates a new handle for library configuration. Use this to set various parameters before processing images.

```rust
pub fn new() -> Attributes {
    Attributes::new()
}
```

--------------------------------

### Create Image Instances

Source: https://docs.rs/imagequant/latest/src/imagequant/image.rs.html

Methods for initializing an Image from various pixel sources including owned data, borrowed slices, and custom conversion functions.

```rust
    #[inline(always)]
    pub fn new<VecRGBA>(attr: &Attributes, pixels: VecRGBA, width: usize, height: usize, gamma: f64) -> Result<Self, Error> where VecRGBA: Into<Box<[RGBA]>> {
        Self::new_stride(attr, pixels, width, height, width, gamma)
    }
```

```rust
    #[inline(always)]
    pub fn new_borrowed(attr: &Attributes, pixels: &'pixels [RGBA], width: usize, height: usize, gamma: f64) -> Result<Self, Error> {
        Self::new_stride_borrowed(attr, pixels, width, height, width, gamma)
    }
```

```rust
    pub unsafe fn new_fn<F: 'pixels + Fn(&mut [MaybeUninit<RGBA>], usize) + Send + Sync>(attr: &Attributes, convert_row_fn: F, width: usize, height: usize, gamma: f64) -> Result<Self, Error> {
        let width = width.try_into().map_err(|_| ValueOutOfRange)?;
        let height = height.try_into().map_err(|_| ValueOutOfRange)?;
        Image::new_internal(attr, PixelsSource::Callback(Box::new(convert_row_fn)), width, height, gamma)
    }
```

--------------------------------

### Get Dithering Level

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Retrieves the dithering level previously set using `set_dithering_level`.

```rust
pub fn dithering_level(&self) -> f32
```

--------------------------------

### Get Quantization Error

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Returns the approximate mean square error of the palette used during quantization.

```rust
pub fn quantization_error(&self) -> Option<f64>
```

--------------------------------

### Configure Posterization and Quality Settings

Source: https://docs.rs/imagequant/latest/src/imagequant/attr.rs.html

Methods to set and retrieve the minimum posterization level and retrieve current quality settings.

```rust
pub fn set_min_posterization(&mut self, value: u8) -> Result<(), Error> {
        if !(0..=4).contains(&value) {
            return Err(Error::ValueOutOfRange);
        }
        self.min_posterization_output = value;
        Ok(())
    }
```

```rust
pub fn min_posterization(&self) -> u8 {
        self.min_posterization_output
    }
```

```rust
pub fn quality(&self) -> (u8, u8) {
        (
            self.max_mse.map_or(0, mse_to_quality),
            mse_to_quality(self.target_mse),
        )
    }
```

--------------------------------

### Image Struct Methods

Source: https://docs.rs/imagequant/latest/imagequant/struct.Image.html

Methods for initializing and configuring an Image instance for the imagequant library.

```APIDOC
## Image Struct Methods

### Description
Methods to create and configure an Image object, which holds pixel data and metadata for quantization.

### Methods
- **new**: Creates an image from RGBA pixels by copying them into an internal buffer.
- **new_borrowed**: Creates an image from a slice of RGBA pixels without copying.
- **new_fn**: Generates rows on demand using a callback function (unsafe).
- **set_importance_map**: Sets a map defining pixel importance for palette allocation.
- **set_background**: Remaps pixels based on a background image.
- **add_fixed_color**: Reserves a specific color in the output palette.
- **width**: Returns the image width.
- **height**: Returns the image height.
- **new_stride_borrowed**: Creates an image from a slice with a custom stride.
- **new_stride**: Creates a self-contained image from pixels with a custom stride.

### Parameters
- **attr** (Attributes) - Required - The library attributes.
- **pixels** (VecRGBA/&[RGBA]) - Required - The pixel data.
- **width** (usize) - Required - Image width in pixels.
- **height** (usize) - Required - Image height in pixels.
- **gamma** (f64) - Required - Gamma correction value (use 0. for sRGB).
- **stride** (usize) - Required - Stride in pixels.

### Response
- **Result<Self, Error>** - Returns the initialized Image instance or an error.
```

--------------------------------

### Configuration Methods

Source: https://docs.rs/imagequant/latest/src/imagequant/attr.rs.html

Methods for configuring image quantization parameters such as quality, speed, and posterization.

```APIDOC
## Configuration Methods

### `set_quality`

Sets the quality and speed trade-off.

### Method

`POST`

### Endpoint

`/config/quality`

### Parameters

#### Request Body

- **value** (u8) - Required - The quality setting.

### Request Example

```json
{
  "value": 5
}
```

### Response

#### Success Response (200)

- **message** (string) - Success message.

#### Response Example

```json
{
  "message": "Quality set successfully."
}
```

## `set_min_posterization`

Sets the minimum posterization level.

### Method

`POST`

### Endpoint

`/config/min_posterization`

### Parameters

#### Request Body

- **value** (u8) - Required - The minimum posterization value (0-4).

### Request Example

```json
{
  "value": 2
}
```

### Response

#### Success Response (200)

- **message** (string) - Success message.

#### Response Example

```json
{
  "message": "Minimum posterization set successfully."
}
```

## `speed`

Returns the current speed setting.

### Method

`GET`

### Endpoint

`/config/speed`

### Response

#### Success Response (200)

- **speed** (u32) - The current speed setting.

#### Response Example

```json
{
  "speed": 5
}
```

## `max_colors`

Returns the maximum number of colors set.

### Method

`GET`

### Endpoint

`/config/max_colors`

### Response

#### Success Response (200)

- **max_colors** (u32) - The maximum number of colors.

#### Response Example

```json
{
  "max_colors": 256
}
```

## `quality`

Returns the current quality settings.

### Method

`GET`

### Endpoint

`/config/quality`

### Response

#### Success Response (200)

- **quality** (tuple of u8) - A tuple representing the quality settings.

#### Response Example

```json
{
  "quality": [8, 8]
}
```
```

--------------------------------

### Callback Configuration

Source: https://docs.rs/imagequant/latest/imagequant/struct.Attributes.html

Methods for setting up custom callbacks for logging, flushing, and progress reporting.

```APIDOC
### pub fn set_log_callback<F: Fn(&Self, &str) + Send + Sync + 'static>( &mut self, callback: F, )

Set callback function to be called every time the library wants to print a message.

To share data with the callback, use `Arc` or `Atomic*` types and `move ||` closures.
```

```APIDOC
### pub fn set_log_flush_callback<F: Fn(&Self) + Send + Sync + 'static>( &mut self, callback: F, )

Callback for flushing output (if you buffer messages, that’s the time to flush those buffers).
```

```APIDOC
### pub fn set_progress_callback<F: Fn(f32) -> ControlFlow + Send + Sync + 'static>( &mut self, callback: F, )

Set callback function to be called every time the library makes a progress. It can be used to cancel operation early.

To share data with the callback, use `Arc` or `Atomic*` types and `move ||` closures.
```

--------------------------------

### Callback Methods

Source: https://docs.rs/imagequant/latest/src/imagequant/attr.rs.html

Methods for setting up callback functions for logging, flushing logs, and progress updates.

```APIDOC
## Callback Methods

### `set_log_callback`

Sets a callback function to be called when the library logs a message.

### Method

`POST`

### Endpoint

`/callbacks/log`

### Parameters

#### Request Body

- **callback** (function) - Required - The callback function to execute. It takes the library instance and a message string as arguments.

### Request Example

```json
{
  "callback": "function(instance, message) { console.log(message); }"
}
```

### Response

#### Success Response (200)

- **message** (string) - Success message.

#### Response Example

```json
{
  "message": "Log callback set successfully."
}
```

## `set_log_flush_callback`

Sets a callback function to be called when log messages need to be flushed.

### Method

`POST`

### Endpoint

`/callbacks/log_flush`

### Parameters

#### Request Body

- **callback** (function) - Required - The callback function to execute. It takes the library instance as an argument.

### Request Example

```json
{
  "callback": "function(instance) { console.log('Flushing logs...'); }"
}
```

### Response

#### Success Response (200)

- **message** (string) - Success message.

#### Response Example

```json
{
  "message": "Log flush callback set successfully."
}
```

## `set_progress_callback`

Sets a callback function to be called to report progress.

### Method

`POST`

### Endpoint

`/callbacks/progress`

### Parameters

#### Request Body

- **callback** (function) - Required - The callback function to execute. It takes a float representing the progress (0.0 to 1.0) and returns a `ControlFlow` enum to indicate whether to continue or cancel the operation.

### Request Example

```json
{
  "callback": "function(progress) { if (progress > 0.9) return 'Cancel'; return 'Continue'; }"
}
```

### Response

#### Success Response (200)

- **message** (string) - Success message.

#### Response Example

```json
{
  "message": "Progress callback set successfully."
}
```
```

--------------------------------

### Get Palette Length

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Returns the expected length of the palette without finalizing the colors. This can be used to pre-allocate buffers.

```rust
pub fn palette_len(&mut self) -> usize {
        self.palette.len()
    }
```

--------------------------------

### Dithering Preparation

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Optional method to prepare for dithering, useful for parallelization when setting background images.

```rust
pub fn optionally_prepare_for_dithering_with_background_set(&mut self, image: &mut Image<'_>, output_buf: &mut [MaybeUninit<PalIndexRemap>]) -> Result<(), Error> {
        let mut output_pixels = RowBitmapMut::new_contiguous(output_buf, image.width());
        Self::optionally_generate_dither_map(self.use_dither_map, image, true, &mut output_pixels, &mut self.palette)?;
        Ok(())
    }
```

--------------------------------

### Get Height in Rust

Source: https://docs.rs/imagequant/latest/src/imagequant/rows.rs.html

Returns the height of the image as a `usize`. This is a constant function, meaning it can be evaluated at compile time.

```rust
pub const fn height(&self) -> usize {
        self.height as usize
    }
```

--------------------------------

### Attributes Initialization

Source: https://docs.rs/imagequant/latest/imagequant/struct.Attributes.html

Methods for creating new instances of Attributes and initializing images.

```APIDOC
## impl Attributes

### pub fn new() -> Self

New handle for library configuration.
See also `Attributes::new_image()`.
```

```APIDOC
### pub fn new_image<VecRGBA>( &self, pixels: VecRGBA, width: usize, height: usize, gamma: f64, ) -> Result<Image<'static>, Error>
where VecRGBA: Into<Box<[RGBA]>>,

Make an image from RGBA pixels.

The `pixels` argument can be `Vec<RGBA>`, or `Box<[RGBA]>` or `&[RGBA]`. See `Attributes::new_image_borrowed` for a non-copying alternative.

Use 0.0 for gamma if the image is sRGB (most images are).
```

```APIDOC
### pub fn new_image_borrowed<'pixels>( &self, bitmap: &'pixels [RGBA], width: usize, height: usize, gamma: f64, ) -> Result<Image<'pixels>, Error>

Describe dimensions of a slice of RGBA pixels.

Use 0.0 for gamma if the image is sRGB (most images are).
```

```APIDOC
### pub fn new_image_stride<VecRGBA>( &self, pixels: VecRGBA, width: usize, height: usize, stride: usize, gamma: f64, ) -> Result<Image<'static>, Error>
where VecRGBA: Into<Box<[RGBA]>>,

Like `new_image_stride_borrowed`, but makes a copy of the pixels.

The `pixels` argument can be `Vec<RGBA>`, or `Box<[RGBA]>` or `&[RGBA]`.
```

--------------------------------

### Get Width in Rust

Source: https://docs.rs/imagequant/latest/src/imagequant/rows.rs.html

Returns the width of the image as a `usize`. This is a constant function, meaning it can be evaluated at compile time.

```rust
pub const fn width(&self) -> usize {
        self.width as usize
    }
```

--------------------------------

### QuantizationResult::new

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Constructor for QuantizationResult, performing the core quantization logic.

```APIDOC
## QuantizationResult::new

### Description
Constructor for QuantizationResult, performing the core quantization logic.

### Method
`QuantizationResult::new(attr: &Attributes, hist: HistogramInternal, freeze_result_colors: bool, gamma: f64) -> Result<Self, Error>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **QuantizationResult** (Self) - The newly created QuantizationResult object.

#### Response Example
None

### Errors
- **Aborted**: If the operation is aborted due to progress callback.
- **QualityTooLow**: If the image degradation exceeds the allowed limit.
```

--------------------------------

### Function new

Source: https://docs.rs/imagequant/latest/imagequant/fn.new.html

Creates a new handle for library configuration.

```APIDOC
## new

### Description
Creates a new handle for library configuration.

### Method
Rust Function

### Endpoint
imagequant::new()

### Response
- **Attributes** (struct) - A new handle for library configuration.
```

--------------------------------

### Get Remapping Error

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Returns the approximate mean square error of the palette used for the most recent remapping operation.

```rust
pub fn remapping_error(&self) -> Option<f64>
```

--------------------------------

### Initialize MedianCutter

Source: https://docs.rs/imagequant/latest/src/imagequant/mediancut.rs.html

Sets up the MedianCutter with initial boxes and histogram data. Requires a mutable slice of HistItem and the total perceptual weight of the histogram.

```rust
struct MedianCutter<'hist> {
    boxes: Vec<MBox<'hist>>,
    hist_total_perceptual_weight: f64,
    target_colors: PalLen,
}

```

--------------------------------

### Get the palette popularity values as a slice

Source: https://docs.rs/imagequant/latest/src/imagequant/pal.rs.html

Provides immutable access to the array of popularity values associated with each color in the palette.

```rust
pub fn pop_as_slice(&self) -> &[PalPop] {
        &self.pops
    }
```

--------------------------------

### Get Expected Palette Length

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Returns the expected number of colors in the palette without finalizing the colors. This reads the length.

```rust
pub fn palette_len(&mut self) -> usize
```

--------------------------------

### QuantizationResult Initialization

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Internal constructor for creating a new QuantizationResult, handling palette finding and error validation.

```rust
pub(crate) fn new(attr: &Attributes, hist: HistogramInternal, freeze_result_colors: bool, gamma: f64) -> Result<Self, Error> {
        if attr.progress(f32::from(attr.progress_stage1)) { return Err(Aborted); }
        let (max_mse, target_mse, target_mse_is_zero) = attr.target_mse(hist.items.len());
        let (mut palette, palette_error) = find_best_palette(attr, target_mse, target_mse_is_zero, max_mse, hist)?;
        if freeze_result_colors {
            palette.iter_mut().for_each(|(_, p)| *p = p.to_fixed());
        }
        if attr.progress(f32::from(attr.progress_stage3).mul_add(0.95, f32::from(attr.progress_stage1) + f32::from(attr.progress_stage2))) {
            return Err(Aborted);
        }
        if let (Some(palette_error), Some(max_mse)) = (palette_error, max_mse) {
            if palette_error > max_mse {
                attr.verbose_print(format!(
                    "  image degradation MSE={:0.3} (Q={}) exceeded limit of {:0.3} ({})",
                    mse_to_standard_mse(palette_error),
                    mse_to_quality(palette_error),
                    mse_to_standard_mse(max_mse),
                    mse_to_quality(max_mse)
                ));
                return Err(QualityTooLow);
            }
        }

        sort_palette(attr, &mut palette);

        Ok(Self {
            palette,
            gamma,
            palette_error,
            min_posterization_output: attr.min_posterization(),
            use_dither_map: attr.use_dither_map,
            remapped: None,
            progress_callback: None,
            int_palette: Palette {
                count: 0,
                entries: [RGBA::default(); MAX_COLORS],
            },
            dither_level: 1.,
            single_threaded_dithering: attr.single_threaded_dithering,
        })
    }
```

--------------------------------

### Get the palette colors as a slice

Source: https://docs.rs/imagequant/latest/src/imagequant/pal.rs.html

Provides immutable access to the array of colors in the palette. This is useful for iterating or reading color data.

```rust
pub fn as_slice(&self) -> &[f_pixel] {
        &self.colors
    }
```

--------------------------------

### Median Cut Entry Point

Source: https://docs.rs/imagequant/latest/src/imagequant/mediancut.rs.html

Public interface for initiating the median cut process on a histogram.

```rust
#[inline(never)]
pub(crate) fn mediancut(hist: &mut HistogramInternal, target_colors: PalLen, target_mse: f64, max_mse_per_color: f64) -> Result<PalF, Error> {
    Ok(MedianCutter::new(hist, target_colors)?.cut(target_mse, max_mse_per_color))
}
```

--------------------------------

### Get the popularity value from PalPop

Source: https://docs.rs/imagequant/latest/src/imagequant/pal.rs.html

Retrieves the absolute popularity value from a PalPop. This is useful for sorting or comparing colors based on their frequency.

```rust
pub fn popularity(self) -> f32 {
        self.0.abs()
    }
```

--------------------------------

### Create RGBA Pixel

Source: https://docs.rs/imagequant/latest/imagequant/type.RGBA.html

Demonstrates how to instantiate a new RGBA pixel using struct literal syntax.

```rust
use rgb::Rgba;

let pixel = Rgba {r : red, g : green, b : blue, a : alpha};
```

--------------------------------

### Get Palette as Vec

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Returns a copy of the final palette as a `Vec<RGBA>`. It is generally better to obtain the palette from the `remapped()` call.

```rust
pub fn palette_vec(&mut self) -> Vec<RGBA>
```

--------------------------------

### Histogram Quantization

Source: https://docs.rs/imagequant/latest/src/imagequant/lib.rs.html

Demonstrates creating a histogram, adding images and color entries, and then quantizing to generate a palette. This is a core part of the color reduction process.

```rust
let attr = Attributes::new();
let mut hist = Histogram::new(&attr);

let bitmap1 = [RGBA { r: 0, g: 0, b: 0, a: 0 }; 1];
let mut image1 = attr.new_image(&bitmap1[..], 1, 1, 0.0).unwrap();
hist.add_image(&attr, &mut image1).unwrap();

let bitmap2 = [RGBA { r: 255, g: 255, b: 255, a: 255 }; 1];
let mut image2 = attr.new_image(&bitmap2[..], 1, 1, 0.0).unwrap();
hist.add_image(&attr, &mut image2).unwrap();

hist.add_colors(&[HistogramEntry {
    color: RGBA::new(255, 128, 255, 128),
    count: 10,
}], 0.0).unwrap();

let mut res = hist.quantize(&attr).unwrap();
let pal = res.palette();
assert_eq!(3, pal.len());
```

--------------------------------

### Image::new

Source: https://docs.rs/imagequant/latest/src/imagequant/image.rs.html

Creates a new Image instance from owned RGBA pixels.

```APIDOC
## Image::new

### Description
Creates an image from owned RGBA pixels. The pixels are copied into the library's internal format.

### Parameters
- **attr** (Attributes) - Required - Library attributes.
- **pixels** (VecRGBA) - Required - The pixel data as a vector or box.
- **width** (usize) - Required - Image width.
- **height** (usize) - Required - Image height.
- **gamma** (f64) - Required - Gamma value (use 0. for sRGB).

### Response
- **Result<Self, Error>** - Returns the initialized Image or an error if parameters are invalid.
```

--------------------------------

### Get Remapping Quality

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Returns the palette remapping error mapped to a 0-100 scale, similar to the scale used in `Attributes::set_quality()`.

```rust
pub fn remapping_quality(&self) -> Option<u8>
```

--------------------------------

### imagequant Library Overview

Source: https://docs.rs/imagequant/latest/imagequant/index.html

Overview of the core structures and functions available in the imagequant crate for image processing.

```APIDOC
## imagequant Library

### Description
The imagequant library converts RGBA images to 8-bit with alpha channel. It provides a structured approach to quantization using attributes, histograms, and image descriptors.

### Core Structs
- **Attributes**: Starting point and settings for the quantization process.
- **Histogram**: Used to generate one shared palette for multiple images.
- **HistogramEntry**: Represents the number of pixels in a given color for `Histogram::add_colors()`.
- **Image**: Describes image dimensions and pixels for the library.
- **QuantizationResult**: The remapping step, computed from `Attributes::quantize()`.

### Core Enums
- **ControlFlow**: Result of callback in `Attributes::set_progress_callback`.
- **Error**: Error codes for library operations.

### Functions
- **new**: Creates a new handle for library configuration.

### Type Aliases
- **RGBA**: 8-bit RGBA in sRGB. This is the only color format publicly used by the library.
```

--------------------------------

### Get Output Gamma

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Retrieves the approximate gamma correction value used for the output. Colors are converted from input gamma to this gamma.

```rust
pub fn output_gamma(&self) -> f64
```

--------------------------------

### Imagequant Crate Overview

Source: https://docs.rs/imagequant/latest/index.html

This section provides an overview of the imagequant crate, its purpose, and key components.

```APIDOC
## Crate imagequant

**Summary**
Converts RGBA images to 8-bit with alpha channel.
See `examples/` directory for example code.

## Structs

- **Attributes**: Starting point and settings for the quantization process.
- **Histogram**: Generate one shared palette for multiple images.
- **HistogramEntry**: Number of pixels in a given color for `Histogram::add_colors()`.
- **Image**: Describes image dimensions and pixels for the library.
- **QuantizationResult**: Remapping step, computed from `Attributes::quantize()`.

## Enums

- **ControlFlow**: Result of callback in `Attributes::set_progress_callback`.
- **Error**: Error codes.

## Functions

- **new**: Start here: creates new handle for library configuration.

## Type Aliases

- **RGBA**: 8-bit RGBA in sRGB. This is the only color format _publicly_ used by the library.
```

--------------------------------

### Get Image Gamma

Source: https://docs.rs/imagequant/latest/src/imagequant/image.rs.html

Returns the gamma value of the image if it's positive, otherwise returns None. Uses inline always optimization.

```rust
pub(crate) fn gamma(&self) -> Option<f64> {
        if self.px.gamma > 0. { Some(self.px.gamma) } else { None }
    }
```

--------------------------------

### Get Quantization Quality

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

Returns an estimated quality score (0-100) indicating how well the input image will appear after remapping to the current palette.

```rust
pub fn quantization_quality(&self) -> Option<u8>
```

--------------------------------

### Create Image Objects

Source: https://docs.rs/imagequant/latest/src/imagequant/attr.rs.html

Methods to initialize image objects from borrowed or owned pixel data.

```rust
pub fn new_image_borrowed<'pixels>(&self, bitmap: &'pixels [RGBA], width: usize, height: usize, gamma: f64) -> Result<Image<'pixels>, Error> {
        Image::new_borrowed(self, bitmap, width, height, gamma)
    }
```

```rust
pub fn new_image_stride<VecRGBA>(&self, pixels: VecRGBA, width: usize, height: usize, stride: usize, gamma: f64) -> Result<Image<'static>, Error> where VecRGBA: Into<Box<[RGBA]>> {
        Image::new_stride(self, pixels, width, height, stride, gamma)
    }
```

```rust
pub fn new_image_stride_copy(&self, bitmap: &[RGBA], width: usize, height: usize, stride: usize, gamma: f64) -> Result<Image<'static>, Error> {
        self.new_image_stride(bitmap, width, height, stride, gamma)
    }
```

--------------------------------

### Get Final Palette

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Provides access to the final palette used for remapping. It is recommended to obtain the palette from the `remapped()` call for potentially better results.

```rust
#[inline]
    #[must_use]
    pub fn palette(&mut self) -> &[RGBA] {
        self.int_palette().as_slice()
    }
```

--------------------------------

### MedianCutter Initialization and Error Management

Source: https://docs.rs/imagequant/latest/src/imagequant/mediancut.rs.html

Methods for initializing the MedianCutter structure and calculating error thresholds for color quantization.

```rust
fn total_box_error_below_target(&mut self, mut target_mse: f64) -> bool {
        target_mse *= self.hist_total_perceptual_weight;
        let mut total_error = self.boxes.iter().filter_map(|mb| mb.total_error).sum::<f64>();
        if total_error > target_mse {
            return false;
        }
        for mb in self.boxes.iter_mut().filter(|mb| mb.total_error.is_none()) {
            total_error += mb.compute_total_error();
            if total_error > target_mse {
                return false;
            }
        }
        true
    }
```

```rust
pub fn new(hist: &'hist mut HistogramInternal, target_colors: PalLen) -> Result<Self, Error> {
        let hist_total_perceptual_weight = hist.total_perceptual_weight;

        debug_assert!(hist.clusters[0].begin == 0);
        debug_assert!(hist.clusters.last().unwrap().end as usize == hist.items.len());

        let mut hist_items = &mut hist.items[..];
        let mut boxes = Vec::new();
        boxes.try_reserve(target_colors as usize)?;

        let used_boxes = hist.clusters.iter().filter(|b| b.begin != b.end).count();
        if used_boxes <= target_colors as usize / 3 {
            // boxes are guaranteed to be sorted
            let mut prev_end = 0;
            for b in hist.clusters.iter().filter(|b| b.begin != b.end) {
                let begin = b.begin as usize;
                debug_assert_eq!(begin, prev_end);
                let end = b.end as usize;
                prev_end = end;
                let (this_box, rest) = hist_items.split_at_mut(end - begin);
                hist_items = rest;
                boxes.push_in_cap(MBox::new(this_box));
            }
        } else {
            boxes.push_in_cap(MBox::new(hist_items));
        }

        Ok(Self {
            boxes,
            hist_total_perceptual_weight,
            target_colors,
        })
    }
```

```rust
fn into_palette(mut self) -> PalF {
        let mut palette = PalF::new();

        for (i, mbox) in self.boxes.iter_mut().enumerate() {
            mbox.colors.iter_mut().for_each(move |a| a.tmp.likely_palette_index = i as _);

            // store total color popularity (perceptual_weight is approximation of it)
```

--------------------------------

### Get Remapping Quality

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Returns the quality score (0-100) of the most recent palette remapping, based on the palette error. This is equivalent to the scale used in `Attributes::set_quality()`.

```rust
#[must_use]
    pub fn remapping_quality(&self) -> Option<u8> {
        self.remapped.as_ref()
            .and_then(|re| re.palette_error)
            .or(self.palette_error)
            .map(mse_to_quality)
    }
```

--------------------------------

### QuantizationResult::optionally_prepare_for_dithering_with_background_set

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Optionally prepares the image for dithering, especially when a background is set.

```APIDOC
## QuantizationResult::optionally_prepare_for_dithering_with_background_set

### Description
Optionally prepares the image for dithering, especially when a background is set. This can allow for better parallelization.

### Method
`optionally_prepare_for_dithering_with_background_set(&mut self, image: &mut Image<'_>, output_buf: &mut [MaybeUninit<PalIndexRemap>]) -> Result<(), Error>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **()**: Indicates successful preparation.

#### Response Example
None

### Errors
- **Error**: Any error encountered during the preparation process.
```

--------------------------------

### Create QuantizationResult from Palette

Source: https://docs.rs/imagequant/latest/imagequant/struct.QuantizationResult.html

A shortcut for creating a `Histogram` with `add_fixed_color`. Set `gamma` to `0.` for sRGB colors.

```rust
pub fn from_palette( attr: &Attributes, palette: &[RGBA], gamma: f64, ) -> Result<Self, Error>
```

--------------------------------

### Get Quantization Quality

Source: https://docs.rs/imagequant/latest/src/imagequant/quant.rs.html

Returns the quantization quality as a number from 0-100, estimating how the input image will look when remapped to the current palette. This is derived from the palette error.

```rust
#[must_use]
    pub fn quantization_quality(&self) -> Option<u8> {
        self.palette_error.map(mse_to_quality)
    }
```

--------------------------------

### Get Posterize Bits

Source: https://docs.rs/imagequant/latest/src/imagequant/attr.rs.html

Returns the effective number of posterization bits, which is the maximum of the minimum input and output posterization bits. This determines the color depth after quantization.

```rust
pub(crate) fn posterize_bits(&self) -> u8 {
        self.min_posterization_output.max(self.min_posterization_input)
    }
```

--------------------------------

### Initialize Floyd-Steinberg Dithering with Dither Map

Source: https://docs.rs/imagequant/latest/src/imagequant/remap.rs.html

Initializes the Floyd-Steinberg dithering process, optionally using a dither map to apply dithering only to flat areas. It prepares necessary buffers and structures for pixel processing.

```rust
let progress_stage1 = if quant.use_dither_map != DitherMapMode::None { 20 } else { 0 };

    let width = input_image.width();
    let height = input_image.height();

    let mut temp_row = temp_buf(width)?;

    let dither_map = if quant.use_dither_map != DitherMapMode::None {
        input_image.dither_map.as_deref().or(input_image.edges.as_deref()).unwrap_or(&[])
    } else {
        &[]
    };

    let n = Nearest::new(palette)?;
    let palette = palette.as_slice();

    let mut background = input_image.background.as_mut().map(|bg| {
        bg.px.prepare_iter(&mut temp_row, true)?;
        Ok::<_, Error>(&bg.px)
    }).transpose()?;

    let transparent_index = if background.is_some() { n.search(&f_pixel::default(), 0).0 as PalIndexRemap } else { 0 };
    if background.is_some() && palette[transparent_index as usize].a > MIN_OPAQUE_A {
        background = None;
    }
    // response to this value is non-linear and without it any value < 0.8 would give almost no dithering
    let mut base_dithering_level = (1. - quant.dither_level).mul_add(-(1. - quant.dither_level), 1.) * (15. / 16.); // prevent small errors from accumulating
    if !dither_map.is_empty() {
        base_dithering_level *= 1. / 255.; // dither_map is in 0-255 scale
    }

    // when using remapping on top of a background, lots of pixels may be transparent, making poor guesses
    // (guesses are only for speed, don't affect visuals)
    let guess_from_remapped_pixels = output_image_is_remapped && background.is_none();

    input_image.px.prepare_iter(&mut temp_row, true)?;
    let input_image_px = &input_image.px;
    let n = &n;

    // Chunks have overhead, so should be big (more than 2 bring diminishing results). Chunks risk causing seams, so should be tall.
    let num_chunks = if quant.single_threaded_dithering { 1 } else { (width * height / 524_288).min(height / 128).max(if height > 128 {2} else {1}).min(num_cpus()) };
    let chunks = output_pixels.chunks((height + num_chunks - 1) / num_chunks).map(CacheLineAlign);
    scope(move |s| {
        let mut chunk_start_row = 0;
        for mut chunk in chunks {
            let chunk_len = chunk.0.len();
            let mut temp_row = temp_buf(width)?;
            let mut input_image_iter = input_image_px.rows_iter_prepared()?;
            let mut background = background.map(|bg| bg.rows_iter_prepared()).transpose()?;
            let mut diffusion = Vec::new();
            let errwidth = width + 2; // +2 saves from checking out of bounds access
            diffusion.try_reserve_exact(errwidth * 2)?;
            diffusion.resize(errwidth * 2, f_pixel::default());

            // restart of dithering creates a seam. this does redundant work to init diffusion state,
            // so that later chunks don't start from scratch
            if chunk_start_row > 2 {
                let mut discard_row = temp_buf(width)?;
                for row in (chunk_start_row - 2) .. chunk_start_row {
                    let row_pixels = input_image_iter.row_f(&mut temp_row, row as _);
                    let bg_pixels = background.as_mut().map(|b| b.row_f(&mut temp_row, row as _)).unwrap_or(&[]);

```
Tokens:
Raw