tpt-cv-core 0.1.0

// SPDX-License-Identifier: MIT OR Apache-2.0

//! Multi-channel pixel types and the [`Sample`] trait.

use core::fmt;

/// A numeric sample type an [`crate::image::Image`] can be composed of.
///
/// Implemented for `u8`, `u16`, and `f32`, covering 8-bit, 16-bit, and
/// 32-bit-float image data. `no_std` compatible.
pub trait Sample:
    Copy + Clone + Default + PartialEq + PartialOrd + fmt::Debug + Send + Sync
{
    /// The additive identity (`0` for every sample type).
    const ZERO: Self;
    /// The multiplicative identity (`1` for every sample type).
    const ONE: Self;
    /// The smallest representable value.
    const MIN: Self;
    /// The largest representable value.
    const MAX: Self;
    /// The sample value equal to 1.0 in normalized (unit) space:
    /// `255.0` for `u8`, `65535.0` for `u16`, `1.0` for `f32`.
    const UNIT: f32;

    /// Convert to `f32`, exact for `u8`/`u16`, identity for `f32`.
    fn as_f32(self) -> f32;

    /// Convert from `f32`, saturating into the representable range and
    /// rounding (for integers).
    fn from_f32(v: f32) -> Self;

    /// Convert to normalized `[0, 1]` unit space.
    #[inline]
    fn to_unit(self) -> f32 {
        self.as_f32() / Self::UNIT
    }

    /// Convert from normalized `[0, 1]` unit space.
    #[inline]
    fn from_unit(v: f32) -> Self {
        Self::from_f32(v * Self::UNIT)
    }

    /// Saturating addition.
    fn saturating_add(self, rhs: Self) -> Self;

    /// Saturating subtraction.
    fn saturating_sub(self, rhs: Self) -> Self;

    /// Saturating multiplication.
    fn saturating_mul(self, rhs: Self) -> Self;

    /// Wrapping addition.
    fn wrapping_add(self, rhs: Self) -> Self;

    /// Wrapping subtraction.
    fn wrapping_sub(self, rhs: Self) -> Self;

    /// Wrapping multiplication.
    fn wrapping_mul(self, rhs: Self) -> Self;

    /// Component-wise minimum.
    fn min(self, rhs: Self) -> Self;

    /// Component-wise maximum.
    fn max(self, rhs: Self) -> Self;

    /// Clamp into `[low, high]`.
    fn clamp(self, low: Self, high: Self) -> Self {
        self.max(low).min(high)
    }
}

impl Sample for u8 {
    const ZERO: Self = 0;
    const ONE: Self = 1;
    const MIN: Self = u8::MIN;
    const MAX: Self = u8::MAX;
    const UNIT: f32 = 255.0;

    #[inline]
    fn as_f32(self) -> f32 {
        self as f32
    }

    #[inline]
    fn from_f32(v: f32) -> Self {
        // `round half up` for the non-negative range; `as` casts saturate.
        (v.clamp(0.0, 255.0) + 0.5) as u8
    }

    #[inline]
    fn saturating_add(self, rhs: Self) -> Self {
        self.saturating_add(rhs)
    }

    #[inline]
    fn saturating_sub(self, rhs: Self) -> Self {
        self.saturating_sub(rhs)
    }

    #[inline]
    fn saturating_mul(self, rhs: Self) -> Self {
        self.saturating_mul(rhs)
    }

    #[inline]
    fn wrapping_add(self, rhs: Self) -> Self {
        self.wrapping_add(rhs)
    }

    #[inline]
    fn wrapping_sub(self, rhs: Self) -> Self {
        self.wrapping_sub(rhs)
    }

    #[inline]
    fn wrapping_mul(self, rhs: Self) -> Self {
        self.wrapping_mul(rhs)
    }

    #[inline]
    fn min(self, rhs: Self) -> Self {
        Ord::min(self, rhs)
    }

