quantette 0.6.0

Fast and high quality image quantization and palette generation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

//! Map the colors of an image to a color palette or to palette indices.

use crate::{Palette, PaletteBuf};
use alloc::{borrow::ToOwned as _, vec::Vec};

mod nearest_neighbor;
mod palette_substitution;

pub use nearest_neighbor::*;
pub use palette_substitution::*;

/// A trait for mapping colors to a retstricted set of palette colors.
///
/// Typically, implementors of this trait consist of a palette and a lookup data structure to map
/// any input color to one of the palette colors.
///
/// The main function of interest is [`palette_index`](IndexedColorMap::palette_index) which takes
/// a color as input and returns an index into [`palette`](IndexedColorMap::palette). The other
/// mapping functions like [`palette_color`](IndexedColorMap::palette_color) and
/// [`map_to_colors`](IndexedColorMap::map_to_colors) have default implementations based off
/// [`palette_index`](IndexedColorMap::palette_index), but these should be overridden with more
/// efficient implementations where it makes sense.
///
/// You can use those trait functions directly, but you likely want to use the various map functions
/// on the image types instead:
/// - [`Image::map_to_image`](crate::Image::map_to_image)
/// - [`Image::map_to_indexed`](crate::Image::map_to_indexed)
/// - [`IndexedImage::map_to_image`](crate::IndexedImage::map_to_image)
/// - [`IndexedImage::map_to_indexed`](crate::IndexedImage::map_to_indexed)
///
/// Additionally, the dither types from the [`dither`](crate::dither) module take an
/// [`IndexedColorMap`] as an input.
///
/// To create an [`IndexedColorMap`], see:
/// - [`wu`](crate::wu)
/// - [`kmeans`](crate::kmeans)
/// - [`NearestNeighborColorMap`]
/// - [`PaletteSubstitution`]
pub trait IndexedColorMap<Input> {
    /// The output color type.
    ///
    /// Oftentimes, this the same type as the [`IndexedColorMap`] `Input`. Sometimes, like for
    /// [`PaletteSubstitution`], each original palette color is mapped to a different output color,
    /// in which case `Input` may not be the same type as `Output`.
    type Output: Clone + Send + Sync;

    /// Consume this color map and return the underlying [`PaletteBuf`] of output colors.
    fn into_palette(self) -> PaletteBuf<Self::Output>;

    /// Returns a refererce to the underlying [`Palette`] of output colors.
    fn palette(&self) -> &Palette<Self::Output>;

    /// Returns a refererce to the underlying [`Palette`] of input colors.
    ///
    /// Oftentimes, this the same as [`palette`](IndexedColorMap::palette). Sometimes, like for
    /// [`PaletteSubstitution`], this will return the original palette which is used to calculate
    /// the nearest color, whereas [`palette`](IndexedColorMap::palette) will return the substitute
    /// palette used to populate the output.
    fn base_palette(&self) -> &Palette<Input>;

    /// Returns the index of the palette color for the given input `color`.
    fn palette_index(&self, color: &Input) -> u8;

    /// Returns the palette color for the given input `color`.
    #[inline]
    fn palette_color(&self, color: &Input) -> Self::Output {
        self.palette()[self.palette_index(color)].clone()
    }

    /// Map each `input` color to an index for one of the palette colors.
    #[inline]
    fn map_to_indices(&self, input: &[Input]) -> Vec<u8> {
        input
            .iter()
            .map(|color| self.palette_index(color))
            .collect()
    }

    /// Map each `input` color to a palette index, but instead of indexing the normal palette,
    /// use the provided substitute `palette` instead.
    #[inline]
    fn map_to_colors_of_palette<T: Clone + Send + Sync>(
        &self,
        palette: &Palette<T>,
        input: &[Input],
    ) -> Vec<T> {
        input
            .iter()
            .map(|color| palette[self.palette_index(color)].clone())
            .collect()
    }

    /// Map each `input` color to one of the palette colors.
    #[inline]
    fn map_to_colors(&self, input: &[Input]) -> Vec<Self::Output> {
        self.map_to_colors_of_palette(self.palette(), input)
    }
}

impl<Input, R> IndexedColorMap<Input> for &R
where
    R: IndexedColorMap<Input>,
{
    type Output = R::Output;

    #[inline]
    fn into_palette(self) -> PaletteBuf<Self::Output> {
        self.palette().to_owned()
    }

    #[inline]
    fn palette(&self) -> &Palette<Self::Output> {
        (*self).palette()
    }

    #[inline]
    fn base_palette(&self) -> &Palette<Input> {
        (*self).base_palette()
    }

    #[inline]
    fn palette_color(&self, color: &Input) -> Self::Output {
        (*self).palette_color(color)
    }

    #[inline]
    fn palette_index(&self, color: &Input) -> u8 {
        (*self).palette_index(color)
    }

    #[inline]
    fn map_to_indices(&self, input: &[Input]) -> Vec<u8> {
        (*self).map_to_indices(input)
    }

    fn map_to_colors_of_palette<T: Clone + Send + Sync>(
        &self,
        palette: &Palette<T>,
        input: &[Input],
    ) -> Vec<T> {
        (*self).map_to_colors_of_palette(palette, input)
    }

    #[inline]
    fn map_to_colors(&self, input: &[Input]) -> Vec<Self::Output> {
        (*self).map_to_colors(input)
    }
}