Type Definition nalgebra::geometry::Rotation3

type Rotation3<N> = Rotation<N, U3>;

A 3-dimensional rotation matrix.

Methods

impl<N: SimdRealField> Rotation3<N> where
    N::Element: SimdRealField, 

pub fn new<SB: Storage<N, U3>>(axisangle: Vector<N, 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());

pub fn from_matrix(m: &Matrix3<N>) -> Self where
    N: 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.

pub fn from_matrix_eps(
    m: &Matrix3<N>,
    eps: N,
    max_iter: usize,
    guess: Self
) -> Self where
    N: 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 to 0.
• 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 to Rotation3::identity() if no other guesses come to mind.

pub fn from_scaled_axis<SB: Storage<N, U3>>(
    axisangle: Vector<N, 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());

pub fn from_axis_angle<SB>(axis: &Unit<Vector<N, U3, SB>>, angle: N) -> Self where
    SB: Storage<N, U3>, 

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());

pub fn from_euler_angles(roll: N, pitch: N, yaw: N) -> 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);

pub fn to_euler_angles(&self) -> (N, N, N) where
    N: RealField, 

Deprecated:

This is renamed to use .euler_angles().

Creates Euler angles from a rotation.

The angles are produced in the form (roll, pitch, yaw).

pub fn euler_angles(&self) -> (N, N, N) where
    N: 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);

pub fn renormalize(&mut self) where
    N: 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.

pub fn face_towards<SB, SC>(
    dir: &Vector<N, U3, SB>,
    up: &Vector<N, U3, SC>
) -> Self where
    SB: Storage<N, U3>,
    SC: Storage<N, U3>, 

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());

pub fn new_observer_frames<SB, SC>(
    dir: &Vector<N, U3, SB>,
    up: &Vector<N, U3, SC>
) -> Self where
    SB: Storage<N, U3>,
    SC: Storage<N, U3>, 

Deprecated:

renamed to face_towards

Deprecated: Use [Rotation3::face_towards] instead.

pub fn look_at_rh<SB, SC>(
    dir: &Vector<N, U3, SB>,
    up: &Vector<N, U3, SC>
) -> Self where
    SB: Storage<N, U3>,
    SC: Storage<N, U3>, 

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());

pub fn look_at_lh<SB, SC>(
    dir: &Vector<N, U3, SB>,
    up: &Vector<N, U3, SC>
) -> Self where
    SB: Storage<N, U3>,
    SC: Storage<N, U3>, 

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());

pub fn rotation_between<SB, SC>(
    a: &Vector<N, U3, SB>,
    b: &Vector<N, U3, SC>
) -> Option<Self> where
    N: RealField,
    SB: Storage<N, U3>,
    SC: Storage<N, U3>, 

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);

pub fn scaled_rotation_between<SB, SC>(
    a: &Vector<N, U3, SB>,
    b: &Vector<N, U3, SC>,
    n: N
) -> Option<Self> where
    N: RealField,
    SB: Storage<N, U3>,
    SC: Storage<N, U3>, 

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);

pub fn angle(&self) -> N

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);

pub fn axis(&self) -> Option<Unit<Vector3<N>>> where
    N: 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());

pub fn scaled_axis(&self) -> Vector3<N> where
    N: 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);

pub fn axis_angle(&self) -> Option<(Unit<Vector3<N>>, N)> where
    N: RealField, 

The rotation axis and angle in ]0, pi] of this unit quaternion.

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());

pub fn angle_to(&self, other: &Self) -> N

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);

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);

pub fn powf(&self, n: N) -> Self where
    N: RealField, 

Raise the quaternion 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);

Trait Implementations

impl<N: SimdRealField> From<Unit<Quaternion<N>>> for Rotation3<N> where
    N::Element: SimdRealField, 

fn from(q: UnitQuaternion<N>) -> Self

Performs the conversion.

impl<N1, N2> SubsetOf<Unit<Quaternion<N2>>> for Rotation3<N1> where
    N1: RealField,
    N2: RealField + SupersetOf<N1>, 

fn to_superset(&self) -> UnitQuaternion<N2>

The inclusion map: converts self to the equivalent element of its superset.

fn is_in_subset(q: &UnitQuaternion<N2>) -> bool

Checks if element is actually part of the subset Self (and can be converted to it).

fn from_superset_unchecked(q: &UnitQuaternion<N2>) -> Self

Use with care! Same as self.to_superset but without any property checks. Always succeeds.

fn from_superset(element: &T) -> Option<Self>

The inverse inclusion map: attempts to construct self from the equivalent element of its superset.