sys/man/2/quaternion

   1 .TH QUATERNION 2
   2 .SH NAME
   3 qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, qmid, qsqrt \- Quaternion arithmetic
   4 .SH SYNOPSIS
   5 .B
   6 #include <draw.h>
   7 .br
   8 .B
   9 #include <geometry.h>
  10 .PP
  11 .B
  12 Quaternion qadd(Quaternion q, Quaternion r)
  13 .PP
  14 .B
  15 Quaternion qsub(Quaternion q, Quaternion r)
  16 .PP
  17 .B
  18 Quaternion qneg(Quaternion q)
  19 .PP
  20 .B
  21 Quaternion qmul(Quaternion q, Quaternion r)
  22 .PP
  23 .B
  24 Quaternion qdiv(Quaternion q, Quaternion r)
  25 .PP
  26 .B
  27 Quaternion qinv(Quaternion q)
  28 .PP
  29 .B
  30 double qlen(Quaternion p)
  31 .PP
  32 .B
  33 Quaternion qunit(Quaternion q)
  34 .PP
  35 .B
  36 void qtom(Matrix m, Quaternion q)
  37 .PP
  38 .B
  39 Quaternion mtoq(Matrix mat)
  40 .PP
  41 .B
  42 Quaternion slerp(Quaternion q, Quaternion r, double a)
  43 .PP
  44 .B
  45 Quaternion qmid(Quaternion q, Quaternion r)
  46 .PP
  47 .B
  48 Quaternion qsqrt(Quaternion q)
  49 .SH DESCRIPTION
  50 The Quaternions are a non-commutative extension field of the Real numbers, designed
  51 to do for rotations in 3-space what the complex numbers do for rotations in 2-space.
  52 Quaternions have a real component
  53 .I r
  54 and an imaginary vector component \fIv\fP=(\fIi\fP,\fIj\fP,\fIk\fP).
  55 Quaternions add componentwise and multiply according to the rule
  56 (\fIr\fP,\fIv\fP)(\fIs\fP,\fIw\fP)=(\fIrs\fP-\fIv\fP\v'-.3m'.\v'.3m'\fIw\fP, \fIrw\fP+\fIvs\fP+\fIv\fP×\fIw\fP),
  57 where \v'-.3m'.\v'.3m' and × are the ordinary vector dot and cross products.
  58 The multiplicative inverse of a non-zero quaternion (\fIr\fP,\fIv\fP)
  59 is (\fIr\fP,\fI-v\fP)/(\fIr\^\fP\u\s-22\s+2\d-\fIv\fP\v'-.3m'.\v'.3m'\fIv\fP).
  60 .PP
  61 The following routines do arithmetic on quaternions, represented as
  62 .IP
  63 .EX
  64 .ta 6n
  65 typedef struct Quaternion Quaternion;
  66 struct Quaternion{
  67         double r, i, j, k;
  68 };
  69 .EE
  70 .TF qunit
  71 .TP
  72 Name
  73 Description
  74 .TP
  75 .B qadd
  76 Add two quaternions.
  77 .TP
  78 .B qsub
  79 Subtract two quaternions.
  80 .TP
  81 .B qneg
  82 Negate a quaternion.
  83 .TP
  84 .B qmul
  85 Multiply two quaternions.
  86 .TP
  87 .B qdiv
  88 Divide two quaternions.
  89 .TP
  90 .B qinv
  91 Return the multiplicative inverse of a quaternion.
  92 .TP
  93 .B qlen
  94 Return
  95 .BR sqrt(q.r*q.r+q.i*q.i+q.j*q.j+q.k*q.k) ,
  96 the length of a quaternion.
  97 .TP
  98 .B qunit
  99 Return a unit quaternion
 100 .RI ( length=1 )
 101 with components proportional to
 102 .IR q 's.
 103 .PD
 104 .PP
 105 A rotation by angle \fIθ\fP about axis
 106 .I A
 107 (where
 108 .I A
 109 is a unit vector) can be represented by
 110 the unit quaternion \fIq\fP=(cos \fIθ\fP/2, \fIA\fPsin \fIθ\fP/2).
 111 The same rotation is represented by \(mi\fIq\fP; a rotation by \(mi\fIθ\fP about \(mi\fIA\fP is the same as a rotation by \fIθ\fP about \fIA\fP.
 112 The quaternion \fIq\fP transforms points by
 113 (0,\fIx',y',z'\fP) = \%\fIq\fP\u\s-2-1\s+2\d(0,\fIx,y,z\fP)\fIq\fP.
 114 Quaternion multiplication composes rotations.
 115 The orientation of an object in 3-space can be represented by a quaternion
 116 giving its rotation relative to some `standard' orientation.
 117 .PP
 118 The following routines operate on rotations or orientations represented as unit quaternions:
 119 .TF slerp
 120 .TP
 121 .B mtoq
 122 Convert a rotation matrix (see
 123 .IR matrix (2))
 124 to a unit quaternion.
 125 .TP
 126 .B qtom
 127 Convert a unit quaternion to a rotation matrix.
 128 .TP
 129 .B slerp
 130 Spherical lerp.  Interpolate between two orientations.
 131 The rotation that carries
 132 .I q
 133 to
 134 .I r
 135 is \%\fIq\fP\u\s-2-1\s+2\d\fIr\fP, so
 136 .B slerp(q, r, t)
 137 is \fIq\fP(\fIq\fP\u\s-2-1\s+2\d\fIr\fP)\u\s-2\fIt\fP\s+2\d.
 138 .TP
 139 .B qmid
 140 .B slerp(q, r, .5)
 141 .TP
 142 .B qsqrt
 143 The square root of
 144 .IR q .
 145 This is just a rotation about the same axis by half the angle.
 146 .PD
 147 .SH SOURCE
 148 .B /sys/src/libgeometry/quaternion.c
 149 .SH SEE ALSO
 150 .IR matrix (2),
 151 .IR qball (2)