    #[inline]
    fn max(self, rhs: Self) -> Self {
        Ord::max(self, rhs)
    }
}

impl Sample for u16 {
    const ZERO: Self = 0;
    const ONE: Self = 1;
    const MIN: Self = u16::MIN;
    const MAX: Self = u16::MAX;
    const UNIT: f32 = 65535.0;

    #[inline]
    fn as_f32(self) -> f32 {
        self as f32
    }

    #[inline]
    fn from_f32(v: f32) -> Self {
        // `round half up` for the non-negative range; `as` casts saturate.
        (v.clamp(0.0, 65535.0) + 0.5) as u16
    }

    #[inline]
    fn saturating_add(self, rhs: Self) -> Self {
        self.saturating_add(rhs)
    }

    #[inline]
    fn saturating_sub(self, rhs: Self) -> Self {
        self.saturating_sub(rhs)
    }

    #[inline]
    fn saturating_mul(self, rhs: Self) -> Self {
        self.saturating_mul(rhs)
    }

    #[inline]
    fn wrapping_add(self, rhs: Self) -> Self {
        self.wrapping_add(rhs)
    }

    #[inline]
    fn wrapping_sub(self, rhs: Self) -> Self {
        self.wrapping_sub(rhs)
    }

    #[inline]
    fn wrapping_mul(self, rhs: Self) -> Self {
        self.wrapping_mul(rhs)
    }

    #[inline]
    fn min(self, rhs: Self) -> Self {
        Ord::min(self, rhs)
    }

    #[inline]
    fn max(self, rhs: Self) -> Self {
        Ord::max(self, rhs)
    }
}

impl Sample for f32 {
    const ZERO: Self = 0.0;
    const ONE: Self = 1.0;
    const MIN: Self = f32::MIN;
    const MAX: Self = f32::MAX;
    const UNIT: f32 = 1.0;

    #[inline]
    fn as_f32(self) -> f32 {
        self
    }

    #[inline]
    fn from_f32(v: f32) -> Self {
        v
    }

    #[inline]
    fn saturating_add(self, rhs: Self) -> Self {
        self + rhs
    }

    #[inline]
    fn saturating_sub(self, rhs: Self) -> Self {
        self - rhs
    }

    #[inline]
    fn saturating_mul(self, rhs: Self) -> Self {
        self * rhs
    }

    #[inline]
    fn wrapping_add(self, rhs: Self) -> Self {
        self + rhs
    }

    #[inline]
    fn wrapping_sub(self, rhs: Self) -> Self {
        self - rhs
    }

    #[inline]
    fn wrapping_mul(self, rhs: Self) -> Self {
        self * rhs
    }

    #[inline]
    fn min(self, rhs: Self) -> Self {
        f32::min(self, rhs)
    }

    #[inline]
    fn max(self, rhs: Self) -> Self {
        f32::max(self, rhs)
    }
}

/// A fixed-size multi-channel pixel value.
///
/// `C` channels are stored interleaved: for `C = 3` this is an RGB/BGR
/// triplet, for `C = 1` a scalar, for `C = 4` RGBA.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct Pixel<T: Sample, const C: usize> {
    /// The channel values.
    pub channels: [T; C],
}

impl<T: Sample, const C: usize> Default for Pixel<T, C> {
    #[inline]
    fn default() -> Self {
        Self::splat(T::ZERO)
    }
}

impl<T: Sample, const C: usize> Pixel<T, C> {
    /// Construct from an array of channel values.
    #[inline]
    pub const fn new(channels: [T; C]) -> Self {
        Self { channels }
    }

    /// A pixel filled with `value` on every channel.
    #[inline]
    pub const fn splat(value: T) -> Self {
        Self {
            channels: [value; C],
        }
    }

    /// Number of channels in this pixel.
    #[inline]
    pub const fn channels() -> usize {
        C
    }

    /// Read channel `index`.
    #[inline]
    pub fn channel(&self, index: usize) -> T {
        self.channels[index]
    }

