Merge #320

320: Implement struct-of-arrays (SoA) utilities r=Ogeon a=Ogeon

This adds a set of iterators and utilities for converting between arrays of structs and structs of arrays. There's definitely more that can be done, but it's a start. This pull request includes:

* Creating  and extending`ColorType<Collection<T>>` from any `IntoIterator<Item=ColorType<T>>`.
* Iterating over `ColorType<Collection<T>>`.
* Some `Vec` functions are available for `ColorType<Vec<T>>`, with more that can be added.
* Slicing and indexing with `get` and `get_mut`.
* Working with `ColorType<&T>` and `ColorType<&mut T>`, using `copied`, `cloned` and `set`.

See the discussion in #303 for some background.

## Closed Issues

* Closes #305.


Co-authored-by: Erik Hedvall <erikwhedvall@gmail.com>

palette/examples/struct_of_arrays.rs

@@ -0,0 +1,50 @@
+use palette::{cast, color_difference::EuclideanDistance, IntoColor, Oklab, Srgb};
+
+fn main() {
+    let image = image::open("example-data/input/fruits.png")
+        .expect("could not open 'example-data/input/fruits.png'")
+        .to_rgb8();
+
+    let image = cast::from_component_slice::<Srgb<u8>>(image.as_raw());
+
+    // Convert and collect the colors in a struct-of-arrays (SoA) format, where
+    // each component is a Vec of all the pixels' component values.
+    let oklab_image: Oklab<Vec<f32>> = image
+        .iter()
+        .map(|rgb| rgb.into_linear::<f32>().into_color())
+        .collect();
+
+    // Find the min, max and average of each component. We are doing it by
+    // iterating over each component Vec separately, starting with l...
+    let (min_l, max_l, average_l) = get_min_max_average(oklab_image.l.iter().copied());
+    let (min_a, max_a, average_a) = get_min_max_average(oklab_image.a.iter().copied());
+    let (min_b, max_b, average_b) = get_min_max_average(oklab_image.b.iter().copied());
+
+    // Find out how far the colors in the image are from the average color. In
+    // this case, we can just iterate over all of the colors and consume the
+    // collection(s).
+    let average_color = Oklab::new(average_l, average_a, average_b);
+    let (min_d, max_d, average_d) = get_min_max_average(
+        oklab_image
+            .into_iter()
+            .map(|color| average_color.distance(color)),
+    );
+
+    // Print the stats.
+    println!("Oklab l: min {min_l}, average {average_l}, max {max_l}");
+    println!("Oklab a: min {min_a}, average {average_a}, max {max_a}");
+    println!("Oklab b: min {min_b}, average {average_b}, max {max_b}");
+    println!("Distance from average color: min {min_d}, average {average_d}, max {max_d}");
+}
+
+/// Calculates the min, max and average of the iterator's values.
+fn get_min_max_average(iter: impl ExactSizeIterator<Item = f32>) -> (f32, f32, f32) {
+    let length = iter.len();
+
+    let (min, max, sum) = iter.fold(
+        (f32::INFINITY, f32::NEG_INFINITY, 0.0),
+        |(min, max, sum), value| (min.min(value), max.max(value), sum + value),
+    );
+
+    (min, max, sum / length as f32)
+}

palette/src/alpha.rs

@@ -1,10 +1,15 @@
+//! Types related to transparent colors.
+
 #[doc(hidden)]
 pub use palette_derive::WithAlpha;
 
 use crate::{num::Zero, stimulus::Stimulus};
 
 pub use self::alpha::*;
 
+#[doc(no_inline)]
+pub use crate::blend::PreAlpha; // Cross-link for visibility.
+
 mod alpha;
 
 /// A trait for color types that can have or be given transparency (alpha channel).

palette/src/alpha/alpha.rs

