pub type Rotation3<T> = Rotation<T, 3>;
Expand description
A 3-dimensional rotation matrix.
Because this is an alias, not all its methods are listed here. See the Rotation
type too.
Aliased Type§
struct Rotation3<T> { /* private fields */ }
Implementations§
source§impl<T: SimdRealField> Rotation3<T>
impl<T: SimdRealField> Rotation3<T>
sourcepub fn slerp(&self, other: &Self, t: T) -> Selfwhere
T: RealField,
pub fn slerp(&self, other: &Self, t: T) -> Selfwhere
T: RealField,
Spherical linear interpolation between two rotation matrices.
Panics if the angle between both rotations is 180 degrees (in which case the interpolation
is not well-defined). Use .try_slerp
instead to avoid the panic.
§Examples:
let q1 = Rotation3::from_euler_angles(std::f32::consts::FRAC_PI_4, 0.0, 0.0);
let q2 = Rotation3::from_euler_angles(-std::f32::consts::PI, 0.0, 0.0);
let q = q1.slerp(&q2, 1.0 / 3.0);
assert_eq!(q.euler_angles(), (std::f32::consts::FRAC_PI_2, 0.0, 0.0));
sourcepub fn try_slerp(&self, other: &Self, t: T, epsilon: T) -> Option<Self>where
T: RealField,
pub fn try_slerp(&self, other: &Self, t: T, epsilon: T) -> Option<Self>where
T: RealField,
Computes the spherical linear interpolation between two rotation matrices or returns None
if both rotations are approximately 180 degrees apart (in which case the interpolation is
not well-defined).
§Arguments
self
: the first rotation to interpolate from.other
: the second rotation to interpolate toward.t
: the interpolation parameter. Should be between 0 and 1.epsilon
: the value below which the sinus of the angle separating both rotations must be to returnNone
.
source§impl<T: SimdRealField> Rotation3<T>where
T::Element: SimdRealField,
impl<T: SimdRealField> Rotation3<T>where
T::Element: SimdRealField,
§Construction from a 3D axis and/or angles
sourcepub fn new<SB: Storage<T, U3>>(axisangle: Vector<T, U3, SB>) -> Self
pub fn new<SB: Storage<T, U3>>(axisangle: Vector<T, U3, SB>) -> Self
Builds a 3 dimensional rotation matrix from an axis and an angle.
§Arguments
axisangle
- A vector representing the rotation. Its magnitude is the amount of rotation in radian. Its direction is the axis of rotation.
§Example
let axisangle = Vector3::y() * f32::consts::FRAC_PI_2;
// Point and vector being transformed in the tests.
let pt = Point3::new(4.0, 5.0, 6.0);
let vec = Vector3::new(4.0, 5.0, 6.0);
let rot = Rotation3::new(axisangle);
assert_relative_eq!(rot * pt, Point3::new(6.0, 5.0, -4.0), epsilon = 1.0e-6);
assert_relative_eq!(rot * vec, Vector3::new(6.0, 5.0, -4.0), epsilon = 1.0e-6);
// A zero vector yields an identity.
assert_eq!(Rotation3::new(Vector3::<f32>::zeros()), Rotation3::identity());
sourcepub fn from_scaled_axis<SB: Storage<T, U3>>(
axisangle: Vector<T, U3, SB>
) -> Self
pub fn from_scaled_axis<SB: Storage<T, U3>>( axisangle: Vector<T, U3, SB> ) -> Self
Builds a 3D rotation matrix from an axis scaled by the rotation angle.
This is the same as Self::new(axisangle)
.
§Example
let axisangle = Vector3::y() * f32::consts::FRAC_PI_2;
// Point and vector being transformed in the tests.
let pt = Point3::new(4.0, 5.0, 6.0);
let vec = Vector3::new(4.0, 5.0, 6.0);
let rot = Rotation3::new(axisangle);
assert_relative_eq!(rot * pt, Point3::new(6.0, 5.0, -4.0), epsilon = 1.0e-6);
assert_relative_eq!(rot * vec, Vector3::new(6.0, 5.0, -4.0), epsilon = 1.0e-6);
// A zero vector yields an identity.
assert_eq!(Rotation3::from_scaled_axis(Vector3::<f32>::zeros()), Rotation3::identity());
sourcepub fn from_axis_angle<SB>(axis: &Unit<Vector<T, U3, SB>>, angle: T) -> Self
pub fn from_axis_angle<SB>(axis: &Unit<Vector<T, U3, SB>>, angle: T) -> Self
Builds a 3D rotation matrix from an axis and a rotation angle.
§Example
let axis = Vector3::y_axis();
let angle = f32::consts::FRAC_PI_2;
// Point and vector being transformed in the tests.
let pt = Point3::new(4.0, 5.0, 6.0);
let vec = Vector3::new(4.0, 5.0, 6.0);
let rot = Rotation3::from_axis_angle(&axis, angle);
assert_eq!(rot.axis().unwrap(), axis);
assert_eq!(rot.angle(), angle);
assert_relative_eq!(rot * pt, Point3::new(6.0, 5.0, -4.0), epsilon = 1.0e-6);
assert_relative_eq!(rot * vec, Vector3::new(6.0, 5.0, -4.0), epsilon = 1.0e-6);
// A zero vector yields an identity.
assert_eq!(Rotation3::from_scaled_axis(Vector3::<f32>::zeros()), Rotation3::identity());
sourcepub fn from_euler_angles(roll: T, pitch: T, yaw: T) -> Self
pub fn from_euler_angles(roll: T, pitch: T, yaw: T) -> Self
Creates a new rotation from Euler angles.
The primitive rotations are applied in order: 1 roll − 2 pitch − 3 yaw.
§Example
let rot = Rotation3::from_euler_angles(0.1, 0.2, 0.3);
let euler = rot.euler_angles();
assert_relative_eq!(euler.0, 0.1, epsilon = 1.0e-6);
assert_relative_eq!(euler.1, 0.2, epsilon = 1.0e-6);
assert_relative_eq!(euler.2, 0.3, epsilon = 1.0e-6);
source§impl<T: SimdRealField> Rotation3<T>where
T::Element: SimdRealField,
impl<T: SimdRealField> Rotation3<T>where
T::Element: SimdRealField,
§Construction from a 3D eye position and target point
sourcepub fn face_towards<SB, SC>(
dir: &Vector<T, U3, SB>,
up: &Vector<T, U3, SC>
) -> Self
pub fn face_towards<SB, SC>( dir: &Vector<T, U3, SB>, up: &Vector<T, U3, SC> ) -> Self
Creates a rotation that corresponds to the local frame of an observer standing at the
origin and looking toward dir
.
It maps the z
axis to the direction dir
.
§Arguments
- dir - The look direction, that is, direction the matrix
z
axis will be aligned with. - up - The vertical direction. The only requirement of this parameter is to not be
collinear to
dir
. Non-collinearity is not checked.
§Example
let dir = Vector3::new(1.0, 2.0, 3.0);
let up = Vector3::y();
let rot = Rotation3::face_towards(&dir, &up);
assert_relative_eq!(rot * Vector3::z(), dir.normalize());
sourcepub fn new_observer_frames<SB, SC>(
dir: &Vector<T, U3, SB>,
up: &Vector<T, U3, SC>
) -> Self
👎Deprecated: renamed to face_towards
pub fn new_observer_frames<SB, SC>( dir: &Vector<T, U3, SB>, up: &Vector<T, U3, SC> ) -> Self
face_towards
Deprecated: Use Rotation3::face_towards
instead.
sourcepub fn look_at_rh<SB, SC>(
dir: &Vector<T, U3, SB>,
up: &Vector<T, U3, SC>
) -> Self
pub fn look_at_rh<SB, SC>( dir: &Vector<T, U3, SB>, up: &Vector<T, U3, SC> ) -> Self
Builds a right-handed look-at view matrix without translation.
It maps the view direction dir
to the negative z
axis.
This conforms to the common notion of right handed look-at matrix from the computer
graphics community.
§Arguments
- dir - The direction toward which the camera looks.
- up - A vector approximately aligned with required the vertical axis. The only
requirement of this parameter is to not be collinear to
dir
.
§Example
let dir = Vector3::new(1.0, 2.0, 3.0);
let up = Vector3::y();
let rot = Rotation3::look_at_rh(&dir, &up);
assert_relative_eq!(rot * dir.normalize(), -Vector3::z());
sourcepub fn look_at_lh<SB, SC>(
dir: &Vector<T, U3, SB>,
up: &Vector<T, U3, SC>
) -> Self
pub fn look_at_lh<SB, SC>( dir: &Vector<T, U3, SB>, up: &Vector<T, U3, SC> ) -> Self
Builds a left-handed look-at view matrix without translation.
It maps the view direction dir
to the positive z
axis.
This conforms to the common notion of left handed look-at matrix from the computer
graphics community.
§Arguments
- dir - The direction toward which the camera looks.
- up - A vector approximately aligned with required the vertical axis. The only
requirement of this parameter is to not be collinear to
dir
.
§Example
let dir = Vector3::new(1.0, 2.0, 3.0);
let up = Vector3::y();
let rot = Rotation3::look_at_lh(&dir, &up);
assert_relative_eq!(rot * dir.normalize(), Vector3::z());
source§impl<T: SimdRealField> Rotation3<T>where
T::Element: SimdRealField,
impl<T: SimdRealField> Rotation3<T>where
T::Element: SimdRealField,
§Construction from an existing 3D matrix or rotations
sourcepub fn rotation_between<SB, SC>(
a: &Vector<T, U3, SB>,
b: &Vector<T, U3, SC>
) -> Option<Self>
pub fn rotation_between<SB, SC>( a: &Vector<T, U3, SB>, b: &Vector<T, U3, SC> ) -> Option<Self>
The rotation matrix required to align a
and b
but with its angle.
This is the rotation R
such that (R * a).angle(b) == 0 && (R * a).dot(b).is_positive()
.
§Example
let a = Vector3::new(1.0, 2.0, 3.0);
let b = Vector3::new(3.0, 1.0, 2.0);
let rot = Rotation3::rotation_between(&a, &b).unwrap();
assert_relative_eq!(rot * a, b, epsilon = 1.0e-6);
assert_relative_eq!(rot.inverse() * b, a, epsilon = 1.0e-6);
sourcepub fn scaled_rotation_between<SB, SC>(
a: &Vector<T, U3, SB>,
b: &Vector<T, U3, SC>,
n: T
) -> Option<Self>
pub fn scaled_rotation_between<SB, SC>( a: &Vector<T, U3, SB>, b: &Vector<T, U3, SC>, n: T ) -> Option<Self>
The smallest rotation needed to make a
and b
collinear and point toward the same
direction, raised to the power s
.
§Example
let a = Vector3::new(1.0, 2.0, 3.0);
let b = Vector3::new(3.0, 1.0, 2.0);
let rot2 = Rotation3::scaled_rotation_between(&a, &b, 0.2).unwrap();
let rot5 = Rotation3::scaled_rotation_between(&a, &b, 0.5).unwrap();
assert_relative_eq!(rot2 * rot2 * rot2 * rot2 * rot2 * a, b, epsilon = 1.0e-6);
assert_relative_eq!(rot5 * rot5 * a, b, epsilon = 1.0e-6);
sourcepub fn rotation_to(&self, other: &Self) -> Self
pub fn rotation_to(&self, other: &Self) -> Self
The rotation matrix needed to make self
and other
coincide.
The result is such that: self.rotation_to(other) * self == other
.
§Example
let rot1 = Rotation3::from_axis_angle(&Vector3::y_axis(), 1.0);
let rot2 = Rotation3::from_axis_angle(&Vector3::x_axis(), 0.1);
let rot_to = rot1.rotation_to(&rot2);
assert_relative_eq!(rot_to * rot1, rot2, epsilon = 1.0e-6);
sourcepub fn powf(&self, n: T) -> Selfwhere
T: RealField,
pub fn powf(&self, n: T) -> Selfwhere
T: RealField,
Raise the rotation to a given floating power, i.e., returns the rotation with the same
axis as self
and an angle equal to self.angle()
multiplied by n
.
§Example
let axis = Unit::new_normalize(Vector3::new(1.0, 2.0, 3.0));
let angle = 1.2;
let rot = Rotation3::from_axis_angle(&axis, angle);
let pow = rot.powf(2.0);
assert_relative_eq!(pow.axis().unwrap(), axis, epsilon = 1.0e-6);
assert_eq!(pow.angle(), 2.4);
sourcepub fn from_basis_unchecked(basis: &[Vector3<T>; 3]) -> Self
pub fn from_basis_unchecked(basis: &[Vector3<T>; 3]) -> Self
Builds a rotation from a basis assumed to be orthonormal.
In order to get a valid rotation matrix, the input must be an orthonormal basis, i.e., all vectors are normalized, and the are all orthogonal to each other. These invariants are not checked by this method.
sourcepub fn from_matrix(m: &Matrix3<T>) -> Selfwhere
T: RealField,
pub fn from_matrix(m: &Matrix3<T>) -> Selfwhere
T: RealField,
Builds a rotation matrix by extracting the rotation part of the given transformation m
.
This is an iterative method. See .from_matrix_eps
to provide mover
convergence parameters and starting solution.
This implements “A Robust Method to Extract the Rotational Part of Deformations” by Müller et al.
sourcepub fn from_matrix_eps(
m: &Matrix3<T>,
eps: T,
max_iter: usize,
guess: Self
) -> Selfwhere
T: RealField,
pub fn from_matrix_eps(
m: &Matrix3<T>,
eps: T,
max_iter: usize,
guess: Self
) -> Selfwhere
T: RealField,
Builds a rotation matrix by extracting the rotation part of the given transformation m
.
This implements “A Robust Method to Extract the Rotational Part of Deformations” by Müller et al.
§Parameters
m
: the matrix from which the rotational part is to be extracted.eps
: the angular errors tolerated between the current rotation and the optimal one.max_iter
: the maximum number of iterations. Loops indefinitely until convergence if set to0
.guess
: a guess of the solution. Convergence will be significantly faster if an initial solution close to the actual solution is provided. Can be set toRotation3::identity()
if no other guesses come to mind.
sourcepub fn renormalize(&mut self)where
T: RealField,
pub fn renormalize(&mut self)where
T: RealField,
Ensure this rotation is an orthonormal rotation matrix. This is useful when repeated computations might cause the matrix from progressively not being orthonormal anymore.
source§impl<T: SimdRealField> Rotation3<T>
impl<T: SimdRealField> Rotation3<T>
§3D axis and angle extraction
sourcepub fn angle(&self) -> T
pub fn angle(&self) -> T
The rotation angle in [0; pi].
§Example
let axis = Unit::new_normalize(Vector3::new(1.0, 2.0, 3.0));
let rot = Rotation3::from_axis_angle(&axis, 1.78);
assert_relative_eq!(rot.angle(), 1.78);
sourcepub fn axis(&self) -> Option<Unit<Vector3<T>>>where
T: RealField,
pub fn axis(&self) -> Option<Unit<Vector3<T>>>where
T: RealField,
The rotation axis. Returns None
if the rotation angle is zero or PI.
§Example
let axis = Unit::new_normalize(Vector3::new(1.0, 2.0, 3.0));
let angle = 1.2;
let rot = Rotation3::from_axis_angle(&axis, angle);
assert_relative_eq!(rot.axis().unwrap(), axis);
// Case with a zero angle.
let rot = Rotation3::from_axis_angle(&axis, 0.0);
assert!(rot.axis().is_none());
sourcepub fn scaled_axis(&self) -> Vector3<T>where
T: RealField,
pub fn scaled_axis(&self) -> Vector3<T>where
T: RealField,
The rotation axis multiplied by the rotation angle.
§Example
let axisangle = Vector3::new(0.1, 0.2, 0.3);
let rot = Rotation3::new(axisangle);
assert_relative_eq!(rot.scaled_axis(), axisangle, epsilon = 1.0e-6);
sourcepub fn axis_angle(&self) -> Option<(Unit<Vector3<T>>, T)>where
T: RealField,
pub fn axis_angle(&self) -> Option<(Unit<Vector3<T>>, T)>where
T: RealField,
The rotation axis and angle in (0, pi] of this rotation matrix.
Returns None
if the angle is zero.
§Example
let axis = Unit::new_normalize(Vector3::new(1.0, 2.0, 3.0));
let angle = 1.2;
let rot = Rotation3::from_axis_angle(&axis, angle);
let axis_angle = rot.axis_angle().unwrap();
assert_relative_eq!(axis_angle.0, axis);
assert_relative_eq!(axis_angle.1, angle);
// Case with a zero angle.
let rot = Rotation3::from_axis_angle(&axis, 0.0);
assert!(rot.axis_angle().is_none());
sourcepub fn angle_to(&self, other: &Self) -> Twhere
T::Element: SimdRealField,
pub fn angle_to(&self, other: &Self) -> Twhere
T::Element: SimdRealField,
The rotation angle needed to make self
and other
coincide.
§Example
let rot1 = Rotation3::from_axis_angle(&Vector3::y_axis(), 1.0);
let rot2 = Rotation3::from_axis_angle(&Vector3::x_axis(), 0.1);
assert_relative_eq!(rot1.angle_to(&rot2), 1.0045657, epsilon = 1.0e-6);
sourcepub fn to_euler_angles(self) -> (T, T, T)where
T: RealField,
👎Deprecated: This is renamed to use .euler_angles()
.
pub fn to_euler_angles(self) -> (T, T, T)where
T: RealField,
.euler_angles()
.Creates Euler angles from a rotation.
The angles are produced in the form (roll, pitch, yaw).
sourcepub fn euler_angles(&self) -> (T, T, T)where
T: RealField,
pub fn euler_angles(&self) -> (T, T, T)where
T: RealField,
Euler angles corresponding to this rotation from a rotation.
The angles are produced in the form (roll, pitch, yaw).
§Example
let rot = Rotation3::from_euler_angles(0.1, 0.2, 0.3);
let euler = rot.euler_angles();
assert_relative_eq!(euler.0, 0.1, epsilon = 1.0e-6);
assert_relative_eq!(euler.1, 0.2, epsilon = 1.0e-6);
assert_relative_eq!(euler.2, 0.3, epsilon = 1.0e-6);
sourcepub fn euler_angles_ordered(
&self,
seq: [Unit<Vector3<T>>; 3],
extrinsic: bool
) -> ([T; 3], bool)
pub fn euler_angles_ordered( &self, seq: [Unit<Vector3<T>>; 3], extrinsic: bool ) -> ([T; 3], bool)
Represent this rotation as Euler angles.
Returns the angles produced in the order provided by seq parameter, along with the observability flag. The Euler axes passed to seq must form an orthonormal basis. If the rotation is gimbal locked, then the observability flag is false.
§Panics
Panics if the Euler axes in seq
are not orthonormal.
§Example 1:
use std::f64::consts::PI;
use approx::assert_relative_eq;
use nalgebra::{Matrix3, Rotation3, Unit, Vector3};
// 3-1-2
let n = [
Unit::new_unchecked(Vector3::new(0.0, 0.0, 1.0)),
Unit::new_unchecked(Vector3::new(1.0, 0.0, 0.0)),
Unit::new_unchecked(Vector3::new(0.0, 1.0, 0.0)),
];
let r1 = Rotation3::from_axis_angle(&n[2], 20.0 * PI / 180.0);
let r2 = Rotation3::from_axis_angle(&n[1], 30.0 * PI / 180.0);
let r3 = Rotation3::from_axis_angle(&n[0], 45.0 * PI / 180.0);
let d = r3 * r2 * r1;
let (angles, observable) = d.euler_angles_ordered(n, false);
assert!(observable);
assert_relative_eq!(angles[0] * 180.0 / PI, 45.0, epsilon = 1e-12);
assert_relative_eq!(angles[1] * 180.0 / PI, 30.0, epsilon = 1e-12);
assert_relative_eq!(angles[2] * 180.0 / PI, 20.0, epsilon = 1e-12);
§Example 2:
use std::f64::consts::PI;
use approx::assert_relative_eq;
use nalgebra::{Matrix3, Rotation3, Unit, Vector3};
let sqrt_2 = 2.0_f64.sqrt();
let n = [
Unit::new_unchecked(Vector3::new(1.0 / sqrt_2, 1.0 / sqrt_2, 0.0)),
Unit::new_unchecked(Vector3::new(1.0 / sqrt_2, -1.0 / sqrt_2, 0.0)),
Unit::new_unchecked(Vector3::new(0.0, 0.0, 1.0)),
];
let r1 = Rotation3::from_axis_angle(&n[2], 20.0 * PI / 180.0);
let r2 = Rotation3::from_axis_angle(&n[1], 30.0 * PI / 180.0);
let r3 = Rotation3::from_axis_angle(&n[0], 45.0 * PI / 180.0);
let d = r3 * r2 * r1;
let (angles, observable) = d.euler_angles_ordered(n, false);
assert!(observable);
assert_relative_eq!(angles[0] * 180.0 / PI, 45.0, epsilon = 1e-12);
assert_relative_eq!(angles[1] * 180.0 / PI, 30.0, epsilon = 1e-12);
assert_relative_eq!(angles[2] * 180.0 / PI, 20.0, epsilon = 1e-12);
Algorithm based on: Malcolm D. Shuster, F. Landis Markley, “General formula for extraction the Euler angles”, Journal of guidance, control, and dynamics, vol. 29.1, pp. 215-221. 2006, and modified to be able to produce extrinsic rotations.
Trait Implementations§
source§impl<T: SimdRealField> From<Unit<Quaternion<T>>> for Rotation3<T>where
T::Element: SimdRealField,
impl<T: SimdRealField> From<Unit<Quaternion<T>>> for Rotation3<T>where
T::Element: SimdRealField,
source§fn from(q: UnitQuaternion<T>) -> Self
fn from(q: UnitQuaternion<T>) -> Self
source§impl<T1, T2> SubsetOf<Unit<DualQuaternion<T2>>> for Rotation3<T1>
impl<T1, T2> SubsetOf<Unit<DualQuaternion<T2>>> for Rotation3<T1>
source§fn to_superset(&self) -> UnitDualQuaternion<T2>
fn to_superset(&self) -> UnitDualQuaternion<T2>
self
to the equivalent element of its superset.source§fn is_in_subset(dq: &UnitDualQuaternion<T2>) -> bool
fn is_in_subset(dq: &UnitDualQuaternion<T2>) -> bool
element
is actually part of the subset Self
(and can be converted to it).source§fn from_superset_unchecked(dq: &UnitDualQuaternion<T2>) -> Self
fn from_superset_unchecked(dq: &UnitDualQuaternion<T2>) -> Self
self.to_superset
but without any property checks. Always succeeds.source§impl<T1, T2> SubsetOf<Unit<Quaternion<T2>>> for Rotation3<T1>
impl<T1, T2> SubsetOf<Unit<Quaternion<T2>>> for Rotation3<T1>
source§fn to_superset(&self) -> UnitQuaternion<T2>
fn to_superset(&self) -> UnitQuaternion<T2>
self
to the equivalent element of its superset.source§fn is_in_subset(q: &UnitQuaternion<T2>) -> bool
fn is_in_subset(q: &UnitQuaternion<T2>) -> bool
element
is actually part of the subset Self
(and can be converted to it).source§fn from_superset_unchecked(q: &UnitQuaternion<T2>) -> Self
fn from_superset_unchecked(q: &UnitQuaternion<T2>) -> Self
self.to_superset
but without any property checks. Always succeeds.