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

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

#fromAngleAxis Source

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.

#toAngleAxis Source

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

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

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

Modules
Data.Quaternion
Data.Quaternion.Rotation
Data.Quaternion.Vec3