@@ -1,5 +1,6 @@
 use core::{
     fmt,
+    iter::FromIterator,
     ops::{
         Add, AddAssign, BitAnd, Deref, DerefMut, Div, DivAssign, Mul, MulAssign, Sub, SubAssign,
     },
@@ -40,6 +41,24 @@ pub struct Alpha<C, T> {
     pub alpha: T,
 }
 
+impl<C, A> Alpha<C, A> {
+    /// Return an iterator over the colors in the wrapped collections.
+    pub fn iter<'a>(&'a self) -> <&'a Self as IntoIterator>::IntoIter
+    where
+        &'a Self: IntoIterator,
+    {
+        self.into_iter()
+    }
+
+    /// Return an iterator that allows modifying the colors in the wrapped collections.
+    pub fn iter_mut<'a>(&'a mut self) -> <&'a mut Self as IntoIterator>::IntoIter
+    where
+        &'a mut Self: IntoIterator,
+    {
+        self.into_iter()
+    }
+}
+
 impl<C: Premultiply> Alpha<C, C::Scalar> {
     /// Alpha mask the color by its transparency.
     pub fn premultiply(self) -> PreAlpha<C> {
@@ -716,6 +735,172 @@ where
     }
 }
 
+impl<Tc, Ta, C, A> Extend<Alpha<Tc, Ta>> for Alpha<C, A>
+where
+    C: Extend<Tc>,
+    A: Extend<Ta>,
+{
+    fn extend<T: IntoIterator<Item = Alpha<Tc, Ta>>>(&mut self, iter: T) {
+        for color in iter {
+            self.color.extend(core::iter::once(color.color));
+            self.alpha.extend(core::iter::once(color.alpha));
+        }
+    }
+}
+
+impl<Tc, Ta, C, A> FromIterator<Alpha<Tc, Ta>> for Alpha<C, A>
+where
+    C: Extend<Tc> + FromIterator<Tc>,
+    A: Extend<Ta> + Default,
+{
+    fn from_iter<T: IntoIterator<Item = Alpha<Tc, Ta>>>(iter: T) -> Self {
+        let mut result = Self {
+            color: C::from_iter(None), // Default is currently a used for black, meaning it's not always what we want here.
+            alpha: A::default(),
+        };
+
+        for color in iter {
+            result.color.extend(core::iter::once(color.color));
+            result.alpha.extend(core::iter::once(color.alpha));
+        }
+
+        result
+    }
+}
+
+impl<C, A> IntoIterator for Alpha<C, A>
+where
+    C: IntoIterator,
+    A: IntoIterator,
+{
+    type Item = Alpha<C::Item, A::Item>;
+
+    type IntoIter = Iter<C::IntoIter, A::IntoIter>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        Iter {
+            color: self.color.into_iter(),
+            alpha: self.alpha.into_iter(),
+        }
+    }
+}
+
+impl<'a, C, A> IntoIterator for &'a Alpha<C, A>
+where
+    &'a C: IntoIterator,
+    &'a A: IntoIterator,
+{
+    type Item = Alpha<<&'a C as IntoIterator>::Item, <&'a A as IntoIterator>::Item>;
+
+    type IntoIter = Iter<<&'a C as IntoIterator>::IntoIter, <&'a A as IntoIterator>::IntoIter>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        Iter {
+            color: (&self.color).into_iter(),
+            alpha: (&self.alpha).into_iter(),
+        }
+    }
+}
+
+impl<'a, C, A> IntoIterator for &'a mut Alpha<C, A>
+where
+    &'a mut C: IntoIterator,
+    &'a mut A: IntoIterator,
+{
+    type Item = Alpha<<&'a mut C as IntoIterator>::Item, <&'a mut A as IntoIterator>::Item>;
+
+    type IntoIter =
+        Iter<<&'a mut C as IntoIterator>::IntoIter, <&'a mut A as IntoIterator>::IntoIter>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        Iter {
+            color: (&mut self.color).into_iter(),
+            alpha: (&mut self.alpha).into_iter(),
+        }
+    }
+}
+
+/// An iterator for transparent colors.
+pub struct Iter<C, A> {
+    pub(crate) color: C,
+    pub(crate) alpha: A,
+}
+
+impl<C, A> Iterator for Iter<C, A>
+where
+    C: Iterator,
+    A: Iterator,
+{
+    type Item = Alpha<C::Item, A::Item>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        let color = self.color.next();
+        let alpha = self.alpha.next();
+
+        if let (Some(color), Some(alpha)) = (color, alpha) {
+            Some(Alpha { color, alpha })
+        } else {
+            None
+        }
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let hint = self.color.size_hint();
+        debug_assert_eq!(
+            self.alpha.size_hint(),
+            hint,
+            "the color and alpha iterators have different size hints"
+        );
+
+        hint
+    }
+
+    fn count(self) -> usize {
+        let count = self.color.count();
+        debug_assert_eq!(
+            self.alpha.count(),
+            count,
+            "the color and alpha iterators have different counts"
+        );
+
+        count
+    }
+}
+
+impl<C, A> DoubleEndedIterator for Iter<C, A>
+where
+    C: DoubleEndedIterator,
+    A: DoubleEndedIterator,
+{
+    fn next_back(&mut self) -> Option<Self::Item> {
+        let color = self.color.next_back();
+        let alpha = self.alpha.next_back();
+
+        if let (Some(color), Some(alpha)) = (color, alpha) {
+            Some(Alpha { color, alpha })
+        } else {
+            None
+        }
+    }
+}
+
+impl<C, A> ExactSizeIterator for Iter<C, A>
+where
+    C: ExactSizeIterator,
+    A: ExactSizeIterator,
+{
+    fn len(&self) -> usize {
+        let len = self.color.len();
+        debug_assert_eq!(
+            self.alpha.len(),
+            len,
+            "the color and alpha iterators have different lengths"
+        );
+
+        len
+    }
+}
+
 #[cfg(feature = "serializing")]
 impl<C, T> serde::Serialize for Alpha<C, T>
 where
