Struct IndexedImage 

pub struct IndexedImage<Color, Index = u8> { /* private fields */ }

An image represented as a palette of colors and a series of indices into that palette.

This type consists of a width, a height, a palette buffer, and an indices buffer. The indices buffer is in row-major order where each index corresponds to one pixel and references one of the palette colors. The length of the indices Vec is guaranteed to match width * height and be less than or equal to MAX_PIXELS.

The default index type is u8, but may also be u16 or u32. Note that u16 or u32 may not be fully supported by other functions throughout the crate.

Examples

Directly creating an IndexedImage from a Vec of palette colors and indices:

let (width, height) = (512, 512);
let palette = vec![Srgb::new(0, 0, 0)];
let indices = vec![0; (width * height) as usize];
let image = IndexedImage::new(width, height, palette, indices)?;

Implementations

impl<Color, Index: BoundedIndex> IndexedImage<Color, Index>

pub fn new( width: u32, height: u32, palette: Vec<Color>, indices: Vec<Index>, ) -> Result<Self, CreateIndexedImageError<Color, Index>>

Create a new IndexedImage from a palette of colors and indices into the palette.

Errors

The provided palette and indices are returned as an Err if any of the following are true:

• The length of indices and width * height do not match.
• width * height overflows a u32.

Note that this function does not validate that all indices in indices are less than palette.len().

pub fn dimensions(&self) -> (u32, u32)

Returns the width and height of the IndexedImage.

pub fn width(&self) -> u32

Returns the width the IndexedImage.

pub fn height(&self) -> u32

Returns the height of the IndexedImage.

pub fn is_empty(&self) -> bool

Returns whether the IndexedImage has zero pixels.

pub fn num_pixels(&self) -> u32

Returns the number of pixels in the IndexedImage specified by width * height.

pub fn palette(&self) -> &[Color]

Returns a slice of the palette colors of the IndexedImage.

pub fn palette_mut(&mut self) -> &mut [Color]

Returns a mutable slice of the palette colors of the IndexedImage.

pub fn indices(&self) -> &[Index]

Returns a slice of the indices of the IndexedImage.

pub fn indices_mut(&mut self) -> &mut [Index]

Returns a mutable slice of the indices of the IndexedImage.

pub fn into_parts(self) -> (Vec<Color>, Vec<Index>)

Consume an IndexedImage and return the inner palette Vec and indices Vec.

pub fn to_larger_indices<NewIndex>(&self) -> IndexedImage<Color, NewIndex>

where Color: Clone, NewIndex: BoundedIndex, Index: Into<NewIndex>,

Create a new IndexedImage with a larger index type.

See also into_larger_indices for a consuming variant that does not need to clone the palette.

pub fn to_smaller_indices<NewIndex>( &self, ) -> Option<IndexedImage<Color, NewIndex>>

where Color: Clone, NewIndex: BoundedIndex, Index: AsPrimitive<NewIndex>,

Create a new IndexedImage with a smaller index type.

See also into_smaller_indices for a consuming variant that does not need to clone the palette.

This returns None if the length of the palette is larger than NewIndex::MAX + 1.

pub fn into_larger_indices<NewIndex>(self) -> IndexedImage<Color, NewIndex>

where NewIndex: BoundedIndex, Index: Into<NewIndex>,

Convert the indices of an IndexedImage to a larger integer type.

See to_larger_indices for a non-consuming variant.

pub fn into_smaller_indices<NewIndex>( self, ) -> Result<IndexedImage<Color, NewIndex>, Self>

where NewIndex: BoundedIndex, Index: AsPrimitive<NewIndex>,

Convert the indices of an IndexedImage to a smaller integer type.

See to_smaller_indices for a non-consuming variant.

Errors

This returns the original IndexedImage as an Err if the length of the palette is larger than NewIndex::MAX + 1.

pub fn replace_palette<NewColor>( self, palette: Vec<NewColor>, ) -> Result<(IndexedImage<NewColor, Index>, Vec<Color>), (Self, Vec<NewColor>)>

Replace the palette of an IndexedImage to a different color type (or to new colors of the same type).

Errors

If the length of the provided palette does not match the length of the current palette in the IndexedImage, then self and palette are returned as an Err. Otherwise, the new IndexedImage is returned alongside the old palette.

pub fn map<NewColor>( self, mapping: impl FnOnce(Vec<Color>) -> Vec<NewColor>, ) -> IndexedImage<NewColor, Index>

Map the palette of an IndexedImage, reusing the existing indices.

See map_ref to instead clone the existing indices and retain the original IndexedImage.

Also see map_to_indexed to map an IndexedImage to a new palette with a potentially different number of colors.

Rather than being a function from Color -> NewColor, mapping takes the whole palette as input and returns a new palette. This is to allow batch or parallel mappings.

Examples

It is recommended to do batch mappings for efficiency where it makes sense. E.g., using the color space conversion functions from the color_space module.

use quantette::color_space::srgb8_to_oklab;
let srgb_image = IndexedImage::<Srgb<u8>>::default();
let oklab_image = srgb_image.map(|palette| srgb8_to_oklab(&palette));

To instead map each color one at a time, use into_iter, map, and collect like normal:

