BRL-CAD
anim.h
Go to the documentation of this file.
1 /* A N I M . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 
21 /*----------------------------------------------------------------------*/
22 /* anim.h */
23 /** @addtogroup anim */
24 /** @{ */
25 
26 /**
27  * @brief Routines useful in animation programs.
28  *
29  * Orientation conventions: The default object orientation is facing
30  * the positive x-axis, with the positive y-axis to the object's left
31  * and the positive z-axis above the object.
32  *
33  * The default view orientation for rt and mged is facing the negative
34  * z-axis, with the negative x-axis leading to the left and the
35  * positive y-axis going upwards.
36  */
37 
38 #ifndef BN_ANIM_H
39 #define BN_ANIM_H
40 
41 #include "common.h"
42 #include <stdio.h> /* For FILE */
43 #include "vmath.h"
44 #include "bn/defines.h"
45 
47 
48 /* FIXME: These should all have bn_ prefixes */
49 
50 /**
51  * @brief Pre-multiply a rotation matrix by a matrix which maps the
52  * z-axis to the negative x-axis, the y-axis to the z-axis and the
53  * x-axis to the negative y-axis.
54  *
55  * This has the effect of twisting an object in the default view
56  * orientation into the default object orientation before applying the
57  * matrix. Given a matrix designed to operate on an object, yield a
58  * matrix which operates on the view.
59  */
60 BN_EXPORT extern void anim_v_permute(mat_t m);
61 
62 /**
63  * @brief Undo the mapping done by anim_v_permute().
64  *
65  * This has the effect of twisting an object in the default object
66  * orientation into the default view orientation before applying the
67  * matrix. Given a matrix designed to operate on the view, yield a
68  * matrix which operates on an object.
69  */
70 BN_EXPORT extern void anim_v_unpermute(mat_t m);
71 
72 /**
73  * @brief Transpose matrix in place
74  */
75 BN_EXPORT extern void anim_tran(mat_t m);
76 
77 /**
78  * @brief
79  * Convert the rotational part of a 4x4 transformation matrix to zyx
80  * form, that is to say, rotations carried out in the order z, y, and
81  * then x. The angles are stored in radians as a vector in the order
82  * x, y, z. A return value of ERROR1 means that arbitrary assumptions
83  * were necessary. ERROR2 means that the conversion failed.
84  */
85 BN_EXPORT extern int anim_mat2zyx(const mat_t viewrot,
86  vect_t angle);
87 
88 /**
89  * @brief
90  * Convert the rotational part of a 4x4 transformation matrix to
91  * yaw-pitch-roll form, that is to say, +roll degrees about the
92  * x-axis, -pitch degrees about the y-axis, and +yaw degrees about the
93  * z-axis. The angles are stored in radians as a vector in the order
94  * y, p, r. A return of ERROR1 means that arbitrary assumptions were
95  * necessary. ERROR2 means that the conversion failed.
96  */
97 BN_EXPORT extern int anim_mat2ypr(mat_t viewrot,
98  vect_t angle);
99 
100 /**
101  * @brief
102  * This interprets the rotational part of a 4x4 transformation matrix
103  * in terms of unit quaternions. The result is stored as a vector in
104  * the order x, y, z, w. The algorithm is from Ken Shoemake,
105  * Animating Rotation with Quaternion Curves, 1985 SIGGraph Conference
106  * Proceeding, p.245.
107  */
108 BN_EXPORT extern int anim_mat2quat(quat_t quat,
109  const mat_t viewrot);
110 
111 /**
112  * @brief Create a premultiplication rotation matrix to turn the front
113  * of an object (its x-axis) to the given yaw, pitch, and roll, which
114  * is stored in radians in the vector a.
115  */
116 BN_EXPORT extern void anim_ypr2mat(mat_t m,
117  const vect_t a);
118 
119 /**
120  * @brief Create a post-multiplication rotation matrix, which could be
121  * used to move the virtual camera to the given yaw, pitch, and roll,
122  * which are stored in radians in the given vector a. The following
123  * are equivalent sets of commands:
124  *
125  * ypr2vmat(matrix, a);
126  * -- or --
127  * ypr2mat(matrix, a);
128  * v_permute(matrix);
129  * transpose(matrix;
130  */
131 BN_EXPORT extern void anim_ypr2vmat(mat_t m,
132  const vect_t a);
133 
134 /**
135  * @brief
136  * Make matrix to rotate an object to the given yaw, pitch, and
137  * roll. (Specified in radians.)
138  */
139 BN_EXPORT extern void anim_y_p_r2mat(mat_t m,
140  double y,
141  double p,
142  double r);
143 
144 /**
145  * @brief Make matrix to rotate an object to the given yaw, pitch, and
146  * roll. (Specified in degrees.)
147  */
148 BN_EXPORT extern void anim_dy_p_r2mat(mat_t m,
149  double y,
150  double p,
151  double r);
152 
153 /**
154  * @brief Make a view rotation matrix, given desired yaw, pitch and
155  * roll. (Note that the matrix is a permutation of the object rotation
156  * matrix).
157  */
158 BN_EXPORT extern void anim_dy_p_r2vmat(mat_t m,
159  double yaw,
160  double pch,
161  double rll);
162 
163 /**
164  * @brief Make a rotation matrix corresponding to a rotation of "x"
165  * radians about the x-axis, "y" radians about the y-axis, and then
166  * "z" radians about the z-axis.
167  */
168 BN_EXPORT extern void anim_x_y_z2mat(mat_t m,
169  double x,
170  double y,
171  double z);
172 
173 /**
174  * @brief Make a rotation matrix corresponding to a rotation of "x"
175  * degrees about the x-axis, "y" degrees about the y-axis, and then
176  * "z" degrees about the z-axis.
177  */
178 BN_EXPORT extern void anim_dx_y_z2mat(mat_t m,
179  double x,
180  double y,
181  double z);
182 
183 /**
184  * @brief Make a rotation matrix corresponding to a rotation of "z"
185  * radians about the z-axis, "y" radians about the y-axis, and then
186  * "x" radians about the x-axis.
187  */
188 BN_EXPORT extern void anim_zyx2mat(mat_t m,
189  const vect_t a);
190 
191 /**
192  * @brief Make a rotation matrix corresponding to a rotation of "z"
193  * radians about the z-axis, "y" radians about the y-axis, and then
194  * "x" radians about the x-axis.
195  */
196 BN_EXPORT extern void anim_z_y_x2mat(mat_t m,
197  double x,
198  double y,
199  double z);
200 
201 /**
202  * @brief
203  * Make a rotation matrix corresponding to a rotation of "z" degrees
204  * about the z-axis, "y" degrees about the y-axis, and then "x"
205  * degrees about the x-axis.
206  */
207 BN_EXPORT extern void anim_dz_y_x2mat(mat_t m,
208  double x,
209  double y,
210  double z);
211 
212 /**
213  * @brief
214  * Make 4x4 matrix from the given quaternion Note: these quaternions
215  * are the conjugates of the quaternions used in the librt/qmath.c
216  * quat_quat2mat()
217  */
218 BN_EXPORT extern void anim_quat2mat(mat_t m,
219  const quat_t qq);
220 
221 /**
222  * @brief
223  * make a matrix which turns a vehicle from the x-axis to point in the
224  * desired direction, staying "right-side up" (i.e. the y-axis never has
225  * a z-component). A second direction vector is consulted when the
226  * given direction is vertical. This is intended to represent the
227  * direction from a previous frame.
228  */
229 BN_EXPORT extern void anim_dir2mat(mat_t m,
230  const vect_t d,
231  const vect_t d2);
232 
233 /**
234  * @brief make a matrix which turns a vehicle from the x-axis to point
235  * in the desired direction, staying "right-side up". In cases where
236  * the direction is vertical, the second vector is consulted. The
237  * second vector defines a normal to the vertical plane into which
238  * the vehicle's x and z axes should be put. A good choice to put here
239  * is the direction of the vehicle's y-axis in the previous frame.
240  */
241 BN_EXPORT extern void anim_dirn2mat(mat_t m,
242  const vect_t dx,
243  const vect_t dn);
244 
245 /**
246  * @brief given the next frame's position, remember the value of the
247  * previous frame's position and calculate a matrix which points the
248  * x-axis in the direction defined by those two positions. Return new
249  * matrix, and the remembered value of the current position, as
250  * arguments; return 1 as the normal value, and 0 when there is not
251  * yet information to remember.
252  */
253 BN_EXPORT extern int anim_steer_mat(mat_t mat,
254  vect_t point,
255  int end);
256 
257 /**
258  * @brief Add pre- and post- translation to a rotation matrix. The
259  * resulting matrix has the effect of performing the first
260  * translation, followed by the rotation, followed by the second
261  * translation.
262  */
263 BN_EXPORT extern void anim_add_trans(mat_t m,
264  const vect_t post,
265  const vect_t pre);
266 
267 /**
268  * @brief Rotate the vector "d" through "a" radians about the z-axis.
269  */
270 BN_EXPORT extern void anim_rotatez(fastf_t a,
271  vect_t d);
272 
273 /**
274  * @brief print out 4X4 matrix, with optional colon
275  */
276 BN_EXPORT extern void anim_mat_print(FILE *fp,
277  const mat_t m,
278  int s_colon);
279 
280 /**
281  * @brief print out 4X4 matrix. formstr must be less than twenty
282  * chars
283  */
284 BN_EXPORT extern void anim_mat_printf(FILE *fp,
285  const mat_t m,
286  const char *formstr,
287  const char *linestr,
288  const char *endstr);
289 
290 /**
291  * @brief Reverse the direction of a view matrix, keeping it
292  * right-side up
293  */
294 BN_EXPORT extern void anim_view_rev(mat_t m);
295 
297 
298 #endif /* BN_ANIM_H */
299 /** @} */
300 /*
301  * Local Variables:
302  * mode: C
303  * tab-width: 8
304  * indent-tabs-mode: t
305  * c-file-style: "stroustrup"
306  * End:
307  * ex: shiftwidth=4 tabstop=8
308  */
void anim_view_rev(mat_t m)
Reverse the direction of a view matrix, keeping it right-side up.
Definition: anim.c:801
void anim_dx_y_z2mat(mat_t m, double x, double y, double z)
Make a rotation matrix corresponding to a rotation of "x" degrees about the x-axis, "y" degrees about the y-axis, and then "z" degrees about the z-axis.
Definition: anim.c:434
void anim_add_trans(mat_t m, const vect_t post, const vect_t pre)
Add pre- and post- translation to a rotation matrix. The resulting matrix has the effect of performin...
Definition: anim.c:748
void anim_y_p_r2mat(mat_t m, double y, double p, double r)
Make matrix to rotate an object to the given yaw, pitch, and roll. (Specified in radians.)
Definition: anim.c:327
void anim_rotatez(fastf_t a, vect_t d)
Rotate the vector "d" through "a" radians about the z-axis.
Definition: anim.c:758
void anim_z_y_x2mat(mat_t m, double x, double y, double z)
Make a rotation matrix corresponding to a rotation of "z" radians about the z-axis, "y" radians about the y-axis, and then "x" radians about the x-axis.
Definition: anim.c:496
void anim_dirn2mat(mat_t m, const vect_t dx, const vect_t dn)
make a matrix which turns a vehicle from the x-axis to point in the desired direction, staying "right-side up". In cases where the direction is vertical, the second vector is consulted. The second vector defines a normal to the vertical plane into which the vehicle's x and z axes should be put. A good choice to put here is the direction of the vehicle's y-axis in the previous frame.
Definition: anim.c:624
void anim_dir2mat(mat_t m, const vect_t d, const vect_t d2)
make a matrix which turns a vehicle from the x-axis to point in the desired direction, staying "right-side up" (i.e. the y-axis never has a z-component). A second direction vector is consulted when the given direction is vertical. This is intended to represent the direction from a previous frame.
Definition: anim.c:580
Header file for the BRL-CAD common definitions.
void anim_dz_y_x2mat(mat_t m, double x, double y, double z)
Make a rotation matrix corresponding to a rotation of "z" degrees about the z-axis, "y" degrees about the y-axis, and then "x" degrees about the x-axis.
Definition: anim.c:520
void anim_zyx2mat(mat_t m, const vect_t a)
Make a rotation matrix corresponding to a rotation of "z" radians about the z-axis, "y" radians about the y-axis, and then "x" radians about the x-axis.
Definition: anim.c:464
void anim_v_permute(mat_t m)
Routines useful in animation programs.
Definition: anim.c:38
void anim_mat_printf(FILE *fp, const mat_t m, const char *formstr, const char *linestr, const char *endstr)
print out 4X4 matrix. formstr must be less than twenty chars
Definition: anim.c:784
int anim_steer_mat(mat_t mat, vect_t point, int end)
given the next frame's position, remember the value of the previous frame's position and calculate a ...
Definition: anim.c:691
#define __BEGIN_DECLS
Definition: common.h:73
void anim_ypr2mat(mat_t m, const vect_t a)
Create a premultiplication rotation matrix to turn the front of an object (its x-axis) to the given y...
Definition: anim.c:265
void anim_v_unpermute(mat_t m)
Undo the mapping done by anim_v_permute().
Definition: anim.c:53
Coord * point
Definition: chull3d.cpp:52
void anim_x_y_z2mat(mat_t m, double x, double y, double z)
Make a rotation matrix corresponding to a rotation of "x" radians about the x-axis, "y" radians about the y-axis, and then "z" radians about the z-axis.
Definition: anim.c:410
void anim_dy_p_r2mat(mat_t m, double y, double p, double r)
Make matrix to rotate an object to the given yaw, pitch, and roll. (Specified in degrees.)
Definition: anim.c:351
void anim_tran(mat_t m)
Transpose matrix in place.
Definition: anim.c:68
void anim_quat2mat(mat_t m, const quat_t qq)
Make 4x4 matrix from the given quaternion Note: these quaternions are the conjugates of the quaternio...
Definition: anim.c:550
void anim_ypr2vmat(mat_t m, const vect_t a)
Create a post-multiplication rotation matrix, which could be used to move the virtual camera to the g...
Definition: anim.c:296
void anim_dy_p_r2vmat(mat_t m, double yaw, double pch, double rll)
Make a view rotation matrix, given desired yaw, pitch and roll. (Note that the matrix is a permutatio...
Definition: anim.c:379
int anim_mat2zyx(const mat_t viewrot, vect_t angle)
Convert the rotational part of a 4x4 transformation matrix to zyx form, that is to say...
Definition: anim.c:89
#define __END_DECLS
Definition: common.h:74
int anim_mat2quat(quat_t quat, const mat_t viewrot)
This interprets the rotational part of a 4x4 transformation matrix in terms of unit quaternions...
Definition: anim.c:208
double fastf_t
Definition: defines.h:300
int anim_mat2ypr(mat_t viewrot, vect_t angle)
Convert the rotational part of a 4x4 transformation matrix to yaw-pitch-roll form, that is to say, +roll degrees about the x-axis, -pitch degrees about the y-axis, and +yaw degrees about the z-axis. The angles are stored in radians as a vector in the order y, p, r. A return of ERROR1 means that arbitrary assumptions were necessary. ERROR2 means that the conversion failed.
Definition: anim.c:149
void anim_mat_print(FILE *fp, const mat_t m, int s_colon)
print out 4X4 matrix, with optional colon
Definition: anim.c:771