diff --git a/src/geometry/isometry.rs b/src/geometry/isometry.rs index 01e78290..7ad3d4d9 100644 --- a/src/geometry/isometry.rs +++ b/src/geometry/isometry.rs @@ -26,19 +26,15 @@ use geometry::{Point, Translation}; #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))] #[cfg_attr( feature = "serde-serialize", - serde(bound( - serialize = "R: Serialize, + serde(bound(serialize = "R: Serialize, DefaultAllocator: Allocator, - Owned: Serialize" - )) + Owned: Serialize")) )] #[cfg_attr( feature = "serde-serialize", - serde(bound( - deserialize = "R: Deserialize<'de>, + serde(bound(deserialize = "R: Deserialize<'de>, DefaultAllocator: Allocator, - Owned: Deserialize<'de>" - )) + Owned: Deserialize<'de>")) )] pub struct Isometry where DefaultAllocator: Allocator @@ -96,7 +92,8 @@ impl> + Copy> Copy for Isome where DefaultAllocator: Allocator, Owned: Copy, -{} +{ +} impl> + Clone> Clone for Isometry where DefaultAllocator: Allocator @@ -283,7 +280,6 @@ where DefaultAllocator: Allocator /// 0.5, 0.8660254, 20.0, /// 0.0, 0.0, 1.0); /// - /// // The translation part should not have changed. /// assert_relative_eq!(iso.to_homogeneous(), expected, epsilon = 1.0e-6); /// ``` #[inline] @@ -305,7 +301,8 @@ impl Eq for Isometry where R: Rotation> + Eq, DefaultAllocator: Allocator, -{} +{ +} impl PartialEq for Isometry where diff --git a/src/geometry/quaternion.rs b/src/geometry/quaternion.rs index da311fb6..10b973b4 100644 --- a/src/geometry/quaternion.rs +++ b/src/geometry/quaternion.rs @@ -941,7 +941,6 @@ impl UnitQuaternion { /// 0.5, 0.8660254, 0.0, /// 0.0, 0.0, 1.0); /// - /// // The translation part should not have changed. /// assert_relative_eq!(*rot.matrix(), expected, epsilon = 1.0e-6); /// ``` #[inline] @@ -1019,7 +1018,6 @@ impl UnitQuaternion { /// 0.0, 0.0, 1.0, 0.0, /// 0.0, 0.0, 0.0, 1.0); /// - /// // The translation part should not have changed. /// assert_relative_eq!(rot.to_homogeneous(), expected, epsilon = 1.0e-6); /// ``` #[inline] diff --git a/src/geometry/rotation.rs b/src/geometry/rotation.rs index 72bbe3c5..2365aa9c 100644 --- a/src/geometry/rotation.rs +++ b/src/geometry/rotation.rs @@ -43,7 +43,8 @@ impl Copy for Rotation where DefaultAllocator: Allocator, >::Buffer: Copy, -{} +{ +} impl Clone for Rotation where @@ -107,28 +108,92 @@ 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. - /// - /// This is unsafe 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] + #[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.unwrap(); + /// 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.unwrap(); + /// let expected = Matrix2::new(0.8660254, -0.5, + /// 0.5, 0.8660254); + /// assert_eq!(mat, expected); + /// ``` #[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, Matrix2, 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 @@ -145,6 +210,25 @@ where DefaultAllocator: Allocator /// 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) -> Rotation { assert!( @@ -162,6 +246,22 @@ where DefaultAllocator: Allocator } /// Inverts `self`. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # 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) -> Rotation { self.transpose() diff --git a/src/geometry/rotation_ops.rs b/src/geometry/rotation_ops.rs index 344d6b3f..94bf6da2 100644 --- a/src/geometry/rotation_ops.rs +++ b/src/geometry/rotation_ops.rs @@ -138,16 +138,16 @@ md_assign_impl_all!( MulAssign, mul_assign; (D, D), (D, D) for D: DimName; self: Rotation, right: Rotation; - [val] => unsafe { self.matrix_mut().mul_assign(right.unwrap()) }; - [ref] => unsafe { self.matrix_mut().mul_assign(right.matrix()) }; + [val] => self.matrix_mut_unchecked().mul_assign(right.unwrap()); + [ref] => self.matrix_mut_unchecked().mul_assign(right.matrix()); ); md_assign_impl_all!( DivAssign, div_assign; (D, D), (D, D) for D: DimName; self: Rotation, right: Rotation; - [val] => unsafe { self.matrix_mut().mul_assign(right.inverse().unwrap()) }; - [ref] => unsafe { self.matrix_mut().mul_assign(right.inverse().matrix()) }; + [val] => self.matrix_mut_unchecked().mul_assign(right.inverse().unwrap()); + [ref] => self.matrix_mut_unchecked().mul_assign(right.inverse().matrix()); ); // Matrix *= Rotation