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`!

#### Instances

• `(Ring a) => Semigroup (Rotation a)`
• `(Ring a) => Monoid (Rotation a)`
• `(Eq a) => Eq (Rotation a)`
• `(Show a) => Show (Rotation a)`

### #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.