M-Labs/nalgebra
3
0
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add some documentation for Rotation.

Browse Source
This commit is contained in:
sebcrozet 2018-11-03 13:35:56 +01:00 committed by Sébastien Crozet
parent bec0777d7f
commit c24caa311f
4 changed files with 117 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
src/geometry/isometry.rs
View File

@ -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<N, D>,
Owned<N, D>: Serialize"
))
Owned<N, D>: Serialize"))
)]
#[cfg_attr(
feature = "serde-serialize",
serde(bound(
deserialize = "R: Deserialize<'de>,
serde(bound(deserialize = "R: Deserialize<'de>,
DefaultAllocator: Allocator<N, D>,
Owned<N, D>: Deserialize<'de>"
))
Owned<N, D>: Deserialize<'de>"))
)]
pub struct Isometry<N: Real, D: DimName, R>
where DefaultAllocator: Allocator<N, D>
@ -96,7 +92,8 @@ impl<N: Real, D: DimName + Copy, R: Rotation<Point<N, D>> + Copy> Copy for Isome
where
DefaultAllocator: Allocator<N, D>,
Owned<N, D>: Copy,
{}
{
}
impl<N: Real, D: DimName, R: Rotation<Point<N, D>> + Clone> Clone for Isometry<N, D, R>
where DefaultAllocator: Allocator<N, D>
@ -283,7 +280,6 @@ where DefaultAllocator: Allocator<N, D>
/// 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<N: Real, D: DimName, R> Eq for Isometry<N, D, R>
where
R: Rotation<Point<N, D>> + Eq,
DefaultAllocator: Allocator<N, D>,
{}
{
}
impl<N: Real, D: DimName, R> PartialEq for Isometry<N, D, R>
where

2
src/geometry/quaternion.rs
View File

@ -941,7 +941,6 @@ impl<N: Real> UnitQuaternion<N> {
/// 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<N: Real> UnitQuaternion<N> {
/// 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]

110
src/geometry/rotation.rs
View File

@ -43,7 +43,8 @@ impl<N: Scalar, D: DimName> Copy for Rotation<N, D>
where
DefaultAllocator: Allocator<N, D, D>,
<DefaultAllocator as Allocator<N, D, D>>::Buffer: Copy,
{}
{
}
impl<N: Scalar, D: DimName> Clone for Rotation<N, D>
where
@ -107,28 +108,92 @@ impl<N: Scalar, D: DimName> Rotation<N, D>
where DefaultAllocator: Allocator<N, D, D>
{
/// 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<N, D> {
&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<N, D> {
&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<N, D> {
&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<N, D> {
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<N, DimNameSum<D, U1>>
where
@ -145,6 +210,25 @@ where DefaultAllocator: Allocator<N, D, D>
/// 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<N, D>) -> Rotation<N, D> {
assert!(
@ -162,6 +246,22 @@ where DefaultAllocator: Allocator<N, D, D>
}
/// 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<N, D> {
self.transpose()

8
src/geometry/rotation_ops.rs
View File

@ -138,16 +138,16 @@ md_assign_impl_all!(
MulAssign, mul_assign;
(D, D), (D, D) for D: DimName;
self: Rotation<N, D>, right: Rotation<N, D>;
[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<N, D>, right: Rotation<N, D>;
[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