let srgb_image = IndexedImage::<Srgb<u8>>::default();
let lin_srgb_image: IndexedImage<LinSrgb> =
    srgb_image.map(|palette| palette.into_iter().map(|srgb| srgb.into_linear()).collect());

Panics

Panics if mapping returns a palette with a different length than the original palette.

pub fn map_ref<NewColor>( &self, mapping: impl FnOnce(&[Color]) -> Vec<NewColor>, ) -> IndexedImage<NewColor, Index>

Map the palette of an IndexedImage, cloning the existing indices.

See map to instead consume the original IndexedImage and avoid a clone of the indices.

Also see map_to_indexed to map an IndexedImage to a new palette with a potentially different number of colors.

Rather than being a function from Color -> NewColor, mapping takes the whole palette as input and returns a new palette. This is to allow batch or parallel mappings.

Examples

It is recommended to do batch mappings for efficiency where it makes sense. E.g., using the color space conversion functions from the color_space module.

use quantette::color_space::srgb8_to_oklab;
let srgb_image = IndexedImage::<Srgb<u8>>::default();
let oklab_image = srgb_image.map_ref(srgb8_to_oklab);

To instead map each color one at a time, use iter, map, and collect like normal:

let srgb_image = IndexedImage::<Srgb<u8>>::default();
let lin_srgb_image: IndexedImage<LinSrgb> =
    srgb_image.map_ref(|palette| palette.iter().map(|srgb| srgb.into_linear()).collect());

Panics

Panics if mapping returns a palette with a different length than the original palette.

pub fn map_to_indexed<ColorMap: IndexedColorMap<Color>>( &self, color_map: ColorMap, ) -> IndexedImage<ColorMap::Output>

Map an IndexedImage to a new palette using the provided IndexedColorMap.

This function recalculates the indices for the new IndexedImage, as the new palette may have a different length. To map only the palette colors see one of the following:

• map_ref
• map
• replace_palette

Panics

Panics if color_map is not a valid implementor of IndexedColorMap. That is, it returns a Vec with a different length than the input slice.

pub fn map_to_indexed_par<ColorMap: IndexedColorMap<Color>>( &self, color_map: ColorMap, ) -> IndexedImage<ColorMap::Output>

Map an IndexedImage to a new palette in parallel using the provided IndexedColorMap.

This function recalculates the indices for the new IndexedImage, as the new palette may have a different length. To map only the palette colors see one of the following:

• map_ref
• map
• replace_palette

Panics

Panics if color_map is not a valid implementor of IndexedColorMap. That is, it returns a Vec with a different length than the input slice.

pub fn map_to_image<ColorMap: IndexedColorMap<Color>>( &self, color_map: ColorMap, ) -> ImageBuf<ColorMap::Output>

Convert an IndexedImage to an ImageBuf while also mapping the palette colors.

This is more efficient than map_ref followed by to_image, since it avoids unnecessary intermediate indices.

Panics

Panics if color_map is not a valid implementor of IndexedColorMap. That is, it returns a Vec with a different length than the input slice.

pub fn map_to_image_par<ColorMap: IndexedColorMap<Color>>( &self, color_map: ColorMap, ) -> ImageBuf<ColorMap::Output>

Convert an IndexedImage to an ImageBuf in parallel while also mapping the palette colors.

This is more efficient than map_ref followed by to_image_par, since it avoids unnecessary intermediate indices.

Panics

Panics if color_map is not a valid implementor of IndexedColorMap. That is, it returns a Vec with a different length than the input slice.

pub fn into_indexed_image_counts(self) -> IndexedImageCounts<Color, Index>

Convert an IndexedImage to an IndexedImageCounts by counting the number of times each palette index appears.

pub fn to_image(&self) -> ImageBuf<Color>

where Color: Clone,

Convert an IndexedImage to an ImageBuf.

See map_to_image if you also need to map the palette colors.

pub fn to_image_par(&self) -> ImageBuf<Color>

where Color: Clone + Send + Sync,

Convert an IndexedImage to an ImageBuf in parallel.

See map_to_image_par if you also need to map the palette colors.

Trait Implementations

impl<Color, Index: BoundedIndex> AsRef<IndexedImage<Color, Index>> for IndexedImageCounts<Color, Index>

fn as_ref(&self) -> &IndexedImage<Color, Index>

Converts this type into a shared reference of the (usually inferred) input type.

impl<Color: Clone, Index: Clone> Clone for IndexedImage<Color, Index>

fn clone(&self) -> IndexedImage<Color, Index>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Color: Debug, Index: Debug> Debug for IndexedImage<Color, Index>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Color, Index: BoundedIndex> Default for IndexedImage<Color, Index>

fn default() -> Self

Returns the “default value” for a type.

impl<Color: Hash, Index: Hash> Hash for IndexedImage<Color, Index>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<Color: PartialEq, Index: PartialEq> PartialEq for IndexedImage<Color, Index>

fn eq(&self, other: &IndexedImage<Color, Index>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Color: Eq, Index: Eq> Eq for IndexedImage<Color, Index>

impl<Color, Index> StructuralPartialEq for IndexedImage<Color, Index>