unicorn_hat/

rotation.rs

//! Rotation and coordinate system support for the display
//!
//! Allows rotating the coordinate system to match different physical orientations
//! of the Unicorn HAT, and choosing the origin location.

/// Coordinate system origin location
///
/// Determines where (0,0) is located on the display.
///
/// # Examples
///
/// ```
/// use unicorn_hat::Origin;
///
/// let origin = Origin::TopLeft;  // Default: (0,0) at top-left
/// let origin = Origin::BottomLeft;  // (0,0) at bottom-left (useful for bar graphs)
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Origin {
    /// Origin at top-left, Y increases downward (default)
    ///
    /// ```text
    /// (0,0) ──────► (7,0)
    ///   │
    ///   ▼
    /// (0,7)       (7,7)
    /// ```
    #[default]
    TopLeft,

    /// Origin at bottom-left, Y increases upward
    ///
    /// Useful for bar graphs and charts where Y represents a value.
    ///
    /// ```text
    /// (0,7)       (7,7)
    ///   ▲
    ///   │
    /// (0,0) ──────► (7,0)
    /// ```
    BottomLeft,
}

impl Origin {
    /// Transforms coordinates based on origin setting
    ///
    /// # Arguments
    ///
    /// * `x` - X coordinate (0-7)
    /// * `y` - Y coordinate (0-7)
    ///
    /// # Returns
    ///
    /// Tuple of (transformed_x, transformed_y) in top-left coordinate space
    pub fn apply(&self, x: usize, y: usize) -> (usize, usize) {
        match self {
            Origin::TopLeft => (x, y),
            Origin::BottomLeft => (x, 7 - y),
        }
    }
}

/// Rotation angles for the display
///
/// Rotations are applied clockwise from the default orientation.
///
/// # Examples
///
/// ```
/// use unicorn_hat::Rotate;
///
/// let rotation = Rotate::RotCW90;  // 90° clockwise
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Rotate {
    /// No rotation (default orientation)
    #[default]
    RotNone,
    /// 90° clockwise rotation
    RotCW90,
    /// 90° counter-clockwise rotation (270° clockwise)
    RotCCW90,
    /// 180° rotation
    Rot180,
}

