Debian Codegraph @

texmf-dist/doc/metapost/mp3d/tb57roegel.ltx

raw
1 % D. Roegel, 25/2/1997 : first draft
2 % 26/2/1997
3 % 23/4/1997 : appendix, types added
4 % 24/4/1997 : better formatting of appendix
5 % 25/4/1997 : two columns
6 % 27/4/1997 : some improvements
7 % 28/4/1997 : changes to take new syntax into account
8 % 30/4/1997 : cleaning and additions
9 % 1/5/1997 : ltugboat macros
10 % addition of appendix b
11 % all overfull hboxes removed; this needed a lot
12 % of rephrasing!
13 % lots of cleaning
14 % 2/5/1997 : extension of future part
15 % 12/5/1997 : several small improvements to take Ulrik Vieth's
16 % comments into account.
17 % 17/5/1997 : some corrections to take modifications in
18 % the source code into account
19 % 18/5/1997 : commas in the syntax have been put in \texttt
20 % some renamings in order to get rid of the overfull
21 % hboxes resulting from the comma changes ...
22 % 29/5/1997 : some renamings of ``object'' into ``obj'' to
23 % be in accordance with the code (version 0.993)
24 % some reformatting of pieces of code with respect
25 % to the indentation
26 % 19/6/1997 : - the `future' part has been corrected with respect
27 % to the general algorithm for drawing the faces
28 % (thanks to Dominique Larchey)
29 % - reference to the ``LaTeX Graphics Companion''
30 % 11/2/1998 : - description of draw_contours and contour_width
31 % - acknowledgment of Denis Barbier and Boguslaw
32 % Jackowski
33 % - one_image changed to an_image at the beginning
34 % of the paper, in order to avoid being misleading
35 % by comparison with the real one_image macro
36 % - a few more lines describing the parameters of
37 % one_image
38 % - ghostscript -> Ghostscript
39 % - footnote added to explain why Ghostscript
40 % has not been used to generate the excerpts
41 % of the images.
42 % - some lines to explain why the color type
43 % was not used for 3d vectors
44 % 12/2/1998 : - rewording to avoid overfull hboxes
45 % 19/2/1998 : - minor ``english'' editing (RF)
46 % and file sent to author for review (mb)
47 % 04/03/1998: - EM fonts removed/ not to be used this issue
48 % 04/08/1998: - TUB-specific inputs modified for portability to
49 % CTAN archives (mb)
50 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
51 \documentclass[nonumber,harvardcite]{ltugboat}
52 \usepackage{mflogo}
53
54 \usepackage{url}
55 \usepackage[dvips]{graphicx}
56
57 \newcommand{\AVN}{\meta{avn}}
58 \newcommand{\LVN}{\meta{lvn}}
59 \newcommand{\APN}{\meta{apn}}
60 \newcommand{\LPN}{\meta{lpn}}
61 \newcommand{\AFN}{\meta{afn}}
62 \newcommand{\LFN}{\meta{lfn}}
63 \newcommand{\CN}{\meta{cl}}
64 \newcommand{\IN}{\meta{obj}}
65 \newcommand{\VL}{\meta{vl}}
66 \newcommand{\VSL}{\meta{vsl}}
67 \newcommand{\HEXCOL}{\meta{hc}}
68 \newcommand{\COL}{\meta{col}}
69 \newcommand{\STR}{\meta{str}}
70 \newcommand{\PAIR}{\meta{pair}}
71 \newcommand{\NUM}{\meta{num}}
72 \newcommand{\BOOL}{\meta{bool}}
73
74 \newcommand{\tc}{\texttt{,}}
75
76 \newenvironment{todo}{\begin{bfseries}}{\end{bfseries}}
77
78 %% this command is already defined in ltugboat.cls and is more robust
79 %% I think....
80 %\newcommand\meta[1]{$\langle$\mbox{\textit{#1}}$\rangle$}
81 %%% the following is the ltugboat.cls definition
82 %\DeclareRobustCommand\meta[1]{%
83 % \ensuremath{\langle}\emph{#1}\ensuremath{\rangle}}
84
85 \let\m=\meta % <-- this command is never used.
86
87 %%%%%TUGboat production-specific files
88 \vol 18, 4. % volume, issue.
89 \issueseqno=57 % sequential issue number
90 \issdate December 1997. % month, year of publication
91 \setcounter{page}{274}
92 \NoBlackBoxes
93 \PrelimDraftfalse
94
95 \widowpenalty=10000
96 \clubpenalty=10000
97 \renewcommand{\topfraction}{0.9}
98 \renewcommand{\bottomfraction}{0.5}
99 \renewcommand{\floatpagefraction}{0.8}
100 \renewcommand{\textfraction}{0.1}
101 \setcounter{bottomnumber}{2}
102 \setcounter{totalnumber}{4}
103 \renewcommand{\dbltopfraction}{0.9}
104 \renewcommand{\dblfloatpagefraction}{0.8}
105 \pretolerance=500
106 \tolerance=1000
107 \hbadness=3000
108 \vbadness=3000
109 \hyphenpenalty=400
110 %%%%%%%END of TUGboat production-specific files
111
112 \begin{document}
113
114 \sectitle{Graphics Applications}
115
116 \title{Creating 3D animations with \MP}
117 \author{Denis Roegel}
118 \address{CRIN (Centre de Recherche en Informatique de Nancy)\\
119 B\^atiment LORIA\\
120 BP 239\\
121 54506 Vand\oe uvre-l\`es-Nancy\\
122 FRANCE}
123 \netaddress{[email protected]}
124 \personalURL{http://www.loria.fr/~roegel}
125
126
127
128 \maketitle
129
130 \begin{abstract}
131 \MP{} can be used to create animations. We show here an example
132 of animation of polyhedra, introducing the \texttt{3d} package.
133 \end{abstract}
134
135 \section{Introduction}
136
137 %%%RF 1998/02/19: N-forms of cite
138 \MP{} (\citeN{hobby1992}; see also the description in
139 \shortciteN{Goossens:LGC97})
140 is a drawing language very similar to \MF,
141 but whose output is \PS. \MP{} is especially suited for geometrical
142 and technical drawings, where a drawing can naturally be decomposed
143 in several parts, related in some logical way.
144 %%%RF 1998/02/19: active voice for passive
145 Knuth is using \MP{} for the revisions of and additions to
146 \emph{The Art Of Computer Programming}~\cite{knuth1997},
147 and it is or will be a component of every standard \TeX{} distribution.
148
149 Unfortunately, \MP{} is still quite bare and the user is only offered
150 %%%RF 1998/02/19: revamped a bit
151 the raw power\Dash a little bit like the \TeX{} user who only has
152 plain \TeX{} at his/her disposal. The lack of libraries is certainly
153 due to the infancy of \MP{} (which came in the public domain at the
154 beginning of 1995) and thus to the small number of its users.
155
156 In this paper, we present a way to produce animations using \MP.
157 The technique is quite general and we illustrate it through the \texttt{3d}
158 package.
159
160 \section{Animations}
161
162 The World Wide Web has accustomed us to various animations,
163 especially \texttt{java} animations.
164 Common components of web pages are animated GIF images.
165
166 Producing animations in \MP{} is actually quite easy. A number of
167 $n$ images will be computed and their sequence produces the animation.
168 The animation will be similar to a movie, with no interaction. More precisely,
169 if \verb|an_image(|$i$\verb|)|
170 produces a picture parameterized by $i$,
171 it suffices to wrap this macro
172 between \verb|beginfig| and \verb|endfig|:
173
174 \begin{verbatim}
175 def one_image_out(expr i)=
176 beginfig(<figure number>);
177 an_image(i);
178 endfig;
179 enddef;
180 \end{verbatim}
181
182 \noindent and to loop over \verb|one_image_out|:
183
184 \begin{verbatim}
185 for j:=1 upto 100:one_image_out(j);endfor;
186 \end{verbatim}
187
188 Assuming that \verb|<figure number>|
189 is equal to the parameter of \verb|an_image|,
190 the compilation of this program will produce
191 a hundred files with extensions \verb|.1|, \verb|.2|, \ldots, \verb|.100|.
192 All these files are \PS{} files and all we need to do is to find a way
193 to collate them in one piece. How to do this depends on the operating
194 system. On UNIX for instance, one can use \texttt{Ghostscript}
195 to transform a \PS{} file
196 into \texttt{ppm} and then transform each \texttt{ppm} file into
197 GIF with \texttt{ppmtogif}. These programs are part of the
198 \texttt{NETPBM} package~\cite{netpbm}. Finally, a program such as
199 \texttt{gifmerge}~\cite{gifmerge}
200 creates an animated GIF file (GIF89A)
201 out of the hundred individual simple GIFs.
202 However, various details must be taken care of. For instance,
203 %%%RF 1998/02/19: reorganised around `grabbed'->`needed'
204 only a part of \texttt{Ghostscript}'s output is needed
205 and selection can be made with \texttt{pnmcut}.
206 %(which is also part of \texttt{NETPBM}).
207
208 The whole process of creating an animation out of \MP's outputs can
209 be summed up in a shell script, similar to the one
210 in figure~\ref{animation-script}. As we will see, this script (including
211 the arguments of \texttt{awk} and \texttt{pnmcut}) can be generated
212 automatically by \MP{} itself.
213
214 %%fig 1
215 \begin{figure*}
216 \begin{verbatim}
217 #! /bin/sh
218
219 /bin/rm -f animpoly.log
220 for i in `ls animpoly.*| grep 'animpoly.[0-9]'`;do
221 echo $i
222 echo '=============='
223 # shift each picture so that it lies in the page:
224 awk < $i '{print} /^%%Page: /{print "172 153 translate\n"}' > $i.ps
225 # produce ppm format:
226 gs -sDEVICE=ppmraw -sPAPERSIZE=a4 -dNOPAUSE -r36 -sOutputFile=$i.ppm -q -- $i.ps
227 /bin/rm -f $i.ps
228 # produce gif:
229 ppmquant 32 $i.ppm | pnmcut 15 99 141 307 | ppmtogif > `expr $i.ppm : '\(.*\)ppm'`gif
230 /bin/rm -f $i.ppm
231 done
232 /bin/rm -f animpoly.gif
233 # merge the gif files:
234 gifmerge -10 -l1000 animpoly.*.gif > animpoly.gif
235 /bin/rm -f animpoly.*.gif
236 \end{verbatim}
237 \caption{Script created by \MP{} (with some additional comments)}
238 \label{animation-script}
239 \end{figure*}
240
241
242 \section{Objects in space}
243
244 \subsection{Introduction}
245
246 The author applied this idea to the animation of objects
247 in space. The macros in the \texttt{3d.mp} package\footnote{On CTAN,
248 under \texttt{graphics/metapost/macros/3d}. The code is documented
249 with \texttt{MFT}~\cite{knuth1989}
250 and illustrated with \MP. This paper describes version 1.0 of the macros.}
251 provide a basis for the
252 representation of three-dimensional objects. The basic components of
253 the objects are the points or the vectors. Both are stored as triplets.
254 More precisely, we have three
255 arrays\footnote{\MP{} has a few simple types such as \texttt{numeric},
256 \texttt{boolean}, \texttt{string}, \texttt{path}, \ldots.
257 It also has pairs (\texttt{pair}) and triples (\texttt{color}). We might
258 have cheated and stored points as colors, but instead, we found it
259 interesting to illustrate a construction equivalent
260 to \textsc{Pascal}'s records or C's structures. In \MP, instead of
261 having a list or an array of structures, we use several lists or arrays,
262 so that a record is a cross-section over several arrays.}
263 of type \verb|numeric|:
264
265 \begin{verbatim}
266 numeric vect[]x,vect[]y,vect[]z;
267 \end{verbatim}
268
269 Vector $i$'s components are \verb|vect[|$i$\verb|]x|, \verb|vect[|$i$\verb|]y|
270 and \verb|vect[|$i$\verb|]z|. It is then straightforward to define the usual
271 operations on vectors using this convention. For instance,
272 vector addition is defined as:
273
274 \begin{verbatim}
275 def vect_sum(expr k,i,j)=
276 vect[k]x:=vect[i]x+vect[j]x;
277 vect[k]y:=vect[i]y+vect[j]y;
278 vect[k]z:=vect[i]z+vect[j]z;
279 enddef;
280 \end{verbatim}
281
282 Often, we need some scratch vectors or vectors local to a macro.
283 A simple vector allocation mechanism solves the problem: we use a stack
284 of vectors and we reserve and free vectors only on top of the stack.
285 For instance, the allocation of a vector is defined by:
286
287 \begin{verbatim}
288 def new_vect=incr(last_vect_) enddef;
289 \end{verbatim}
290
291 \noindent where \verb|last_vect_| is the index of the top of the stack.
292 Hence, a vector is manipulated by its index on the stack.
293 Writing \verb|v:=new_vect;| lets \verb|v| be the index of the newly allocated
294 vector.
295
296 Freeing a vector is also easy and is only allowed at the top of the stack:
297
298 \begin{verbatim}
299 def free_vect(expr i)=
300 if i=last_vect_:
301 last_vect_:=last_vect_-1;
302 else: errmessage("Vector " &
303 decimal i & " can't be freed!");
304 fi;
305 enddef;
306 \end{verbatim}
307
308 How these macros are used is made explicit in the \verb|vect_rotate| macro
309 which does a rotation of a vector \verb|v| around a vector \verb|axis|
310 by an angle \verb|alpha|. This rotation is illustrated
311 in figure~\ref{vector-rotation}.
312 $\vec{v}$ is written as the sum of $\vec{h}$ and $\vec{a}$ where
313 $\vec{h} \perp \vec{a}$. If $\vec{b}$ is
314 $\overrightarrow{axis}/{\|\overrightarrow{axis}\|}$, $\vec{c}$ is computed
315 as the vector product of $\vec{b}$ and $\vec{a}$ and $\vec{a}$ is then
316 rotated in a simple way resulting in $\vec{f}$.
317
318 The vectors declared with \verb|new_vect| are freed in the inverse order.
319 The \verb|vect_rotate| macro makes use of a few other macros:
320 \verb|vect_mod| computes the modulus of a vector; \verb|vect_dprod(a,b)| is
321 the dot product of vectors \texttt{a} and \texttt{b}; \verb|vect_mult(b,a,x)|
322 lets vector \texttt{b} equal vector \texttt{a} multiplied by the scalar
323 \texttt{x}; \verb|vect_sum| and \verb|vect_diff| compute as their first
324 argument the sum or the difference of the two other vectors;
325 \verb|vect_prod(c,a,b)| lets vector \texttt{c} equal the vectorial
326 product of vectors \texttt{a} and \texttt{b}. These macros are
327 described in appendix A.
328
329 %% fig2
330 \begin{figure*}
331 \begin{center}
332 \includegraphics{vect-fig.9}\hspace{1cm}\includegraphics{vect-fig.10}
333 \end{center}
334 \caption{Vector rotation}\label{vector-rotation}
335 \end{figure*}
336
337 \begin{verbatim}
338 vardef vect_rotate(expr v,axis,alpha)=
339 save v_a,v_b,v_c,v_d,v_e,v_f;
340 v_a:=new_vect;v_b:=new_vect;
341 v_c:=new_vect;v_d:=new_vect;
342 v_e:=new_vect;v_f:=new_vect;
343 v_g:=new_vect;v_h:=new_vect;
344 vect_mult(v_b,axis,1/vect_mod(axis));
345 vect_mult(v_h,v_b,vect_dprod(v_b,v));
346 vect_diff(v_a,v,v_h);
347 vect_prod(v_c,v_b,v_a);
348 vect_mult(v_d,v_a,cosd(alpha));
349 vect_mult(v_e,v_c,sind(alpha));
350 vect_sum(v_f,v_d,v_e);
351 vect_sum(v,v_f,v_h);
352 free_vect(v_h);free_vect(v_g);
353 free_vect(v_f);free_vect(v_e);
354 free_vect(v_d);free_vect(v_c);
355 free_vect(v_b);free_vect(v_a);
356 enddef;
357 \end{verbatim}
358
359 The \verb|3d| package defines other macros in order to set the observer,
360 %%%RF 1998/02/19: was `to manipulate'
361 to compute a reference matrix, etc. Provision is given for
362 manipulating objects.
363
364 \subsection{Objects and classes}
365
366 The \texttt{3d} package understands a notion of \emph{class}.
367 A \emph{class} is a parameterized object. For instance, we have the class
368 of regular tetrahedra, the class of regular cubes, etc. Our classes
369 %%%RF 1998/02/19: `first level of genericity'->... abstraction
370 are the lowest level of abstraction and classes can not be composed.
371 They can only be \emph{instanciated}. When we need a specific tetrahedron,
372 we call a generic function to create a tetrahedron, but with an identifier
373 specific to one instance.
374
375 A class is a set of vertices in space, together with a way to draw
376 faces, and therefore edges.
377 The author's focus was to manipulate (and later animate) polyhedra.
378 As an example, the \verb|poly.mp| package provides the definition of
379 each of the five regular convex polyhedra.
380
381 %%%RF 1998/02/19: `is defining'->defines, etc, `both macros'->`each macro'
382 Each class consists of two macros: one defines the points,
383 the other calls the first macro and defines the faces.
384 Each macro has a parameter which is a string identifying
385 the particular instance of that class.
386
387 \tolerance=4500
388 The points of a regular tetrahedron are defined in
389 \verb|set_tetrahedron_points|,
390 %%%RF 1998/02/19: second half sentence rewritten
391 an example of the general macro name \verb|set_|\meta{class}\verb|_points|.
392 Five points are defined, four of
393 them with \verb|set_obj_point|, a macro which defines points \emph{local}
394 to an object. The first four points are the vertices and the fifth
395 is the center of the tetrahedron. \verb|set_obj_point|'s first parameter
396 is the point number and the other three are the cartesian coordinates.
397 The first three points are in a plane and the fourth is obtained with
398 the \verb|new_face_point| macro, which folds a face
399 %%%RF 1998/02/19: tagged reference sentence on to end in parens
400 (see the description in appendix A for more details).
401 The \verb|new_face_point| macro
402 is used with the angle \verb|an| which is computed in advance.
403 Once the four points are set, the object is normalized, which means
404 that it is centered with respect to the list of vertices given
405 as parameter (here \verb|1,2,3,4|) and the last vertex is put on a sphere
406 of radius 1, centered on the origin. Therefore, point 5 is the center
407 of the tetrahedron, and the tetrahedron is set symmetrically
408 with respect to the origin.
409
410 \tolerance=1000
411 %%%RF 1998/02/19: was `are hence inscriptible'
412 All five convex regular polyhedra are defined in this way and may
413 therefore be inscribed in a sphere of radius 1.
414
415 \begin{verbatim}
416 def set_tetrahedron_points(expr inst)=
417 set_obj_point(1,0,0,0);
418 set_obj_point(2,1,0,0);
419 set_obj_point(3,cosd(60),sind(60),0);
420 sinan=1/sqrt(3);
421 cosan=sqrt(1-sinan**2);
422 an=180-2*angle((cosan,sinan));
423 new_face_point(4,1,2,3,an);
424 normalize_obj(inst)(1,2,3,4);
425 set_obj_point(5,0,0,0);
426 enddef;
427 \end{verbatim}
428
429 The second macro, \verb|def_tetrahedron| defines the number of points and
430 faces of the instance, calls the previous macro and defines the faces
431 with the macro \verb|set_obj_face|.
432 The first argument of that macro is a \emph{local}
433 face number, the second is a list of vertices such that the list goes clockwise
434 when the face is visible. The last argument is the color of the face in RGB.
435
436 \begin{verbatim}
437 vardef def_tetrahedron(expr inst)=
438 new_obj_points(inst,5);
439 new_obj_faces(inst,4);
440 set_tetrahedron_points(inst);
441 set_obj_face(1,"1,2,4","b4fefe");
442 set_obj_face(2,"2,3,4","b49bc0");
443 set_obj_face(3,"1,4,3","b4c8fe");
444 set_obj_face(4,"1,3,2","b4fe40");
445 enddef;
446 \end{verbatim}
447
448 The result of the drawing is:
449
450 \begin{center}
451 \includegraphics{tetra.ps}
452 \end{center}
453
454 A more complex example is the icosahedron which is defined below.
455
456 \begin{verbatim}
457 def set_icosahedron_points(expr inst)=
458 set_obj_point(1,0,0,0);
459 set_obj_point(2,1,0,0);
460 set_obj_point(3,cosd(60),sind(60),0);
461 cosan=1-8/3*cosd(36)*cosd(36);
462 sinan=sqrt(1-cosan*cosan);
463 an=180-angle((cosan,sinan));
464 new_face_point(4,1,2,3,an);
465 new_face_point(5,2,3,1,an);
466 new_face_point(6,3,1,2,an);
467 new_face_point(7,2,4,3,an);
468 new_face_point(8,3,5,1,an);
469 new_face_point(9,1,6,2,an);
470 new_face_point(10,3,4,7,an);
471 new_face_point(11,3,7,5,an);
472 new_face_point(12,1,8,6,an);
473 % 1 and 10 are opposite vertices
474 normalize_obj(inst)(1,10);
475 % center of icosahedron
476 set_obj_point(13,0,0,0);
477 enddef;
478 \end{verbatim}
479
480 \begin{verbatim}
481 vardef def_icosahedron(expr inst)=
482 save cosan,sinan,an;
483 new_obj_points(inst,13);
484 new_obj_faces(inst,20);
485 set_icosahedron_points(inst);
486 set_obj_face(1,"3,2,1","b40000");
487 set_obj_face(2,"2,3,4","ff0fa1");
488 set_obj_face(3,"3,7,4","b49b49");
489 set_obj_face(4,"3,5,7","b49bc0");
490 set_obj_face(5,"3,1,5","b4c8fe");
491 set_obj_face(6,"1,8,5","b4fefe");
492 set_obj_face(7,"1,6,8","b4fe40");
493 set_obj_face(8,"1,2,6","45d040");
494 set_obj_face(9,"2,9,6","45a114");
495 set_obj_face(10,"2,4,9","45a1d4");
496 set_obj_face(11,"9,4,10","4569d4");
497 set_obj_face(12,"4,7,10","112da1");
498 set_obj_face(13,"7,5,11","b4fefe");
499 set_obj_face(14,"5,8,11","b49bc0");
500 set_obj_face(15,"8,6,12","45a114");
501 set_obj_face(16,"6,9,12","b49b49");
502 set_obj_face(17,"8,12,11","b40000");
503 set_obj_face(18,"7,11,10","45a1d4");
504 set_obj_face(19,"12,10,11","b4c8fe");
505 set_obj_face(20,"9,10,12","ff0fa1");
506 enddef;
507 \end{verbatim}
508
509 Since all points of the objects are stored in a unique global array,
510 they are internally
511 accessed by the local numbers and an offset defined by the
512 macro \verb|new_obj_points|.
513 The icosahedron example shows a systematic use of the
514 \verb|new_face_point| macro to compute a point on an adjacent face.
515 Displaying such an icosahedron results in the figure~\ref{icosahedron}.
516 %% fig3
517 \begin{figure}[h]
518 \begin{center}
519 \includegraphics{icosa.ps}
520 \end{center}
521 \caption{An icosahedron}\label{icosahedron}
522 \end{figure}
523
524 The other three regular convex polyhedra are:
525 \begin{center}
526 \includegraphics{cube.ps}
527 \end{center}
528
529 \begin{center}
530 \includegraphics{octa.ps}\hfill\includegraphics{dodeca.ps}
531 \end{center}
532
533 The dodecahedron code is a bit special, since the vertices are built
534 using ten additional points corresponding to face centers. These points
535 are defined as an array of variables \verb|fc1| through \verb|fc10|
536 with \verb|new_points(fc)(10)|.
537 \verb|free_points(fc)(10)| frees them when they are no longer
538 necessary. An excerpt of the dodecahedron code is:
539
540 \begin{verbatim}
541 def set_dodecahedron_points(expr inst)=
542 new_points(fc)(10);% face centers
543 set_point(fc1,0,0,0);
544 set_obj_point(1,1,0,0);
545 set_obj_point(2,cosd(72),sind(72),0);
546 rotate_in_plane(3,fc1,1,2);
547 ...
548 free_points(fc)(10);
549 enddef;
550 \end{verbatim}
551
552
553 Finally, wire drawings can be obtained by setting the boolean
554 \verb|filled_faces| to false:
555
556 \begin{center}
557 \includegraphics{icosa-w.ps}
558 \end{center}
559
560 \subsection{Animating objects}
561
562 The animation of one or several objects involves the object(s) and an observer.
563 The animation is a set of images and from an image to the next one,
564 the observer as well as the objects can move. For instance
565 the macro \verb|one_image| in \verb|3d.mp| is:
566
567 \begin{verbatim}
568 def one_image(expr name,i,a,rd,ang)=
569 beginfig(i);
570 set_point(Obs,
571 -rd*cosd(a*ang),-rd*sind(a*ang),1);
572 Obs_phi:=90;Obs_dist:=2;
573 % fix point 1 of object |name|
574 point_of_view_obj(name,1,Obs_phi);
575 draw_obj(name);
576 rotate_obj_pv(name,1,vect_I,ang);
577 % show the rotation point
578 draw_point(name,1);
579 draw_axes(red,green,blue);
580 endfig;
581 enddef;
582 \end{verbatim}
583
584 The parameters of this macro are a name of an object (\verb|name|),
585 an image index (\verb|i|), and three values defining the position
586 of the observer.
587 The observer (\verb|Obs| is a global point and set with \verb|set_point|,
588 not with \verb|set_obj_point|)
589 follows a circle of radius \verb|rd|.
590 %%%RF 1998/02/19: reversed `usually is'
591 The parameter \verb|a|, which is usually a function of \verb|i|,
592 determines the number of rotation steps
593 of the observer, each step being a rotation of angle \verb|ang|.
594 The distance between the observer and the
595 projection plane is $2$ (see figure~\ref{proj-screen}).
596
597 %% fig4
598 \begin{figure*}
599 \begin{center}
600 \includegraphics{vect-fig.8}
601 \end{center}
602 \caption{Projection on the screen}\label{proj-screen}
603 \end{figure*}
604
605 %% fig5
606 \begin{figure*}
607 \begin{center}
608 \includegraphics{vect-fig.16}
609 \end{center}
610 \caption{Orientation of the observer}\label{obs-orientation}
611 \end{figure*}
612
613
614 The orientation of the observer is defined by three angles
615 (see figure~\ref{obs-orientation}). The \verb|Obs_phi| angle
616 is given and the two others are computed with a call to
617 \verb|point_of_view_obj(name,1,Obs_phi)| which constrains the observer
618 to look towards point 1 of object \verb|name|. Therefore, this
619 point will seem fixed on the animation and \verb|draw_point(name,1)|
620 draws it later so that this feature can be observed.
621 There is nothing special about that point, except that it
622 remains fix when the object is rotated. The object is drawn
623 with \verb|draw_obj(name)| and
624 %%%RF 1998/02/19: `does rotate'->rotates -- these arguments aren't
625 %%% described here, which seems wrong, but i don't think
626 %%% it's easy to do better....
627 \verb|rotate_obj_pv| rotates the object \verb|name|
628 by \verb|ang| degrees around an axis going through point 1
629 and directed by vector \verb|vect_I| ($\vec{\imath}$).
630 The reference vectors ($\vec\imath$,
631 $\vec\jmath$ and $\vec k$) are drawn in red, green and blue with
632 \verb|draw_axes|.
633
634 Finally, a complete animation of an icosahedron is obtained
635 with
636
637 \begin{verbatim}
638 animate_object("icosahedron",1,100,100);
639 \end{verbatim}
640
641 %%%RF 1998/02/19: `and this'->`which'
642 \noindent which generates files \verb|anim.101|,
643 %%%RF 1998/02/19: `if ... is'->`from ...'
644 \ldots, \verb|anim.200| from the main file \verb|anim.mp|.
645 The first parameter of \verb|animate_object| is the name of the object
646 to animate, the second and third parameters are minimal and maximal
647 values of the index loop and the fourth parameter is an offset added
648 to the index loop in order to get the file extension, which must lie
649 in the interval $0..4096$.
650
651 After each image is drawn, the values of the current bounding box
652 are used to compute the bounding box of the sequence of images.
653 The internal values \verb|xmin_|, \verb|ymin_|, \verb|xmax_|
654 and \verb|ymax_| hold the minimal and maximal values of the coordinates
655 of the past images' corners.
656 They are updated just before each image is shipped out.
657
658 \subsection{Putting the pieces together}
659
660 Once all the views have been computed, they can be used separately
661 (see for instance the five views of figure~\ref{anim-five-views})
662 or more interestingly, they can be merged.
663 This task is made almost straightforward by \MP{} itself.
664 Indeed, every time \verb|animate_object| is used, a shell script
665 named \verb|create_animation.sh|
666 is generated, as a side-effect of a call to
667 \verb|show_animation_bbox|. The script is
668 similar to that shown in figure~\ref{animation-script}.
669 This script uses the values
670 computed for the global bounding box of the sequence of images,
671 for these values are necessary in order to extract the right parts
672 of the images and get correct alignments; the parts are extracted
673 with \texttt{pnmcut}.\footnote{One might think of using
674 \texttt{Ghostscript} for generating an excerpt of an image,
675 but if \texttt{Ghostscript} is used to generate the bounding box
676 of an image, it will in general not be possible to have a good alignment
677 between all images. The sizes of the excerpts are only known when all images
678 have been produced.}
679 If you have the programs
680 used in this script (\texttt{Ghostscript}, etc.), you can just run
681 it with \verb|sh create_animation.sh| on UNIX. You may need
682 to adapt it to your needs, and for that purpose, you can modify the macro
683 \verb|write_script| in \verb|3d.mp|.
684
685 Some examples are included in the \verb|3d| distribution, and they
686 can be viewed for instance with \texttt{netscape} or
687 special programs such as \verb|xanim|.
688
689 %% fig6
690 \begin{figure*}
691 \includegraphics[scale=0.5]{anim.1}\hfill
692 \includegraphics[scale=0.5]{anim.2}\hfill
693 \includegraphics[scale=0.5]{anim.3}\hfill
694 \includegraphics[scale=0.5]{anim.4}\hfill
695 \includegraphics[scale=0.5]{anim.5}
696
697 \caption{Five views of an animation}\label{anim-five-views}
698 \end{figure*}
699
700 \section{Future}
701
702 It is quite easy to improve and extend the \verb|3d| macros but the
703 author decided to go no further for the moment. Other objects can
704 be implemented easily and new algorithms can be added. For instance
705 in order to take light sources or shadows into account, one can compute
706 the angles under which a face gets its light, and the angle under which
707 this very face is seen, in order to decide how much darker or lighter
708 it must be rendered. Another problem is to represent
709 overlapping objects correctly. In the current implementation, each
710 object is drawn
711 independently from the other objects, so that the overlapping may be wrong.
712 One solution is to sort all the faces according to their distance
713 to the observer and, if two faces can not be ordered, to split them.
714 Then, the faces can be drawn starting with the most distant, and
715 ending with the closest one.
716 Appendix B explains the internal representation of the objects and
717 shows that this algorithm can be implemented without much surgery to
718 the present code.
719
720 \section{Acknowledgments}
721
722 Thanks to John Hobby who always answers all my queries on the \MF{} mailing
723 list. Thanks to Alain Filbois who helped me with the shell script
724 syntax, to Thomas Lambolais and Thomas Genet who gave some feedback
725 on this work, and to Dominique Larchey who pointed out a shortcoming
726 in the conclusion. Thanks to Denis Barbier who
727 was one of the first users of these
728 macros and contributed the animated crayons in the distribution. Thanks to
729 Bogus\l aw Jackowski who made valuable comments on some peculiarities of
730 the code.
731 And finally, special thanks to Ulrik Vieth who not only
732 pushed me to polish my code and this paper more than I had first intended,
733 but also made it possible to use \MP{} under \texttt{web2c}.
734
735 \bibliography{paper}
736
737 \appendix
738
739 \section{Appendix A\\
740 Summary of the \texttt{3d} package}
741
742 \subsection{Types}
743
744 The commands in the \texttt{3d} package take parameters
745 of several different types. The types are described here.
746
747 \begin{itemize}
748 \item An \AVN{} (\emph{Absolute Vector Number}) is the internal
749 number identifying a vector in the \verb|vect| array (an integer).
750 \item An \APN{} (\emph{Absolute Point Number}) refers to a vector
751 in the same way as an \AVN{} (an integer).
752 \item A \LPN{} (\emph{Local Point Number}) is a number identifying a
753 point \emph{within} an object (an integer). Two \LPN{}s with the same value
754 can correspond to different points in different objects.
755 \item An \AFN{} (\emph{Absolute Face Number}) is the internal
756 number identifying a face.
757 \item A \LFN{} (\emph{Local Face Number}) is a number identifying a face
758 \emph{within} an object (an integer). As for points, two \LFN{}s with
759 the same value
760 can correspond to different faces in different objects.
761 \item A \CN{} (\emph{Class}) is a string representing a class,
762 for instance \verb|"tetrahedron"|. It may only contain
763 letters and underscores.
764 \item An \IN{} (\emph{Object}) is a string representing an object, that is
765 an instance of a class. Such a string may only contain
766 letters and underscores.
767 \item A \VL{} (\emph{Vertex List}) is a list
768 of integers, where each integer identifies a vertex. For instance, \verb|1,7|
769 is the list of vertices 1 and 7.
770 \item A \VSL{} (\emph{Vertex String List}) is a string corresponding to a list
771 of integers, where each integer identifies a vertex. For instance,
772 \verb|"1,2,6,5"| is the list of vertices 1, 2, 6 and 5.
773 \item \HEXCOL{} (\emph{Hex Color}) is a string representing a color with
774 the three RGB components in hexadecimal and in the range
775 $0..255$. For instance, \verb|"b4fe40"|.
776 \item \COL{} (\emph{Color}) is a standard \MP{} color
777 (a triplet of RGB components in the range $0..1$),
778 such as \verb|red|.
779 \item \STR{} (\emph{String}) is a string.
780 \item \PAIR{} (\emph{Pair}) is a pair of numerics.
781 \item \NUM{} (\emph{Numeric}) is a number.
782 \item \BOOL{} (\emph{Boolean}) is a boolean.
783 \end{itemize}
784
785 \subsection{Low level vector commands}
786
787 The low level vector commands define the classical operations in vector
788 algebra.
789
790 \begin{itemize}
791 %\item \verb|vect_def(|\AVN\tc$x$\tc$y$\tc$z$\verb|)|; defines vector \AVN{}
792 \item \verb|vect_def(|\AVN\tc$x$\tc$y$\tc$z$\verb|)|: defines vector \AVN{}
793 as $(x,y,z)$;
794
795 %\item \verb|set_point|: synonym of \verb|vect_def|; a point is stored in the
796 \item \verb|set_point|; synonym of \verb|vect_def|: a point is stored in the
797 same array as vectors.
798
799 %\item \verb|set_obj_point(|\LPN\tc$x$\tc$y$\tc$z$\verb|)|;
800 \item \verb|set_obj_point(|\LPN\tc$x$\tc$y$\tc$z$\verb|)|:
801 this defines the point \LPN{} as $(x,y,z)$;
802
803 %\item \verb|vect_def_vect(|\AVN$_1$\tc\AVN$_2$\verb|)|;
804 \item \verb|vect_def_vect(|\AVN$_1$\tc\AVN$_2$\verb|)|:
805 vector \AVN$_1$ becomes equal to vector \AVN$_2$;
806
807 \item \verb|vect_sum(|\AVN$_1$\tc\AVN$_2$\tc\AVN$_3$\verb|)|:
808 the vector \AVN$_1$ becomes the sum of vectors \AVN$_2$ and \AVN$_3$.
809
810 \item \verb|vect_translate(|\AVN$_1$\tc\AVN$_2$\verb|)|:
811 add vector \AVN$_2$
812 to vector \AVN$_1$; vector \AVN$_2$ remains unchanged.
813
814 \item \verb|vect_diff(|\AVN$_1$\tc\AVN$_2$\tc\AVN$_3$\verb|)|:
815 the vector \AVN$_1$
816 becomes the difference between vectors \AVN$_2$ and \AVN$_3$.
817
818 \item \verb|vect_dprod(|\AVN$_1$\tc\AVN$_2$\verb|)| $\rightarrow $ \NUM{}:
819 returns the dot product of vectors \AVN$_1$ and \AVN$_2$.
820
821 \item \verb|vect_mod(|\AVN\verb|)| $\rightarrow $ \NUM{}: returns the
822 modulus of vector \AVN.
823
824 \item \verb|vect_prod(|\AVN$_1$\tc\AVN$_2$\tc\AVN$_3$\verb|)|:
825 the vector \AVN$_1$
826 becomes the vector product of vectors \AVN$_2$ and \AVN$_3$.
827
828 \tolerance=1000
829 \item \verb|vect_mult(|\AVN$_1$\tc\AVN$_2$\tc\NUM\verb|)|: \AVN$_1$
830 becomes vector \AVN$_2$ scaled by \NUM.
831
832 \item \verb|mid_point(|\AVN$_1$\tc\AVN$_2$\tc\AVN$_3$\verb|)|:
833 vector (or point) \AVN$_1$ becomes the mid-point of vectors (or of the
834 line joining the points)
835 \AVN$_2$ and \AVN$_3$.
836
837 \item \verb|vect_rotate(|\AVN$_1$\tc\AVN$_2$\tc$a$\verb|)|: vector \AVN$_1$ is
838 rotated around vector \AVN$_2$ by the angle $a$.
839 \end{itemize}
840
841 \tolerance=1000
842 \subsection{Operations on objects}
843
844 Several operations apply globally on objects:
845
846 \begin{itemize}
847 \item \verb|assign_obj(|\IN\tc\CN\verb|)|:
848 create \IN{} as an instance of class \CN.
849 \item \verb|reset_obj(|\IN\verb|)|: put \IN{} back where it
850 was just after it was initialized.
851 \item \verb|put_obj(|\IN\tc\AVN\tc$s$\tc$\psi$\tc$\theta$\tc$\phi$\verb|)|:
852 object \IN{} is scaled by $s$, shifted by vector \AVN{} and
853 oriented with the angles $\psi$, $\theta$, $\phi$,
854 as for the observer orientation (figure~\ref{obs-orientation}).
855 \item \verb|rotate_obj_pv(|\IN\tc\LPN\tc\AVN\tc$a$\verb|)|:
856 object \IN{} is rotated
857 around an axis going through local point \LPN{}
858 and directed by vector \AVN; the rotation is by $a$ degrees.
859 \item \verb|rotate_obj_abs_pv(|\IN\tc\APN\tc\AVN\tc$a$\verb|)|:\break
860 the object \IN{} is rotated around an axis going through absolute
861 point \APN{} and directed by vector \AVN; the rotation is by $a$ degrees.
862 \item \verb|rotate_obj_pp(|\IN\tc\LPN$_1$\tc\LPN$_2$\tc$a$\verb|)|:
863 \IN{} is rotated around an axis going through local points
864 \LPN$_1$ and \LPN$_2$; the rotation is by $a$ degrees.
865 \item \verb|translate_obj(|\IN\tc\AVN\verb|)|: object \IN{} is translated
866 by vector \AVN.
867 \item \verb|scale_obj(|\IN\tc$v$\verb|)|: object~\IN{}~is~scaled~by~$v$.
868 \end{itemize}
869
870 \subsection{Building new points in space}
871
872 Three macros are especially useful for the definition of regular polyhedra:
873
874 \begin{itemize}
875 \item \verb|rotate_in_plane(|$k$\tc$o$\tc$i$\tc$j$\verb|)|:
876 get point $k$ from point $j$ by rotation
877 around point $o$ by an angle $\alpha$ equal to the angle from $i$ to $j$;
878 $i$, $j$ and $k$ are of type \LPN, whereas $o$ is of type \APN.
879
880 \begin{center}
881 \includegraphics{vect-fig.11}
882 \end{center}
883
884 \item \verb|new_face_point(|$c$\tc$o$\tc$i$\tc$j$\tc$\alpha$\verb|)|:
885 the middle $m$ of points $i$ and $j$ is such that
886 $\widehat{(\overrightarrow{om},\overrightarrow{mc})}=\alpha$
887 and $\overrightarrow{mc}$ is $\overrightarrow{om}$ rotated around
888 $\overrightarrow{ji}$. $c$, $o$, $i$ and $j$ are of type \LPN.
889
890 \begin{center}
891 \includegraphics{vect-fig.7}
892 \end{center}
893
894 \item \verb|new_abs_face_point(|$c$\tc$o$\tc$i$\tc$j$\tc$\alpha$\verb|)|:
895 similar to the previous definition, but $c$ and $o$ are of type \APN.
896
897 \end{itemize}
898
899 \subsection{Drawing points, axes, objects}
900
901 \begin{itemize}
902 \item \verb|draw_point(|\IN\tc\LPN\verb|)|: draw point \LPN{} in
903 object \IN.
904 \item \verb|draw_axes(|\COL$_1$\tc\COL$_2$\tc\COL$_3$\verb|)|:
905 draw vectors $\vec\imath$, $\vec\jmath$ and $\vec{k}$ in colors
906 \COL$_1$, \COL$_2$ and \COL$_3$.
907 \item \verb|draw_obj(|\IN\verb|)|: draw object \IN.
908 \end{itemize}
909
910 \subsection{Setting faces}
911
912 \begin{itemize}
913 \item \verb|set_face(|\AFN\tc\VSL\tc\HEXCOL\verb|)|:
914 set absolute face \AFN{} as
915 delimited by the vertex list \VSL{} (local point numbers) and colored by
916 color \HEXCOL.
917 \item \verb|set_obj_face(|\LFN\tc\VSL\tc\HEXCOL\verb|)|:
918 set local face \LFN{} as
919 delimited by the vertex list \VSL{} (local point numbers) and colored by
920 color \HEXCOL.
921
922 \end{itemize}
923
924 \break
925
926 \subsection{View points, distance}
927
928 \begin{itemize}
929 \item \verb|compute_reference(|$\psi$\tc$\theta$\tc$\phi$\verb|)|: defines
930 the orientation of the observer by the three angles $\psi$,
931 $\theta$ and $\phi$. See figure~\ref{obs-orientation}.
932
933 \item \verb|point_of_view_obj(|\IN\tc\LPN\tc$\phi$\verb|)|: the orientation
934 of the observer is defined as looking local point \LPN{} of object \IN,
935 with an angle of $\phi$;
936 \item \verb|point_of_view_abs(|\APN\tc$\phi$\verb|)|: the observer's
937 orientation is defined as looking absolute point \APN{},
938 with an angle of $\phi$;
939 \item \verb|obs_distance(|$v$\verb|)(|\IN\tc\LPN\verb|)|: let $v$ equal
940 the distance between the observer and local point \LPN{} in object \IN{}.
941 \end{itemize}
942
943 \subsection{Vector and point allocation}
944
945 \begin{itemize}
946 \item \verb|new_vect|$\rightarrow $ \AVN{}: return a new vector;
947 \item \verb|new_point|: synonym of \verb|new_vect|;
948 \item \verb|new_points(|$v$\verb|)(|$n$\verb|)|: defines the absolute points
949 $v_1, \ldots, v_n$, using \verb|new_point|;
950 \item \verb|free_vect(|\AVN\verb|)|: free vector \AVN;
951 \item \verb|free_point(|\APN\verb|)|: free point \APN;
952 \item \verb|free_points(|$v$\verb|)(|$n$\verb|)|: frees the absolute points
953 $v_1, \ldots, v_n$, using \verb|free_point|.
954 \end{itemize}
955
956 \subsection{Debugging}
957
958 \begin{itemize}
959 \item \verb|show_vect(|\STR\tc\AVN\verb|)|:
960 shows vector \AVN, with string \STR.
961 \item \verb|show_point|: synonym of \verb|show_vect|
962 \item \verb|show_pair(|\STR\tc\PAIR\verb|)|: this shows a numeric pair,
963 with string \STR.
964 \end{itemize}
965
966 \subsection{Normalization}
967
968 \begin{itemize}
969 \item \verb|normalize_obj(|\IN\tc\VL\verb|)|: normalize object \IN{}
970 with respect to the list of vertices \VL.
971 \end{itemize}
972
973 \subsection{Parameters}
974
975 \begin{itemize}
976 \item \verb|Obs_dist| $\rightarrow$ \NUM: distance between the observer
977 and the projection plane.
978 \item \verb|h_field| $\rightarrow$ \NUM: horizontal field of view
979 (default: 100 degrees)
980 \item \verb|v_field| $\rightarrow$ \NUM: vertical field of view
981 (default: 70 degrees)
982 \item \verb|Obs_phi| $\rightarrow$ \NUM: angle $\phi$ for the orientation
983 of the observer;
984 \item \verb|Obs_theta| $\rightarrow$ \NUM: angle $\theta$ for the orientation
985 of the observer;
986 \item \verb|Obs_psi| $\rightarrow$ \NUM: angle $\psi$ for the orientation
987 of the observer;
988 \item \verb|drawing_scale| $\rightarrow$ \NUM: scale factor applied for
989 drawing;
990 \item \verb|filled_faces| $\rightarrow$ \BOOL: if \texttt{true}, the faces
991 are drawn filled; if \texttt{false}, only the edges are drawn,
992 and hidden edges are drawn dashed;
993 \item \verb|draw_contours| $\rightarrow$ \BOOL: if \texttt{true}, the contours
994 of the faces are drawn, and the lines have the thickness
995 \verb|contour_width|; if \texttt{false}, the contours are not drawn;
996 \item \verb|contour_width| $\rightarrow$ \NUM: dimension used for drawing
997 contours of faces (default: 1pt).
998 \end{itemize}
999
1000 \subsection{Constants}
1001
1002 These values represent constant objects such
1003 as reference vectors, and should not be changed.
1004
1005 \begin{itemize}
1006 \item \verb|vect_null| $\rightarrow$ \AVN: internal index for $\vec0$.
1007 \item \verb|vect_I| $\rightarrow$ \AVN: internal index for $\vec\imath$.
1008 \item \verb|vect_J| $\rightarrow$ \AVN: internal index for $\vec\jmath$.
1009 \item \verb|vect_K| $\rightarrow$ \AVN: internal index for $\vec k$.
1010 \item \verb|point_null| $\rightarrow$ \APN: internal index for $\vec0$.
1011 \item \verb|Obs| $\rightarrow$ \APN: observer's internal point number.
1012 \end{itemize}
1013
1014 \subsection{Defining new object points and faces}
1015
1016 \begin{itemize}
1017 \item \verb|new_obj_points(|\IN\tc\NUM\verb|)|:
1018 defines points $1$ to \NUM{} in object \IN; must be used before setting
1019 the points;
1020 \item \verb|new_obj_faces(|\IN\tc\NUM\verb|)|:
1021 defines \NUM{} faces in object \IN; must be used before setting
1022 the faces;
1023 \end{itemize}
1024
1025 \subsection{Offsets}
1026
1027 \begin{itemize}
1028 \item \verb|pnt(|\LPN\verb|)| $\rightarrow$ \APN: returns the absolute point
1029 number for a given local point index.
1030 \item \verb|face(|\LFN\verb|)| $\rightarrow$ \AFN: returns the absolute face
1031 number for a given local face index.
1032 \end{itemize}
1033
1034 \subsection{Standard classes}
1035
1036 Five standard classes are defined in \texttt{poly.mp}:
1037 they define the five regular convex polyhedra. For each class \meta{class},
1038 there are two macros:
1039
1040 \begin{itemize}
1041
1042 \item \verb|set_|\meta{class}\verb|_points|
1043 (e.g. \verb|set_cube_points|)
1044
1045 \item \verb|def_|\meta{class} (e.g. \verb|def_cube|)
1046
1047 \end{itemize}
1048
1049 Each of these macros is defined with a parameter which is the instance
1050 name.
1051
1052 \subsection{Standard animations}
1053
1054 The \texttt{3d} package provides a few standard animations using
1055 the convex polyhedra. In each of these animations, the observer
1056 follows a circular path pictured in figure~\ref{observer-motion}.
1057 Each standard animation is divided into two macros. The first,
1058 such as \verb|animate_object|, defines the class(es) that are used
1059 and sets the objects. The second, such as \verb|one_image|, sets
1060 the observer, draws the object(s) and moves the object(s) and the
1061 observer. The file \verb|animpoly.mp| gives examples of the use
1062 of the standard animations.
1063
1064 \iffalse
1065 \begin{itemize}
1066 \item \verb|one_image(name,i,a)|
1067 \item \verb|one_image_two_objects(name_a,name_b,i,a)|
1068 \item \verb|one_image_three_objects(name_a,name_b,name_c,i,a)|
1069 \item \verb|one_image_two_identical_objects(name_a,name_b,i,a)|
1070 \item \verb|animate_object(name,imin,imax,index)|
1071 \item \verb|animate_two_objects(name_a,name_b,imin,imax,index)|
1072 \item \verb|animate_three_objects(name_a,name_b,name_c,imin,imax,index)|
1073 \item \verb|animate_two_identical_objects(name,imin,imax,index)|
1074 \end{itemize}
1075 \fi
1076
1077 %% fig7
1078 \begin{figure*}
1079 \begin{center}
1080 \includegraphics{vect-fig.17}
1081 \end{center}
1082 \caption{Motion of the observer}\label{observer-motion}
1083 \end{figure*}
1084
1085 \section{Appendix B\\
1086 Coding an object}
1087
1088 In order to extend the \texttt{3d} package, it is necessary to
1089 understand how the objects are coded. We give here an overview of
1090 this coding, but the reader is advised to peek in the code to get
1091 a better understanding on how all the functions interact.
1092
1093 First, an object has a name, for instance \verb|"box"|.
1094 The macro \verb|box_class| (which can be called with \verb|obj_class_("box")|)
1095 is the string corresponding to the class of
1096 \verb|"box"|, for instance \verb|"cube"|.
1097 The variable \verb|cube_point_offsetbox|, of type \texttt{numeric},
1098 and obtained with \verb|obj_point_offset_("box")|,
1099 is equal to the absolute index of the last
1100 point of the previous object. A cube is defined with $8+1$ points. Assuming
1101 it was defined after an icosahedron ($12+1$ points) named
1102 \verb|"ico"|, \verb|cube_point_offsetbox| will be a \verb|numeric|
1103 equal to $13$. \verb|cube_pointsbox|
1104 (obtained with \verb|obj_points_("box")|)
1105 is a macro equal to $9$.
1106 %(\verb|current_point_offset_| is equal to \verb|cube_point_offsetbox|.)
1107 The variable \verb|cube_face_offsetbox|,
1108 similar to \verb|cube_point_offsetbox|,
1109 obtained with a call to \verb|obj_face_offset_("box")|,
1110 equals $20$.
1111 The macro \verb|cube_facesbox|
1112 (obtained by \verb|obj_faces_("box")|)
1113 is equal to $6$.
1114 %(\verb|current_face_offset_| is equal to \verb|cube_face_offsetbox|.)
1115
1116 The \verb|obj_name| macro is extended each time a new object is defined.
1117 To an absolute face number, it associates an object name. Hence, it is possible
1118 to go through all faces. \verb|last_point_offset_| and
1119 \verb|last_face_offset_| are the absolute numbers of the last points and faces
1120 defined up to now.
1121
1122 \begin{verbatim}
1123 def obj_name(expr i)=
1124 if i<1: elseif i<=20:"ico"
1125 elseif i<=26:"box"
1126 fi;
1127 enddef;
1128 \end{verbatim}
1129
1130 \verb|pnt(i)| gives the absolute vector corresponding to local point $i$.
1131 \verb|ipnt_(i)| is the absolute point number, that is $i$ plus the number
1132 of points defined beforehand in other objects.
1133 \verb|points_[j]| is the absolute vector corresponding to absolute object
1134 point $j$. Similarly, \verb|face(i)|
1135 is the absolute face corresponding to local face $i$.
1136
1137 The list of vertices of absolute face number $i$ is \verb|face_points_[i]|.
1138 The color of absolute face number $i$ is \verb|face_color_[i]|.
1139
1140
1141 When the macros \verb|pnt| or \verb|face| are to be used, the calls
1142 \verb|define_current_point_offset_("box")| and
1143 \verb|define_current_face_offset_("box")| must be issued.
1144
1145
1146 \makesignature
1147
1148 \end{document}
1149