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
public Quaternion(double a, double b, double c, double d)
Initializes a new quaternion with the provided coefficients.
Parameters:
a (double)A number. This is the real part.
b (double)Another number. This is the first coefficient of the imaginary part.
c (double)Another number. This is the second coefficient of the imaginary part.
d (double)Another number. This is the third coefficient of the imaginary part.

Properties

A

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

B

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

C

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

Conjugate

#Since v5.0
public Quaternion Conjugate { get; }
Gets a new quaternion that is the conjugate of this quaternion.

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

D

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

I

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

Identity

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

Inverse

#Since v5.0
public Quaternion Inverse { get; }
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.

IsScalar

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

IsValid

#Since v5.0
public bool IsValid { get; }
Determines if the four coefficients are valid numbers within RhinoCommon.

See RhinoMath.IsValidDouble(double).

IsVector

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

IsZero

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

J

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

K

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

Length

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

LengthSquared

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

Scalar

#Since v5.0
public double Scalar { get; }
The real (scalar) part of the quaternion

This is A.

Vector

#Since v5.0
public Vector3d Vector { get; }
The imaginary part of the quaternion

(B,C,D)

Zero

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

Methods

CreateFromRotationZYX

#Since v8.0
public static Quaternion CreateFromRotationZYX(double yaw, double pitch, double roll)
Constructs a quaternion defined by Tait-Byran angles, also loosely known as Euler angles.
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.
Parameters:
yaw (double)Angle, in radians, to rotate about the ZAxis.
pitch (double)Angle, in radians, to rotate about the YAxis.
roll (double)Angle, in radians, to rotate about the XAxis.
Returns: The quaternion.

CreateFromRotationZYZ

#Since v8.0
public static Quaternion CreateFromRotationZYZ(double alpha, double beta, double gamma)
Constructs a quaternion defined by Euler angles.
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.
Parameters:
alpha (double)Angle, in radians, to rotate about the ZAxis.
beta (double)Angle, in radians, to rotate about the YAxis.
gamma (double)Angle, in radians, to rotate about the ZAxis.
Returns: The quaternion.

CrossProduct

#Since v5.0
public static Quaternion CrossProduct(Quaternion p, Quaternion q)
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.

Parameters:
p (Quaternion)A quaternion.
q (Quaternion)Another quaternion.
Returns: A new quaternion.

Distance

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

DistanceTo

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

EpsilonEquals

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

Equals

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

Equals

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

GetEulerZYZ

#Since v8.0
[ConstOperation] public bool GetEulerZYZ(out double alpha, out double beta, out double gamma)
Find the Euler angles for a rotation transformation.
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].
Parameters:
alpha (out double)Angle, in radians, to rotate about the ZAxis.
beta (out double)Angle, in radians, to rotate about the YAxis.
gamma (out double)Angle, in radians, to rotate about the ZAxis.
Returns: true if successful, or false if this is not a rotation.

GetHashCode

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

GetRotation

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

GetRotation

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

GetRotation

#Since v7.12
[ConstOperation] public bool GetRotation(out Transform xform)
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.
Remarks: Do not confuse the result of this method the transformation matrix returned by MatrixForm().
Parameters:
xform (out Transform)
Returns: true if successful, false otherwise.

GetYawPitchRoll

#Since v8.0
[ConstOperation] public bool GetYawPitchRoll(out double yaw, out double pitch, out double roll)
Find sthe Tait-Byran angles, also loosely called Euler angles, for this quaternion.
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].
Parameters:
yaw (out double)Angle, in radians, to rotate about the ZAxis.
pitch (out double)Angle, in radians, to rotate about the YAxis.
roll (out double)Angle, in radians, to rotate about the XAxis.
Returns: true if successful, or false if this is not a rotation.

Invert

#Since v5.0
public bool Invert()
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).

Returns: true if successful. false if the quaternion is zero and cannot be inverted.

Lerp

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

MatrixForm

#Since v5.0
[ConstOperation] public Transform MatrixForm()
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.
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.
Returns: A transform value.

Product

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

Rotate

#Since v5.0
[ConstOperation] public Vector3d Rotate(Vector3d v)
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.
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.
Parameters:
v (Vector3d)The vector to be rotated.
Returns: 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
public static Quaternion RotateTowards(Quaternion a, Quaternion b, double maxRadians)
Returns the quaternion obtained by rotating a towards b, limiting the rotation by MaxRadians.
Parameters:
a (Quaternion)The first quaternion.
b (Quaternion)The second quaternion.
maxRadians (double)The maximum rotation in radians.
Returns: The rotated quaternion.

Rotation

#Since v5.0
public static Quaternion Rotation(double angle, Vector3d axisOfRotation)
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.
Parameters:
angle (double)An angle in radians.
axisOfRotation (Vector3d)The axis of rotation.
Returns: A new quaternion.

Rotation

#Since v5.0
public static Quaternion Rotation(Plane plane0, Plane plane1)
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.
Remarks: The plane origins are ignored
Parameters:
plane0 (Plane)The first plane.
plane1 (Plane)The second plane.
Returns: A quaternion value.

Set

#Since v5.0
public void Set(double a, double b, double c, double d)
Sets all coefficients of the quaternion.
Parameters:
a (double)
b (double)
c (double)
d (double)

SetRotation

#Since v5.0
public void SetRotation(double angle, Vector3d axisOfRotation)
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.
Parameters:
angle (double)in radians.
axisOfRotation (Vector3d)The direction of the axis of rotation.

SetRotation

#Since v5.0
public void SetRotation(Plane plane0, Plane plane1)
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.
Remarks: The plane origins are ignored
Parameters:
plane0 (Plane)The "from" rotation plane. Origin point is ignored.
plane1 (Plane)The "to" rotation plane. Origin point is ignored.

Slerp

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

ToString

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

Unitize

#Since v5.0
public bool Unitize()
Scales the quaternion's coordinates so that a*a + b*b + c*c + d*d = 1.
Returns: 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.