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