# Module `OCADml.Quaternion`

Provides functions for the creation of and operations between quaternions. These can be used to create composable and interpolatable rotations to be applied to 3d vectors (`V3.t`), and shapes.

`type t`
`val id : t`

The identity quaternion: `{ x = 0.; y = 0.; z = 0.; w = 1. }`

`val make : V3.t -> float -> t`

`make ax angle`

Create a quaternion representing a rotation of `angle` (in radians) around the vector `ax`.

## Basic Arithmetic

`val add : t -> t -> t`

`add a b`

Hadamard (element-wise) addition of quaternions `a` and `b`.

`val sub : t -> t -> t`

`sub a b`

Hadamard (element-wise) subtraction of quaternion `b` from `a`.

`val mul : t -> t -> t`

`mul a b`

Quaternion multiplication of `a` and `b`.

`val neg : t -> t`

`neg t`

Negation of all elements of `t`.

`val sadd : t -> float -> t`

`sadd t s`

Add `s` to the magnitude of `t`, leaving the imaginary parts unchanged.

`val ssub : t -> float -> t`

`ssub t s`

Subtract `s` from the magnitude of `t`, leaving the imaginary parts unchanged.

`val ssub_neg : t -> float -> t`

`ssub_neg t s`

Negate the imaginary parts of `t`, and subtract the magnitude from `s` to obtain the new magnitude.

`val smul : t -> float -> t`

`smul t s`

Element-wise multiplication of `t` by `s`.

`val sdiv : t -> float -> t`

`div_scalar t s`

Element-wise division of `t` by `s`.

## Vector Math

`val norm : t -> float`

`norm t`

Calculate the vector norm (a.k.a. magnitude) of `t`.

`val normalize : t -> t`

`normalize t`

Normalize `t` to a quaternion for which the magnitude is equal to 1. e.g. `norm (normalize t) = 1.`

`val dot : t -> t -> float`

`dot a b`

Vector dot product of `a` and `b`.

`val conj : t -> t`

`conj t`

Take the conjugate of the quaternion `t`, negating the imaginary parts (x, y, and z) of `t`, leaving the magnitude unchanged.

`val distance : t -> t -> float`

`distance a b`

Calculate the magnitude of the difference (Hadamard subtraction) between `a` and `b`.

Conversions

`val of_euler : V3.t -> t`

`of_euler v`

Create a quaternion equivalent to the Euler angle rotations represented by `v`.

`val to_euler : t -> V3.t`

`to_euler t`

Convert the quaternion `t` to equivalent Euler angles.

`val to_affine : ?trans:V3.t -> t -> Affine3.t`

`to_affine ?trans t`

Convert quaternion `t` into an `Affine3.t`, optionally providing a translation vector `trans` to tack on.

## Vector Transformations

`val align : V3.t -> V3.t -> t`

`align a b`

Calculate a quaternion that would bring `a` into alignment with `b`.

`val transform : ?about:V3.t -> t -> V3.t -> V3.t`

`transform ?about t v`

Rotate `v` with the quaternion `t` around the origin (or the point `about` if provided).

## Utilities

`val slerp : t -> t -> float -> t`

`slerp a b step`

Spherical linear interpotation. Adapted from pyquaternion.

`val to_string : t -> string`