Struct Rotation3 

pub struct Rotation3 { /* private fields */ }

A 3x3 rotation matrix for orientation transforms.

Internally stores row-major data as [[f64; 3]; 3]. This is a pure mathematical operator with no frame semantics— frame tagging is handled by the caller.

Conventions

• Right-handed coordinate system assumed.
• Matrix applied as y = R * x (column vector convention).
• Transpose of a rotation matrix is its inverse.

Example

use affn::Rotation3;
use qtty::angular::Radians;
use std::f64::consts::FRAC_PI_2;

// Rotate 90° around the Z axis
let rot = Rotation3::rz(Radians::new(FRAC_PI_2));
let x_axis = [1.0, 0.0, 0.0];
let rotated = rot.apply_array(x_axis);

// X-axis becomes Y-axis (within numerical tolerance)
assert!((rotated[0]).abs() < 1e-10);
assert!((rotated[1] - 1.0).abs() < 1e-10);
assert!((rotated[2]).abs() < 1e-10);

Implementations

impl Rotation3

pub const IDENTITY: Self

The identity rotation (no change in orientation).

pub const fn from_matrix_unchecked(m: [[f64; 3]; 3]) -> Self

Creates a rotation matrix from raw row-major data without validation.

Arguments

• m: A 3x3 array in row-major order where m[row][col].

Safety (logical)

m must be an orthogonal matrix with det = +1 (a proper rotation). No validation is performed. Passing an invalid matrix produces a mathematically incoherent Rotation3 whose composition and inversion will silently propagate garbage values, and Rotation3 * Direction<F> will manufacture a Direction whose norm is not 1.

pub fn try_from_matrix(m: [[f64; 3]; 3]) -> Option<Self>

Creates a rotation matrix from raw row-major data, validating orthogonality.

Returns None if m is not a proper rotation matrix (i.e., Mᵀ·M is not close to the identity within tolerance 1e-7, or det(M) is not close to +1).

Arguments

• m: A 3x3 array in row-major order where m[row][col].

pub fn from_axis_angle(axis: [f64; 3], angle: Radians) -> Self

Creates a rotation from an axis-angle representation.

Uses Rodrigues’ rotation formula.

Arguments

• axis: The rotation axis (will be normalized if not unit length).
• angle: The rotation angle (right-hand rule).

Returns

A rotation matrix representing the given axis-angle rotation.

pub fn from_euler_xyz(x: Radians, y: Radians, z: Radians) -> Self

Creates a rotation from Euler angles (XYZ convention).

Applies rotations in order: X, then Y, then Z. Internally uses a fused constructor to avoid intermediate matrices.

Arguments

• x: Rotation around X axis.
• y: Rotation around Y axis.
• z: Rotation around Z axis.

pub fn from_euler_zxz(z1: Radians, x: Radians, z2: Radians) -> Self

Creates a rotation from Euler angles (ZXZ convention).

This is the classical astronomical convention used in precession. Applies rotations in order: first Z, then X, then Z. Internally uses a fused constructor to avoid intermediate matrices.

Arguments

• z1: First rotation around Z axis.
• x: Rotation around X axis.
• z2: Second rotation around Z axis.

pub fn rx(angle: Radians) -> Self

Creates a rotation around the X axis from a typed Radians angle.

pub fn ry(angle: Radians) -> Self

Creates a rotation around the Y axis from a typed Radians angle.

pub fn rz(angle: Radians) -> Self

Creates a rotation around the Z axis from a typed Radians angle.

pub fn transpose(&self) -> Self

Returns the transpose (inverse) of this rotation.

For rotation matrices, transpose equals inverse.

pub fn inverse(&self) -> Self

Returns the inverse of this rotation.

Alias for transpose.

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

Composes two rotations: self * other.

The result applies other first, then self.

pub fn apply_array(&self, v: [f64; 3]) -> [f64; 3]

Applies this rotation to a raw [f64; 3] array.

Computes R * v where v is treated as a column vector.

pub fn apply_xyz(&self, xyz: XYZ<f64>) -> XYZ<f64>

Applies this rotation to an XYZ<f64>.

