RealityServer® Extras

Class: Quaternion

RS.Quaternion

The Quaternion class reprents quaternion rotations and supports conversion to/from matrices and Euler rotation representations.

new RS.Quaternion (initial)

Creates a new Quaternion. Accepts any arguments that RS.Quaternion#set accepts.

Name Type Description
initial RS.Quaternion | RS.Euler | RS.Math.Matrix4x4 | Array | Object | Number optional

initial value.

Members

w Number

The w component of the quaternion.

x Number

The x component of the quaternion.

y Number

The y component of the quaternion.

z Number

The z component of the quaternion.

Methods

RS.Quaternion.multiply_quaternions_flat (target, target_offset, src0, src_offset0, src1, src_offset1) static

Multiplies quaternions where the quaternions are represented by flat arrays of numbers rather than the RS.Quaternion class.

Name Type Description
target Array

Target array to store result.
target_offset Number

Offset into target to store result at.
src0 Array

Source array for the left hand quaternion.
src_offset0 Number

Offset into src0 to read quaternion from.
src1 Array

Source array for the right hand quaternion.
src_offset1 Number

Offset into src1 to read quaternion from.

RS.Quaternion.slerp (start, end, target, t) static

Spherically interpolates start to end by t storing the result in target

Name Type Description
start RS.Quaternion

The starting quaternion (where t is 0).
end RS.Quaternion

The end quaternion (where t is 1).
target RS.Quaternion

Target quaternion to store result in.
t Number

interploation factor in range [0, 1]

RS.Quaternion.slerp_flat (target, target_offset, src0, src_offset0, src1, src_offset1, t) static

Spherical interpolates quaternions where the quaternions are represented by flat arrays of numbers rather than the RS.Quaternion class.

Name Type Description
target Array

Target array to store result.
target_offset Number

Offset into target to store result at.
src0 Array

Source array for the starting quaternion.
src_offset0 Number

Offset into src0 to read quaternion from.
src1 Array

Source array for the end quaternion.
src_offset1 Number

Offset into src1 to read quaternion from.
t Number

interploation factor in range [0, 1]

angle_to (q)Number

Returns the angle between this quaternion and quaternion q in radians.

Name Type Description
q RS.Quaternion

the quaternion to measure against.
Returns:
Type Description
Number the angle between this and q in radians

clone ()RS.Euler

Returns a copy of this quaternion.

Returns:
Type Description
RS.Euler a copy of this

conjugate ()RS.Quaternion

Sets this quaternion to its rotational conjugate. The conjugate of a quaternion represents the same rotation in the opposite direction about the rotational axis.

Returns:
Type Description
RS.Quaternion this

dot (v)Number

Calculates the dot product between this and the quaternion v.

Name Type Description
v RS.Quaternion

the other quaternion.
Returns:
Type Description
Number the dot product.

equal (rhs, tolerance)Boolean

Returns whether this euler is equal to another quaternion within an optional tolerance.

Name Type Description
rhs RS.Euler

the euler to compare to.
tolerance Number optional

if provided then this level of tolerance is used, otherwise uses an exact match.
Returns:
Type Description
Boolean true if equal, false if not.

equal_with_tolerance (rhs, tolerance)Boolean

Returns whether this quaternion is equal to another quaternion within a tolerance.

Name Type Description
rhs RS.Quaternion

the quaternion to compare to.
tolerance Number optional

if provided then this level of tolerance is used, otherwise tolerance is 10e-5.
Returns:
Type Description
Boolean true if equal, false if not.

identity ()RS.Quaternion

Sets this quaternion to the identity quaternion.

Returns:
Type Description
RS.Quaternion this

invert ()RS.Quaternion

Inverts this quaternion

Returns:
Type Description
RS.Quaternion this

length ()Number

Calculates the length of this quaternion.

Returns:
Type Description
Number the length.

length_sq ()Number

Calculates the squared length of this quaternion.

Returns:
Type Description
Number the squared length.

