Quaternion

References
[StructLayout(LayoutKind.Sequential, Pack = 8, Size = 32)] [Serializable] public struct Quaternion : IEquatable<Quaternion>, IEpsilonComparable<Quaternion>
Represents the four coefficient values in a quaternion.

The first value a is the real part, while the rest multiplies i, j and k, that are imaginary.

quaternion = a + bi + cj + dk

Constructors

Quaternion

#Since v5.0
Initializes a new quaternion with the provided coefficients.
public Quaternion(
a,
A number. This is the real part.
b,
Another number. This is the first coefficient of the imaginary part.
c,
Another number. This is the second coefficient of the imaginary part.
d
Another number. This is the third coefficient of the imaginary part.
)

Properties

A

#Since v5.0
Gets or sets the real part of the quaternion.
public double A { get; set; }

B

#Since v5.0
Gets or sets the first imaginary coefficient of the quaternion.
public double B { get; set; }

C

#Since v5.0
Gets or sets the second imaginary coefficient of the quaternion.
public double C { get; set; }

Conjugate

#Since v5.0
Gets a new quaternion that is the conjugate of this quaternion.

This is (a,-b,-c,-d)

public Quaternion Conjugate { get; }

D

#Since v5.0
Gets or sets the third imaginary coefficient of the quaternion.
public double D { get; set; }

I

#Since v5.0
Returns the (0,1,0,0) quaternion.
public static Quaternion I { get; }

Identity

#Since v5.0
Returns the (1,0,0,0) quaternion.
public static Quaternion Identity { get; }

Inverse

#Since v5.0
Computes a new inverted quaternion,

(a/L2, -b/L2, -c/L2, -d/L2),

where L2 = length squared = (a*a + b*b + c*c + d*d).

This is the multiplicative inverse, i.e., (a,b,c,d)*(a/L2, -b/L2, -c/L2, -d/L2) = (1,0,0,0). If this is the zero quaternion, then the zero quaternion is returned.
public Quaternion Inverse { get; }

IsScalar

#Since v5.0
true if b, c, and d are all zero.
public bool IsScalar { get; }

IsValid

#Since v5.0
Determines if the four coefficients are valid numbers within RhinoCommon.

See RhinoMath.IsValidDouble(double).

public bool IsValid { get; }

IsVector

#Since v5.0
true if a = 0 and at least one of b, c, or d is not zero.
public bool IsVector { get; }

IsZero

#Since v5.0
true if a, b, c, and d are all zero.
public bool IsZero { get; }

J

#Since v5.0
Returns the (0,0,1,0) quaternion.
public static Quaternion J { get; }

K

#Since v5.0
Returns the (0,0,0,1) quaternion.
public static Quaternion K { get; }

Length

#Since v5.0
Returns the length or norm of the quaternion.
public double Length { get; }
Math.Sqrt(a*a + b*b + c*c + d*d)

LengthSquared

#Since v5.0
Gets the result of (a^2 + b^2 + c^2 + d^2).
public double LengthSquared { get; }

Scalar

#Since v5.0
The real (scalar) part of the quaternion

This is A.

public double Scalar { get; }

Vector

#Since v5.0
The imaginary part of the quaternion

(B,C,D)

public Vector3d Vector { get; }

Zero

#Since v5.0
Returns the default quaternion, where all coefficients are 0.
public static Quaternion Zero { get; }

Methods

CreateFromRotationZYX

#Since v8.0
Constructs a quaternion defined by Tait-Byran angles, also loosely known as Euler angles.
public static Quaternion CreateFromRotationZYX(
yaw,
Angle, in radians, to rotate about the ZAxis.
pitch,
Angle, in radians, to rotate about the YAxis.
roll
Angle, in radians, to rotate about the XAxis.
)
Remarks: CreateFromRotationZYX(yaw, pitch, roll) = R_z(yaw) * R_y(pitch) * R_x(roll), where R_*(angle) is rotation of angle radians about the corresponding world coordinate axis.
The quaternion.

CreateFromRotationZYZ

#Since v8.0
Constructs a quaternion defined by Euler angles.
public static Quaternion CreateFromRotationZYZ(
alpha,
Angle, in radians, to rotate about the ZAxis.
beta,
Angle, in radians, to rotate about the YAxis.
gamma
Angle, in radians, to rotate about the ZAxis.
)
Remarks: CreateFromRotationZYZ(alpha, beta, gamma) = R_z(alpha) * R_y(beta) * R_z(gamma), where R_*(angle) is rotation of angle radians about the corresponding *-world coordinate axis.
The quaternion.

CrossProduct

#Since v5.0
Computes the vector cross product of p and q = (0,x,y,z),

where (x,y,z) = CrossProduct(p.Vector,q.Vector).