pub fn apply_vec<F1, F2, U>(&self, v: Vector<F1, U>) -> Vector<F2, U>

where F1: ReferenceFrame, F2: ReferenceFrame, U: Unit,

Applies this rotation to a typed Vector, changing its reference frame.

Rotates the vector’s components and re-tags the result with frame F2. The unit U is unchanged. This is a zero-overhead operation: the matrix multiplication uses the same path as [apply_array], with a frame tag change at compile time.

Example

use affn::{Rotation3, cartesian::Displacement};
use affn::frames::ReferenceFrame;
use qtty::unit::Kilometer;
use std::f64::consts::FRAC_PI_2;

#[derive(Debug, Copy, Clone)] struct FrameA;
#[derive(Debug, Copy, Clone)] struct FrameB;
impl ReferenceFrame for FrameA { fn frame_name() -> &'static str { "A" } }
impl ReferenceFrame for FrameB { fn frame_name() -> &'static str { "B" } }

let rot = Rotation3::rz(qtty::angular::Radians::new(FRAC_PI_2));
let v = Displacement::<FrameA, Kilometer>::new(1.0, 0.0, 0.0);
let rotated: Displacement<FrameB, Kilometer> = rot.apply_vec(v);
assert!((rotated.x().value() - 0.0).abs() < 1e-10);
assert!((rotated.y().value() - 1.0).abs() < 1e-10);

pub const fn as_matrix(&self) -> &[[f64; 3]; 3]

Returns the underlying matrix as a row-major array.

pub fn fused_rx_rz(a: Radians, b: Radians) -> Self

Constructs the rotation Rx(a) · Rz(b) directly.

Faster than Rotation3::rx(a) * Rotation3::rz(b) because it avoids the intermediate 3×3 matrix multiply and computes each element from trig products.

Arguments

• a: Angle for the X rotation (applied second / left factor).
• b: Angle for the Z rotation (applied first / right factor).

pub fn fused_rz_rx(a: Radians, b: Radians) -> Self

Constructs the rotation Rz(a) · Rx(b) directly.

Faster than Rotation3::rz(a) * Rotation3::rx(b) because it avoids the intermediate 3×3 matrix multiply.

Arguments

• a: Angle for the Z rotation (applied second / left factor).
• b: Angle for the X rotation (applied first / right factor).

pub fn fused_rx_rz_rx(a: Radians, b: Radians, c: Radians) -> Self

Constructs the rotation Rx(a) · Rz(b) · Rx(c) directly.

Used in nutation: N = Rx(ε+Δε) · Rz(Δψ) · Rx(−ε).

Computes the 9 elements from 3 sin/cos pairs and their products, avoiding 2 intermediate matrix multiplications.

Arguments

• a: Angle for the outer X rotation (left).
• b: Angle for the Z rotation (middle).
• c: Angle for the inner X rotation (right).

pub fn fused_rz_ry_rz(a: Radians, b: Radians, c: Radians) -> Self

Constructs the rotation Rz(a) · Ry(b) · Rz(c) directly.

Used in Meeus precession: P = Rz(z) · Ry(−θ) · Rz(ζ).

Arguments

• a: Angle for the outer Z rotation (left).
• b: Angle for the Y rotation (middle).
• c: Angle for the inner Z rotation (right).

pub fn fused_rx_rz_rx_rz(a: Radians, b: Radians, c: Radians, d: Radians) -> Self

Constructs the Fukushima-Williams rotation Rx(a) · Rz(b) · Rx(c) · Rz(d) directly.

This is the standard form for IAU 2006 precession and precession-nutation matrices. In the SOFA convention (translated to standard rotations):

P = Rx(ε_A) · Rz(ψ̄) · Rx(−φ̄) · Rz(−γ̄)

This fused constructor computes all 9 matrix elements directly from 4 sin/cos pairs, avoiding 3 intermediate matrix multiplications. Provides a ~45% speedup over the sequential composition.

Arguments

• a: Angle for the outer X rotation (left, e.g., ε_A).
• b: Angle for the first Z rotation (e.g., ψ̄).
• c: Angle for the inner X rotation (e.g., −φ̄).
• d: Angle for the innermost Z rotation (e.g., −γ̄).

Trait Implementations

impl Clone for Rotation3

fn clone(&self) -> Rotation3

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Rotation3

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Rotation3

fn default() -> Self

Returns the “default value” for a type.

impl<U: Unit> Mul<&[Quantity<U>; 3]> for &Rotation3

type Output = <Rotation3 as Mul<[Quantity<U>; 3]>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &[Quantity<U>; 3]) -> <Self as Mul<&[Quantity<U>; 3]>>::Output

Performs the * operation.

impl<U: Unit> Mul<&[Quantity<U>; 3]> for Rotation3

type Output = <Rotation3 as Mul<[Quantity<U>; 3]>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &[Quantity<U>; 3]) -> <Self as Mul<&[Quantity<U>; 3]>>::Output

