Urchin Reference - Quaternion

A quaternion is number system that consists of a scalar real component (a) and an imaginary vector component comprised of three units (i, j, k) that satisfy the equation i² = j² = k² = ijk = -1.

Urchin uses quaternions to represent rotations since rotational quaternions do not have the problem of gimbal lock that is a characteristic Euler Angles. The default Quaternion in Urchin is 1 + 0i + 0j + 0k. Any vector rotated by the default quaternion will remain in the same position.

If you don't know how quaternions work, don't worry! Usually, the easiest way to set up your orientations and rotations is to use Quaternion.fromAxisRotation(), which allows you to obtain any any rotation around any axis. You can also rotate an existing Quaternion with the rotateX(), rotateY(), rotateZ(), and rotateAxis() functions to bring you one step closer to the comfort of Euler Angles.

All rotations in Urchin follow the Right-hand rule.

Constructors

Quaternion( ): Quaternion	Initializes with a = 1, i = 0, j = 0, k = 0.
Quaternion( a: number, i: number, j: number, k: number ): Quaternion	Initializes with the given values.

Variables

Public Variables

a: number	The scalar component of the quaternion.
i: number	The real number to be multiplied by the imaginary i unit of the vector component of the quaternion.
j: number	The real number to be multiplied by the imaginary j unit of the vector component of the quaternion.
k: number	The real number to be multiplied by the imaginary k unit of the vector component of the quaternion.

Functions

Public Functions

add(q: Quaternion): Quaternion	Adds the given quaternion to the current quaternion and returns the result. Note: This will not result in the addition of two rotations. To combine rotational quaternions, use quaternionRotate().
conjugate(): Quaternion	Conjugates the current vector and returns the result. Note: The conjugation of a quaternion is the same as negating the vector portion (i, j, k) of the quaternion. Conjugating a rotational quaternion results in the opposite of the given rotation.
copy(): Quaternion	Returns a copy of the current quaternion.
div(a: number): Quaternion	Divides each component of the current quaternion by the given number and returns the result.
getRotationMatrix(): Array<Array<number>>	Returns the 3-dimensional rotation matrix achieved by the current quaternion.
mag(): number	Returns the magnitude of the quaternion.
normalize(): Quaternion	Normalizes the quaternion and returns the result.
mult(a: number): Quaternion	Multiplies each component of the current quaternion by the given number and returns the result. Note: To multiply two quaternions, see quaternionMult().
qMult(q: Quaternion): Quaternion	Shorthand for quaternionMult()
quaternionMult(q: Quaternion): Quaternion	Multiplies the current quaternion by the given quaternion and returns the result. Note: This is NOT the same as multiplying each individual component of the quaternions together and is NOT commutative. i.e. q0.quaternionMult(q1) ≠ q1.quaternionMult(q0)
qRotate(q: Quaternion): Quaternion	Shorthand for quaternionRotate()
quaternionRotate(q: Quaternion): Quaternion	Multiplies the given rotational quaternion with the current rotational quaternion and returns the result. The resulting quaternion is effectively the same as applying the current rotational quaternion and then the given rotational quaternion.
rotateAxis(axis: number \| Vector, angle: number): Quaternion	Rotates the current quaternion by the given angle in radians around the given axis and returns the result.
rotateX(a: number): Quaternion	Rotates the current quaternion by the given angle in radians around the X-axis and returns the result.
rotateY(a: number): Quaternion	Rotates the current quaternion by the given angle in radians around the Y-axis and returns the result.
rotateZ(a: number): Quaternion	Rotates the current quaternion by the given angle in radians around the Z-axis and returns the result.
sub(q: Quaternion): Quaternion	Subtracts the given quaternion from the current quaternion and returns the result. Note: This will not result in the subtraction of two rotations. To combine rotational quaternions, use quaternionRotate() and conjugate().

Static Functions

Quaternion.add(q0: Quaternion, q1: Quaternion): Quaternion	Adds the second quaternion to a copy of the first and returns the result.
Quaternion.conjugate(q: Quaternion): Quaternion	Conjugates a copy of the given quaternion and returns the result.
Quaternion.copy(q: Quaternion \| {a: number, i: number, j: number, k: number}): Quaternion	Returns a copy of the given quaternion of creates a new quaternion from the given object with a, i, j, k properties.
Quaternion.div(q: Quaternion, a: number): Quaternion	Divides each component of a copy of the given quaternion by the given number and returns the result.
Quaternion.fromAxisRotation(axis: number \| Vector, angle: number): Quaternion	Returns the quaternion that will achieve a rotation around the given axis by the given angle in radians. One of the following number constants can also be given as the axis: (Vector.X_AXIS, Vector.Y_AXIS, Vector.Z_AXIS). See also: Vector
Quaternion.fromVector(v: Vector, reference?: Vector): Quaternion	Returns a quaternion that will rotate the normalized reference Vector to the normalized given vector. If a reference is not given, Vector.xAxis() is used. Note: This function acts as a "dirty" way of obtaining an orientation for an object that needs to point in a particular direction and may provide an unexpected outcome. For example, if you use this function to provide an orientation for an Urbject that needs to be pointed in the direction of the Vector(x, y, z) axis, you will achieve that rotation, but the Urbject may be rotated about the Vector(x, y, z) axis in a seemingly-random rotation. See also: Vector
Quaternion.getRotationMatrix(q: Quaternion): Array<Array<number>>	Returns the 3-dimensional rotation matrix achieved by the given quaternion.
Quaternion.mag(q; Quaternion): number	Returns the magnitude of the given quaternion.
Quaternion.mult(q: Quaternion, a: number): Quaternion	Multiplies each component of a copy of the given quaternion by the given number and returns the result. Note: To multiply two quaternions, see Quaternion.quaternionMult().
Quaternion.normalize(q: Quaternion): Quaternion	Normalizes a copy of the given quaternion and returns the result.
Quaternion.qMult(q0: Quaternion, q1: Quaternion): Quaternion	Shorthand for Quaternion.quaternionMult()
Quaternion.quaternionMult(q0: Quaternion, q1: Quaternion): Quaternion	Multiplies a copy of the first quaternion by the second and returns the result. Note: This is NOT the same as multiplying each individual component of the quaternions together and is NOT commutative. i.e. Quaternion.quaternionMult(q0, q1) ≠ Quaternion.quaternionMult(q1, q0)
Quaternion.qRotate(q0: Quaternion, q1: Quaternion): Quaternion	Shorthand for Quaternion.quaternionRotate()
Quaternion.quaternionRotate(q0: Quaternion, q1: Quaternion): Quaternion	Multiplies a copy or the the first rotational quaternion with the second rotational quaternion and returns the result. The resulting quaternion is effectively the same as applying the first rotational quaternion and then the second rotational quaternion.
Quaternion.rotateAxis(q: Quaternion, axis: number \| Vector, angle: number): Quaternion	Rotates a copy of the given quaternion around the given axis by the given angle in radians and returns the result.
Quaternion.rotateX(q: Quaternion, a: number): Quaternion	Rotates a copy of the given quaternion around the X-axis by the given angle in radians and returns the result.
Quaternion.rotateY(q: Quaternion, a: number): Quaternion	Rotates a copy of the given quaternion around the Y-axis by the given angle in radians and returns the result.
Quaternion.rotateZ(q: Quaternion, a: number): Quaternion	Rotates a copy of the given quaternion around the Z-axis by the given angle in radians and returns the result.
Quaternion.sub(q0: Quaternion, q1: Quaternion): Quaternion	Subtracts the second quaternion from a copy of the first and returns the result.

Home