Quaternion Type
A struct containing 4 floats, representing an immutable unitized Quaternion, for arbitrary 3D rotations. This implementation guarantees the Quaternion to be always unitized. Note: Never use the struct default constructor Quaternion() as it will create an invalid zero length Quaternion. Use Quaternion.create or Quaternion.createUnchecked instead.
Record fields
| Record Field |
Description
|
Full Usage:
W
Field type: float
|
The field holding the W component of this Quaternion.
|
Full Usage:
X
Field type: float
|
The field holding the X component of this Quaternion.
|
Full Usage:
Y
Field type: float
|
The field holding the Y component of this Quaternion.
|
Full Usage:
Z
Field type: float
|
The field holding the Z component of this Quaternion.
|
Instance members
| Instance member |
Description
|
Full Usage:
this.AngleInDegrees
Returns: float
Modifiers: inline |
Returns the angle in degrees.
|
Full Usage:
this.AngleInRadians
Returns: float
Modifiers: inline |
Returns the angle in radians.
|
Full Usage:
this.AsFSharpCode
Returns: string
|
Format Quaternion into an F# code string that can be used to recreate the quaternion.
|
Full Usage:
this.AsString
Returns: string
|
Format Quaternion into string also showing angle in degrees as nicely formatted floating point number. Using nice floating point number formatting. But without full type name as in q.ToString()
|
Returns the rotation axis of this Quaternion as a (non-unit) vector. This is just q.X, q.Y and q.Z, which equals axis * sin(angle/2). For the identity quaternion (no rotation), this returns a zero-length vector Vec(0,0,0). The length of this vector is sin(angle/2), ranging from 0 (no rotation) to 1 (180° rotation).
|
|
|
Returns a new Quaternion for the inverse rotation. Same as q.Inverse.
|
Full Usage:
this.Half
Returns: Quaternion
A unit quaternion whose composition with itself represents this rotation.
|
Returns half the shortest rotation. Preserves the encoded axis for rotations between -180 and 180 degrees, inclusive. Reverses the axis only when the encoded rotation exceeds 180 degrees in magnitude (W is negative).
|
|
Returns a new Quaternion for the inverse rotation. Same as q.Conjugate.
|
|
This method should normally not be needed as Euclid Quaternions are always unitized. However, use this to correct numerical drift after many quaternion multiplications. This is the same as calling Quaternion.create with the current components. Returns a renormalized copy of this Quaternion with unit length.
|
Full Usage:
this.ScaleAngle
Parameters:
float
-
The finite multiplier applied to the encoded angle.
Returns: Quaternion
A new unit quaternion; ordinary identity remains identity.
|
Scales the encoded rotation angle in [0, 360] degrees, preserving the encoded axis. This is basically `slerp` (spherical linear interpolation) with the identity quaternion as the start and the same axis as the target. Negative factors reverse the rotation; factors above one extend it. The factor is not clamped. Unlike quat.Half, this does not choose the shortest rotation. Fails for (0, 0, 0, -1), whose full-turn axis is undefined, or if the factor or scaled half angle is not finite.
|
Full Usage:
this.Slerp
Parameters:
Quaternion
-
The quaternion at factor 1.
factor : float
-
The finite interpolation factor.
Returns: Quaternion
A new unit quaternion.
|
Spherical linear interpolation along the shortest rotation from this quaternion to finish. If the 4D dot product of the two quaternions is negative, finish is negated first, so q and -q as finish give the same orientations. The result rotates at a constant angular speed around one fixed axis, so a rotated vector moves on a cone around that axis. Factor 0 returns this quaternion and factor 1 returns finish, or finish with all components negated if the dot product is negative. The factor is not clamped: negative factors and factors above one extrapolate the rotation. Fails if the factor is not finite.
|
Full Usage:
this.SlerpEncoded
Parameters:
Quaternion
-
The quaternion at factor 1.
factor : float
-
The finite interpolation factor.
Returns: Quaternion
A new unit quaternion.
|
Spherical linear interpolation along the encoded path from this quaternion to finish. Unlike Slerp, this never negates finish, so it may take the long way around: from q to -q it does a full 360 degree turn. From the identity quaternion this is the same as finish.ScaleAngle factor. The result rotates at a constant angular speed around one fixed axis, so a rotated vector moves on a cone around that axis. Factor 0 returns this quaternion and factor 1 returns finish. The factor is not clamped: negative factors and factors above one extrapolate the rotation. Fails if the factor is not finite, or if finish is exactly the negation of this quaternion, because then the axis of the full turn is undefined.
|
Full Usage:
this.Then
Parameters:
Quaternion
-
The other Quaternion (applied second).
Returns: Quaternion
A new Quaternion that rotates like this one followed by other.
Modifiers: inline |
Combines this rotation with another one. The resulting rotation will first do this Quaternion and then the other. The application order is the same as in Matrix.multiply and RigidMatrix.multiply.
|
Full Usage:
this.WithAngleInDegrees
Parameters:
float
Returns: Quaternion
Modifiers: inline |
Get a new Quaternion that rotates around the same axis but with a different angle. In degrees. Fails for identity or near-identity quaternions where the rotation axis is not defined (angle ≈ 0).
|
|
Get a new Quaternion that rotates around the same axis but with a different angle. In radians. Fails for identity or near-identity quaternions where the rotation axis is not defined (angle ≈ 0).
|
Static members
| Static member |
Description
|
|
Rotate by Quaternion around Origin. Multiplies (or applies) a Quaternion to a 3D point.
|
|
Rotate by Quaternion around Origin. Multiplies (or applies) a Quaternion to a 3D unit-vector.
|
|
Rotate by Quaternion around Origin. Multiplies (or applies) a Quaternion to a 3D vector.
|
|
Multiply two Quaternions (Hamilton product l * r). Note: The resulting rotation first does r and then l. This is the opposite order of the *** operator on Matrix and RigidMatrix. Use l.Then(r) for the same application order as in Matrix *** Matrix (first l, then r).
|
|
The identity quaternion that does not do any rotation. This is Quaternion(x=0, y=0, z=0, w=1)
|
Full Usage:
Quaternion.andThen next q
Parameters:
Quaternion
-
The Quaternion applied second.
q : Quaternion
-
The Quaternion applied first.
Returns: Quaternion
A new Quaternion that rotates like q followed by next.
Modifiers: inline |
Combines two rotations for use in a pipeline: 'q |> Quaternion.andThen next' first does q and then next. Same as q.Then next. Unlike Quaternion.multiply, the first argument is applied second.
|
|
|
|
|
|
Format Quaternion into an F# code string that can be used to recreate the quaternion.
|
|
Format Quaternion into string also showing angle in degrees as nicely formatted floating point number. Using nice floating point number formatting. But without full type name as in q.ToString()
|
|
Returns the rotation axis of this Quaternion as a (non-unit) vector. This is just q.X, q.Y and q.Z, which equals axis * sin(angle/2). For the identity quaternion (no rotation), this returns a zero-length vector Vec(0,0,0). The length of this vector is sin(angle/2), ranging from 0 (no rotation) to 1 (180° rotation).
|
|
Returns a new Quaternion for the inverse rotation. Same as q.Inverse.
|
Full Usage:
Quaternion.create (x, y, z, w)
Parameters:
float
y : float
z : float
w : float
Returns: Quaternion
|
This constructor does unitizing too. And fails if the input has near-zero length. Unlike Rotation2D.create, this normalizes its input instead of only validating it.
|
Full Usage:
Quaternion.createFromDegreesUnitVec axis angleInDegrees
Parameters:
UnitVec
angleInDegrees : float
Returns: Quaternion
Modifiers: inline |
The created rotation is Clockwise looking in the direction of the unit-vector.
|
Full Usage:
Quaternion.createFromDegreesVec axis angleInDegrees
Parameters:
Vec
angleInDegrees : float
Returns: Quaternion
Modifiers: inline |
The created rotation is Clockwise looking in the direction of the vector (of any length but zero).
|
Full Usage:
Quaternion.createFromEulerXYZDegrees degreesX degreesY degreesZ
Parameters:
float
degreesY : float
degreesZ : float
Returns: Quaternion
|
Angles are given in degrees, The order in which to apply rotations is X-Y-Z, which means that the object will first be rotated around its X-axis, then its Y-axis and finally its Z-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order X-Y-Z, the rotation is first around the local-X-axis (which is the same as the World-X-axis), then around local-Y (which may now be different from the World Y-axis), then local-Z (which may be different from the World Z-axis) Same as Quaternion.createFromEulerXYZRadians with the angles converted to radians.
|
Full Usage:
Quaternion.createFromEulerXYZRadians radiansX radiansY radiansZ
Parameters:
float
radiansY : float
radiansZ : float
Returns: Quaternion
|
Angles are given in radians, The order in which to apply rotations is X-Y-Z, which means that the object will first be rotated around its X-axis, then its Y-axis and finally its Z-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order X-Y-Z, the rotation is first around the local-X-axis (which is the same as the World-X-axis), then around local-Y (which may now be different from the World Y-axis), then local-Z (which may be different from the World Z-axis)
|
Full Usage:
Quaternion.createFromEulerXZYDegrees degreesX degreesZ degreesY
Parameters:
float
degreesZ : float
degreesY : float
Returns: Quaternion
|
Angles are given in degrees, The order in which to apply rotations is X-Z-Y, which means that the object will first be rotated around its X-axis, then its Z-axis and finally its Y-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order X-Z-Y, the rotation is first around the local-X-axis (which is the same as the World-X-axis), then around local-Z (which may now be different from the World Z-axis), then local-Y (which may be different from the World Y-axis) Same as Quaternion.createFromEulerXZYRadians with the angles converted to radians.
|
Full Usage:
Quaternion.createFromEulerXZYRadians radiansX radiansZ radiansY
Parameters:
float
radiansZ : float
radiansY : float
Returns: Quaternion
|
Angles are given in radians, The order in which to apply rotations is X-Z-Y, which means that the object will first be rotated around its X-axis, then its Z-axis and finally its Y-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order X-Z-Y, the rotation is first around the local-X-axis (which is the same as the World-X-axis), then around local-Z (which may now be different from the World Z-axis), then local-Y (which may be different from the World Y-axis)
|
Full Usage:
Quaternion.createFromEulerYXZDegrees degreesY degreesX degreesZ
Parameters:
float
degreesX : float
degreesZ : float
Returns: Quaternion
|
Angles are given in degrees, The order in which to apply rotations is Y-X-Z, which means that the object will first be rotated around its Y-axis, then its X-axis and finally its Z-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order Y-X-Z, the rotation is first around the local-Y-axis (which is the same as the World-Y-axis), then around local-X (which may now be different from the World X-axis), then local-Z (which may be different from the World Z-axis) Same as Quaternion.createFromEulerYXZRadians with the angles converted to radians.
|
Full Usage:
Quaternion.createFromEulerYXZRadians radiansY radiansX radiansZ
Parameters:
float
radiansX : float
radiansZ : float
Returns: Quaternion
|
Angles are given in radians, The order in which to apply rotations is Y-X-Z, which means that the object will first be rotated around its Y-axis, then its X-axis and finally its Z-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order Y-X-Z, the rotation is first around the local-Y-axis (which is the same as the World-Y-axis), then around local-X (which may now be different from the World X-axis), then local-Z (which may be different from the World Z-axis)
|
Full Usage:
Quaternion.createFromEulerYZXDegrees degreesY degreesZ degreesX
Parameters:
float
degreesZ : float
degreesX : float
Returns: Quaternion
|
Angles are given in degrees, The order in which to apply rotations is Y-Z-X, which means that the object will first be rotated around its Y-axis, then its Z-axis and finally its X-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order Y-Z-X, the rotation is first around the local-Y-axis (which is the same as the World-Y-axis), then around local-Z (which may now be different from the World Z-axis), then local-X (which may be different from the World X-axis) Same as Quaternion.createFromEulerYZXRadians with the angles converted to radians.
|
Full Usage:
Quaternion.createFromEulerYZXRadians radiansY radiansZ radiansX
Parameters:
float
radiansZ : float
radiansX : float
Returns: Quaternion
|
Angles are given in radians, The order in which to apply rotations is Y-Z-X, which means that the object will first be rotated around its Y-axis, then its Z-axis and finally its X-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order Y-Z-X, the rotation is first around the local-Y-axis (which is the same as the World-Y-axis), then around local-Z (which may now be different from the World Z-axis), then local-X (which may be different from the World X-axis)
|
Full Usage:
Quaternion.createFromEulerZXYDegrees degreesZ degreesX degreesY
Parameters:
float
degreesX : float
degreesY : float
Returns: Quaternion
|
Angles are given in degrees, The order in which to apply rotations is Z-X-Y, which means that the object will first be rotated around its Z-axis, then its X-axis finally its Y-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order Z-X-Y, the rotation is first around the local-Z-axis (which is the same as the World-Z-axis), then around local-X (which may now be different from the World X-axis), then local-Y (which may be different from the World Y-axis) Same as Quaternion.createFromEulerZXYRadians with the angles converted to radians.
|
Full Usage:
Quaternion.createFromEulerZXYRadians radiansZ radiansX radiansY
Parameters:
float
radiansX : float
radiansY : float
Returns: Quaternion
|
Angles are given in radians, The order in which to apply rotations is Z-X-Y, which means that the object will first be rotated around its Z-axis, then its X-axis finally its Y-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order Z-X-Y, the rotation is first around the local-Z-axis (which is the same as the World-Z-axis), then around local-X (which may now be different from the World X-axis), then local-Y (which may be different from the World Y-axis)
|
Full Usage:
Quaternion.createFromEulerZYXDegrees degreesZ degreesY degreesX
Parameters:
float
degreesY : float
degreesX : float
Returns: Quaternion
|
Angles are given in degrees, The order in which to apply rotations is Z-Y-X, which means that the object will first be rotated around its Z-axis, then its Y-axis and finally its X-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order Z-Y-X, the rotation is first around the local Z-axis (which is the same as the World Z-axis), then around local-Y (which may now be different from the World Y-axis), then local-X (which may be different from the World X-axis) Same as Quaternion.createFromEulerZYXRadians with the angles converted to radians.
|
Full Usage:
Quaternion.createFromEulerZYXRadians radiansZ radiansY radiansX
Parameters:
float
radiansY : float
radiansX : float
Returns: Quaternion
|
Angles are given in radians, The order in which to apply rotations is Z-Y-X, which means that the object will first be rotated around its Z-axis, then its Y-axis and finally its X-axis. This uses intrinsic Tait-Bryan angles. This means that rotations are performed with respect to the local coordinate system. That is, for order Z-Y-X, the rotation is first around the local Z-axis (which is the same as the World Z-axis), then around local-Y (which may now be different from the World Y-axis), then local-X (which may be different from the World X-axis)
|
Full Usage:
Quaternion.createFromRadiansUnitVec axis angleInRadians
Parameters:
UnitVec
angleInRadians : float
Returns: Quaternion
Modifiers: inline |
The created rotation is Clockwise looking in the direction of the unit-vector.
|
Full Usage:
Quaternion.createFromRadiansVec axis angleInRadians
Parameters:
Vec
angleInRadians : float
Returns: Quaternion
|
The created rotation is Clockwise looking in the direction of the vector. The vector may be of any length but zero.
|
Full Usage:
Quaternion.createFromUnitVecs vecFrom vecTo
Parameters: Returns: Quaternion
Modifiers: inline |
Creates a rotation from one vector's direction to another vector's direction. If the tips of the two unit vectors are closer than 1e-12 (squared: 1e-24) then an identity Quaternion is returned. If the tips of the two vectors are almost exactly opposite (sum length too small), there is no valid unique 180 degree rotation that can be found, so an exception is raised.
|
|
Creates a rotation from one vector's direction to another vector's direction. If the tips of the two vectors (unitized) are closer than 1e-12 (squared: 1e-24) then an identity Quaternion is returned. If the tips of the two vectors (unitized) are almost exactly opposite (sum length too small), there is no valid unique 180 degree rotation that can be found, so an exception is raised.
|
Full Usage:
Quaternion.createUnchecked (x, y, z, w)
Parameters:
float
y : float
z : float
w : float
Returns: Quaternion
Modifiers: inline |
This unsafe constructor does NOT do any unitizing or zero length checks.
|
Full Usage:
Quaternion.equalsExact a b
Parameters:
Quaternion
b : Quaternion
Returns: bool
Modifiers: inline |
Checks if two Quaternions are exactly equal. Compares each field with the = operator, so a NaN value is never equal.
|
Full Usage:
Quaternion.equalsRotationWithin tolerance a b
Parameters:
float
a : Quaternion
b : Quaternion
Returns: bool
Modifiers: inline |
Checks if two Quaternion represent an equal rotation within tolerance. The tolerance applies to each of the X, Y, Z and W components separately, as in Quaternion.equalsWithin. Use a tolerance of 0.0 to check for an exact match. Note: A Quaternion with every component negated represents the same rotation and will be considered equal by this function. For component-wise equality, consider using Quaternion.equalsWithin function.
|
Full Usage:
Quaternion.equalsWithin tolerance a b
Parameters:
float
a : Quaternion
b : Quaternion
Returns: bool
Modifiers: inline |
Checks if two Quaternion are equal within tolerance. The tolerance applies to each of the X, Y, Z and W components separately. Use Quaternion.equalsExact to check for an exact match. Note: A Quaternion with every component negated represents the same rotation but will be considered unequal by this function. For rotational equivalence, consider using Quaternion.equalsRotationWithin function.
|
Full Usage:
Quaternion.half rotation
Parameters:
Quaternion
-
The unit quaternion to halve.
Returns: Quaternion
The half rotation; both identity representations return identity.
Modifiers: inline |
Returns half the shortest rotation. Preserves the encoded axis for rotations between -180 and 180 degrees, inclusive. Reverses the axis only when the encoded rotation exceeds 180 degrees in magnitude (W is negative).
|
|
Returns a new Quaternion for the inverse rotation. Same as q.Conjugate.
|
Full Usage:
Quaternion.multiply (l, r)
Parameters:
Quaternion
r : Quaternion
Returns: Quaternion
|
Multiply two Quaternions (Hamilton product l * r). Note: The resulting rotation first does r and then l. This is the opposite order of Matrix.multiply and RigidMatrix.multiply. Use l.Then(r) for the same application order as in Matrix.multiply (first l, then r). Note: Repeated multiplications may accumulate floating-point errors that violate the unit-length invariant. Use q.Normalize() to renormalize if combining many rotations.
|
|
This method should normally not be needed as Euclid Quaternions are always unitized. However, use this to correct numerical drift after many quaternion multiplications. This is the same as calling Quaternion.create with the current components. Returns a renormalized copy of this Quaternion with unit length.
|
Full Usage:
Quaternion.scaleAngle factor rotation
Parameters:
float
-
The finite angle multiplier; negative values and values above one are supported.
rotation : Quaternion
-
The unit quaternion whose encoded angle is scaled.
Returns: Quaternion
A new unit quaternion; ordinary identity remains identity.
Modifiers: inline |
Scales the encoded angle, preserving its axis without choosing the shortest rotation. This is basically `slerp` (spherical linear interpolation) with the identity quaternion as the start and the same axis as the target. The factor is not clamped. Fails for (0, 0, 0, -1), whose axis is undefined, or if the factor or scaled half angle is not finite.
|
Full Usage:
Quaternion.slerp start finish factor
Parameters:
Quaternion
-
The quaternion at factor 0.
finish : Quaternion
-
The quaternion at factor 1.
factor : float
-
The finite interpolation factor.
Returns: Quaternion
A new unit quaternion.
Modifiers: inline |
Spherical linear interpolation along the shortest rotation from start to finish. If the 4D dot product of the two quaternions is negative, finish is negated first, so q and -q as finish give the same orientations. The result rotates at a constant angular speed around one fixed axis, so a rotated vector moves on a cone around that axis. Factor 0 returns start and factor 1 returns finish, or finish with all components negated if the dot product is negative. The factor is not clamped: negative factors and factors above one extrapolate the rotation. Fails if the factor is not finite.
|
Full Usage:
Quaternion.slerpEncoded start finish factor
Parameters:
Quaternion
-
The quaternion at factor 0.
finish : Quaternion
-
The quaternion at factor 1.
factor : float
-
The finite interpolation factor.
Returns: Quaternion
A new unit quaternion.
Modifiers: inline |
Spherical linear interpolation along the encoded path from start to finish. Unlike slerp, this never negates finish, so it may take the long way around: from q to -q it does a full 360 degree turn. From the identity quaternion this is the same as Quaternion.scaleAngle factor finish. The result rotates at a constant angular speed around one fixed axis, so a rotated vector moves on a cone around that axis. Factor 0 returns start and factor 1 returns finish. The factor is not clamped: negative factors and factors above one extrapolate the rotation. Fails if the factor is not finite, or if finish is exactly the negation of start, because then the axis of the full turn is undefined.
|
|
The quaternion expresses a relationship between two coordinate frames, A and B say. Returns the EulerAngles in degrees: Alpha, Beta, Gamma. This relationship, if expressed using Euler angles, is as follows: 1) Rotate Frame A about its Z-axis by angle Gamma; 2) Rotate the resulting frame about its (new) Y-axis by angle Beta; 3) Rotate the resulting frame about its (new) X-axis by angle Alpha, to arrive at frame B. Returns the angles in degrees as triple. For rotating first around the axis Z then local Y and finally local X. Note: This conversion may encounter gimbal lock issues when Beta is near ±90°. see Quaternion.createFromEulerZYXDegrees z y x
|
Full Usage:
Quaternion.withAngleInDegrees angleInDegrees q
Parameters:
float
q : Quaternion
Returns: Quaternion
Modifiers: inline |
Get a new Quaternion that rotates around the same axis but with a different angle. In degrees. Fails for identity or near-identity quaternions where the rotation axis is not defined (angle ≈ 0).
|
Full Usage:
Quaternion.withAngleInRadians angleInRadians q
Parameters:
float
q : Quaternion
Returns: Quaternion
Modifiers: inline |
Returns a quaternion with the same rotation axis and the specified angle in radians. Fails for identity or near-identity quaternions where the rotation axis is not defined (angle ≈ 0).
|
Euclid