Performs the * operation.

impl Mul<&[f64; 3]> for &Rotation3

type Output = <Rotation3 as Mul<[f64; 3]>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &[f64; 3]) -> <Self as Mul<&[f64; 3]>>::Output

Performs the * operation.

impl Mul<&[f64; 3]> for Rotation3

type Output = <Rotation3 as Mul<[f64; 3]>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &[f64; 3]) -> <Self as Mul<&[f64; 3]>>::Output

Performs the * operation.

impl<F: ReferenceFrame> Mul<&Direction<F>> for &Rotation3

type Output = <Rotation3 as Mul<Direction<F>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Direction<F>) -> <Self as Mul<&Direction<F>>>::Output

Performs the * operation.

impl<F: ReferenceFrame> Mul<&Direction<F>> for Rotation3

type Output = <Rotation3 as Mul<Direction<F>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Direction<F>) -> <Self as Mul<&Direction<F>>>::Output

Performs the * operation.

impl<C, F, U> Mul<&Position<C, F, U>> for &Rotation3

where C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit, C::Params: Copy,

type Output = <Rotation3 as Mul<Position<C, F, U>>>::Output

The resulting type after applying the * operator.

fn mul( self, rhs: &Position<C, F, U>, ) -> <Self as Mul<&Position<C, F, U>>>::Output

Performs the * operation.

impl<C, F, U> Mul<&Position<C, F, U>> for Rotation3

where C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit, C::Params: Copy,

type Output = <Rotation3 as Mul<Position<C, F, U>>>::Output

The resulting type after applying the * operator.

fn mul( self, rhs: &Position<C, F, U>, ) -> <Self as Mul<&Position<C, F, U>>>::Output

Performs the * operation.

impl Mul<&Rotation3> for &Rotation3

type Output = <Rotation3 as Mul>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Rotation3) -> <Self as Mul<&Rotation3>>::Output

Performs the * operation.

impl Mul<&Rotation3> for Rotation3

type Output = <Rotation3 as Mul>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Rotation3) -> <Self as Mul<&Rotation3>>::Output

Performs the * operation.

impl<F, U> Mul<&Vector<F, U>> for &Rotation3

where F: ReferenceFrame, U: Unit,

type Output = <Rotation3 as Mul<Vector<F, U>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Vector<F, U>) -> <Self as Mul<&Vector<F, U>>>::Output

Performs the * operation.

impl<F, U> Mul<&Vector<F, U>> for Rotation3

where F: ReferenceFrame, U: Unit,

type Output = <Rotation3 as Mul<Vector<F, U>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Vector<F, U>) -> <Self as Mul<&Vector<F, U>>>::Output

Performs the * operation.

impl<U: Unit> Mul<&XYZ<Quantity<U>>> for &Rotation3

type Output = <Rotation3 as Mul<XYZ<Quantity<U>>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &XYZ<Quantity<U>>) -> <Self as Mul<&XYZ<Quantity<U>>>>::Output

Performs the * operation.

impl<U: Unit> Mul<&XYZ<Quantity<U>>> for Rotation3

type Output = <Rotation3 as Mul<XYZ<Quantity<U>>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &XYZ<Quantity<U>>) -> <Self as Mul<&XYZ<Quantity<U>>>>::Output