@@ -771,6 +956,7 @@ where
     }
 }
 
+/// Sample transparent colors uniformly.
 #[cfg(feature = "random")]
 pub struct UniformAlpha<C, T>
 where

palette/src/hsl.rs

@@ -1,3 +1,5 @@
+//! Types for the HSL color space.
+
 use core::{
     any::TypeId,
     marker::PhantomData,
@@ -24,6 +26,7 @@ use crate::{
     clamp, clamp_assign, contrast_ratio,
     convert::FromColorUnclamped,
     encoding::Srgb,
+    hues::RgbHueIter,
     num::{
         self, Arithmetics, FromScalarArray, IntoScalarArray, IsValidDivisor, MinMax, One,
         PartialCmp, Real, Zero,
@@ -276,6 +279,9 @@ impl<S, T, A> Alpha<Hsl<S, T>, A> {
     }
 }
 
+impl_reference_component_methods_hue!(Hsl<S>, [saturation, lightness], standard);
+impl_struct_of_arrays_methods_hue!(Hsl<S>, [saturation, lightness], standard);
+
 impl<S1, S2, T> FromColorUnclamped<Hsl<S1, T>> for Hsl<S2, T>
 where
     S1: RgbStandard + 'static,
@@ -628,6 +634,7 @@ impl_color_sub!(Hsl<S, T>, [hue, saturation, lightness], standard);
 
 impl_array_casts!(Hsl<S, T>, [T; 3]);
 impl_simd_array_conversion_hue!(Hsl<S>, [saturation, lightness], standard);
+impl_struct_of_array_traits_hue!(Hsl<S>, RgbHueIter, [saturation, lightness], standard);
 
 impl_eq_hue!(Hsl<S>, RgbHue, [hue, saturation, lightness]);
 
@@ -661,6 +668,7 @@ where
     }
 }
 
+/// Sample HSL colors uniformly.
 #[cfg(feature = "random")]
 pub struct UniformHsl<S, T>
 where
@@ -835,6 +843,24 @@ mod test {
         assert_relative_eq!(Hsl::<Srgb>::max_lightness(), 1.0);
     }
 
+    struct_of_arrays_tests!(
+        Hsl<Srgb>,
+        Hsl::new(0.1f32, 0.2, 0.3),
+        Hsl::new(0.2, 0.3, 0.4),
+        Hsl::new(0.3, 0.4, 0.5)
+    );
+
+    mod alpha {
+        use crate::{encoding::Srgb, hsl::Hsla};
+
+        struct_of_arrays_tests!(
+            Hsla<Srgb>,
+            Hsla::new(0.1f32, 0.2, 0.3, 0.4),
+            Hsla::new(0.2, 0.3, 0.4, 0.5),
+            Hsla::new(0.3, 0.4, 0.5, 0.6)
+        );
+    }
+
     #[cfg(feature = "serializing")]
     #[test]
     fn serialize() {