khora_sdk::prelude::math::affine_transform

Struct AffineTransform

#[repr(transparent)]
pub struct AffineTransform(pub Mat4);

Expand description

Represents a 3D affine transformation (translation, rotation, scale).

This is a semantic wrapper around a Mat4 that guarantees the matrix represents a valid affine transform. It provides a dedicated API for creating and manipulating these transformations.

Tuple Fields§

§0: Mat4

Implementations§

§

impl AffineTransform

pub const IDENTITY: AffineTransform

The identity transform, which results in no change.

pub fn from_translation(v: Vec3) -> AffineTransform

Creates an AffineTransform from a translation vector.

§Arguments

v - The translation vector to apply

§Example

use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let transform = AffineTransform::from_translation(Vec3::new(1.0, 2.0, 3.0));
assert_eq!(transform.translation(), Vec3::new(1.0, 2.0, 3.0));

pub fn from_scale(scale: Vec3) -> AffineTransform

Creates an AffineTransform from a non-uniform scale vector.

§Arguments

scale - The scale vector to apply to each axis

§Example

use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let transform = AffineTransform::from_scale(Vec3::new(2.0, 1.5, 0.5));

pub fn from_rotation_x(angle: f32) -> AffineTransform

Creates an AffineTransform from a rotation around the X axis.

§Arguments

angle - The angle of rotation in radians

§Example

use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;
use std::f32::consts::PI;

let transform = AffineTransform::from_rotation_x(PI / 2.0);

pub fn from_rotation_y(angle: f32) -> AffineTransform

Creates an AffineTransform from a rotation around the Y axis.

§Arguments

angle - The angle of rotation in radians

§Example

use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;
use std::f32::consts::PI;

let transform = AffineTransform::from_rotation_y(PI / 2.0);

pub fn from_rotation_z(angle: f32) -> AffineTransform

Creates an AffineTransform from a rotation around the Z axis.

§Arguments

angle - The angle of rotation in radians

§Example

use std::f32::consts::PI;
use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let transform = AffineTransform::from_rotation_z(PI / 2.0);

pub fn from_axis_angle(axis: Vec3, angle: f32) -> AffineTransform

Creates an AffineTransform from a rotation around an arbitrary axis.

Uses Rodrigues’ rotation formula to create a rotation matrix.

§Arguments

axis - The axis of rotation (will be normalized automatically)
angle - The angle of rotation in radians

§Example

use std::f32::consts::PI;
use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let axis = Vec3::new(1.0, 1.0, 0.0);
let transform = AffineTransform::from_axis_angle(axis, PI / 4.0);

pub fn from_quat(q: Quaternion) -> AffineTransform

Creates an AffineTransform from a quaternion representing a rotation.

§Arguments

q - The quaternion representing the rotation

§Example

use khora_core::math::{Quaternion, Vec3};
use khora_core::math::affine_transform::AffineTransform;
use std::f32::consts::PI;

let q = Quaternion::from_axis_angle(Vec3::Y, PI / 2.0);
let transform = AffineTransform::from_quat(q);

pub fn to_matrix(&self) -> Mat4

Converts the AffineTransform to a Mat4.

This is useful when you need to pass the transformation matrix to shaders or other systems that expect a raw matrix.

§Example

use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let transform = AffineTransform::IDENTITY;
let matrix = transform.to_matrix();

pub fn translation(&self) -> Vec3

Extracts the translation component from the affine transform.

Returns the translation vector representing the position offset applied by this transformation.

§Example

use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let transform = AffineTransform::from_translation(Vec3::new(1.0, 2.0, 3.0));
assert_eq!(transform.translation(), Vec3::new(1.0, 2.0, 3.0));

pub fn right(&self) -> Vec3

Extracts the right direction vector from the affine transform.

This returns the first column of the transformation matrix (excluding the w component), which represents the transformed positive X-axis direction.

§Example

use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;
use std::f32::consts::PI;

let transform = AffineTransform::from_rotation_z(PI / 2.0);
let right = transform.right();
// After 90° rotation around Z, right vector points in -Y direction

pub fn up(&self) -> Vec3

Extracts the up direction vector from the affine transform.

This returns the second column of the transformation matrix (excluding the w component), which represents the transformed positive Y-axis direction.

§Example

use std::f32::consts::PI;
use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let transform = AffineTransform::from_rotation_x(PI / 2.0);
let up = transform.up();
// After 90° rotation around X, up vector points in -Z direction

pub fn forward(&self) -> Vec3

Extracts the forward direction vector from the affine transform.

This returns the third column of the transformation matrix (excluding the w component), which represents the transformed positive Z-axis direction.

§Example

use std::f32::consts::PI;
use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let transform = AffineTransform::from_rotation_y(PI / 2.0);
let forward = transform.forward();
// After 90° rotation around Y, forward vector points in X direction

pub fn rotation(&self) -> Quaternion

Extracts the rotation component as a quaternion.

This method extracts the rotation represented by the upper-left 3x3 portion of the transformation matrix.

§Note

This assumes the transform has uniform or no scale. For transforms with non-uniform scale, the result may not represent a pure rotation. In such cases, consider normalizing the direction vectors first.

§Example

use khora_core::math::{Quaternion, Vec3};
use khora_core::math::affine_transform::AffineTransform;
use std::f32::consts::PI;

let q = Quaternion::from_axis_angle(Vec3::Y, PI / 2.0);
let transform = AffineTransform::from_quat(q);
let extracted = transform.rotation();
// extracted should be approximately equal to q

pub fn scale(&self) -> Vec3

Extracts the non-negative scale factors along each local axis.

Returns the Euclidean lengths of the three basis columns (right, up, forward). For a transform built as translation ∘ rotation ∘ scale this recovers the original scale vector. Mirror/negative scales are reported as their magnitudes (sign is folded into the rotation extraction).

pub fn interpolate( &self, other: &AffineTransform, alpha: f32, ) -> AffineTransform

Interpolates between two affine transforms for smooth rendering between discrete simulation steps.

Decomposes both transforms into translation / rotation / scale and blends each channel independently: translation and scale by linear interpolation, rotation by spherical interpolation (shortest-path slerp). alpha is clamped to [0, 1]; alpha = 0 returns self (the previous transform) and alpha = 1 returns other (the current transform).

This is a render-only blend: it never feeds back into the authoritative simulation state.

§Examples

use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let prev = AffineTransform::from_translation(Vec3::ZERO);
let curr = AffineTransform::from_translation(Vec3::new(10.0, 0.0, 0.0));

// The endpoints round-trip the inputs; the midpoint blends them.
assert_eq!(prev.interpolate(&curr, 0.0).translation(), Vec3::ZERO);
assert_eq!(prev.interpolate(&curr, 1.0).translation(), curr.translation());

let mid = prev.interpolate(&curr, 0.5).translation();
assert!((mid - Vec3::new(5.0, 0.0, 0.0)).length() < 1e-5);

pub fn inverse(&self) -> Option<AffineTransform>

Computes the inverse of the affine transformation.

This uses an optimized affine inverse algorithm that’s more efficient than a general matrix inverse, taking advantage of the affine transform structure. Returns None if the transformation is not invertible (e.g., zero scale).

§Returns

Some(AffineTransform) if the inverse exists, None otherwise.

§Example

use khora_core::math::Vec3;
use khora_core::math::affine_transform::AffineTransform;

let transform = AffineTransform::from_translation(Vec3::new(1.0, 2.0, 3.0));
let inverse = transform.inverse().unwrap();
// The inverse should translate by (-1, -2, -3)