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

### #Rotation Source

`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

### #fromQuaternion Source

`fromQuaternion :: Quaternion Number -> Rotation Number`

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

### #toQuaternion Source

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

Get the underlying versor.

### #showAngleAxis Source

`showAngleAxis :: Rotation Number -> String`

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

### #inverse Source

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

### #act Source

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

### #normalize Source

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

### #toRotationMatrix Source

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

### #fromRotationMatrix Source

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