GLM_GTC_quaternion

Header: <glm/gtc/quaternion.hpp>

Notations in this page

A quaternion \[q=w+ix+jy+kz\in\mathbf{H}\] may be written as \[q=(w;x,y,z)\] or by the scalar part and the vector part \[q=(w;v)\quad\text{where }v=(x,y,z)\in\mathbf{R}^3\]

For \(q=w+ix+jy+kz\), \[\overline{q}:=w-ix-jy-kz\] \[\left\lvert q\right\rvert:=\sqrt{w^2+x^2+y^2+z^2}\] \[\operatorname{Re}q:=w,\quad \operatorname{Im}q:=(x,y,z)=ix+jy+kz\]

Multiplication is induced by the following relations: \[\begin{gathered} i^2=j^2=k^2=ijk=-1, \\ ij=k,\;jk=i,\;ki=j, \\ ji=-k,\;kj=-i,\;ik=-j. \end{gathered}\]

A quaternion whose real part is zero can be viewed as a three-dimensional vector: \[ \begin{array}{ccc} \mathbf{R}^3&\subset&\mathbf{H}\\ (x,y,z)&\leftrightarrow&(0;x,y,z) \end{array} \]

In this page, tquat stands for tquat<T, Q>, tmat3x3 for mat<3, 3, T, Q>, tmat4x4 for mat<4, 4, T, Q>, tvec3 for vec<3, T, Q>, and tvec4 for vec<4, T, Q>.

Types

• struct tquat<typename T, qualifier Q>
  • members T x, y, z, w
    • \(w+ix+jy+kz=(w; x, y, z)\)
  • length() -> length_type (always return 4)
  • operator[](length_type i) -> T&
  • operator[](length_type i) const -> T const&
    • [0] = x, [1] = y, [2] = z, [3] = w
  • constructor tquat()
    • Members are initialized if GLM_FORCE_CTOR_INIT is defined.
  • constructor tquat(tquat q) = default
  • constructor tquat(tquat<T, P> q)
  • constructor tquat(T s, tvec3 v)
  • constructor tquat(T w, T x, T y, T z)
  • constructor tquat(tquat<U, P> q)
  • explicit operator tmat3x3()
    • See mat3_cast in Rotation.
  • explicit operator tmat4x4()
    • See mat4_cast in Rotation.
  • tquat(tvec3 u, tvec3 v)
    • See Rotation.
  • (maybe explicit) constructor tquat(tvec3 eulerAngles)
    • See Euler angles.
  • (maybe explicit) constructor tquat(tmat3x3 q)
    • See quat_cast(tmat3x3 q) -> tquat in Rotation.
  • (maybe explicit) constructor tquat(tmat4x4 q)
    • See quat_cast(tmat4x4 q) -> tquat in Rotation.
    • These constructors are explicit if GLM_FORCE_EXPLICIT_CTOR is defined.
  • operator=(tquat q) = default
  • operator=(tquat<U, Q> q)
  • operator+=(tquat<U, Q> q)
  • operator-=(tquat<U, Q> q)
  • operator*=(tquat<U, Q> q)
    • Multiply q from right.
  • operator*=(U s)
  • operator/=(U s)
• quat = tquat<float>
• fquat = tquat<float>
• dquat = tquat<double>
• {lowp,mediump,highp}_quat = tquat<float, {lowp,mediump,highp}>
• {lowp,mediump,highp}_fquat = tquat<float, {lowp,mediump,highp}>
• {lowp,mediump,highp}_dquat = tquat<double, {lowp,mediump,highp}>

Arithmetic