Performs the * operation.

impl<U: Unit> Mul<[Quantity<U>; 3]> for &Rotation3

type Output = <Rotation3 as Mul<[Quantity<U>; 3]>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: [Quantity<U>; 3]) -> <Self as Mul<[Quantity<U>; 3]>>::Output

Performs the * operation.

impl<U: Unit> Mul<[Quantity<U>; 3]> for Rotation3

type Output = [Quantity<U>; 3]

The resulting type after applying the * operator.

fn mul(self, rhs: [Quantity<U>; 3]) -> [Quantity<U>; 3]

Performs the * operation.

impl Mul<[f64; 3]> for &Rotation3

type Output = <Rotation3 as Mul<[f64; 3]>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: [f64; 3]) -> <Self as Mul<[f64; 3]>>::Output

Performs the * operation.

impl Mul<[f64; 3]> for Rotation3

Applies a rotation to a raw [f64; 3] column vector: R * v.

type Output = [f64; 3]

The resulting type after applying the * operator.

fn mul(self, rhs: [f64; 3]) -> [f64; 3]

Performs the * operation.

impl<F: ReferenceFrame> Mul<Direction<F>> for &Rotation3

type Output = <Rotation3 as Mul<Direction<F>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: Direction<F>) -> <Self as Mul<Direction<F>>>::Output

Performs the * operation.

impl<F: ReferenceFrame> Mul<Direction<F>> for Rotation3

Rotation3 * Direction<F> — rotates a unit direction, preserving frame.

Translations do not apply to directions; only rotation changes their orientation. The result is guaranteed to remain a unit vector because rotation preserves norms.

type Output = Direction<F>

The resulting type after applying the * operator.

fn mul(self, rhs: Direction<F>) -> Direction<F>

Performs the * operation.

impl<C, F, U> Mul<Position<C, F, U>> for &Rotation3

where C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit, C::Params: Copy,

type Output = <Rotation3 as Mul<Position<C, F, U>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: Position<C, F, U>) -> <Self as Mul<Position<C, F, U>>>::Output

Performs the * operation.

impl<C, F, U> Mul<Position<C, F, U>> for Rotation3

where C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit, C::Params: Clone,

type Output = Position<C, F, U>

The resulting type after applying the * operator.

fn mul(self, rhs: Position<C, F, U>) -> Position<C, F, U>

Performs the * operation.

impl Mul<Rotation3> for &Rotation3

type Output = <Rotation3 as Mul>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: Rotation3) -> <Self as Mul<Rotation3>>::Output

Performs the * operation.

impl<F, U> Mul<Vector<F, U>> for &Rotation3

where F: ReferenceFrame, U: Unit,

type Output = <Rotation3 as Mul<Vector<F, U>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: Vector<F, U>) -> <Self as Mul<Vector<F, U>>>::Output

Performs the * operation.

impl<F, U> Mul<Vector<F, U>> for Rotation3

where F: ReferenceFrame, U: Unit,

Rotation3 * Vector<F, U> — rotates a free vector, preserving frame and unit.

Translations do not apply to free vectors (they are translation-invariant), so this is only implemented for Rotation3.

type Output = Vector<F, U>

The resulting type after applying the * operator.

fn mul(self, rhs: Vector<F, U>) -> Vector<F, U>

Performs the * operation.

impl<U: Unit> Mul<XYZ<Quantity<U>>> for &Rotation3

type Output = <Rotation3 as Mul<XYZ<Quantity<U>>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: XYZ<Quantity<U>>) -> <Self as Mul<XYZ<Quantity<U>>>>::Output

Performs the * operation.

impl<U: Unit> Mul<XYZ<Quantity<U>>> for Rotation3

type Output = XYZ<Quantity<U>>

The resulting type after applying the * operator.

fn mul(self, rhs: XYZ<Quantity<U>>) -> XYZ<Quantity<U>>

Performs the * operation.

impl Mul for Rotation3

type Output = Rotation3

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl PartialEq for Rotation3

fn eq(&self, other: &Rotation3) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Rotation3

impl StructuralPartialEq for Rotation3