impl Rotate {
    /// Applies rotation to an (x, y) coordinate
    ///
    /// Transforms coordinates according to the rotation angle.
    /// The grid is always 8x8, so coordinates stay in 0-7 range.
    ///
    /// # Arguments
    ///
    /// * `x` - Original x coordinate (0-7)
    /// * `y` - Original y coordinate (0-7)
    ///
    /// # Returns
    ///
    /// Tuple of (rotated_x, rotated_y)
    pub fn apply(&self, x: usize, y: usize) -> (usize, usize) {
        match self {
            Rotate::RotNone => (x, y),
            Rotate::RotCW90 => {
                // 90° clockwise: (x, y) -> (7-y, x)
                (7 - y, x)
            }
            Rotate::RotCCW90 => {
                // 90° counter-clockwise: (x, y) -> (y, 7-x)
                (y, 7 - x)
            }
            Rotate::Rot180 => {
                // 180°: (x, y) -> (7-x, 7-y)
                (7 - x, 7 - y)
            }
        }
    }
}

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

    #[test]
    fn test_rotate_none() {
        let r = Rotate::RotNone;
        assert_eq!(r.apply(0, 0), (0, 0));
        assert_eq!(r.apply(7, 0), (7, 0));
        assert_eq!(r.apply(0, 7), (0, 7));
        assert_eq!(r.apply(7, 7), (7, 7));
        assert_eq!(r.apply(3, 4), (3, 4));
    }

    #[test]
    fn test_rotate_cw90() {
        let r = Rotate::RotCW90;

        // Corners: 90° clockwise
        // Top-left (0,0) -> Top-right (7,0)
        assert_eq!(r.apply(0, 0), (7, 0));

        // Top-right (7,0) -> Bottom-right (7,7)
        assert_eq!(r.apply(7, 0), (7, 7));

        // Bottom-right (7,7) -> Bottom-left (0,7)
        assert_eq!(r.apply(7, 7), (0, 7));

        // Bottom-left (0,7) -> Top-left (0,0)
        assert_eq!(r.apply(0, 7), (0, 0));
    }

    #[test]
    fn test_rotate_ccw90() {
        let r = Rotate::RotCCW90;

        // Corners: 90° counter-clockwise
        // Top-left (0,0) -> Bottom-left (0,7)
        assert_eq!(r.apply(0, 0), (0, 7));

        // Top-right (7,0) -> Top-left (0,0)
        assert_eq!(r.apply(7, 0), (0, 0));

        // Bottom-right (7,7) -> Top-right (7,0)
        assert_eq!(r.apply(7, 7), (7, 0));

        // Bottom-left (0,7) -> Bottom-right (7,7)
        assert_eq!(r.apply(0, 7), (7, 7));
    }

    #[test]
    fn test_rotate_180() {
        let r = Rotate::Rot180;

        // Corners: 180°
        // Top-left (0,0) -> Bottom-right (7,7)
        assert_eq!(r.apply(0, 0), (7, 7));

        // Top-right (7,0) -> Bottom-left (0,7)
        assert_eq!(r.apply(7, 0), (0, 7));

        // Bottom-right (7,7) -> Top-left (0,0)
        assert_eq!(r.apply(7, 7), (0, 0));

        // Bottom-left (0,7) -> Top-right (7,0)
        assert_eq!(r.apply(0, 7), (7, 0));

        // Center should stay near center
        assert_eq!(r.apply(3, 3), (4, 4));
        assert_eq!(r.apply(4, 4), (3, 3));
    }

    #[test]
    fn test_double_rotation_cw90() {
        let r = Rotate::RotCW90;

        // Two 90° CW rotations = 180°
        let (x1, y1) = r.apply(2, 3);
        let (x2, y2) = r.apply(x1, y1);

        assert_eq!((x2, y2), Rotate::Rot180.apply(2, 3));
    }

    #[test]
    fn test_four_rotations_cw90() {
        let r = Rotate::RotCW90;

        // Four 90° CW rotations = back to original
        let (mut x, mut y) = (2, 3);
        for _ in 0..4 {
            (x, y) = r.apply(x, y);
        }

        assert_eq!((x, y), (2, 3));
    }

    #[test]
    fn test_cw90_then_ccw90() {
        // CW90 followed by CCW90 should return to original
        let original = (3, 5);
        let (x, y) = Rotate::RotCW90.apply(original.0, original.1);
        let (x, y) = Rotate::RotCCW90.apply(x, y);

        assert_eq!((x, y), original);
    }

    #[test]
    fn test_default_rotation() {
        assert_eq!(Rotate::default(), Rotate::RotNone);
    }

    #[test]
    fn test_rotation_bounds() {
        // All rotations should keep coordinates in bounds (0-7)
        let rotations = [Rotate::RotNone, Rotate::RotCW90, Rotate::RotCCW90, Rotate::Rot180];

        for rotation in &rotations {
            for y in 0..8 {
                for x in 0..8 {
                    let (rx, ry) = rotation.apply(x, y);
                    assert!(rx < 8, "Rotated x {} out of bounds for ({}, {}) with {:?}", rx, x, y, rotation);
                    assert!(ry < 8, "Rotated y {} out of bounds for ({}, {}) with {:?}", ry, x, y, rotation);
                }
            }
        }
    }

    // Origin tests
    #[test]
    fn test_origin_top_left() {
        let origin = Origin::TopLeft;
        assert_eq!(origin.apply(0, 0), (0, 0));
        assert_eq!(origin.apply(7, 0), (7, 0));
        assert_eq!(origin.apply(0, 7), (0, 7));
        assert_eq!(origin.apply(7, 7), (7, 7));
        assert_eq!(origin.apply(3, 4), (3, 4));
    }

    #[test]
    fn test_origin_bottom_left() {
        let origin = Origin::BottomLeft;
        // Bottom-left: (0,0) should map to (0,7) in top-left space
        assert_eq!(origin.apply(0, 0), (0, 7));
        assert_eq!(origin.apply(7, 0), (7, 7));
        assert_eq!(origin.apply(0, 7), (0, 0));
        assert_eq!(origin.apply(7, 7), (7, 0));
        assert_eq!(origin.apply(3, 4), (3, 3));
    }

    #[test]
    fn test_origin_default() {
        assert_eq!(Origin::default(), Origin::TopLeft);
    }

    #[test]
    fn test_origin_bounds() {
        let origins = [Origin::TopLeft, Origin::BottomLeft];

        for origin in &origins {
            for y in 0..8 {
                for x in 0..8 {
                    let (ox, oy) = origin.apply(x, y);
                    assert!(ox < 8, "Origin x {} out of bounds for ({}, {}) with {:?}", ox, x, y, origin);
                    assert!(oy < 8, "Origin y {} out of bounds for ({}, {}) with {:?}", oy, x, y, origin);
                }
            }
        }
    }
}