This is not the same as the quaternion product p*q.

public static Quaternion CrossProduct(
p,
A quaternion.
q
Another quaternion.
)
A new quaternion.

Distance

#Since v5.0
Returns the distance or norm of the difference between two quaternions.
public static double Distance(
p,
A quaternion.
q
Another quaternion.
)
(p - q).Length()

DistanceTo

#Since v5.0
Computes the distance or norm of the difference between this and another quaternion.
[ConstOperation] public double DistanceTo(
q
Another quaternion.
)
(this - q).Length.

EpsilonEquals

#Since v5.4
Check that all values in other are within epsilon of the values in this
[ConstOperation] public bool EpsilonEquals(
other,
epsilon
)
EpsilonEquals

Equals

#
Determines whether an object is a quaternion and has the same value of this quaternion.
[ConstOperation] public override bool Equals(
obj
Another object to compare.
)
true if obj is a quaternion and has exactly equal coefficients; otherwise false.
ValueType.Equals

Equals

#Since v5.0
Determines whether this quaternion has the same value of another quaternion.
[ConstOperation] public bool Equals(
other
Another quaternion to compare.
)
true if the quaternions have exactly equal coefficients; otherwise false.

GetEulerZYZ

#Since v8.0
Find the Euler angles for a rotation transformation.
[ConstOperation] public bool GetEulerZYZ(
out double
alpha,
Angle, in radians, to rotate about the ZAxis.
out double
beta,
Angle, in radians, to rotate about the YAxis.
out double
gamma
Angle, in radians, to rotate about the ZAxis.
)
Remarks: When true, this = RotationZYZ(alpha, beta, gamma) = R_z(alpha) * R_y(beta) * R_z(gamma), where R_*(angle) is rotation of angle radians about the corresponding *-world coordinate axis. alpha and gamma are in the range (-pi, pi], while beta in the range [0, pi].
true if successful, or false if this is not a rotation.

GetHashCode

#
Gets a non-unique but repeatable hashing code for this quaternion.
[ConstOperation] public override int GetHashCode()
A signed number.

GetRotation

#Since v5.0
Returns the rotation defined by the quaternion.
[ConstOperation] public bool GetRotation(
out double
angle,
An angle in radians.
axis
unit axis of rotation of 0 if (b,c,d) is the zero vector.
)
Remarks: If the quaternion is not unitized, the rotation of its unitized form is returned.
True if the operation succeeded; otherwise, false.

GetRotation

#Since v5.0
Returns the frame created by applying the quaternion's rotation to the canonical world frame (1,0,0),(0,1,0),(0,0,1).
[ConstOperation] public bool GetRotation(
out Plane
plane
A plane. This out value will be assigned during this call.
)
true if the operation succeeded; otherwise, false.

GetRotation

#Since v7.12
Returns a transformation matrix that performs the rotation defined by the quaternion. The transformation returned by this method has the property that xform * V = q.Rotate(V). If the quaternion is not unitized, the rotation of its unitized form is returned.
[ConstOperation] public bool GetRotation(
xform
)
Remarks: Do not confuse the result of this method the transformation matrix returned by MatrixForm().
true if successful, false otherwise.

GetYawPitchRoll

#Since v8.0
Find sthe Tait-Byran angles, also loosely called Euler angles, for this quaternion.
[ConstOperation] public bool GetYawPitchRoll(
out double
yaw,
Angle, in radians, to rotate about the ZAxis.
out double
pitch,
Angle, in radians, to rotate about the YAxis.
out double
roll
Angle, in radians, to rotate about the XAxis.
)
Remarks: When true, this = RotationZYX(yaw, pitch, roll) = R_z(yaw) * R_y(pitch) * R_x(roll), where R_*(angle) is rotation of angle radians about the corresponding world coordinate axis. roll and yaw are in the range (-pi, pi], and pitch is in [-pi/2, pi/2].
true if successful, or false if this is not a rotation.

Invert

#Since v5.0
Modifies this quaternion to become

(a/L2, -b/L2, -c/L2, -d/L2),

where L2 = length squared = (a*a + b*b + c*c + d*d).

This is the multiplicative inverse, i.e., (a,b,c,d)*(a/L2, -b/L2, -c/L2, -d/L2) = (1,0,0,0).

public bool Invert()
true if successful. false if the quaternion is zero and cannot be inverted.

Lerp

#Since v8.0
Interpolates between two quaternions, using linear interpolation.
public static Quaternion Lerp(
a,
The first quaternion.
b,
The second quaternion.
t
The parameter in the range [0, 1].
)
The interpolated quaternion.

MatrixForm

