nphollon / geo3d / Quaternion

A quaternion type. Used for rotations in three dimensions.

Building


type alias Quaternion =
{ 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.

Working With Rotations

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

Interop

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

Lesser Math

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.