From d9f3d4c16b6b0f62d55a2975612c1a7f8d609542 Mon Sep 17 00:00:00 2001 From: gennyble Date: Fri, 12 Jan 2024 16:50:04 -0600 Subject: colorsquash: docs and rename algorithms --- src/difference.rs | 54 ++++++++++++++++++++++++++++++++++++++++-------------- src/lib.rs | 26 ++++++++++---------------- 2 files changed, 50 insertions(+), 30 deletions(-) diff --git a/src/difference.rs b/src/difference.rs index 42c4c4f..b52b34f 100644 --- a/src/difference.rs +++ b/src/difference.rs @@ -1,30 +1,56 @@ -//! A set of difference functions you can use with [SquasherBuilder::difference] +//! A set of difference functions you can use with [SquasherBuilder::difference()] +//! +//! # Writing your own difference function +//! The type you want is `dyn Fn(&RGB8, &RGB8) -> f32` +//! (defined as [`DiffFn`]) +//! +//! The first argument is the color already in the palette and the second is +//! the color we're checking. These are [RGB8] which is a rexport from the `rgb` +//! crate. +//! +//! The value returned is between 0 and 768, but that's not a hard-rule. If you +//! return a value out of that range you'll have to adjust the tolerance with +//! [Squasher::set_tolerance()] or [SquasherBuilder::tolerance]. +//! +//! The difference functions have the possibility of being called hundreds of +//! thousands of times; you might want to `#[inline(always)]` + +// This is used in the module level documentation just above. Without it we'd +// have to fully qualify the interlink which is also how it'd be displayed. +#[allow(unused_imports)] +use crate::{Squasher, SquasherBuilder}; // rexport this so people don't need to add the rgb crate to their project. this // also helps avoid crate version mismatch +/// rexport from the [`rgb`](https://docs.rs/rgb/0.8.37/rgb/) crate. pub use rgb::RGB8; +/// Type definition for difference functions. +pub type DiffFn = dyn Fn(&RGB8, &RGB8) -> f32; + /// A naïve comparison just summing the channel differences /// I.E. `|a.red - b.red| + |a.green - b.green| + |a.blue - b.blue|` #[allow(clippy::many_single_char_names)] #[inline(always)] -pub fn rgb_difference(a: &RGB8, b: &RGB8) -> f32 { - let absdiff = |a: u8, b: u8| (a as f32 - b as f32).abs(); - absdiff(a.r, b.r) + absdiff(a.g, b.g) + absdiff(a.b, b.b) +pub fn rgb(a: &RGB8, b: &RGB8) -> f32 { + let absdiff = |a: u8, b: u8| (a as f32 - b as f32).abs(); + absdiff(a.r, b.r) + absdiff(a.g, b.g) + absdiff(a.b, b.b) } // https://en.wikipedia.org/wiki/Color_difference#sRGB +/// a slightly more intelligent algorithm that weighs the channels in an attempt +/// to better align with human color perception. #[inline(always)] -pub fn redmean_difference(a: &RGB8, b: &RGB8) -> f32 { - let delta_r = a.r as f32 - b.r as f32; - let delta_g = a.g as f32 - b.g as f32; - let delta_b = a.b as f32 - b.b as f32; - // reasonably sure calling it prime is wrong, but - let r_prime = 0.5 * (a.r as f32 + b.r as f32); +pub fn redmean(a: &RGB8, b: &RGB8) -> f32 { + let delta_r = a.r as f32 - b.r as f32; + let delta_g = a.g as f32 - b.g as f32; + let delta_b = a.b as f32 - b.b as f32; + // reasonably sure calling it prime is wrong, but + let r_prime = 0.5 * (a.r as f32 + b.r as f32); - let red_part = (2.0 + (r_prime / 256.0)) * (delta_r * delta_r); - let green_part = 4.0 * (delta_g * delta_g); - let blue_part = (2.0 + (255.0 - r_prime) / 256.0) * (delta_b * delta_b); + let red_part = (2.0 + (r_prime / 256.0)) * (delta_r * delta_r); + let green_part = 4.0 * (delta_g * delta_g); + let blue_part = (2.0 + (255.0 - r_prime) / 256.0) * (delta_b * delta_b); - (red_part + green_part + blue_part).sqrt() + (red_part + green_part + blue_part).sqrt() } diff --git a/src/lib.rs b/src/lib.rs index 213adfc..cbf8216 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -3,7 +3,7 @@ use std::collections::HashMap; pub mod difference; -type DiffFn = dyn Fn(&RGB8, &RGB8) -> f32; +use difference::DiffFn; pub struct SquasherBuilder { max_colours: T, @@ -26,7 +26,8 @@ impl SquasherBuilder { /// The function to use to compare colours. /// - /// see the [difference] module for functions included with the crate. + /// see the [difference] module for functions included with the crate and + /// information on implementing your own. pub fn difference(mut self, difference: &'static DiffFn) -> SquasherBuilder { self.difference_fn = Box::new(difference); self @@ -52,7 +53,7 @@ impl Default for SquasherBuilder { fn default() -> Self { Self { max_colours: T::from_usize(255), - difference_fn: Box::new(difference::rgb_difference), + difference_fn: Box::new(difference::rgb), tolerance: 1.0, } } @@ -72,11 +73,7 @@ impl Squasher { /// contains every 24-bit color and ends up with an amount of memory /// equal to `16MB * std::mem::size_of(T)`. pub fn new(max_colors_minus_one: T, buffer: &[u8]) -> Self { - let mut this = Self::from_parts( - max_colors_minus_one, - Box::new(difference::rgb_difference), - 1.0, - ); + let mut this = Self::from_parts(max_colors_minus_one, Box::new(difference::rgb), 1.0); this.recolor(buffer); this @@ -86,6 +83,7 @@ impl Squasher { SquasherBuilder::new() } + /// Set the tolerance pub fn set_tolerance(&mut self, percent: f32) { self.tolerance_percent = percent; } @@ -200,10 +198,6 @@ impl Squasher { /// Pick the colors in the palette from a Vec of colors sorted by number /// of times they occur, high to low. fn select_colors(&self, sorted: Vec) -> Vec { - // I made these numbers up - #[allow(non_snake_case)] - //let RGB_TOLERANCE: f32 = 0.01 * 765.0; - //let RGB_TOLERANCE: f32 = 36.0; let tolerance = (self.tolerance_percent / 100.0) * 765.0; let max_colours = self.max_colours_min1.as_usize() + 1; let mut selected_colors: Vec = Vec::with_capacity(max_colours); @@ -211,10 +205,9 @@ impl Squasher { for sorted_color in sorted { if max_colours <= selected_colors.len() { break; - } else if selected_colors - .iter() - .all(|color| (self.difference_fn)(&sorted_color, color) > tolerance) - { + } else if selected_colors.iter().all(|selected_color| { + (self.difference_fn)(selected_color, &sorted_color) > tolerance + }) { selected_colors.push(sorted_color); } } @@ -303,6 +296,7 @@ count_impl!(u32); count_impl!(u64); count_impl!(usize); +/// Compute the color index into the big-map-of-all-colours. #[inline(always)] fn color_index(c: &RGB8) -> usize { c.r as usize * (256 * 256) + c.g as usize * 256 + c.b as usize -- cgit 1.4.1-3-g733a5