Module

# Data.Quaternion.Rotation

Package
purescript-quaternions
Repository
hdgarrood/purescript-quaternions

This module provides rotations in 3D space based on quaternions. It is intended to be imported qualified, for example like this:

import Data.Quaternion.Rotation (Rotation)
import Data.Quaternion.Rotation as Rotation

### #RotationSource

newtype Rotation a

A rotation in three-dimensional space, represented by a unit quaternion (also known as a versor).

The constructor is not exported to ensure that only valid rotations can be constructed.

The semigroup instance provides composition of rotations; p <> q gives a rotation representating the rotation q followed by the rotation p. Note that in general, this is not the same as p followed by q!

### #fromQuaternionSource

fromQuaternion :: Quaternion Number -> Rotation Number

Construct a Rotation from any Quaternion, by normalizing to a versor.

### #toQuaternionSource

toQuaternion :: forall a. Rotation a -> Quaternion a

Get the underlying versor.

### #fromAngleAxisSource

fromAngleAxis :: { angle :: Number, axis :: Vec3 Number } -> Rotation Number

Construct a Rotation representing the rotation by the specified angle (in radians) about the specified axis. The rotation is clockwise from the point of view of someone looking along the direction of the rotation axis.

### #toAngleAxisSource

toAngleAxis :: Rotation Number -> { angle :: Number, axis :: Vec3 Number }

Gives the angle and axis that a rotation represents. This is the inverse of fromAngleAxis.

### #showAngleAxisSource

showAngleAxis :: Rotation Number -> String

An alternative string representation, which can be useful for debugging.

### #inverseSource

inverse :: forall a. DivisionRing a => Rotation a -> Rotation a

The inverse of a rotation. The following should hold for any rotation p:

• inverse p <> p == mempty
• p <> inverse p == mempty

### #actSource

act :: forall a. DivisionRing a => Rotation a -> Vec3 a -> Vec3 a

The action of a rotation on a vector in 3D space. This is a group action, which means that the following hold:

• Identity: act mempty == id
• Compatibility: act p (act q v) = act (p <> q) v

### #normalizeSource

normalize :: Rotation Number -> Rotation Number

Though all functions in this library which create a Rotation ensure that the underlying Quaternion has magnitude 1, after a sufficient number of arithmetic operations the magnitude may drift away from 1. In this case normalize can be used; normalize takes a possibly-drifted Rotation and rescales if it necessary, so that its magnitude returns to 1.

### #toRotationMatrixSource

toRotationMatrix :: Rotation Number -> Array Number

Represent a Rotation as a 3-by-3 rotation matrix. The return value is an array with exactly 9 elements, in column-major order.

### #fromRotationMatrixSource

fromRotationMatrix :: Partial => Array Number -> Rotation Number

Convert a 3-by-3 rotation matrix to a Rotation representing the same rotation. The argument should be an array with exactly 9 elements, with the entries in column-major order. If the argument does not have 9 elements, or if it does not represent a rotation matrix, the behaviour of this function is not defined.