Rotation3 in nalgebra::geometry - Rust
Description: A 3-dimensional rotation matrix.
Keywords: rust, rustlang, rust-lang, Rotation3

# Type Definition nalgebra::geometry::Rotation3

source ·

    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.

## Implementations§

source§

### impl<T: SimdRealField> Rotation3<T>

source

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

source

#### 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 return `None`.

source§

### impl<T: SimdRealField> Rotation3<T>where
T::Element: SimdRealField,

#### Construction from a 3D axis and/or angles

source

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

source

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

source

#### pub fn from_axis_angle<SB>(axis: &Unit<Vector<T, U3, SB>>, angle: T) -> Selfwhere
SB: Storage<T, 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());

source

#### 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,

#### Construction from a 3D eye position and target point

source

#### pub fn face_towards<SB, SC>(
dir: &Vector<T, U3, SB>,
up: &Vector<T, U3, SC>
) -> Selfwhere
SB: Storage<T, U3>,
SC: Storage<T, 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());

source

#### pub fn new_observer_frames<SB, SC>(
dir: &Vector<T, U3, SB>,
up: &Vector<T, U3, SC>
) -> Selfwhere
SB: Storage<T, U3>,
SC: Storage<T, U3>,

👎Deprecated: renamed to `face_towards`

Deprecated: Use `Rotation3::face_towards` instead.

source

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

source

#### pub fn look_at_lh<SB, SC>(
dir: &Vector<T, U3, SB>,
up: &Vector<T, U3, SC>
) -> Selfwhere
SB: Storage<T, U3>,
SC: Storage<T, 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());

source§

### impl<T: SimdRealField> Rotation3<T>where
T::Element: SimdRealField,

#### Construction from an existing 3D matrix or rotations

source

#### pub fn rotation_between<SB, SC>(
a: &Vector<T, U3, SB>,
b: &Vector<T, U3, SC>
) -> Option<Self>where
T: RealField,
SB: Storage<T, U3>,
SC: Storage<T, 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);

source

#### pub fn scaled_rotation_between<SB, SC>(
a: &Vector<T, U3, SB>,
b: &Vector<T, U3, SC>,
n: T
) -> Option<Self>where
T: RealField,
SB: Storage<T, U3>,
SC: Storage<T, 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);

source

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

source

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

source

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

source

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

source

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

source

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

#### 3D axis and angle extraction

source

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

source

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

source

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

source

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

source

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

source

#### pub fn to_euler_angles(self) -> (T, T, T)where
T: 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).

source

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

## Trait Implementations§

source§

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

source§

#### fn from(q: UnitQuaternion<T>) -> Self

Converts to this type from the input type.
source§

### impl<T1, T2> SubsetOf<Unit<DualQuaternion<T2>>> for Rotation3<T1>where
T1: RealField,
T2: RealField + SupersetOf<T1>,

source§

#### fn to_superset(&self) -> UnitDualQuaternion<T2>

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

#### fn is_in_subset(dq: &UnitDualQuaternion<T2>) -> bool

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

#### fn from_superset_unchecked(dq: &UnitDualQuaternion<T2>) -> Self

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

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

The inverse inclusion map: attempts to construct `self` from the equivalent element of its superset. Read more
source§

### impl<T1, T2> SubsetOf<Unit<Quaternion<T2>>> for Rotation3<T1>where
T1: RealField,
T2: RealField + SupersetOf<T1>,

source§

#### fn to_superset(&self) -> UnitQuaternion<T2>

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

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

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

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

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

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

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