#Since v5.0
Returns 4x4 real valued matrix form of the quaternion a b c d -b a -d c -c d a -b -d -c b a which has the same arithmetic properties as the quaternion.
[ConstOperation] public Transform MatrixForm()
Remarks: Do not confuse this with the rotation defined by the quaternion. This function will only be interesting to math nerds and is not useful in rendering or animation applications.
A transform value.

Product

#Since v5.0
The quaternion product of p and q. This is the same value as p*q.
public static Quaternion Product(
p,
The first transform.
q
The second transform.
)
A transform value.

Rotate

#Since v5.0
Rotates a 3d vector. This operation is also called conjugation, because the result is the same as (q.Conjugate()*(0,x,y,x)*q/q.LengthSquared).Vector.
[ConstOperation] public Vector3d Rotate(
v
The vector to be rotated.
)
Remarks: If you need to rotate more than a dozen or so vectors, it will be more efficient to calculate the rotation matrix once and use it repeatedly.
R*v, where R is the rotation defined by the unit quaternion. This is mathematically the same as the values (Inverse(q)*(0,x,y,z)*q).Vector and (q.Conjugate()*(0,x,y,x)*q/q.LengthSquared).Vector.

RotateTowards

#Since v8.0
Returns the quaternion obtained by rotating a towards b, limiting the rotation by MaxRadians.
public static Quaternion RotateTowards(
a,
The first quaternion.
b,
The second quaternion.
maxRadians
The maximum rotation in radians.
)
The rotated quaternion.

Rotation

#Since v5.0
Returns the unit quaternion cos(angle/2), sin(angle/2)*x, sin(angle/2)*y, sin(angle/2)*z where (x,y,z) is the unit vector parallel to axis. This is the unit quaternion that represents the rotation of angle about axis.
public static Quaternion Rotation(
angle,
An angle in radians.
axisOfRotation
The axis of rotation.
)
A new quaternion.

Rotation

#Since v5.0
Returns the unit quaternion that represents the rotation that maps plane0.xaxis to plane1.xaxis, plane0.yaxis to plane1.yaxis, and plane0.zaxis to plane1.zaxis.
public static Quaternion Rotation(
plane0,
The first plane.
plane1
The second plane.
)
Remarks: The plane origins are ignored
A quaternion value.

Set

#Since v5.0
Sets all coefficients of the quaternion.
public void Set()

SetRotation

#Since v5.0
Sets the quaternion to cos(angle/2), sin(angle/2)*x, sin(angle/2)*y, sin(angle/2)*z where (x,y,z) is the unit vector parallel to axis. This is the unit quaternion that represents the rotation of angle about axis.
public void SetRotation(
angle,
in radians.
axisOfRotation
The direction of the axis of rotation.
)

SetRotation

#Since v5.0
Sets the quaternion to the unit quaternion which rotates plane0.xaxis to plane1.xaxis, plane0.yaxis to plane1.yaxis, and plane0.zaxis to plane1.zaxis.
public void SetRotation(
plane0,
The "from" rotation plane. Origin point is ignored.
plane1
The "to" rotation plane. Origin point is ignored.
)
Remarks: The plane origins are ignored

Slerp

#Since v8.0
Interpolates between two quaternions, using spherical linear interpolation.
public static Quaternion Slerp(
a,
The first quaternion.
b,
The second quaternion.
t
The parameter in the range [0, 1].
)
The interpolated quaternion.

ToString

#Since v7.12
Returns a string representation of this Quaternion.
[ConstOperation] public override string ToString()
A textual representation.

Unitize

#Since v5.0
Scales the quaternion's coordinates so that a*a + b*b + c*c + d*d = 1.
public bool Unitize()
true if successful. false if the quaternion is zero and cannot be unitized.

Operators

OperationResultDescription
Quaternion+QuaternionQuaternionAdds two quaternions.

This sums each quaternion coefficient with its correspondent and returns a new result quaternion.

Quaternion/doubleQuaternionDivides all quaternion coefficients by a factor and returns a new quaternion with the result.
Quaternion==QuaternionboolDetermines whether two quaternions have the same value.
Quaternion!=QuaternionboolDetermines whether two quaternions have different values.
Quaternion*QuaternionQuaternionMultiplies a quaternion with another one.

Quaternion multiplication (Hamilton product) is not commutative.

Quaternion*doubleQuaternionMultiplies (scales) all quaternion coefficients by a factor and returns a new quaternion with the result.
Quaternion*floatQuaternionMultiplies (scales) all quaternion coefficients by a factor and returns a new quaternion with the result.
Quaternion*intQuaternionMultiplies (scales) all quaternion coefficients by a factor and returns a new quaternion with the result.
Quaternion-QuaternionQuaternionSubtracts a quaternion from another one.

This computes the difference of each quaternion coefficient with its correspondent and returns a new result quaternion.