image/
traits.rs

1//! This module provides useful traits that were deprecated in rust
2
3// Note copied from the stdlib under MIT license
4
5use num_traits::{Bounded, Num, NumCast};
6use std::ops::AddAssign;
7
8use crate::color::{Luma, LumaA, Rgb, Rgba};
9use crate::ExtendedColorType;
10
11/// Types which are safe to treat as an immutable byte slice in a pixel layout
12/// for image encoding.
13pub trait EncodableLayout: seals::EncodableLayout {
14    /// Get the bytes of this value.
15    fn as_bytes(&self) -> &[u8];
16}
17
18impl EncodableLayout for [u8] {
19    fn as_bytes(&self) -> &[u8] {
20        bytemuck::cast_slice(self)
21    }
22}
23
24impl EncodableLayout for [u16] {
25    fn as_bytes(&self) -> &[u8] {
26        bytemuck::cast_slice(self)
27    }
28}
29
30impl EncodableLayout for [f32] {
31    fn as_bytes(&self) -> &[u8] {
32        bytemuck::cast_slice(self)
33    }
34}
35
36/// The type of each channel in a pixel. For example, this can be `u8`, `u16`, `f32`.
37// TODO rename to `PixelComponent`? Split up into separate traits? Seal?
38pub trait Primitive: Copy + NumCast + Num + PartialOrd<Self> + Clone + Bounded {
39    /// The maximum value for this type of primitive within the context of color.
40    /// For floats, the maximum is `1.0`, whereas the integer types inherit their usual maximum values.
41    const DEFAULT_MAX_VALUE: Self;
42
43    /// The minimum value for this type of primitive within the context of color.
44    /// For floats, the minimum is `0.0`, whereas the integer types inherit their usual minimum values.
45    const DEFAULT_MIN_VALUE: Self;
46}
47
48macro_rules! declare_primitive {
49    ($base:ty: ($from:expr)..$to:expr) => {
50        impl Primitive for $base {
51            const DEFAULT_MAX_VALUE: Self = $to;
52            const DEFAULT_MIN_VALUE: Self = $from;
53        }
54    };
55}
56
57declare_primitive!(usize: (0)..Self::MAX);
58declare_primitive!(u8: (0)..Self::MAX);
59declare_primitive!(u16: (0)..Self::MAX);
60declare_primitive!(u32: (0)..Self::MAX);
61declare_primitive!(u64: (0)..Self::MAX);
62
63declare_primitive!(isize: (Self::MIN)..Self::MAX);
64declare_primitive!(i8: (Self::MIN)..Self::MAX);
65declare_primitive!(i16: (Self::MIN)..Self::MAX);
66declare_primitive!(i32: (Self::MIN)..Self::MAX);
67declare_primitive!(i64: (Self::MIN)..Self::MAX);
68declare_primitive!(f32: (0.0)..1.0);
69declare_primitive!(f64: (0.0)..1.0);
70
71/// An `Enlargable::Larger` value should be enough to calculate
72/// the sum (average) of a few hundred or thousand Enlargeable values.
73pub trait Enlargeable: Sized + Bounded + NumCast {
74    type Larger: Copy + NumCast + Num + PartialOrd<Self::Larger> + Clone + Bounded + AddAssign;
75
76    fn clamp_from(n: Self::Larger) -> Self {
77        if n > Self::max_value().to_larger() {
78            Self::max_value()
79        } else if n < Self::min_value().to_larger() {
80            Self::min_value()
81        } else {
82            NumCast::from(n).unwrap()
83        }
84    }
85
86    fn to_larger(self) -> Self::Larger {
87        NumCast::from(self).unwrap()
88    }
89}
90
91impl Enlargeable for u8 {
92    type Larger = u32;
93}
94impl Enlargeable for u16 {
95    type Larger = u32;
96}
97impl Enlargeable for u32 {
98    type Larger = u64;
99}
100impl Enlargeable for u64 {
101    type Larger = u128;
102}
103impl Enlargeable for usize {
104    // Note: On 32-bit architectures, u64 should be enough here.
105    type Larger = u128;
106}
107impl Enlargeable for i8 {
108    type Larger = i32;
109}
110impl Enlargeable for i16 {
111    type Larger = i32;
112}
113impl Enlargeable for i32 {
114    type Larger = i64;
115}
116impl Enlargeable for i64 {
117    type Larger = i128;
118}
119impl Enlargeable for isize {
120    // Note: On 32-bit architectures, i64 should be enough here.
121    type Larger = i128;
122}
123impl Enlargeable for f32 {
124    type Larger = f64;
125}
126impl Enlargeable for f64 {
127    type Larger = f64;
128}
129
130/// Linear interpolation without involving floating numbers.
131pub trait Lerp: Bounded + NumCast {
132    type Ratio: Primitive;
133
134    fn lerp(a: Self, b: Self, ratio: Self::Ratio) -> Self {
135        let a = <Self::Ratio as NumCast>::from(a).unwrap();
136        let b = <Self::Ratio as NumCast>::from(b).unwrap();
137
138        let res = a + (b - a) * ratio;
139
140        if res > NumCast::from(Self::max_value()).unwrap() {
141            Self::max_value()
142        } else if res < NumCast::from(0).unwrap() {
143            NumCast::from(0).unwrap()
144        } else {
145            NumCast::from(res).unwrap()
146        }
147    }
148}
149
150impl Lerp for u8 {
151    type Ratio = f32;
152}
153
154impl Lerp for u16 {
155    type Ratio = f32;
156}
157
158impl Lerp for u32 {
159    type Ratio = f64;
160}
161
162impl Lerp for f32 {
163    type Ratio = f32;
164
165    fn lerp(a: Self, b: Self, ratio: Self::Ratio) -> Self {
166        a + (b - a) * ratio
167    }
168}
169
170/// The pixel with an associated `ColorType`.
171/// Not all possible pixels represent one of the predefined `ColorType`s.
172pub trait PixelWithColorType:
173    Pixel + private::SealedPixelWithColorType<TransformableSubpixel = <Self as Pixel>::Subpixel>
174{
175    /// This pixel has the format of one of the predefined `ColorType`s,
176    /// such as `Rgb8`, `La16` or `Rgba32F`.
177    /// This is needed for automatically detecting
178    /// a color format when saving an image as a file.
179    const COLOR_TYPE: ExtendedColorType;
180}
181
182impl PixelWithColorType for Rgb<u8> {
183    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgb8;
184}
185impl PixelWithColorType for Rgb<u16> {
186    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgb16;
187}
188impl PixelWithColorType for Rgb<f32> {
189    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgb32F;
190}
191
192impl PixelWithColorType for Rgba<u8> {
193    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgba8;
194}
195impl PixelWithColorType for Rgba<u16> {
196    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgba16;
197}
198impl PixelWithColorType for Rgba<f32> {
199    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgba32F;
200}
201
202impl PixelWithColorType for Luma<u8> {
203    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::L8;
204}
205impl PixelWithColorType for Luma<u16> {
206    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::L16;
207}
208impl PixelWithColorType for LumaA<u8> {
209    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::La8;
210}
211impl PixelWithColorType for LumaA<u16> {
212    const COLOR_TYPE: ExtendedColorType = ExtendedColorType::La16;
213}
214
215/// Prevents down-stream users from implementing the `Primitive` trait
216pub(crate) mod private {
217    use crate::color::*;
218    use crate::metadata::cicp::{self, CicpApplicable};
219
220    #[derive(Clone, Copy, Debug)]
221    pub enum LayoutWithColor {
222        Rgb,
223        Rgba,
224        Luma,
225        LumaAlpha,
226    }
227
228    impl From<ColorType> for LayoutWithColor {
229        fn from(color: ColorType) -> LayoutWithColor {
230            match color {
231                ColorType::L8 | ColorType::L16 => LayoutWithColor::Luma,
232                ColorType::La8 | ColorType::La16 => LayoutWithColor::LumaAlpha,
233                ColorType::Rgb8 | ColorType::Rgb16 | ColorType::Rgb32F => LayoutWithColor::Rgb,
234                ColorType::Rgba8 | ColorType::Rgba16 | ColorType::Rgba32F => LayoutWithColor::Rgba,
235            }
236        }
237    }
238
239    impl LayoutWithColor {
240        pub(crate) fn channels(self) -> usize {
241            match self {
242                Self::Rgb => 3,
243                Self::Rgba => 4,
244                Self::Luma => 1,
245                Self::LumaAlpha => 2,
246            }
247        }
248    }
249
250    #[derive(Clone, Copy)]
251    pub struct PrivateToken;
252
253    pub trait SealedPixelWithColorType {
254        #[expect(private_bounds)] // This is a sealed trait.
255        type TransformableSubpixel: HelpDispatchTransform;
256        fn layout(_: PrivateToken) -> LayoutWithColor;
257    }
258
259    impl SealedPixelWithColorType for Rgb<u8> {
260        type TransformableSubpixel = u8;
261        fn layout(_: PrivateToken) -> LayoutWithColor {
262            LayoutWithColor::Rgb
263        }
264    }
265
266    impl SealedPixelWithColorType for Rgb<u16> {
267        type TransformableSubpixel = u16;
268        fn layout(_: PrivateToken) -> LayoutWithColor {
269            LayoutWithColor::Rgb
270        }
271    }
272
273    impl SealedPixelWithColorType for Rgb<f32> {
274        type TransformableSubpixel = f32;
275        fn layout(_: PrivateToken) -> LayoutWithColor {
276            LayoutWithColor::Rgb
277        }
278    }
279
280    impl SealedPixelWithColorType for Rgba<u8> {
281        type TransformableSubpixel = u8;
282        fn layout(_: PrivateToken) -> LayoutWithColor {
283            LayoutWithColor::Rgba
284        }
285    }
286
287    impl SealedPixelWithColorType for Rgba<u16> {
288        type TransformableSubpixel = u16;
289        fn layout(_: PrivateToken) -> LayoutWithColor {
290            LayoutWithColor::Rgba
291        }
292    }
293
294    impl SealedPixelWithColorType for Rgba<f32> {
295        type TransformableSubpixel = f32;
296        fn layout(_: PrivateToken) -> LayoutWithColor {
297            LayoutWithColor::Rgba
298        }
299    }
300
301    impl SealedPixelWithColorType for Luma<u8> {
302        type TransformableSubpixel = u8;
303        fn layout(_: PrivateToken) -> LayoutWithColor {
304            LayoutWithColor::Luma
305        }
306    }
307
308    impl SealedPixelWithColorType for LumaA<u8> {
309        type TransformableSubpixel = u8;
310        fn layout(_: PrivateToken) -> LayoutWithColor {
311            LayoutWithColor::LumaAlpha
312        }
313    }
314
315    impl SealedPixelWithColorType for Luma<u16> {
316        type TransformableSubpixel = u16;
317        fn layout(_: PrivateToken) -> LayoutWithColor {
318            LayoutWithColor::Luma
319        }
320    }
321
322    impl SealedPixelWithColorType for Luma<f32> {
323        type TransformableSubpixel = f32;
324        fn layout(_: PrivateToken) -> LayoutWithColor {
325            LayoutWithColor::Luma
326        }
327    }
328
329    impl SealedPixelWithColorType for LumaA<u16> {
330        type TransformableSubpixel = u16;
331        fn layout(_: PrivateToken) -> LayoutWithColor {
332            LayoutWithColor::LumaAlpha
333        }
334    }
335
336    impl SealedPixelWithColorType for LumaA<f32> {
337        type TransformableSubpixel = f32;
338        fn layout(_: PrivateToken) -> LayoutWithColor {
339            LayoutWithColor::LumaAlpha
340        }
341    }
342
343    // Consider a situation in a function bounded `Self: Pixel + PixelWithColorType`. Then, if we
344    // tried this directly:
345    //
346    // <
347    //   <Self as SealedPixelWithColorType>::TransformableSubpixel as HelpDispatchTransform
348    // >::transform_on::<Self>(tr, LayoutWithColor::Rgb);
349    //
350    // the type checker is mightily confused. I think what's going on is as follows: It find the
351    // fact that `Self::Subpixel` is used for `TransformableSubpixel` from the bound on
352    // `PixelWithColorType`, but then there is no existing bound on `Subpixel` that would guarantee
353    // that `HelpDispatchTransform` is fulfilled. That would only be available by substituting
354    // _back_ so that the bound on `TransformableSubpixel` gets applied to the `Subpixel` generic,
355    // too. But now there are no variables here, so unification of bounds takes place we never
356    // never get to see the bound (until next gen, I guess?). It finally find that there is still
357    // an unfulfilled bound and complains.
358    //
359    // Hence we must avoid mentioning the `Pixel` and `PixelWithColorType` bound so that _only_ the
360    // `TransformableSubpixel` is available. Then all substitutions work forwards, and since we
361    // return a `TransformableSubpixel` we get the function back without new variables to solve
362    // for, and that can then be unified just fine. This extra function essentially introduces that
363    // missing unknown which can unify the available impl set. Yay.
364    pub(crate) fn dispatch_transform_from_sealed<P: SealedPixelWithColorType>(
365        transform: &cicp::CicpTransform,
366        into: LayoutWithColor,
367    ) -> &'_ CicpApplicable<'_, P::TransformableSubpixel> {
368        <P::TransformableSubpixel as HelpDispatchTransform>::transform_on::<P>(transform, into)
369    }
370
371    pub(crate) fn double_dispatch_transform_from_sealed<
372        P: SealedPixelWithColorType,
373        Into: SealedPixelWithColorType,
374    >(
375        transform: &cicp::CicpTransform,
376    ) -> &'_ CicpApplicable<'_, P::TransformableSubpixel> {
377        dispatch_transform_from_sealed::<P>(transform, Into::layout(PrivateToken))
378    }
379
380    pub(crate) trait HelpDispatchTransform: Sized + 'static {
381        fn transform_on<O: SealedPixelWithColorType<TransformableSubpixel = Self>>(
382            transform: &cicp::CicpTransform,
383            into: LayoutWithColor,
384        ) -> &'_ (dyn Fn(&[Self], &mut [Self]) + Send + Sync);
385    }
386
387    impl HelpDispatchTransform for u8 {
388        fn transform_on<O: SealedPixelWithColorType<TransformableSubpixel = Self>>(
389            transform: &cicp::CicpTransform,
390            into: LayoutWithColor,
391        ) -> &'_ (dyn Fn(&[Self], &mut [Self]) + Send + Sync) {
392            &**transform.select_transform_u8::<O>(into)
393        }
394    }
395
396    impl HelpDispatchTransform for u16 {
397        fn transform_on<O: SealedPixelWithColorType<TransformableSubpixel = Self>>(
398            transform: &cicp::CicpTransform,
399            into: LayoutWithColor,
400        ) -> &'_ (dyn Fn(&[Self], &mut [Self]) + Send + Sync) {
401            &**transform.select_transform_u16::<O>(into)
402        }
403    }
404
405    impl HelpDispatchTransform for f32 {
406        fn transform_on<O: SealedPixelWithColorType<TransformableSubpixel = Self>>(
407            transform: &cicp::CicpTransform,
408            into: LayoutWithColor,
409        ) -> &'_ (dyn Fn(&[Self], &mut [Self]) + Send + Sync) {
410            &**transform.select_transform_f32::<O>(into)
411        }
412    }
413}
414
415/// A generalized pixel.
416///
417/// A pixel object is usually not used standalone but as a view into an image buffer.
418pub trait Pixel: Copy + Clone {
419    /// The scalar type that is used to store each channel in this pixel.
420    type Subpixel: Primitive;
421
422    /// The number of channels of this pixel type.
423    const CHANNEL_COUNT: u8;
424
425    /// Returns the components as a slice.
426    fn channels(&self) -> &[Self::Subpixel];
427
428    /// Returns the components as a mutable slice
429    fn channels_mut(&mut self) -> &mut [Self::Subpixel];
430
431    /// A string that can help to interpret the meaning each channel
432    /// See [gimp babl](http://gegl.org/babl/).
433    const COLOR_MODEL: &'static str;
434
435    /// Returns true if the alpha channel is contained.
436    const HAS_ALPHA: bool = false;
437
438    /// Returns the channels of this pixel as a 4 tuple. If the pixel
439    /// has less than 4 channels the remainder is filled with the maximum value
440    #[deprecated(since = "0.24.0", note = "Use `channels()` or `channels_mut()`")]
441    fn channels4(
442        &self,
443    ) -> (
444        Self::Subpixel,
445        Self::Subpixel,
446        Self::Subpixel,
447        Self::Subpixel,
448    );
449
450    /// Construct a pixel from the 4 channels a, b, c and d.
451    /// If the pixel does not contain 4 channels the extra are ignored.
452    #[deprecated(
453        since = "0.24.0",
454        note = "Use the constructor of the pixel, for example `Rgba([r,g,b,a])` or `Pixel::from_slice`"
455    )]
456    fn from_channels(
457        a: Self::Subpixel,
458        b: Self::Subpixel,
459        c: Self::Subpixel,
460        d: Self::Subpixel,
461    ) -> Self;
462
463    /// Returns a view into a slice.
464    ///
465    /// Note: The slice length is not checked on creation. Thus the caller has to ensure
466    /// that the slice is long enough to prevent panics if the pixel is used later on.
467    fn from_slice(slice: &[Self::Subpixel]) -> &Self;
468
469    /// Returns mutable view into a mutable slice.
470    ///
471    /// Note: The slice length is not checked on creation. Thus the caller has to ensure
472    /// that the slice is long enough to prevent panics if the pixel is used later on.
473    fn from_slice_mut(slice: &mut [Self::Subpixel]) -> &mut Self;
474
475    /// Convert this pixel to RGB
476    fn to_rgb(&self) -> Rgb<Self::Subpixel>;
477
478    /// Convert this pixel to RGB with an alpha channel
479    fn to_rgba(&self) -> Rgba<Self::Subpixel>;
480
481    /// Convert this pixel to luma
482    fn to_luma(&self) -> Luma<Self::Subpixel>;
483
484    /// Convert this pixel to luma with an alpha channel
485    fn to_luma_alpha(&self) -> LumaA<Self::Subpixel>;
486
487    /// Apply the function ```f``` to each channel of this pixel.
488    fn map<F>(&self, f: F) -> Self
489    where
490        F: FnMut(Self::Subpixel) -> Self::Subpixel;
491
492    /// Apply the function ```f``` to each channel of this pixel.
493    fn apply<F>(&mut self, f: F)
494    where
495        F: FnMut(Self::Subpixel) -> Self::Subpixel;
496
497    /// Apply the function ```f``` to each channel except the alpha channel.
498    /// Apply the function ```g``` to the alpha channel.
499    fn map_with_alpha<F, G>(&self, f: F, g: G) -> Self
500    where
501        F: FnMut(Self::Subpixel) -> Self::Subpixel,
502        G: FnMut(Self::Subpixel) -> Self::Subpixel;
503
504    /// Apply the function ```f``` to each channel except the alpha channel.
505    /// Apply the function ```g``` to the alpha channel. Works in-place.
506    fn apply_with_alpha<F, G>(&mut self, f: F, g: G)
507    where
508        F: FnMut(Self::Subpixel) -> Self::Subpixel,
509        G: FnMut(Self::Subpixel) -> Self::Subpixel;
510
511    /// Apply the function ```f``` to each channel except the alpha channel.
512    fn map_without_alpha<F>(&self, f: F) -> Self
513    where
514        F: FnMut(Self::Subpixel) -> Self::Subpixel,
515    {
516        let mut this = *self;
517        this.apply_with_alpha(f, |x| x);
518        this
519    }
520
521    /// Apply the function ```f``` to each channel except the alpha channel.
522    /// Works in place.
523    fn apply_without_alpha<F>(&mut self, f: F)
524    where
525        F: FnMut(Self::Subpixel) -> Self::Subpixel,
526    {
527        self.apply_with_alpha(f, |x| x);
528    }
529
530    /// Apply the function ```f``` to each channel of this pixel and
531    /// ```other``` pairwise.
532    fn map2<F>(&self, other: &Self, f: F) -> Self
533    where
534        F: FnMut(Self::Subpixel, Self::Subpixel) -> Self::Subpixel;
535
536    /// Apply the function ```f``` to each channel of this pixel and
537    /// ```other``` pairwise. Works in-place.
538    fn apply2<F>(&mut self, other: &Self, f: F)
539    where
540        F: FnMut(Self::Subpixel, Self::Subpixel) -> Self::Subpixel;
541
542    /// Invert this pixel
543    fn invert(&mut self);
544
545    /// Blend the color of a given pixel into ourself, taking into account alpha channels
546    fn blend(&mut self, other: &Self);
547}
548
549/// Private module for supertraits of sealed traits.
550mod seals {
551    pub trait EncodableLayout {}
552
553    impl EncodableLayout for [u8] {}
554    impl EncodableLayout for [u16] {}
555    impl EncodableLayout for [f32] {}
556}