multiply (rhs)RS.Quaternion

Multiplies this quaternion with rhs. IE: this = this x rhs.

Name Type Description
rhs RS.Quaternion

the right hand quaternion.
Returns:
Type Description
RS.Quaternion this

multiply_quaternions (lhs, rhs)RS.Quaternion

Sets this quaternion to lhs x rhs.

Name Type Description
lhs RS.Quaternion

the left hand quaternion.
rhs RS.Quaternion

the right hand quaternion.
Returns:
Type Description
RS.Quaternion this

normalize ()RS.Quaternion

Normalizes this quaternion to unit length.

Returns:
Type Description
RS.Quaternion this

premultiply (lhs)RS.Quaternion

Premultiplies this quaternion with lhs. IE: this = lhs x this.

Name Type Description
lhs RS.Quaternion

the left hand quaternion.
Returns:
Type Description
RS.Quaternion this

rotate_towards (q, step)RS.Quaternion

Rotates this quaternion by a given angular amount towards the quaternion q. The method ensures that the final quaternion will not overshoot q.

Name Type Description
q RS.Quaternion

the quaternion to rotate towards.
step Number

the amount to rotate by in radians.
Returns:
Type Description
RS.Quaternion this

rotate_vector (vec)RS.Math.Vector3

Rotates the provided vector by this quaternion. Equivalent to Vector3.multiply(q.to_matrix()) but will be faster. The vector is modified.

Name Type Description
vec RS.Math.Vector3

the vector to rotate.
Returns:
Type Description
RS.Math.Vector3 the rotated vector.

set (source)RS.Quaternion

Sets this quaternion. The source may be of the following types:

  • RS.Quaternion
  • RS.Euler
  • RS.Math.Matrix4x4
  • an Array with 4 or more members
  • an Object.
  • individual arguments for x, y, z and w

If the source is RS.Math.Matrix4x4 then it is expected to have no scaling factors. The matrix is expected to be a forward transformation, IE: an object to world space matrix.

In the case of an object being supplied it should have the members x, y, z and w. Parsing failures on x, y or z will set them to 0, failures on w will set it to 1.

Name Type Description
source RS.Quaternion | RS.Euler | RS.Math.Matrix4x4 | Array | Object | Number

the object to set from or a set of numbers.
Returns:
Type Description
RS.Quaternion this
Example
const v = new RS.Quaternion();
v.set(1,2,0,1);
v.set([0.2,-0.3,-.5,-0.2]);
v.set({x: 0.1, y: 0.53,z: -0.3, w:1});

set_from_unit_vectors (from, to)RS.Quaternion

Sets this quaternion to the rotation required to rotate direction vector from to direction vector to.

Name Type Description
from RS.Math.Vector3

the from vector, assumed to be normalized.
to RS.Math.Vector3

the to vector, assumed to be normalized.
Returns:
Type Description
RS.Quaternion this

set_rotation_around_axis (axis, angle)RS.Quaternion

Sets this quaternion to the rotation about the given axis by the given angle in radians.

Name Type Description
axis RS.Math.Vector3

the axis to rotate around.
angle Number

the amount to rotate by in radians.
Returns:
Type Description
RS.Quaternion this

slerp (end, t)RS.Quaternion

Handles spherical linear interpolation between quaternions. t represents the amount of rotation between this quaternion (where t is 0) and end (where t is 1). This quaternion is set to the result. Also see the static version of slerp.

Name Type Description
end RS.Quaternion

the quaternion to interpolate to.
t RS.Quaternion

interpolation factor in the closed interval [0, 1].
Returns:
Type Description
RS.Quaternion this

to_matrix ()RS.Math.Matrix4x4

Returns a matrix representing this quaternion. This will be a forward transformation, IE: an object to world space matrix. The matrix can be passed to RS.Math.Vector3.rotate to rotate a vector by this quaternion.

Returns:
Type Description
RS.Math.Matrix4x4 the rotation matrix.