Class Quaternion

Package: @aspose/3d (v24.12.0)

Quaternion is used throughout the @aspose/3d API to represent rotations without gimbal lock. It is the type returned by Transform.rotation and GlobalTransform.rotation. The identity quaternion (1, 0, 0, 0) represents no rotation. Quaternion is exported from the @aspose/3d/utilities sub-path.

export class Quaternion

import { Quaternion } from '@aspose/3d/utilities';

Examples

Rotate a node 90° around the Y axis and then smoothly interpolate back to identity.

import { Scene } from '@aspose/3d';
import { Quaternion } from '@aspose/3d/utilities';

const scene = new Scene();
const node = scene.rootNode.createChildNode('spinner');

// 90° around Y
const q90 = Quaternion.fromEulerAngle(0, Math.PI / 2, 0);
node.transform.rotation = q90;

// Slerp halfway back to identity
const identity = Quaternion.IDENTITY;
const half = Quaternion.slerp(0.5, q90, identity);
console.log(`Half rotation W: ${half.w.toFixed(4)}`);
// Half rotation W: 0.9239

Constructors

Signature	Description
`new Quaternion()`	Creates the identity quaternion `(1, 0, 0, 0)`.
`new Quaternion(w, x, y, z)`	Creates a quaternion from explicit components.

Properties

Property	Type	Description
`w`	`number`	Scalar (real) component. For a unit rotation quaternion, `w = cos(θ/2)`.
`x`	`number`	X component of the vector part.
`y`	`number`	Y component of the vector part.
`z`	`number`	Z component of the vector part.
`length`	`number` (read-only)	Magnitude: `sqrt(w² + x² + y² + z²)`. Should be 1.0 for a valid rotation quaternion.

Static Properties

Property	Type	Description
`Quaternion.IDENTITY`	`Quaternion`	Returns a new identity quaternion `(1, 0, 0, 0)`.

Static Methods

Quaternion.fromEulerAngle(pitch, yaw, roll)

Creates a quaternion from Euler angles in radians.

static fromEulerAngle(pitch: number, yaw: number, roll: number): Quaternion
static fromEulerAngle(vec: Vector3): Quaternion

Parameters

pitch number — Rotation around X axis in radians.

yaw number — Rotation around Y axis in radians.

roll number — Rotation around Z axis in radians.

Alternatively, pass a single Vector3 whose x, y, z hold pitch, yaw, and roll.

Examples

import { Quaternion } from '@aspose/3d/utilities';

const q = Quaternion.fromEulerAngle(0, Math.PI / 4, 0); // 45° around Y
console.log(`W: ${q.w.toFixed(4)}`); // W: 0.9239

Quaternion.fromAngleAxis(angle, axis)

Creates a quaternion representing a rotation of angle radians around axis.

static fromAngleAxis(angle: number, axis: Vector3): Quaternion

Parameters

angle number — Rotation angle in radians.

axis Vector3 — The axis of rotation. Does not need to be normalized.

Examples

import { Quaternion, Vector3 } from '@aspose/3d/utilities';

const axis = new Vector3(0, 1, 0);
const q = Quaternion.fromAngleAxis(Math.PI / 2, axis);
console.log(`Rotating 90° around Y — W: ${q.w.toFixed(4)}`);
// Rotating 90° around Y — W: 0.7071

Quaternion.fromRotation(orig, dest)

Creates the shortest-arc quaternion that rotates direction vector orig to dest.

static fromRotation(orig: Vector3, dest: Vector3): Quaternion

Quaternion.slerp(t, v1, v2)

Performs spherical linear interpolation between v1 and v2 at parameter t (0.0 = v1, 1.0 = v2).

static slerp(t: number, v1: Quaternion, v2: Quaternion): Quaternion

Examples

import { Quaternion } from '@aspose/3d/utilities';

const start = Quaternion.fromEulerAngle(0, 0, 0);
const end = Quaternion.fromEulerAngle(0, Math.PI, 0);
const mid = Quaternion.slerp(0.5, start, end);
console.log(`Mid W: ${mid.w.toFixed(4)}`); // Mid W: 0.7071

Quaternion.interpolate(t, fromQ, toQ)

Alias for slerp. Performs spherical linear interpolation.

static interpolate(t: number, fromQ: Quaternion, toQ: Quaternion): Quaternion

Instance Methods

normalize()

Returns a new quaternion scaled to unit length.

normalize(): Quaternion

conjugate()

Returns the conjugate (w, -x, -y, -z).

conjugate(): Quaternion

inverse()

Returns the inverse quaternion. Throws if the quaternion has zero length.

inverse(): Quaternion

dot(q)

Returns the scalar dot product with quaternion q.

dot(q: Quaternion): number

concat(rhs)

Returns the quaternion product this * rhs, representing the combined rotation of first applying this and then rhs.

concat(rhs: Quaternion): Quaternion

eulerAngles()

Returns the rotation expressed as Euler angles in radians as a Vector3(pitch, yaw, roll).

eulerAngles(): Vector3

Examples

import { Quaternion } from '@aspose/3d/utilities';

const q = Quaternion.fromEulerAngle(0, Math.PI / 3, 0);
const euler = q.eulerAngles();
console.log(`Yaw: ${euler.y.toFixed(4)}`);
// Yaw: 1.0472  (= π/3)

toMatrix()

Converts this quaternion to an equivalent Matrix4 rotation matrix.

toMatrix(): Matrix4

equals(other)

Returns true if all four components are strictly equal.

equals(other: Quaternion): boolean

toString()

Returns a string in the form Quaternion(w, x, y, z).

toString(): string