use approx::{AbsDiffEq, RelativeEq, UlpsEq}; use num::{One, Zero}; use std::fmt; use std::hash; #[cfg(feature = "abomonation-serialize")] use std::io::{Result as IOResult, Write}; #[cfg(feature = "serde-serialize")] use serde::{Deserialize, Deserializer, Serialize, Serializer}; #[cfg(feature = "serde-serialize")] use crate::base::storage::Owned; #[cfg(feature = "abomonation-serialize")] use abomonation::Abomonation; use alga::general::RealField; use crate::base::allocator::Allocator; use crate::base::dimension::{DimName, DimNameAdd, DimNameSum, U1}; use crate::base::{DefaultAllocator, MatrixN, Scalar, VectorN}; use crate::geometry::Point; /// A rotation matrix. #[repr(C)] #[derive(Debug)] pub struct Rotation where DefaultAllocator: Allocator { matrix: MatrixN, } impl hash::Hash for Rotation where DefaultAllocator: Allocator, >::Buffer: hash::Hash, { fn hash(&self, state: &mut H) { self.matrix.hash(state) } } impl Copy for Rotation where DefaultAllocator: Allocator, >::Buffer: Copy, { } impl Clone for Rotation where DefaultAllocator: Allocator, >::Buffer: Clone, { #[inline] fn clone(&self) -> Self { Self::from_matrix_unchecked(self.matrix.clone()) } } #[cfg(feature = "abomonation-serialize")] impl Abomonation for Rotation where N: Scalar + Copy, D: DimName, MatrixN: Abomonation, DefaultAllocator: Allocator, { unsafe fn entomb(&self, writer: &mut W) -> IOResult<()> { self.matrix.entomb(writer) } fn extent(&self) -> usize { self.matrix.extent() } unsafe fn exhume<'a, 'b>(&'a mut self, bytes: &'b mut [u8]) -> Option<&'b mut [u8]> { self.matrix.exhume(bytes) } } #[cfg(feature = "serde-serialize")] impl Serialize for Rotation where DefaultAllocator: Allocator, Owned: Serialize, { fn serialize(&self, serializer: S) -> Result where S: Serializer { self.matrix.serialize(serializer) } } #[cfg(feature = "serde-serialize")] impl<'a, N: Scalar + Copy, D: DimName> Deserialize<'a> for Rotation where DefaultAllocator: Allocator, Owned: Deserialize<'a>, { fn deserialize(deserializer: Des) -> Result where Des: Deserializer<'a> { let matrix = MatrixN::::deserialize(deserializer)?; Ok(Self::from_matrix_unchecked(matrix)) } } impl Rotation where DefaultAllocator: Allocator { /// A reference to the underlying matrix representation of this rotation. /// /// # Example /// ``` /// # use nalgebra::{Rotation2, Rotation3, Vector3, Matrix2, Matrix3}; /// # use std::f32; /// let rot = Rotation3::from_axis_angle(&Vector3::z_axis(), f32::consts::FRAC_PI_6); /// let expected = Matrix3::new(0.8660254, -0.5, 0.0, /// 0.5, 0.8660254, 0.0, /// 0.0, 0.0, 1.0); /// assert_eq!(*rot.matrix(), expected); /// /// /// let rot = Rotation2::new(f32::consts::FRAC_PI_6); /// let expected = Matrix2::new(0.8660254, -0.5, /// 0.5, 0.8660254); /// assert_eq!(*rot.matrix(), expected); /// ``` #[inline] pub fn matrix(&self) -> &MatrixN { &self.matrix } /// A mutable reference to the underlying matrix representation of this rotation. #[inline] #[deprecated(note = "Use `.matrix_mut_unchecked()` instead.")] pub unsafe fn matrix_mut(&mut self) -> &mut MatrixN { &mut self.matrix } /// A mutable reference to the underlying matrix representation of this rotation. /// /// This is suffixed by "_unchecked" because this allows the user to replace the matrix by another one that is /// non-square, non-inversible, or non-orthonormal. If one of those properties is broken, /// subsequent method calls may be UB. #[inline] pub fn matrix_mut_unchecked(&mut self) -> &mut MatrixN { &mut self.matrix } /// Unwraps the underlying matrix. /// /// # Example /// ``` /// # use nalgebra::{Rotation2, Rotation3, Vector3, Matrix2, Matrix3}; /// # use std::f32; /// let rot = Rotation3::from_axis_angle(&Vector3::z_axis(), f32::consts::FRAC_PI_6); /// let mat = rot.into_inner(); /// let expected = Matrix3::new(0.8660254, -0.5, 0.0, /// 0.5, 0.8660254, 0.0, /// 0.0, 0.0, 1.0); /// assert_eq!(mat, expected); /// /// /// let rot = Rotation2::new(f32::consts::FRAC_PI_6); /// let mat = rot.into_inner(); /// let expected = Matrix2::new(0.8660254, -0.5, /// 0.5, 0.8660254); /// assert_eq!(mat, expected); /// ``` #[inline] pub fn into_inner(self) -> MatrixN { self.matrix } /// Unwraps the underlying matrix. /// Deprecated: Use [Rotation::into_inner] instead. #[deprecated(note="use `.into_inner()` instead")] #[inline] pub fn unwrap(self) -> MatrixN { self.matrix } /// Converts this rotation into its equivalent homogeneous transformation matrix. /// /// This is the same as `self.into()`. /// /// # Example /// ``` /// # use nalgebra::{Rotation2, Rotation3, Vector3, Matrix3, Matrix4}; /// # use std::f32; /// let rot = Rotation3::from_axis_angle(&Vector3::z_axis(), f32::consts::FRAC_PI_6); /// let expected = Matrix4::new(0.8660254, -0.5, 0.0, 0.0, /// 0.5, 0.8660254, 0.0, 0.0, /// 0.0, 0.0, 1.0, 0.0, /// 0.0, 0.0, 0.0, 1.0); /// assert_eq!(rot.to_homogeneous(), expected); /// /// /// let rot = Rotation2::new(f32::consts::FRAC_PI_6); /// let expected = Matrix3::new(0.8660254, -0.5, 0.0, /// 0.5, 0.8660254, 0.0, /// 0.0, 0.0, 1.0); /// assert_eq!(rot.to_homogeneous(), expected); /// ``` #[inline] pub fn to_homogeneous(&self) -> MatrixN> where N: Zero + One, D: DimNameAdd, DefaultAllocator: Allocator, DimNameSum>, { // We could use `MatrixN::to_homogeneous()` here, but that would imply // adding the additional traits `DimAdd` and `IsNotStaticOne`. Maybe // these things will get nicer once specialization lands in Rust. let mut res = MatrixN::>::identity(); res.fixed_slice_mut::(0, 0).copy_from(&self.matrix); res } /// Creates a new rotation from the given square matrix. /// /// The matrix squareness is checked but not its orthonormality. /// /// # Example /// ``` /// # use nalgebra::{Rotation2, Rotation3, Matrix2, Matrix3}; /// # use std::f32; /// let mat = Matrix3::new(0.8660254, -0.5, 0.0, /// 0.5, 0.8660254, 0.0, /// 0.0, 0.0, 1.0); /// let rot = Rotation3::from_matrix_unchecked(mat); /// /// assert_eq!(*rot.matrix(), mat); /// /// /// let mat = Matrix2::new(0.8660254, -0.5, /// 0.5, 0.8660254); /// let rot = Rotation2::from_matrix_unchecked(mat); /// /// assert_eq!(*rot.matrix(), mat); /// ``` #[inline] pub fn from_matrix_unchecked(matrix: MatrixN) -> Self { assert!( matrix.is_square(), "Unable to create a rotation from a non-square matrix." ); Self { matrix: matrix } } /// Transposes `self`. /// /// Same as `.inverse()` because the inverse of a rotation matrix is its transform. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::{Rotation2, Rotation3, Vector3}; /// let rot = Rotation3::new(Vector3::new(1.0, 2.0, 3.0)); /// let tr_rot = rot.transpose(); /// assert_relative_eq!(rot * tr_rot, Rotation3::identity(), epsilon = 1.0e-6); /// assert_relative_eq!(tr_rot * rot, Rotation3::identity(), epsilon = 1.0e-6); /// /// let rot = Rotation2::new(1.2); /// let tr_rot = rot.transpose(); /// assert_relative_eq!(rot * tr_rot, Rotation2::identity(), epsilon = 1.0e-6); /// assert_relative_eq!(tr_rot * rot, Rotation2::identity(), epsilon = 1.0e-6); /// ``` #[inline] pub fn transpose(&self) -> Self { Self::from_matrix_unchecked(self.matrix.transpose()) } /// Inverts `self`. /// /// Same as `.transpose()` because the inverse of a rotation matrix is its transform. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::{Rotation2, Rotation3, Vector3}; /// let rot = Rotation3::new(Vector3::new(1.0, 2.0, 3.0)); /// let inv = rot.inverse(); /// assert_relative_eq!(rot * inv, Rotation3::identity(), epsilon = 1.0e-6); /// assert_relative_eq!(inv * rot, Rotation3::identity(), epsilon = 1.0e-6); /// /// let rot = Rotation2::new(1.2); /// let inv = rot.inverse(); /// assert_relative_eq!(rot * inv, Rotation2::identity(), epsilon = 1.0e-6); /// assert_relative_eq!(inv * rot, Rotation2::identity(), epsilon = 1.0e-6); /// ``` #[inline] pub fn inverse(&self) -> Self { self.transpose() } /// Transposes `self` in-place. /// /// Same as `.inverse_mut()` because the inverse of a rotation matrix is its transform. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::{Rotation2, Rotation3, Vector3}; /// let rot = Rotation3::new(Vector3::new(1.0, 2.0, 3.0)); /// let mut tr_rot = Rotation3::new(Vector3::new(1.0, 2.0, 3.0)); /// tr_rot.transpose_mut(); /// /// assert_relative_eq!(rot * tr_rot, Rotation3::identity(), epsilon = 1.0e-6); /// assert_relative_eq!(tr_rot * rot, Rotation3::identity(), epsilon = 1.0e-6); /// /// let rot = Rotation2::new(1.2); /// let mut tr_rot = Rotation2::new(1.2); /// tr_rot.transpose_mut(); /// /// assert_relative_eq!(rot * tr_rot, Rotation2::identity(), epsilon = 1.0e-6); /// assert_relative_eq!(tr_rot * rot, Rotation2::identity(), epsilon = 1.0e-6); /// ``` #[inline] pub fn transpose_mut(&mut self) { self.matrix.transpose_mut() } /// Inverts `self` in-place. /// /// Same as `.transpose_mut()` because the inverse of a rotation matrix is its transform. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::{Rotation2, Rotation3, Vector3}; /// let rot = Rotation3::new(Vector3::new(1.0, 2.0, 3.0)); /// let mut inv = Rotation3::new(Vector3::new(1.0, 2.0, 3.0)); /// inv.inverse_mut(); /// /// assert_relative_eq!(rot * inv, Rotation3::identity(), epsilon = 1.0e-6); /// assert_relative_eq!(inv * rot, Rotation3::identity(), epsilon = 1.0e-6); /// /// let rot = Rotation2::new(1.2); /// let mut inv = Rotation2::new(1.2); /// inv.inverse_mut(); /// /// assert_relative_eq!(rot * inv, Rotation2::identity(), epsilon = 1.0e-6); /// assert_relative_eq!(inv * rot, Rotation2::identity(), epsilon = 1.0e-6); /// ``` #[inline] pub fn inverse_mut(&mut self) { self.transpose_mut() } } impl Rotation where DefaultAllocator: Allocator + Allocator { /// Rotate the given point. /// /// This is the same as the multiplication `self * pt`. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Point3, Rotation2, Rotation3, UnitQuaternion, Vector3}; /// let rot = Rotation3::new(Vector3::y() * f32::consts::FRAC_PI_2); /// let transformed_point = rot.transform_point(&Point3::new(1.0, 2.0, 3.0)); /// /// assert_relative_eq!(transformed_point, Point3::new(3.0, 2.0, -1.0), epsilon = 1.0e-6); /// ``` #[inline] pub fn transform_point(&self, pt: &Point) -> Point { self * pt } /// Rotate the given vector. /// /// This is the same as the multiplication `self * v`. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Rotation2, Rotation3, UnitQuaternion, Vector3}; /// let rot = Rotation3::new(Vector3::y() * f32::consts::FRAC_PI_2); /// let transformed_vector = rot.transform_vector(&Vector3::new(1.0, 2.0, 3.0)); /// /// assert_relative_eq!(transformed_vector, Vector3::new(3.0, 2.0, -1.0), epsilon = 1.0e-6); /// ``` #[inline] pub fn transform_vector(&self, v: &VectorN) -> VectorN { self * v } /// Rotate the given point by the inverse of this rotation. This may be /// cheaper than inverting the rotation and then transforming the given /// point. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Point3, Rotation2, Rotation3, UnitQuaternion, Vector3}; /// let rot = Rotation3::new(Vector3::y() * f32::consts::FRAC_PI_2); /// let transformed_point = rot.inverse_transform_point(&Point3::new(1.0, 2.0, 3.0)); /// /// assert_relative_eq!(transformed_point, Point3::new(-3.0, 2.0, 1.0), epsilon = 1.0e-6); /// ``` #[inline] pub fn inverse_transform_point(&self, pt: &Point) -> Point { Point::from(self.inverse_transform_vector(&pt.coords)) } /// Rotate the given vector by the inverse of this rotation. This may be /// cheaper than inverting the rotation and then transforming the given /// vector. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Rotation2, Rotation3, UnitQuaternion, Vector3}; /// let rot = Rotation3::new(Vector3::y() * f32::consts::FRAC_PI_2); /// let transformed_vector = rot.inverse_transform_vector(&Vector3::new(1.0, 2.0, 3.0)); /// /// assert_relative_eq!(transformed_vector, Vector3::new(-3.0, 2.0, 1.0), epsilon = 1.0e-6); /// ``` #[inline] pub fn inverse_transform_vector(&self, v: &VectorN) -> VectorN { self.matrix().tr_mul(v) } } impl Eq for Rotation where DefaultAllocator: Allocator {} impl PartialEq for Rotation where DefaultAllocator: Allocator { #[inline] fn eq(&self, right: &Self) -> bool { self.matrix == right.matrix } } impl AbsDiffEq for Rotation where N: Scalar + Copy + AbsDiffEq, DefaultAllocator: Allocator, N::Epsilon: Copy, { type Epsilon = N::Epsilon; #[inline] fn default_epsilon() -> Self::Epsilon { N::default_epsilon() } #[inline] fn abs_diff_eq(&self, other: &Self, epsilon: Self::Epsilon) -> bool { self.matrix.abs_diff_eq(&other.matrix, epsilon) } } impl RelativeEq for Rotation where N: Scalar + Copy + RelativeEq, DefaultAllocator: Allocator, N::Epsilon: Copy, { #[inline] fn default_max_relative() -> Self::Epsilon { N::default_max_relative() } #[inline] fn relative_eq( &self, other: &Self, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool { self.matrix .relative_eq(&other.matrix, epsilon, max_relative) } } impl UlpsEq for Rotation where N: Scalar + Copy + UlpsEq, DefaultAllocator: Allocator, N::Epsilon: Copy, { #[inline] fn default_max_ulps() -> u32 { N::default_max_ulps() } #[inline] fn ulps_eq(&self, other: &Self, epsilon: Self::Epsilon, max_ulps: u32) -> bool { self.matrix.ulps_eq(&other.matrix, epsilon, max_ulps) } } /* * * Display * */ impl fmt::Display for Rotation where N: RealField + fmt::Display, DefaultAllocator: Allocator + Allocator, { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { let precision = f.precision().unwrap_or(3); writeln!(f, "Rotation matrix {{")?; write!(f, "{:.*}", precision, self.matrix)?; writeln!(f, "}}") } } // // /* // // * // // * Absolute // // * // // */ // // impl Absolute for $t { // // type AbsoluteValue = $submatrix; // // // // #[inline] // // fn abs(m: &$t) -> $submatrix { // // Absolute::abs(&m.submatrix) // // } // // }