Type Definition nalgebra::geometry::Rotation3

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

A 3-dimensional rotation matrix.

Implementations

impl<N: Real> Rotation3<N>

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_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) -> Selfwhere
    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)

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

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 new_observer_frame<SB, SC>(
    dir: &Vector<N, U3, SB>,
    up: &Vector<N, U3, SC>
) -> Selfwhere
    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::new_observer_frame(&dir, &up);
assert_relative_eq!(rot * Vector3::z(), dir.normalize());

pub fn look_at_rh<SB, SC>(
    dir: &Vector<N, U3, SB>,
    up: &Vector<N, U3, SC>
) -> Selfwhere
    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>
) -> Selfwhere
    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
    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
    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>>>

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>

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

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: &Rotation3<N>) -> 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: &Rotation3<N>) -> Rotation3<N>

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) -> Rotation3<N>

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<N1, N2> SubsetOf<Unit<Quaternion<N2>>> for Rotation3<N1>where
    N1: Real,
    N2: Real + 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).

unsafe 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.