    /// Convert every channel to `f32`.
    #[inline]
    pub fn as_f32(&self) -> [f32; C] {
        let mut out = [0.0f32; C];
        for (dst, src) in out.iter_mut().zip(self.channels.iter()) {
            *dst = src.as_f32();
        }
        out
    }
}

impl<T: Sample, const C: usize> From<[T; C]> for Pixel<T, C> {
    #[inline]
    fn from(channels: [T; C]) -> Self {
        Self::new(channels)
    }
}

impl<T: Sample> Pixel<T, 1> {
    /// The scalar value of a single-channel pixel.
    #[inline]
    pub fn scalar(&self) -> T {
        self.channels[0]
    }
}

/// Per-channel arithmetic on pixels (wrapping for integers).
impl<T: Sample, const C: usize> core::ops::Add for Pixel<T, C> {
    type Output = Self;

    #[inline]
    fn add(self, rhs: Self) -> Self {
        let mut out = self;
        for (d, s) in out.channels.iter_mut().zip(rhs.channels.iter()) {
            *d = d.wrapping_add(*s);
        }
        out
    }
}

/// Per-channel subtraction on pixels (wrapping for integers).
impl<T: Sample, const C: usize> core::ops::Sub for Pixel<T, C> {
    type Output = Self;

    #[inline]
    fn sub(self, rhs: Self) -> Self {
        let mut out = self;
        for (d, s) in out.channels.iter_mut().zip(rhs.channels.iter()) {
            *d = d.wrapping_sub(*s);
        }
        out
    }
}

/// Sealed marker for sample types whose in-memory representation is a plain
/// byte sequence that can be viewed directly through
/// [`crate::image::ImageBuf::as_bytes`].
///
/// Only `u8` implements it: viewing a `u16`/`f32` buffer as raw bytes via
/// `align_to::<u8>` would otherwise be unsound (the `debug_assert!` that
/// guarded it was not enforced by the type system). Making `as_bytes` bound on
/// [`ByteRepr`] instead of the general [`Sample`] closes that gap.
///
/// The trait has no public methods and is not meant to be implemented outside
/// this crate, so it stays effectively sealed.
pub trait ByteRepr: Sample {}

impl ByteRepr for u8 {}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn sample_saturating() {
        assert_eq!(u8::MAX.saturating_add(1), u8::MAX);
        assert_eq!(0u8.saturating_sub(1), 0);
        assert_eq!(u16::MAX.saturating_add(1), u16::MAX);
        assert_eq!(255.0f32.saturating_add(1.0), 256.0);
    }

    #[test]
    fn sample_wrapping() {
        assert_eq!(u8::MAX.wrapping_add(1), 0);
        assert_eq!(0u8.wrapping_sub(1), 255);
    }

    #[test]
    fn sample_from_f32_roundtrip() {
        assert_eq!(u8::from_f32(0.0), 0);
        assert_eq!(u8::from_f32(255.0), 255);
        assert_eq!(u8::from_f32(-10.0), 0);
        assert_eq!(u8::from_f32(300.0), 255);
        assert_eq!(u8::from_f32(127.6), 128);
        assert_eq!(u16::from_f32(65535.0), 65535);
        assert_eq!(f32::from_f32(1.5), 1.5);
    }

    #[test]
    fn pixel_channels() {
        let p = Pixel::<u8, 3>::new([10, 20, 30]);
        assert_eq!(Pixel::<u8, 3>::channels(), 3);
        assert_eq!(p.channel(1), 20);
        assert_eq!(p.as_f32(), [10.0, 20.0, 30.0]);
    }

    #[test]
    fn pixel_arithmetic() {
        let a = Pixel::<u8, 3>::new([250, 0, 5]);
        let b = Pixel::<u8, 3>::new([10, 255, 2]);
        assert_eq!(a + b, Pixel::new([4, 255, 7]));
        assert_eq!(a - b, Pixel::new([240, 1, 3]));
    }
}