• unary operator+(tquat q) -> tquat
• unary operator-(tquat q) -> tquat
• binary operator+(tquat q, tquat p) -> tquat
• binary operator-(tquat q, tquat p) -> tquat
• binary operator*(tquat q, tquat p) -> tquat
  • Let \(q=(w;x,y,z)=(w;v)\) and \(p=(w';x',y',z')=(w';v')\).
  • Returns \[\begin{aligned} qp=&(ww'-v\cdot v';wv'+vw'+v\times v') \\ =&(ww'-xx'-yy'-zz') \\ &+i(wx'+xw'+yz'-zy') \\ &+j(wy'-xz'+yw'+zx') \\ &+k(wz'+xy'-yx'+zw'). \end{aligned}\]
• binary operator*(tquat q, tvec3 v) -> tvec3
  • See Rotation.
• binary operator*(tvec3 v, tquat q) -> tvec3
  • See Rotation.
• binary operator*(tquat q, tvec4 v) -> tvec4
  • See Rotation.
• binary operator*(tvec4 v, tquat q) -> tvec4
  • See Rotation.
• binary operator*(tquat q, T s) -> tquat
  • Scalar multiplication.
• binary operator*(T s, tquat q) -> tquat
  • Scalar multiplication.
• binary operator/(tquat q, T s) -> tquat
  • Division by scalar.
• binary operator==(tquat q1, tquat q2) -> bool

• binary operator!=(tquat q1, tquat q2) -> bool

• conjugate(tquat q) -> tquat
  • Returns \((w; -x, -y, -z)\).
• inverse(tquat q) -> tquat
  • Returns multiplicative inverse of \(q\), that is \(q^{-1}=\frac{\overline{q}}{\left\lvert q\right\rvert^2}\).
• dot(tquat x, tquat y) -> T
  • Returns \(\operatorname{Re}(x\cdot\overline{y})\).
• length(tquat q) -> T
  • Returns \(\left\lvert q\right\rvert=\sqrt{\operatorname{dot}(q,q)}\).
• normalize(tquat q) -> tquat
  • Returns \(\frac{q}{\left\lvert q\right\rvert}\).

Rotation

• constructor tquat(tvec3 u, tvec3 v)
  • Assuming \(u\) and \(v\) are unit vectors, constructs a quaternion that moves \(u\) to \(v\) by rotation; i.e. \(v=quq^{-1}\).
  • If we define \(\theta\) and \(\mathsf{axis}\) by \(\cos\theta=u\cdot v\), \(\mathsf{axis}\cdot\sin\theta=u\times v\), the quaternion is given by \[\begin{aligned} q&=\bigl(\cos\tfrac{\theta}{2};\mathsf{axis}\cdot\sin\tfrac{\theta}{2}\bigr) \\ &=\operatorname{normalize}\bigl(2\cos^2\tfrac{\theta}{2};2\mathsf{axis}\cdot\cos\tfrac{\theta}{2}\sin\tfrac{\theta}{2}\bigr) \\ &=\operatorname{normalize}(1+\cos\theta;\mathsf{axis}\cdot\sin\theta) \\ &=\operatorname{normalize}(1+u\cdot v;u\times v). \end{aligned}\]
  • If \(u\) and \(v\) are exactly opposite, rotate 180 degrees around an arbitrary orthogonal axis.
• binary operator*(tquat q, tvec3 v) -> tvec3
  • Returns \(qv\overline{q}+(1-\left\lvert q\right\rvert^2)v=v+2((\operatorname{Im}q\times v)\cdot\operatorname{Re}q+\operatorname{Im}q\times(\operatorname{Im}q\times v))\).
  • If \(\left\lvert q\right\rvert=1\), this is just \(qvq^{-1}=qv\overline{q}\).
• binary operator*(tvec3 v, tquat q) -> tvec3
  • Returns \(q^{-1}*v\).
  • If \(\left\lvert q\right\rvert=1\), this is just \(q^{-1}vq=\overline{q}vq\).
• binary operator*(tquat q, tvec4 v) -> tvec4
  • Returns \((q*(v_x,v_y,v_z),v.w)\)
  • If \(\left\lvert q\right\rvert=1\), this is just \((q(v_x,v_y,v_z)q^{-1},v_w)\).
• binary operator*(tvec4 v, tquat q) -> tvec4
  • Returns \(q^{-1}*v\).
  • If \(\left\lvert q\right\rvert=1\), this is just \((q^{-1}(v_x,v_y,v_z)q,v_w)\).
• angle(tquat q) -> T
  • Assuming \(\left\lvert q\right\rvert=1\), returns \(\theta\) in \(q=(\cos\frac{\theta}{2};v\sin\frac{\theta}{2})\); that is, \(\theta=2\arccos(\operatorname{Re}q)\).
• angleAxis(T angle, tvec3 axis) -> tquat
  • axis should be a unit vector.
  • Returns \((\cos(\mathsf{angle}/2);\mathsf{axis}\cdot\sin(\mathsf{angle}/2)))\).
• axis(tquat q) -> tvec3
  • Assuming \(\left\lvert q\right\rvert=1\), returns \(v\) in \(q=(\cos\frac{\theta}{2};v\sin\frac{\theta}{2})\); that is, \(v=\frac{\operatorname{Im}q}{\sqrt{1-(\operatorname{Re}q)^2}}\).
  • If \(\left\lvert \operatorname{Re}q\right\rvert=1\), return \((0,0,1)\).
• mat3_cast(tquat q) -> tmat3x3
  • Assuming \(\left\lvert q\right\rvert=1\), returns the rotation \(\mathbf{R}^3\ni v \mapsto qvq^{-1} \in\mathbf{R}^3\) as a matrix: \[ \begin{pmatrix} 1-2(y^2+z^2) & 2(xy-wz) & 2(xz+wy) \\ 2(xy+wz) & 1-2(x^2+z^2) & 2(yz-wx) \\ 2(xz-wy) & 2(yz+wx) & 1-2(x^2+y^2) \end{pmatrix} \]
• mat4_cast(tquat q) -> tmat4x4
  • Returns tmat4x4(mat3_cast(q))
• quat_cast(tmat3x3 m) -> tquat
  • Assuming \[m=\begin{pmatrix}a_{11}&a_{12}&a_{13}\\a_{21}&a_{22}&a_{23}\\a_{31}&a_{32}&a_{33}\end{pmatrix}\] is a rotation matrix, do the inverse of mat3_cast.
  • Returns one of:
    • \(\bigl(w;\frac{a_{32}-a_{23}}{4w},\frac{a_{13}-a_{31}}{4w},\frac{a_{21}-a_{12}}{4w}\bigr)\) with \(w:=\frac{\sqrt{1+a_{11}+a_{22}+a_{33}}}{2}\).
    • \(\bigl(\frac{a_{32}-a_{23}}{4x};x,\frac{a_{12}+a_{21}}{4x},\frac{a_{13}+a_{31}}{4x}\bigr)\) with \(x:=\frac{\sqrt{1+a_{11}-a_{22}-a_{33}}}{2}\).
    • \(\bigl(\frac{a_{13}-a_{31}}{4y};\frac{a_{12}+a_{21}}{4y},y,\frac{a_{23}+a_{32}}{4y}\bigr)\) with \(y:=\frac{\sqrt{1-a_{11}+a_{22}-a_{33}}}{2}\).
    • \(\bigl(\frac{a_{21}-a_{12}}{4z};\frac{a_{13}+a_{31}}{4z},\frac{a_{23}+a_{32}}{4z},z\bigr)\) with \(z:=\frac{\sqrt{1-a_{11}-a_{22}+a_{33}}}{2}\).
• quat_cast(tmat4x4 m) -> tquat
  • Returns quat_cast(tmat3x3(m))
• rotate(tquat q, T angle, tvec3 axis) -> tquat
  • axis should be a unit vector.
  • Returns \(q\cdot(\cos(\mathsf{angle}/2);\mathsf{axis}\cdot\sin(\mathsf{angle}/2))\).

Euler angles

• (maybe explicit) constructor tquat(tvec3 eulerAngles)
  • Constructs a unit quaternion with the rotation represented by eulerAngles.
  • See the following note.
• eulerAngles(tquat x) -> tvec3
  • Returns \((\operatorname{pitch}(x),\operatorname{yaw}(x),\operatorname{roll}(x))\).
  • See the following note.
• pitch(tquat x) -> T
  • See the following note.
• roll(tquat x) -> T
  • See the following note.
• yaw(tquat x) -> T
  • See the following note.

From Euler angles to quaternion

Let \(\mathsf{eulerAngles}=(\alpha,\beta,\gamma)\) (\(\alpha\): pitch, \(\beta\): yaw, \(\gamma\): roll). \[ \begin{aligned} q=&\Bigl(\cos\frac{\gamma}{2}+k\sin\frac{\gamma}{2}\Bigr) \Bigl(\cos\frac{\beta}{2}+j\sin\frac{\beta}{2}\Bigr) \Bigl(\cos\frac{\alpha}{2}+i\sin\frac{\alpha}{2}\Bigr) \\ =&\Bigl(\cos\frac{\alpha}{2}\cos\frac{\beta}{2}\cos\frac{\gamma}{2}+\sin\frac{\alpha}{2}\sin\frac{\beta}{2}\sin\frac{\gamma}{2}\Bigr) \\ &+i\Bigl(\sin\frac{\alpha}{2}\cos\frac{\beta}{2}\cos\frac{\gamma}{2}-\cos\frac{\alpha}{2}\sin\frac{\beta}{2}\sin\frac{\gamma}{2}\Bigr) \\ &+j\Bigl(\cos\frac{\alpha}{2}\sin\frac{\beta}{2}\cos\frac{\gamma}{2}+\sin\frac{\alpha}{2}\cos\frac{\beta}{2}\sin\frac{\gamma}{2}\Bigr) \\ &+k\Bigl(\cos\frac{\alpha}{2}\cos\frac{\beta}{2}\sin\frac{\gamma}{2}-\sin\frac{\alpha}{2}\sin\frac{\beta}{2}\cos\frac{\gamma}{2}\Bigr) \end{aligned} \]

From quaternion to Euler angles

Let \[q=(w;x,y,z)=\Bigl(\cos\frac{\gamma}{2}+k\sin\frac{\gamma}{2}\Bigr) \Bigl(\cos\frac{\beta}{2}+j\sin\frac{\beta}{2}\Bigr) \Bigl(\cos\frac{\alpha}{2}+i\sin\frac{\alpha}{2}\Bigr).\] By comparing \[qiq^{-1}=i\cos\beta\cos\gamma+j\cos\beta\sin\gamma-k\sin\beta\] and \[qi\overline{q}=i(w^2+x^2-y^2-z^2)+2j(xy+zw)+2k(xz-wy),\] we obtain \[\sin\beta=-2(xz-wy),\quad\tan\gamma=\frac{2(xy+zw)}{w^2+x^2-y^2-z^2}\] and the yaw \(\beta\in[-\pi,\pi]\) and the roll \(\gamma\in[-\pi,\pi]\) can be computed by \[\beta=\arcsin(-2(xz-wy)),\quad\gamma=\arctan\frac{2(xy+zw)}{w^2+x^2-y^2-z^2}.\]

Similarly, by comparing \[q^{-1}kq=-i\sin\beta+j\sin\alpha\cos\beta+k\cos\alpha\cos\beta\] and \[\overline{q}kq=2i(xz-yw)+2j(yz+wx)+k(w^2-x^2-y^2+z^2),\] we obtain \[\tan\alpha=\frac{2(yz+wx)}{w^2-x^2-y^2+z^2}\] and the pitch \(\alpha\in[-\pi,\pi]\) can be computed by \[\alpha=\arctan\frac{2(yz+wx)}{w^2-x^2-y^2+z^2}.\]

Interpolation

• lerp(tquat x, tquat y, T a) -> tquat
  • Precondition: \(0 \le a \le 1\).
  • Returns \(x\cdot(1-a)+y\cdot a\).
• mix(tquat x, tquat y, T a) -> tquat
  • x and y should be unit quaternions and a should be in \([0,1]\).
  • Let \(\theta=\arccos(\operatorname{dot}(x,y))\).
  • Returns \(\frac{\sin((1-a)\theta)}{\sin\theta}x+\frac{\sin(a\theta)}{\sin\theta}y\).
• slerp(tquat x, tquat y, T a) -> tquat
  • x and y should be unit quaternions and a should be in \([0,1]\).
  • If \(\operatorname{dot}(x,y)<0\), negate \(y\).
  • Let \(\theta=\arccos(\operatorname{dot}(x,y))\).
  • Returns \(\frac{\sin((1-a)\theta)}{\sin\theta}x+\frac{\sin(a\theta)}{\sin\theta}y\).

Element-wise comparison

• equal(tquat x, tquat y) -> bvec4
• notEqual(tquat x, tquat y) -> bvec4
• greaterThan(tquat x, tquat y) -> bvec4
• greaterThanEqual(tquat x, tquat y) -> bvec4
• lessThan(tquat x, tquat y) -> bvec4
• lessThanEqual(tquat x, tquat y) -> bvec4
• isinf(tquat x) -> bvec4
• isnan(tquat x) -> bvec4

Site proudly generated by Hakyll