HMath.Quaternion

Module index · Numerical conventions

Description

Finite Hamilton quaternions in scalar-first (w,x,y,z) order. Rotations are active, right-handed, column-vector rotations in radians. Product a*b applies b first. Euler angles are intrinsic ZYX (yaw, pitch, roll), returned as (roll,pitch,yaw) with pitch in [-pi2,pi2]. At gimbal lock roll is zero. Unit quaternions differing by sign represent the same rotation. Interpolation chooses the shortest sign-equivalent arc; SQUAD tangents use quaternion logs.

On this page

API	Purpose
Quaternion	A finite scalar-first Hamilton quaternion.
quaternion	Finite scalar-first constructor.
components	Scalar, x, y, z components.
norm	Scaled Euclidean norm (may overflow only when the true norm is unrepresentable).
normalize	Normalize without forming a squared norm; zero has no normalization.
inverse	Multiplicative inverse; uses component scaling to avoid norm overflow.
conjugate	Quaternion conjugation.
multiply	Hamilton product.
add	Component sum.
scale	Checked real scaling.
rotateVector	Rotate a finite three-vector; any nonzero quaternion is normalized first.
axisAngle	Axis-angle conversion.
toAxisAngle	Principal rotation angle in [0,pi]; identity uses the x axis.
fromEuler	Intrinsic ZYX rotation from (roll,pitch,yaw).
toEuler	Intrinsic ZYX angles, choosing roll zero at gimbal lock.
toMatrix	Active rotation as a row-major 3x3 matrix.
fromMatrix	Validate SO(3) within 1e-9, then use the largest-diagonal conversion near pi.
nlerp	Shortest-arc normalized linear interpolation on [0,1].
slerp	Shortest-arc spherical interpolation, with stable NLERP near equal rotations.
squad	Shoemake SQUAD through q1 to q2 using neighboring q0 and q3.
exponential	General quaternion exponential; sinc expansion stabilizes a tiny vector part.
logarithm	Principal quaternion logarithm; the negative real axis chooses positive x.
swingTwist	Decompose q = swing * twist around a nonzero axis.

Documentation

Quaternion

data Quaternion Source #

A finite scalar-first Hamilton quaternion. Construction is checked.

Instances

Instances details

Show Quaternion Source #
Instance details Defined in HMath.Quaternion Methods showsPrec :: Int -> Quaternion -> ShowS # show :: Quaternion -> String # showList :: [Quaternion] -> ShowS #
Eq Quaternion Source #
Instance details Defined in HMath.Quaternion Methods (==) :: Quaternion -> Quaternion -> Bool # (/=) :: Quaternion -> Quaternion -> Bool #

quaternion

quaternion :: Double -> Double -> Double -> Double -> Either MathError Quaternion Source #

Finite scalar-first constructor.

components

components :: Quaternion -> [Double] Source #

Scalar, x, y, z components.

norm

norm :: Quaternion -> Double Source #

Scaled Euclidean norm (may overflow only when the true norm is unrepresentable).

normalize

normalize :: Quaternion -> Either MathError Quaternion Source #

Normalize without forming a squared norm; zero has no normalization.

inverse

inverse :: Quaternion -> Either MathError Quaternion Source #

Multiplicative inverse; uses component scaling to avoid norm overflow.

conjugate

conjugate :: Quaternion -> Quaternion Source #

Quaternion conjugation.

multiply

multiply :: Quaternion -> Quaternion -> Either MathError Quaternion Source #

Hamilton product.

add

add :: Quaternion -> Quaternion -> Either MathError Quaternion Source #

Component sum.

scale

scale :: Double -> Quaternion -> Either MathError Quaternion Source #

Checked real scaling.

rotateVector

rotateVector :: Quaternion -> [Double] -> Either MathError [Double] Source #

Rotate a finite three-vector; any nonzero quaternion is normalized first.

axisAngle

axisAngle :: [Double] -> Double -> Either MathError Quaternion Source #

Axis-angle conversion. The axis must be nonzero even for a zero angle.

toAxisAngle

toAxisAngle :: Quaternion -> Either MathError ([Double], Double) Source #

Principal rotation angle in [0,pi]; identity uses the x axis.

fromEuler

fromEuler :: Double -> Double -> Double -> Either MathError Quaternion Source #

Intrinsic ZYX rotation from (roll,pitch,yaw).

toEuler

toEuler :: Quaternion -> Either MathError (Double, Double, Double) Source #

Intrinsic ZYX angles, choosing roll zero at gimbal lock.

toMatrix

toMatrix :: Quaternion -> Either MathError (Matrix Double) Source #

Active rotation as a row-major 3x3 matrix.

fromMatrix

fromMatrix :: Matrix Double -> Either MathError Quaternion Source #

Validate SO(3) within 1e-9, then use the largest-diagonal conversion near pi.

nlerp

nlerp :: Double -> Quaternion -> Quaternion -> Either MathError Quaternion Source #

Shortest-arc normalized linear interpolation on [0,1].

slerp

slerp :: Double -> Quaternion -> Quaternion -> Either MathError Quaternion Source #

Shortest-arc spherical interpolation, with stable NLERP near equal rotations.

squad

squad :: Double -> Quaternion -> Quaternion -> Quaternion -> Quaternion -> Either MathError Quaternion Source #

Shoemake SQUAD through q1 to q2 using neighboring q0 and q3.

exponential

exponential :: Quaternion -> Either MathError Quaternion Source #

General quaternion exponential; sinc expansion stabilizes a tiny vector part.

logarithm

logarithm :: Quaternion -> Either MathError Quaternion Source #

Principal quaternion logarithm; the negative real axis chooses positive x.

swingTwist

swingTwist :: [Double] -> Quaternion -> Either MathError (Quaternion, Quaternion) Source #

Decompose q = swing * twist around a nonzero axis. A pi swing with zero twist projection uses identity twist, a deterministic singular convention.