A quaternion type. Used for rotations in three dimensions.
{ vector : Vector
, scalar : Basics.Float
}
Quaternion is a combination of a 3-vector and a scalar.
quaternion : Basics.Float -> Basics.Float -> Basics.Float -> Basics.Float -> Quaternion
Construct a quaternion given its four components. The first argument is the scalar component, the rest are the vector components.
identity : Quaternion
The identity quaternion corresponds to no rotation.
identity == quaternion 1 0 0 0
xRotation : Basics.Float -> Quaternion
Create a quaternion corresponding to a rotation about the x axis by the given angle. Rotation is counter-clockwise.
q = xRotation (degrees 90)
v = vector 0 1 0 -- y axis
rotate q v == vector 0 0 1 -- rotated into z axis
yRotation : Basics.Float -> Quaternion
Create a quaternion corresponding to a rotation about the y axis by the given angle.
zRotation : Basics.Float -> Quaternion
Create a quaternion corresponding to a rotation about the z axis by the given angle.
rotationFor : Vector -> Vector -> Quaternion
Given two vectors, return a quaternion that would rotate the first vector to the second vector. The lengths of the vectors are ignored. If one or both vectors are zero, return the identity quaternion.
fromAxisAngle : Vector -> Basics.Float -> Maybe Quaternion
Create a quaternion given an axis and angle of rotation. The length of the axis is ignored, but returns Nothing if the axis is the zero vector.
fromVector : Vector -> Quaternion
Convert a rotation vector to a quaternion. A rotation vector's direction is the axis of rotation, and its length is the angle of rotation.
toVector : Quaternion -> Vector
Convert a quaternion to a rotation vector.
similar : Quaternion -> Quaternion -> Basics.Bool
Returns true if two quaternions represent the same rotation.
Rotation depends on the direction that a quaternion points in, but not its length.
The zero quaternion is only similar to itself.
mul : Quaternion -> Quaternion -> Quaternion
Multiply two quaternions.
compose : Quaternion -> Quaternion -> Quaternion
Multiplication with the operands flipped.
This can make multiplication easier to use along with the pipe operators |>
and <|
compose p q == mul q p
conjugate : Quaternion -> Quaternion
The conjugate of a quaternion.
rotate : Quaternion -> Vector -> Vector
Rotate a vector by a quaternion.
The quaternion does not have to be a unit quaternion. The vector length will be preserved.
If given the zero quaternion, no rotation will be performed.
reverseRotate : Quaternion -> Vector -> Vector
Rotate vector in the opposite direction. reverseRotate q v == rotate (conjugate q) v
encode : Quaternion -> Json.Encode.Value
Convert to a Json Value.
decode : Json.Decode.Decoder Quaternion
A Json Decoder for vectors encoded with encode
.
toMat4 : Quaternion -> Math.Matrix4.Mat4
Convert to an elm-linear-algebra Mat4
These functions are not as useful if you are just using quaternions to handle 3D rotations.
equal : Quaternion -> Quaternion -> Basics.Bool
Returns true when two quaternions are about equal (within 10^-5).
getW : Quaternion -> Basics.Float
Get scalar component.
getX : Quaternion -> Basics.Float
Get first vector component.
getY : Quaternion -> Basics.Float
Get second vector component.
getZ : Quaternion -> Basics.Float
Get third vector component.
normalize : Quaternion -> Maybe Quaternion
Return the unit quaternion that points in the same direction as the given quaternion. Return Nothing if given the zero quaternion.
lengthSquared : Quaternion -> Basics.Float
The square of the length.
length : Quaternion -> Basics.Float
The length, or norm, of the quaternion.
add : Quaternion -> Quaternion -> Quaternion
Add two quaternions.
If you are trying to combine rotations, you should to use mul
or compose
instead.
scale : Basics.Float -> Quaternion -> Quaternion
Multiply all of the quaternion's components by a factor.