Debian Codegraph @

doc/geomview-1

raw
1 This is ../../doc/geomview, produced by makeinfo version 4.13 from
2 ../../doc/geomview.texi.
3
4 INFO-DIR-SECTION Graphics Applications
5 START-INFO-DIR-ENTRY
6 * Geomview: (geomview). The interactive 3D viewing program.
7 END-INFO-DIR-ENTRY
8
9 
10 File: geomview, Node: Top, Next: Intro, Prev: (dir), Up: (dir)
11
12 Geomview, the interactive 3D viewing program.
13
14 * Menu:
15
16 * Intro:: Introduction to Geomview.
17 * Distrib:: How to get the latest Geomview distribution.
18 * Copying:: The GNU Lesser Public License.
19 * History:: History of Geomview's Development.
20 * Platforms:: Supported Platforms.
21 * Pronunciation:: How to Pronounce ``Geomview''.
22 * Overview:: Overview of Geomview.
23 * Tutorial:: Introductory Tutorial.
24 * Interaction:: Interacting with Geomview.
25 * OOGL File Formats:: Formats for Geometry Input.
26 * Customization:: Modifying the behavior of Geomview.
27 * Modules:: Programs that use Geomview for graphics display.
28 * GCL:: GCL: the Geomview Command Language.
29 * Non-Euclidean Geometry:: Non-Euclidean Geometry.
30 * Mathematica:: Mathematica Graphics in Geomview or RenderMan.
31 * Installation:: Installing Geomview on your computer.
32 * Support:: Getting Technical Support for Geomview.
33
34 * Contributing:: How to contribute to Geomview.
35 * Function Index:: A node for each GCL function.
36 * List of Figures:: List of Figures.
37
38 
39 File: geomview, Node: Intro, Next: Distrib, Prev: Top, Up: Top
40
41 Introduction to Geomview
42 ************************
43
44 Geomview is an interactive program for viewing and manipulating
45 geometric objects, originally written by staff members of the Geometry
46 Center at the University of Minnesota, starting in 1991. It can be used
47 as a stand-alone viewer for static objects or as a display engine for
48 other programs which produce dynamically changing geometry. It runs on
49 many kinds of Unix computers, including Linux, SGI, Sun, and HP. It also
50 runs with Cygwin. This manual describes Geomview version 1.9.
51
52 Geomview is free software, available under the terms of the GNU
53 Lesser Public License; *note Copying:: for details.
54
55 Geomview and this manual are available for download from
56 `http://www.geomview.org'.
57
58 Permission is granted to make copies of this manual.
59
60 If you have questions or comments about Geomview or this manual,
61 consider joining in the `geomview-users' mailing list, which is a forum
62 in which users of Geomview communicate to answer each others' questions
63 and to share news about what they are doing with Geomview. The
64 Geomview authors participate in this list and sometimes post answers to
65 questions there. To join the list, visit the list web page at
66 `http://lists.sourceforge.net/mailman/listinfo/geomview-users'.
67
68 
69 File: geomview, Node: Distrib, Next: Copying, Prev: Intro, Up: Top
70
71 Distribution
72 ************
73
74 Geomview is "free software"; this means that everyone is free to use it
75 and free to redistribute it on certain conditions. Geomview is not in
76 the public domain; it is copyrighted and there are restrictions on its
77 distribution, but these restrictions are designed to permit everything
78 that a good cooperating citizen would want to do. What is not allowed
79 is to try to prevent others from further sharing any version of
80 Geomview that they might get from you. The precise conditions are
81 found in the GNU Lesser Public License that comes with Geomview and also
82 appears following this section.
83
84 One way to get a copy of Geomview is from someone else who has it.
85 You need not ask for our permission to do so, or tell any one else; just
86 copy it. If you have access to the Internet, you can get the latest
87 distribution version of Geomview at `http://www.geomview.org'.
88
89 You may also receive Geomview when you buy a computer. Computer
90 manufacturers are free to distribute copies on the same terms that
91 apply to everyone else. These terms require them to give you the full
92 sources, including whatever changes they may have made, and to permit
93 you to redistribute the Geomview received from them under the usual
94 terms of the General Public License. In other words, the program must
95 be free for you when you get it, not just free for the manufacturer.
96
97 
98 File: geomview, Node: Copying, Next: History, Prev: Distrib, Up: Top
99
100 Copying
101 *******
102
103 NOTE: Geomview is distributed under the GNU LESSER GENERAL PUBLIC
104 LICENSE. For the purposes of this license we think of Geomview as if it
105 were a "library", and of Geomview external modules as "programs that
106 link with the library". We do this because we specifically want to
107 allow proprietary programs and modules to use Geomview.
108
109 GNU LESSER PUBLIC LICENSE
110 *************************
111
112 Version 2.1, February 1999
113
114 Copyright (C) 1991, 1999 Free Software Foundation, Inc.
115 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
116
117 Everyone is permitted to copy and distribute verbatim copies
118 of this license document, but changing it is not allowed.
119
120 [This is the first released version of the Lesser GPL. It also counts
121 as the successor of the GNU Library Public License, version 2, hence
122 the version number 2.1.]
123
124 Preamble
125 ========
126
127 The licenses for most software are designed to take away your freedom
128 to share and change it. By contrast, the GNU General Public Licenses
129 are intended to guarantee your freedom to share and change free
130 software-to make sure the software is free for all its users.
131
132 This license, the Lesser General Public License, applies to some
133 specially designated software packages-typically libraries-of the Free
134 Software Foundation and other authors who decide to use it. You can
135 use it too, but we suggest you first think carefully about whether this
136 license or the ordinary General Public License is the better strategy
137 to use in any particular case, based on the explanations below.
138
139 When we speak of free software, we are referring to freedom of use,
140 not price. Our General Public Licenses are designed to make sure that
141 you have the freedom to distribute copies of free software (and charge
142 for this service if you wish); that you receive source code or can get
143 it if you want it; that you can change the software and use pieces of
144 it in new free programs; and that you are informed that you can do
145 these things.
146
147 To protect your rights, we need to make restrictions that forbid
148 distributors to deny you these rights or to ask you to surrender these
149 rights. These restrictions translate to certain responsibilities for
150 you if you distribute copies of the library or if you modify it.
151
152 For example, if you distribute copies of the library, whether gratis
153 or for a fee, you must give the recipients all the rights that we gave
154 you. You must make sure that they, too, receive or can get the source
155 code. If you link other code with the library, you must provide
156 complete object files to the recipients, so that they can relink them
157 with the library after making changes to the library and recompiling
158 it. And you must show them these terms so they know their rights.
159
160 We protect your rights with a two-step method: (1) we copyright the
161 library, and (2) we offer you this license, which gives you legal
162 permission to copy, distribute and/or modify the library.
163
164 To protect each distributor, we want to make it very clear that
165 there is no warranty for the free library. Also, if the library is
166 modified by someone else and passed on, the recipients should know that
167 what they have is not the original version, so that the original
168 author's reputation will not be affected by problems that might be
169 introduced by others.
170
171 Finally, software patents pose a constant threat to the existence of
172 any free program. We wish to make sure that a company cannot
173 effectively restrict the users of a free program by obtaining a
174 restrictive license from a patent holder. Therefore, we insist that
175 any patent license obtained for a version of the library must be
176 consistent with the full freedom of use specified in this license.
177
178 Most GNU software, including some libraries, is covered by the
179 ordinary GNU General Public License. This license, the GNU Lesser
180 General Public License, applies to certain designated libraries, and is
181 quite different from the ordinary General Public License. We use this
182 license for certain libraries in order to permit linking those
183 libraries into non-free programs.
184
185 When a program is linked with a library, whether statically or using
186 a shared library, the combination of the two is legally speaking a
187 combined work, a derivative of the original library. The ordinary
188 General Public License therefore permits such linking only if the
189 entire combination fits its criteria of freedom. The Lesser General
190 Public License permits more lax criteria for linking other code with
191 the library.
192
193 We call this license the "Lesser" General Public License because it
194 does Less to protect the user's freedom than the ordinary General
195 Public License. It also provides other free software developers Less
196 of an advantage over competing non-free programs. These disadvantages
197 are the reason we use the ordinary General Public License for many
198 libraries. However, the Lesser license provides advantages in certain
199 special circumstances.
200
201 For example, on rare occasions, there may be a special need to
202 encourage the widest possible use of a certain library, so that it
203 becomes a de-facto standard. To achieve this, non-free programs must
204 be allowed to use the library. A more frequent case is that a free
205 library does the same job as widely used non-free libraries. In this
206 case, there is little to gain by limiting the free library to free
207 software only, so we use the Lesser General Public License.
208
209 In other cases, permission to use a particular library in non-free
210 programs enables a greater number of people to use a large body of free
211 software. For example, permission to use the GNU C Library in non-free
212 programs enables many more people to use the whole GNU operating
213 system, as well as its variant, the GNU/Linux operating system.
214
215 Although the Lesser General Public License is Less protective of the
216 users' freedom, it does ensure that the user of a program that is
217 linked with the Library has the freedom and the wherewithal to run that
218 program using a modified version of the Library.
219
220 The precise terms and conditions for copying, distribution and
221 modification follow. Pay close attention to the difference between a
222 "work based on the library" and a "work that uses the library". The
223 former contains code derived from the library, whereas the latter must
224 be combined with the library in order to run.
225
226 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
227 ===============================================================
228
229 0. This License Agreement applies to any software library or other
230 program which contains a notice placed by the copyright holder or
231 other authorized party saying it may be distributed under the
232 terms of this Lesser General Public License (also called "this
233 License"). Each licensee is addressed as "you".
234
235 A "library" means a collection of software functions and/or data
236 prepared so as to be conveniently linked with application programs
237 (which use some of those functions and data) to form executables.
238
239 The "Library", below, refers to any such software library or work
240 which has been distributed under these terms. A "work based on the
241 Library" means either the Library or any derivative work under
242 copyright law: that is to say, a work containing the Library or a
243 portion of it, either verbatim or with modifications and/or
244 translated straightforwardly into another language. (Hereinafter,
245 translation is included without limitation in the term
246 "modification".)
247
248 "Source code" for a work means the preferred form of the work for
249 making modifications to it. For a library, complete source code
250 means all the source code for all modules it contains, plus any
251 associated interface definition files, plus the scripts used to
252 control compilation and installation of the library.
253
254 Activities other than copying, distribution and modification are
255 not covered by this License; they are outside its scope. The act
256 of running a program using the Library is not restricted, and
257 output from such a program is covered only if its contents
258 constitute a work based on the Library (independent of the use of
259 the Library in a tool for writing it). Whether that is true
260 depends on what the Library does and what the program that uses
261 the Library does.
262
263 1. You may copy and distribute verbatim copies of the Library's
264 complete source code as you receive it, in any medium, provided
265 that you conspicuously and appropriately publish on each copy an
266 appropriate copyright notice and disclaimer of warranty; keep
267 intact all the notices that refer to this License and to the
268 absence of any warranty; and distribute a copy of this License
269 along with the Library.
270
271 You may charge a fee for the physical act of transferring a copy,
272 and you may at your option offer warranty protection in exchange
273 for a fee.
274
275 2. You may modify your copy or copies of the Library or any portion
276 of it, thus forming a work based on the Library, and copy and
277 distribute such modifications or work under the terms of Section 1
278 above, provided that you also meet all of these conditions:
279
280 a. The modified work must itself be a software library.
281
282 b. You must cause the files modified to carry prominent notices
283 stating that you changed the files and the date of any change.
284
285 c. You must cause the whole of the work to be licensed at no
286 charge to all third parties under the terms of this License.
287
288 d. If a facility in the modified Library refers to a function or
289 a table of data to be supplied by an application program that
290 uses the facility, other than as an argument passed when the
291 facility is invoked, then you must make a good faith effort
292 to ensure that, in the event an application does not supply
293 such function or table, the facility still operates, and
294 performs whatever part of its purpose remains meaningful.
295
296 (For example, a function in a library to compute square roots
297 has a purpose that is entirely well-defined independent of the
298 application. Therefore, Subsection 2d requires that any
299 application-supplied function or table used by this function
300 must be optional: if the application does not supply it, the
301 square root function must still compute square roots.)
302
303 These requirements apply to the modified work as a whole. If
304 identifiable sections of that work are not derived from the
305 Library, and can be reasonably considered independent and separate
306 works in themselves, then this License, and its terms, do not
307 apply to those sections when you distribute them as separate
308 works. But when you distribute the same sections as part of a
309 whole which is a work based on the Library, the distribution of
310 the whole must be on the terms of this License, whose permissions
311 for other licensees extend to the entire whole, and thus to each
312 and every part regardless of who wrote it.
313
314 Thus, it is not the intent of this section to claim rights or
315 contest your rights to work written entirely by you; rather, the
316 intent is to exercise the right to control the distribution of
317 derivative or collective works based on the Library.
318
319 In addition, mere aggregation of another work not based on the
320 Library with the Library (or with a work based on the Library) on
321 a volume of a storage or distribution medium does not bring the
322 other work under the scope of this License.
323
324 3. You may opt to apply the terms of the ordinary GNU General Public
325 License instead of this License to a given copy of the Library.
326 To do this, you must alter all the notices that refer to this
327 License, so that they refer to the ordinary GNU General Public
328 License, version 2, instead of to this License. (If a newer
329 version than version 2 of the ordinary GNU General Public License
330 has appeared, then you can specify that version instead if you
331 wish.) Do not make any other change in these notices. ^L Once
332 this change is made in a given copy, it is irreversible for that
333 copy, so the ordinary GNU General Public License applies to all
334 subsequent copies and derivative works made from that copy.
335
336 This option is useful when you wish to copy part of the code of
337 the Library into a program that is not a library.
338
339 4. You may copy and distribute the Library (or a portion or
340 derivative of it, under Section 2) in object code or executable
341 form under the terms of Sections 1 and 2 above provided that you
342 accompany it with the complete corresponding machine-readable
343 source code, which must be distributed under the terms of Sections
344 1 and 2 above on a medium customarily used for software
345 interchange.
346
347 If distribution of object code is made by offering access to copy
348 from a designated place, then offering equivalent access to copy
349 the source code from the same place satisfies the requirement to
350 distribute the source code, even though third parties are not
351 compelled to copy the source along with the object code.
352
353 5. A program that contains no derivative of any portion of the
354 Library, but is designed to work with the Library by being
355 compiled or linked with it, is called a "work that uses the
356 Library". Such a work, in isolation, is not a derivative work of
357 the Library, and therefore falls outside the scope of this License.
358
359 However, linking a "work that uses the Library" with the Library
360 creates an executable that is a derivative of the Library (because
361 it contains portions of the Library), rather than a "work that
362 uses the library". The executable is therefore covered by this
363 License. Section 6 states terms for distribution of such
364 executables.
365
366 When a "work that uses the Library" uses material from a header
367 file that is part of the Library, the object code for the work may
368 be a derivative work of the Library even though the source code is
369 not. Whether this is true is especially significant if the work
370 can be linked without the Library, or if the work is itself a
371 library. The threshold for this to be true is not precisely
372 defined by law.
373
374 If such an object file uses only numerical parameters, data
375 structure layouts and accessors, and small macros and small inline
376 functions (ten lines or less in length), then the use of the object
377 file is unrestricted, regardless of whether it is legally a
378 derivative work. (Executables containing this object code plus
379 portions of the Library will still fall under Section 6.)
380
381 Otherwise, if the work is a derivative of the Library, you may
382 distribute the object code for the work under the terms of Section
383 6. Any executables containing that work also fall under Section 6,
384 whether or not they are linked directly with the Library itself.
385
386 6. As an exception to the Sections above, you may also combine or
387 link a "work that uses the Library" with the Library to produce a
388 work containing portions of the Library, and distribute that work
389 under terms of your choice, provided that the terms permit
390 modification of the work for the customer's own use and reverse
391 engineering for debugging such modifications.
392
393 You must give prominent notice with each copy of the work that the
394 Library is used in it and that the Library and its use are covered
395 by this License. You must supply a copy of this License. If the
396 work during execution displays copyright notices, you must include
397 the copyright notice for the Library among them, as well as a
398 reference directing the user to the copy of this License. Also,
399 you must do one of these things:
400
401 a. Accompany the work with the complete corresponding
402 machine-readable source code for the Library including
403 whatever changes were used in the work (which must be
404 distributed under Sections 1 and 2 above); and, if the work
405 is an executable linked with the Library, with the complete
406 machine-readable "work that uses the Library", as object code
407 and/or source code, so that the user can modify the Library
408 and then relink to produce a modified executable containing
409 the modified Library. (It is understood that the user who
410 changes the contents of definitions files in the Library will
411 not necessarily be able to recompile the application to use
412 the modified definitions.)
413
414 b. Use a suitable shared library mechanism for linking with the
415 Library. A suitable mechanism is one that (1) uses at run
416 time a copy of the library already present on the user's
417 computer system, rather than copying library functions into
418 the executable, and (2) will operate properly with a modified
419 version of the library, if the user installs one, as long as
420 the modified version is interface-compatible with the version
421 that the work was made with.
422
423 c. Accompany the work with a written offer, valid for at least
424 three years, to give the same user the materials specified in
425 Subsection 6a, above, for a charge no more than the cost of
426 performing this distribution.
427
428 d. If distribution of the work is made by offering access to copy
429 from a designated place, offer equivalent access to copy the
430 above specified materials from the same place.
431
432 e. Verify that the user has already received a copy of these
433 materials or that you have already sent this user a copy.
434
435 For an executable, the required form of the "work that uses the
436 Library" must include any data and utility programs needed for
437 reproducing the executable from it. However, as a special
438 exception, the materials to be distributed need not include
439 anything that is normally distributed (in either source or binary
440 form) with the major components (compiler, kernel, and so on) of
441 the operating system on which the executable runs, unless that
442 component itself accompanies the executable.
443
444 It may happen that this requirement contradicts the license
445 restrictions of other proprietary libraries that do not normally
446 accompany the operating system. Such a contradiction means you
447 cannot use both them and the Library together in an executable
448 that you distribute.
449
450 7. You may place library facilities that are a work based on the
451 Library side-by-side in a single library together with other
452 library facilities not covered by this License, and distribute
453 such a combined library, provided that the separate distribution
454 of the work based on the Library and of the other library
455 facilities is otherwise permitted, and provided that you do these
456 two things:
457
458 a. Accompany the combined library with a copy of the same work
459 based on the Library, uncombined with any other library
460 facilities. This must be distributed under the terms of the
461 Sections above.
462
463 b. Give prominent notice with the combined library of the fact
464 that part of it is a work based on the Library, and explaining
465 where to find the accompanying uncombined form of the same
466 work.
467
468 8. You may not copy, modify, sublicense, link with, or distribute the
469 Library except as expressly provided under this License. Any
470 attempt otherwise to copy, modify, sublicense, link with, or
471 distribute the Library is void, and will automatically terminate
472 your rights under this License. However, parties who have
473 received copies, or rights, from you under this License will not
474 have their licenses terminated so long as such parties remain in
475 full compliance.
476
477 9. You are not required to accept this License, since you have not
478 signed it. However, nothing else grants you permission to modify
479 or distribute the Library or its derivative works. These actions
480 are prohibited by law if you do not accept this License.
481 Therefore, by modifying or distributing the Library (or any work
482 based on the Library), you indicate your acceptance of this
483 License to do so, and all its terms and conditions for copying,
484 distributing or modifying the Library or works based on it.
485
486 10. Each time you redistribute the Library (or any work based on the
487 Library), the recipient automatically receives a license from the
488 original licensor to copy, distribute, link with or modify the
489 Library subject to these terms and conditions. You may not impose
490 any further restrictions on the recipients' exercise of the rights
491 granted herein. You are not responsible for enforcing compliance
492 by third parties with this License.
493
494 11. If, as a consequence of a court judgment or allegation of patent
495 infringement or for any other reason (not limited to patent
496 issues), conditions are imposed on you (whether by court order,
497 agreement or otherwise) that contradict the conditions of this
498 License, they do not excuse you from the conditions of this
499 License. If you cannot distribute so as to satisfy simultaneously
500 your obligations under this License and any other pertinent
501 obligations, then as a consequence you may not distribute the
502 Library at all. For example, if a patent license would not permit
503 royalty-free redistribution of the Library by all those who
504 receive copies directly or indirectly through you, then the only
505 way you could satisfy both it and this License would be to refrain
506 entirely from distribution of the Library.
507
508 If any portion of this section is held invalid or unenforceable
509 under any particular circumstance, the balance of the section is
510 intended to apply, and the section as a whole is intended to apply
511 in other circumstances.
512
513 It is not the purpose of this section to induce you to infringe any
514 patents or other property right claims or to contest validity of
515 any such claims; this section has the sole purpose of protecting
516 the integrity of the free software distribution system which is
517 implemented by public license practices. Many people have made
518 generous contributions to the wide range of software distributed
519 through that system in reliance on consistent application of that
520 system; it is up to the author/donor to decide if he or she is
521 willing to distribute software through any other system and a
522 licensee cannot impose that choice.
523
524 This section is intended to make thoroughly clear what is believed
525 to be a consequence of the rest of this License.
526
527 12. If the distribution and/or use of the Library is restricted in
528 certain countries either by patents or by copyrighted interfaces,
529 the original copyright holder who places the Library under this
530 License may add an explicit geographical distribution limitation
531 excluding those countries, so that distribution is permitted only
532 in or among countries not thus excluded. In such case, this
533 License incorporates the limitation as if written in the body of
534 this License.
535
536 13. The Free Software Foundation may publish revised and/or new
537 versions of the Lesser General Public License from time to time.
538 Such new versions will be similar in spirit to the present version,
539 but may differ in detail to address new problems or concerns.
540
541 Each version is given a distinguishing version number. If the
542 Library specifies a version number of this License which applies
543 to it and "any later version", you have the option of following
544 the terms and conditions either of that version or of any later
545 version published by the Free Software Foundation. If the Library
546 does not specify a license version number, you may choose any
547 version ever published by the Free Software Foundation.
548
549 14. If you wish to incorporate parts of the Library into other free
550 programs whose distribution conditions are incompatible with these,
551 write to the author to ask for permission. For software which is
552 copyrighted by the Free Software Foundation, write to the Free
553 Software Foundation; we sometimes make exceptions for this. Our
554 decision will be guided by the two goals of preserving the free
555 status of all derivatives of our free software and of promoting
556 the sharing and reuse of software generally.
557
558 NO WARRANTY
559
560 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
561 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE
562 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
563 HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT
564 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
565 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
566 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
567 QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE
568 LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
569 SERVICING, REPAIR OR CORRECTION.
570
571 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
572 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
573 MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
574 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
575 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
576 INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
577 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
578 OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY
579 OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
580 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
581
582 END OF TERMS AND CONDITIONS
583
584 How to Apply These Terms to Your New Programs
585 =============================================
586
587 If you develop a new library, and you want it to be of the greatest
588 possible use to the public, we recommend making it free software that
589 everyone can redistribute and change. You can do so by permitting
590 redistribution under these terms (or, alternatively, under the terms of
591 the ordinary General Public License).
592
593 To apply these terms, attach the following notices to the library.
594 It is safest to attach them to the start of each source file to most
595 effectively convey the exclusion of warranty; and each file should have
596 at least the "copyright" line and a pointer to where the full notice is
597 found.
598
599 ONE LINE TO GIVE THE LIBRARY'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
600 Copyright (C) <year> NAME OF AUTHOR
601
602 This library is free software; you can redistribute it and/or
603 modify it under the terms of the GNU Lesser General Public
604 License as published by the Free Software Foundation; either
605 version 2 of the License, or (at your option) any later version.
606
607 This library is distributed in the hope that it will be useful,
608 but WITHOUT ANY WARRANTY; without even the implied warranty of
609 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
610 Lesser General Public License for more details.
611
612 You should have received a copy of the GNU Lesser General Public
613 License along with this library; if not, write to the Free Software
614 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
615
616 Also add information on how to contact you by electronic and paper
617 mail.
618
619 You should also get your employer (if you work as a programmer) or
620 your school, if any, to sign a "copyright disclaimer" for the library,
621 if necessary. Here is a sample; alter the names:
622
623 Yoyodyne, Inc., hereby disclaims all copyright interest in the
624 library `Frob' (a library for tweaking knobs) written by James
625 Random Hacker.
626
627 <signature of Ty Coon>, 1 April 1990
628 Ty Coon, President of Vice
629
630 That's all there is to it!
631
632 
633 File: geomview, Node: History, Next: Platforms, Prev: Copying, Up: Top
634
635 History of Geomview's Development
636 *********************************
637
638 Geomview was originally written at the Geometry Center at the University
639 of Minnesota in Minneapolis. The Geometry Center was a research and
640 education center funded by the National Science Foundation, with a
641 mission to promote research and communication of mathematics. Much of
642 the work there involved the use of computers to help visualize
643 mathematical concepts.
644
645 The project that eventually led to Geomview began in the summer of
646 1988 with the work of Pat Hanrahan on a viewing program called
647 MinneView. Shortly thereafter Charlie Gunn begin developing OOGL
648 (Object Oriented Graphics Language) in conjunction with MinneView.
649 Many people contributed to OOGL and MinneView, including Stuart Levy,
650 Mark Meuer, Tamara Munzner, Steve Anderson, Mario Lopez, Todd Kaplan.
651
652 In 1991 the staff of the Geometry Center began work on a new improved
653 version of OOGL, and a new and improved viewing program, which they
654 called Geomview. At that time essentially the only game in town for
655 interactive 3D graphics was Silicon Graphics (SGI), so Geomview was
656 developed initially on SGI workstations, using IRIS GL. The first
657 version was finished in January of 1992. It immediately became very
658 popular among visitors to the Geometry Center, and through the Center's
659 ftp archive (this was before the web) people at other institutions began
660 using it too.
661
662 In addition to SGI workstations the Geometry Center had quite a few
663 NeXT stations, so soon after Geomview was running on SGIs the staff
664 developed a version for NeXTStep as well. By this time there were
665 several thousand people using it around the world.
666
667 A few years later the staff ported Geomview to X windows and OpenGL,
668 and eventually, with the demise of NeXT, the NeXT version fell by the
669 wayside.
670
671 In its mission to foster communication among researchers and
672 educators, the Geometry Center developed a web site, www.geom.umn.edu,
673 in late 1993. It was one of the first 300 web sites in existence. A
674 part of the web site was of course devoted to Geomview, and helped to
675 spread the word about its existence.
676
677 The Geometry Center closed its "brick and mortar" facilities in
678 August of 1998 (NSF cut its funding), but the web site continued to
679 exist, and Geomview continued to be very popular around the world. In
680 December of 1999 some of the former Geometry Center staff set up
681 `http://www.geomview.org' as a permanent home on the web for Geomview.
682
683 Geomview's original authors, as well as a number of other volunteers
684 around the world, are still actively involved in using and developing
685 Geomview.
686
687 * Menu:
688
689 * Authors:: Authors.
690
691 
692 File: geomview, Node: Authors, Prev: History, Up: History
693
694 Authors
695 =======
696
697 Tamara Munzner, Stuart Levy, and Mark Phillips are the original authors
698 of Geomview. Celeste Fowler, Charlie Gunn, and Nathaniel Thurston also
699 made significant contributions. Daniel Krech and Scott Wisdom did the
700 NeXTStep and RenderMan port, and Daeron Meyer and Tim Rowley did the
701 port to X windows. Many other Geometry Center staff members, as well
702 as several people elsewhere, also contributed.
703
704 Mark Phillips wrote this manual, with substantial help from Stuart
705 Levy and Tamara Munzner. Countless Geomview users have also been of
706 great help by reading it and pointing out mistakes.
707
708 
709 File: geomview, Node: Platforms, Next: Pronunciation, Prev: History, Up: Top
710
711 Supported Platforms
712 *******************
713
714 Geomview 1.9 should - in principle - compile and run on any fairly
715 recent Unix-like operating system. Specifically, it runs on Linux and on
716 Cygwin (Cygwin emulates a SystemV Unix-like environment under Microsoft
717 Windows). Unluckily Geomview compiles with MacOS X (Darwin), but
718 seemingly communicating with Geomview by means of pipes and sockets
719 cause segmentation faults. Feel free to fix that! *Note Contributing::,
720 for details.
721
722 
723 File: geomview, Node: Pronunciation, Next: Overview, Prev: Platforms, Up: Top
724
725 How to Pronounce "Geomview"
726 ***************************
727
728 The word 'Geomview' is a combination of the first syllable of the word
729 'geometry', and the word 'view'. The authors pronounce it with the
730 accent on the first syllable
731
732 GE-om-view
733
734 Some people put the accent on the second syllable, where it falls in
735 the word 'geometry', but the original authors, who invented the name,
736 prefer the accent-on-first-syllable pronunciation.
737
738 
739 File: geomview, Node: Overview, Next: Tutorial, Prev: Pronunciation, Up: Top
740
741 1 Overview
742 **********
743
744 Geomview's main purpose is to display objects whose geometry is given,
745 allowing interactive control over details such as point of view, speed
746 of movement, appearance of surfaces and lines, and so on. Geomview can
747 handle any number of objects and allows both separate and collective
748 control over them.
749
750 The simplest way to use Geomview is as a stand-alone viewer to see
751 and manipulate objects. It can display objects described in a variety
752 of file formats. It comes with a wide variety of example objects, and
753 you can create your own objects.
754
755 You can also use Geomview to handle the display of data coming from
756 another program that is running simultaneously. As the other program
757 changes the data, the Geomview image reflects the changes. Programs
758 that generate objects and use Geomview to display them are called
759 _external modules_. External modules can control almost all aspects of
760 Geomview. The idea here is that many aspects of the display and
761 interaction parts of geometry software are independent of the geometric
762 content and can be collected together in a single piece of software
763 that can be used in a wide variety of situations. The author of the
764 external module can then concentrate on implementing the desired
765 algorithms and leave the display aspects to Geomview. Geomview comes
766 with a collection of sample external modules, and this manual describes
767 how to write your own.
768
769 Geomview is the product of an effort at the Geometry Center to
770 provide interactive geometry software that is particularly appropriate
771 for mathematics research and education. In particular, Geomview can
772 display things in hyperbolic and spherical space as well as Euclidean
773 space.
774
775 Geomview allows multiple independently controllable objects and
776 cameras. It provides interactive control for motion, appearances
777 (including lighting, shading, and materials), picking on an object,
778 edge or vertex level, snapshots in SGI image file or Renderman RIB
779 format, and adding or deleting objects is provided through direct mouse
780 manipulation, control panels, and keyboard shortcuts.
781
782 Geomview supports the following simple data types: polyhedra with
783 shared vertices (.off), quadrilaterals, rectangular meshes, vectors,
784 and Bezier surface patches of arbitrary degree including rational
785 patches. Object hierarchies can be constructed with lists of objects
786 and instances of object(s) transformed by one or many 4x4 matrices.
787 Arbitrary portions of changing hierarchies may be transmitted by
788 creating named references.
789
790 Geomview can display 3-D graphics output from Mathematica and Maple.
791
792 
793 File: geomview, Node: Tutorial, Next: Interaction, Prev: Overview, Up: Top
794
795 2 Tutorial
796 **********
797
798 This chapter leads you through some of the basics of using Geomview.
799 Work through this chapter in front of a computer where you can try out
800 the examples given here to get a feel for what you can do with Geomview.
801
802 To start Geomview, login to the computer and get a shell window. A
803 shell window is a window in which you can type Unix commands; the prompt
804 in the window usually ends with a '%'. In the shell window (the mouse
805 cursor must be in the window) type the following (`<Enter>' here means
806 hit the "Enter" key):
807
808 geomview tetra dodec <Enter>
809
810 This command starts up Geomview and loads two example objects, a
811 tetrahedron and a dodecahedron. After a few seconds three windows
812 should appear; *note Figure: figinitial.
813
814 Figure 2.1: Initial Geomview display.
815
816 The panel on the left is Geomview's main control panel; it's called
817 the _Main_ panel. The skinny panel in the middle is the _Tools_ panel
818 and is for selecting different kinds of motions. The window on the
819 right is the camera window and in it you see a large tetrahedron and a
820 dodecahedron which is partially obscured by the tetrahedron.
821
822 Geomview has lots of panels but by default it displays only these
823 three. We'll describe some aspects of these and a couple of the others
824 in this tutorial. You can read more about these and other panels in
825 the later chapters of this manual.
826
827 Put the mouse cursor in the camera window and press down and hold the
828 left mouse button. Now, while holding down the button, slowly move the
829 mouse around. You should see the picture rotate in the direction you
830 move the mouse. If you lift up on the mouse button while moving the
831 mouse, the picture continues rotating. To stop it, hold the mouse very
832 still and click down and up on the left mouse button.
833
834 Geomview uses the _glass sphere_ model for mouse-based motion. This
835 means you are supposed to think of the object as being inside an
836 invisible sphere and the mouse cursor is a gripper outside the sphere.
837 When you hold down the left mouse button, the gripper grabs the sphere;
838 when you let go of the button, the gripper releases the sphere. Moving
839 the mouse while holding the button down causes the sphere (and hence
840 the object) to move in the same direction as the mouse.
841
842 In addition to the two solids you should also see two wire-frame
843 boxes in the camera window. These are the "bounding boxes" of the two
844 objects. By default Geomview puts a bounding box around each object
845 that it displays so that you have an idea of how large it is.
846
847 Notice that as you move the mouse around the tetrahedron and
848 dodecahedron move as a unit. That is because by default what you are
849 actually moving is the "World". To move an individual object instead of
850 the whole world, move the mouse cursor to the _Targets_ browser in the
851 _Main_ panel. Click (any button) on the word _tetra_. This makes the
852 tetrahedron be the "target object". Now move the cursor back to the
853 camera window and you can rotate just the tetrahedron.
854
855 The motion that you have been applying up to now has been rotation,
856 because that is the motion mode that is selected in the _Tools_ panel.
857 To translate instead, click on the _Translate_ button. Now when you
858 move the mouse in the camera window while holding down the left button,
859 the tetrahedron (which should still be the target object from before)
860 will translate in the direction you move the mouse. Notice that you
861 can translate it beyond the edge of the window as long as you keep
862 holding the left mouse button down. If you lift up on the mouse button
863 while moving the mouse, the tetrahedron will keep going. It moves
864 rather rapidly so it is very easy to lose track of where it is.
865
866 If you accidentally lose the tetrahedron by translating it too far
867 out of the view of the window, you can get it back by clicking on the
868 _Center_ button in the _Tools_ panel. This causes it to come back to
869 its initial position.
870
871 Click on the _Center_ button to bring the tetrahedron home, and then
872 translate it off to one side so that you can completely see the
873 dodecahedron.
874
875 Your world now has two objects in it that are beside each other. You
876 should see the dodecahedron in the middle of the window and maybe part
877 of the tetrahedron off to one side. Go back to the _Targets_ browser
878 in the _Main_ panel and click on "World" to select the whole world
879 again. Now click on the _Look At_ button in the _Tools_ panel. You
880 should see the dodecahedron and the tetrahedron in the middle of the
881 window next to each other (*note Figure: figlookatworld.). The _Look
882 At_ button positions the camera in such a way that the target object is
883 centered in the window.
884 Figure 2.2: Looking at the world.
885
886 Now put the cursor over the middle of the dodecahedron and
887 double-click the right mouse button. This means click it down-and-up
888 two times in rapid succession. Notice that the dodecahedron becomes
889 the target object; you can see this in the _Targets_ browser in the
890 _Main_ panel. Double-clicking the right mouse button on an object is
891 another way to make it the target object.
892
893 [image src="figs/ap.png"]
894
895 Figure 2.3: The Appearance Panel.
896
897 Go to the _Inspect_ menu at the top of the _Main_ panel and select
898 _Appearance_. This brings up the _Appearance_ panel. When it appears,
899 if it partially obscures another Geomview window you can move it off to
900 one side by dragging its frame with the middle mouse button down.
901
902 The _Appearance_ panel lets you control various things about the way
903 Geomview draws objects. Note the buttons labeled _[af] Faces_ and
904 _[ae] Edges_. Click on the _[ae] Edges_ one, and notice that Geomview
905 is now drawing the edges of the dodecahedron. Click on it again and
906 the edges go away. Click several times and watch the edges come and
907 go. When you've had enough of this, leave the edges on and click the
908 _[af] Faces_ button. This toggles the faces on and off. Click the
909 button again to turn them back on.
910
911 Now click on the _[Cf] Faces_ button under the word _COLOR_. A color
912 chooser panel should appear (*note Figure: figcolorchooser.).
913 Figure 2.4: Color Chooser Panel.
914
915 Note the three sliders, _H_, _S_, and _V_, controlling the color's
916 hue, saturation, and value (lightness). Clicking the _HSV_ button
917 gives a different set of sliders, one each for red, green, and blue.
918 Numerical values for both RGB and HSV color systems can be seen or
919 edited at the bottom of the panel. The dodecahedron's previous colors
920 were specified in the file `dodec' that you loaded when we started
921 Geomview. The color that you specify with the color panel overrides
922 the old colors. You can adjust the intensity of the color with the
923 _Intensity_ slider. When you find a color that you like, click the
924 _Done_ button.
925
926 Now put the cursor somewhere over the gray background and
927 double-click the right mouse button; this picks "World" as the target
928 object. Click the _Look At_ button to look at the world again.
929
930 Notice that in the _Appearance_ panel the settings of the buttons
931 have changed from the way you left them with the dodecahedron. That's
932 because the _Appearance_ panel always displays the settings for the
933 target object, which is now the world, which still has its default
934 settings.
935
936 Click on the _[ab] BBox_ button under the word _Draw_. The bounding
937 boxes go away. Now put the cursor back in the camera window. At the
938 keyboard, type the keys `a 'b. Notice that the bounding boxes come
939 back. `a 'b is the keyboard shortcut for the bounding box toggle
940 button; the string "[ab]" appears on the button to indicate this. Most
941 of Geomview's buttons have keyboard shortcuts that you can use instead
942 if you want. This is useful once you are familiar with Geomview and
943 don't want to have to move around among lots of panels.
944
945 Now select the tetrahedron, either by double-clicking the right mouse
946 button on it, or by selecting "tetra" in the _Targets_ browser. Then
947 click on the _Delete_ button in the _Main_ panel. The tetrahedron
948 should disappear. This is how you get rid of an object.
949
950 You can also load objects from within Geomview. Click on the _File_
951 menu in the _Main_ panel and choose _Open_. The _Files_ panel will
952 appear. Below the middle of this panel is a browser with three lines
953 in it; the second line is a directory with lots of Geomview example
954 files in it. Click on that second line; *note Figure: figfilespanel.
955 Scroll down in the list of files until you see `tref.off'. Click on
956 that line, and then click on the _OK_ button. A large trefoil-shaped
957 tube will appear in your window. Click the _Hide_ button in the
958 _Files_ panel to dismiss the panel.
959
960 Figure 2.5: The Files Panel.
961
962 Now click on the _Reset_ button in the _Tools_ panel. This causes
963 everything to return to its home position. You should see a
964 dodecahedron and a trefoil knot (*note Figure: figtrefdodec.).
965
966 Play around with the trefoil knot and the dodecahedron. Experiment
967 with some of the other buttons in the _Tools_ panel. Try coloring the
968 trefoil knot with the _Appearance_ panel.
969
970 For a tutorial on how to create your own objects to load into
971 Geomview, see file `doc/oogltour' distributed with Geomview. The
972 things in that file will be incorporated into a future version of this
973 manual.
974
975 Figure 2.6: Trefoil and Dodecahedron.
976
977 
978 File: geomview, Node: Interaction, Next: OOGL File Formats, Prev: Tutorial, Up: Top
979
980 3 Interaction
981 *************
982
983 This chapter describes how you interact with Geomview through the mouse
984 and keyboard.
985
986 * Menu:
987
988 * Starting Geomview:: Starting Geomview.
989 * Command Line Options:: Command Line Options.
990 * Basic Interaction:: Basic Interaction: The Main Panel.
991 * Loading:: Loading Objects Into Geomview.
992 * Mouse Motions:: Using the Mouse to Manipulate Objects.
993 * Appearance:: Changing the Way Things Look.
994 * Cameras:: Cameras.
995 * Saving:: Saving your work.
996 * Commands:: The Commands Panel.
997 * Keyboard Shortcuts:: Keyboard Shortcuts.
998
999 
1000 File: geomview, Node: Starting Geomview, Next: Command Line Options, Prev: Interaction, Up: Interaction
1001
1002 3.1 Starting Geomview
1003 =====================
1004
1005 The usual way to start Geomview is to type `geomview <Enter>' in a shell
1006 window (<Enter> means hit the "Enter" key). It may take Geomview a few
1007 seconds to start up; one or more windows will appear and you can begin
1008 interacting with Geomview immediately.
1009
1010 It is also possible to specify actions for Geomview to perform at
1011 startup time by giving arguments in the shell command line. *Note
1012 Command Line Options::.
1013
1014 
1015 File: geomview, Node: Command Line Options, Next: Basic Interaction, Prev: Starting Geomview, Up: Interaction
1016
1017 3.2 Command Line Options
1018 ========================
1019
1020 Here are the command line options that Geomview allows:
1021
1022 `-b R G b'
1023 Set the window background color to the given R G b values.
1024
1025 `-c FILE'
1026 Interpret the GCL commands in FILE, which may be the special
1027 symbol `-' for standard input. For a description of GCL, *Note
1028 GCL::.
1029
1030 `-c COMMAND'
1031 Commands may also be supplied literally, as in
1032 -c "(ui-panel main off)"
1033 Since COMMAND includes parentheses, which have special meaning to
1034 the shell, COMMAND must be quoted. Multiple -C options are
1035 allowed.
1036
1037 `-wins NWINS'
1038 Causes Geomview to initially display NWINS camera windows.
1039
1040 `-wpos WIDTH,HEIGHT[@XMIN,YMIN]'
1041 Specifies the initial location and size of the first camera
1042 window. The values for WIDTH, HEIGHT, XMIN, and YMIN are in
1043 screen (pixel) coordinates.
1044
1045 `-M[cg][ps[un|in|in6]] PIPENAME|TCPPORT'
1046 The `-M' option accepts modifiers: a `g' suffix expects geometry
1047 data (the default), while a `c' suffix expects GCL commands. A `p'
1048 implies the connection should use a named pipe (the default on
1049 everything except on the NeXT), while `s' implies using a
1050 UNIX-domain socket (the default on the NeXT). Since version 1.9 of
1051 Geomview Internet domain sockets are also supported; use `sin' to
1052 make Geomview listen on the IPv4 port given by TCPPORT, or use
1053 `sin6' to make Geomview listen on an IPv6 port (also as specified
1054 by TCPPORT). `sun' is a synonym for `s', i.e. use the Unix domain
1055 socket with the name PIPENAME. If PIPENAME starts with a slash
1056 ('/'), then it is assumed to be an absolute pathname, otherwise
1057 the named pipe or socket is created below `${TMPDIR}/geomview/'.
1058
1059 Listening to command streams on TCP ports can be a security risk,
1060 as Geomview itself does not take any security precautions, it
1061 simply executes all commands fed to it through the network socket.
1062 This also implies that disk-io can be initiated remotely.
1063
1064 Examples:
1065 `-M OBJECTNAME'
1066 Display (possibly dynamically changing) geometry sent from the
1067 programs `geomstuff' or `togeomview'. This actually listens
1068 to the named pipe `/tmp/geomview/objectname'; you can achieve
1069 the same effect with the shell commands:
1070 mkdir /tmp/geomview
1071 mknod /tmp/geomview/objectname p
1072 (assuming the directory and named pipe don't already exist),
1073 then executing the GCL command:
1074 (geometry objectname < /tmp/geomview/objectname)
1075 (*note `(geometry ...)': geometry.)
1076
1077 `-Mc PIPENAME'
1078 Like `-M' above, but expects GCL commands, rather than OOGL
1079 geometry data, on the connection.
1080
1081 `-Mcs fred'
1082 Read commands from the UNIX-domain socket named.
1083 `/tmp/geomview/fred'
1084
1085 `-Mcsin 40000'
1086 Read commands from the IPv4 port `40000'. Geomview itself
1087 does not take any security precautions, so this can be a
1088 security risk.
1089
1090 `-noopengl'
1091 Disable the use of OpenGL for (possibly) hardware accelerated
1092 rendering, even if the Geomview binary has support for OpenGL
1093 compiled in. This also disables the support for transparency and
1094 textures in the camera windows. RenderMan snapshots still will
1095 have correct transparency and some limited texture support.
1096
1097 `-nopanels'
1098 Start up displaying no panels, only graphics windows. Panels may
1099 be invoked later as usual with the `Px' keyboard shortcuts or with
1100 the `ui-panel' command. *Note `(ui-panel ...)': ui-panel.
1101
1102 `-noinit'
1103 Read no initialization files. By default, geomview reads the
1104 system-wide `.geomview' file, followed by those in
1105 `${HOME}/.geomview' and `./.geomview'.
1106
1107 `-e MODULE'
1108 Start an external module; MODULE is the name associated with the
1109 module, appearing in the main panel's Applications browser, as
1110 defined by the `emodule-define' command. *Note `(emodule-define
1111 ...)': emodule-define.
1112
1113 `-start MODULE ARGS ...'
1114 Like -e but allows you to pass arguments to the external module.
1115 "-" signals the end of the argument list; the "-" may be omitted
1116 if it would be the last argument on the Geomview command line.
1117
1118 `-run SHELL-COMMAND ARGS ...'
1119 Like -start but takes the pathname of executable of the external
1120 module instead of the module's name. The pathnames of all known
1121 module directories are appended to the UNIX search path when
1122 invoking SHELL-COMMAND.
1123
1124
1125 
1126 File: geomview, Node: Basic Interaction, Next: Loading, Prev: Command Line Options, Up: Interaction
1127
1128 3.3 Basic Interaction: The Main Panel
1129 =====================================
1130
1131 Normally when you invoke Geomview, three windows appear: the _Main_
1132 panel, the _Tools_ panel, and one camera window. Geomview has many
1133 other windows but most things can be done with these three and so by
1134 default the others do not appear. This section of the manual
1135 introduces some basic concepts that are used throughout the rest of the
1136 manual and describes the _Main_ panel.
1137 Figure 3.1: The Main Panel
1138
1139 Geomview can display an arbitrary number of objects simultaneously.
1140 The _Targets_ browser in the _Main_ panel displays a list of all the
1141 objects that Geomview currently knows about. This browser has a line
1142 for each object that you have loaded, plus some lines for other
1143 objects. One of the other objects is called `World' and corresponds to
1144 the all the currently loaded objects, treated as if they were one
1145 object. Most of the operations that you can do to one object, such as
1146 applying a motion or changing a color, can also be done to the "World"
1147 object.
1148
1149 The _Targets_ browser also has an entry for each camera. By default
1150 there is only one camera; it is possible to add more of them via the
1151 _New Camera_ entry of the _Main_ panel's _File_ menu. Geomview treats
1152 cameras in much the same way as it does geometric objects. For
1153 example, you can move cameras around and add them and delete them just
1154 as with geometric objects. Cameras do not usually show up in the
1155 display as an object that you see. Each camera has a separate camera
1156 window which displays the view as seen by that camera. (It is possible
1157 for each camera to display a geometric representation of other cameras.
1158 *Note Cameras::.)
1159
1160 Because Geomview treats cameras and geometric objects very similarly,
1161 the term "object" in this documentation is used to refer to either one.
1162 When we need to distinguish between the two kinds of objects, we use
1163 the term "geom" to denote a geometric object and the word "camera" to
1164 denote a camera.
1165
1166 The object which is selected (highlighted) in the _Targets_ browser
1167 is called the "target" object. This is the object that receives any
1168 actions that you do with the mouse or keyboard. You can change the
1169 target object by selecting a different line in the _Targets_ browser.
1170 Another way to change the target object is to put the mouse cursor
1171 directly over a geometry in a camera window and rapidly double-click
1172 the right mouse button. This process is called "picking"; the picked
1173 object becomes the new target.
1174
1175 Geomview objects are all known by two names, both of which are shown
1176 in the _Targets_ browser. The first name given there, which appears in
1177 square brackets ([ ]), is a short name assigned by Geomview when you
1178 load the object. It consists of the letter `g' for geometries and `c'
1179 for cameras, followed by a number. The second name is a longer more
1180 descriptive name; by default this is the name of the file that the
1181 object was loaded from. The two names are equivalent as far as Geomview
1182 is concerned; at any point where you need to specify a name you can give
1183 either one.
1184
1185 To manipulate an object, make sure you that the object you want to
1186 move is the target object, and put the mouse cursor in a camera window.
1187 Motions are applied by holding down either the left or middle mouse
1188 button and moving the mouse. There are several different motion
1189 "modes", each for applying a different kind of motion. The _MOTION
1190 MODE_ browser in the _Main_ panel indicates the current motion mode.
1191 The default is "Rotate". You can change the current motion mode by
1192 selecting a new one in the _MOTION MODE_ browser, or by using the
1193 _Tools_ panel. For more information about motion modes, *Note Mouse
1194 Motions::.
1195
1196 The _Modules_ browser lists Geomview external modules. An external
1197 module is a separate program that interacts with Geomview to extend its
1198 functionality. For information on external modules, *Note Modules::.
1199
1200 The menu bar at the top of the main panel offers menus for common
1201 operations.
1202
1203 To create new windows, load new objects, save objects or other
1204 information, or quit from geomview, see the _File_ menu.
1205
1206 To copy or delete objects, see the _Edit_ menu.
1207
1208 You can invoke any panel from the _Inspect_ menu.
1209
1210 The _Space_ menu lets you choose whether geomview operates in
1211 Euclidean, Hyperbolic, or Spherical mode. Euclidean mode is selected
1212 by default. For details about using _Hyperbolic_ and _Spherical_
1213 spaces, *Note Non-Euclidean Geometry::.
1214
1215 Most actions that you can do through Geomview's panels have
1216 equivalent keyboard shortcuts so that you can do the same action by
1217 typing a sequence of keys on the keyboard. This is useful for advanced
1218 users who are familiar with Geomview's capabilities and want to work
1219 quickly without having to have lots of panels cluttering up the screen.
1220 Keyboard shortcuts are usually indicated in square brackets ([ ]) near
1221 the corresponding item in a panel. For example, the keyboard shortcut
1222 for _Rotate_ mode is 'r'; this is indicated by "[r]" appearing before
1223 the word "Rotate" in the _MOTION MODE_ browser. To use this keyboard
1224 shortcut, just hit the `r' key while the mouse cursor is in any
1225 Geomview window. Do not hit the `<Enter>' key afterwards.
1226
1227 Some keyboard shortcuts consist of more than one key. In these cases
1228 just type the keys one after the other, with no `<Enter>' afterwards.
1229 Keyboard shortcuts are case sensitive.
1230
1231 Many keyboard shortcuts can be preceded by a numeric parameter. For
1232 example, typing `ae' toggles the state of drawing edges, while `1ae'
1233 always enables edge drawing.
1234
1235 The _keyboard_ field in the upper left corner of the _Main_ panel
1236 echos the current state of keyboard shortcuts.
1237
1238 For a list of all keyboard shortcuts, press the _`?'_ key.
1239
1240 
1241 File: geomview, Node: Loading, Next: Mouse Motions, Prev: Basic Interaction, Up: Interaction
1242
1243 3.4 Loading Objects Into Geomview
1244 =================================
1245
1246 There are several ways to load an object into Geomview.
1247
1248 the _Files_ panel
1249 If you click the _Load_ button in Geomview's _Main_ panel, the
1250 _Files_ panel will appear.
1251
1252 Figure 3.2: The Files Panel.
1253
1254 This panel lets you select a file from a variety of directories.
1255 The top of the panel is a standard Motif file browser. Below this
1256 is a list of directories on Geomview's standard search path; click
1257 on one of these to browse files in that directory.
1258
1259 To select a file, double-click on its name in the browser at
1260 upper right, or click on its name and press the <Enter> key, or
1261 type the file's name into the text box at the bottom of the
1262 browser and press <Enter>.
1263
1264 If the selected file contains OOGL geometric data, it will be
1265 added to the geomview _Targets_ browser. If it contains GCL
1266 commands instead, the file will be interpreted. *Note GCL::.
1267
1268 When the _Files_ panel first appears, the directory selected in
1269 the directory browser is the current directory -- the one from
1270 which you invoked Geomview. The file browser shows _all_ the
1271 files in this directory, including ones that are not Geomview
1272 files. If you try to load a file that doesn't contain either an
1273 OOGL object or Geomview commands, Geomview will print out an error
1274 message.
1275
1276 The directory browser also lists a second and third directory in
1277 addition to the current directory. The second one, which ends in
1278 `data/geom', is the Geomview example data directory. This contains
1279 a wide variety of sample objects. It also contains several
1280 subdirectories. In particular, the `hyperbolic' and `spherical'
1281 subdirectories have sample hyperbolic and spherical objects,
1282 respectively. Directory entries in the browser look just like
1283 file entries; to view a subdirectory, click on it.
1284
1285 The third directory shown in the directory browser, which ends
1286 in `geom', contains several subdirectories with other Geomview
1287 files in them. These are used less frequently than the ones in the
1288 `data/geom' directory.
1289
1290 You can change the list of directories shown the _Files_
1291 panel's directory browser by using the `set-load-path' command;
1292 *note `(set-load-path ...)': set-load-path.
1293
1294 the `<' keyboard shortcut:
1295 If you type `<' in any Geomview window, the _Load_ panel will
1296 appear. This is a small version of the _Files_ panel; it contains
1297 a text field in which you can enter the name of a file to load (or
1298 a GCL command surrounded by parentheses). After typing the name
1299 of the file to load, type `<Enter>'; Geomview will load the file
1300 as if you had loaded it with the _Add_ button in the _Files_
1301 panel. If, after bringing up the small load panel with `<', you
1302 decide you want to use the larger _Files_ panel after all, press
1303 the _File Browser_ button.
1304 Figure 3.3: The Load Panel.
1305
1306 geometry loading commands:
1307 The `load', `geometry', `new-geometry', and `read' GCL commands
1308 allow you to load an object into Geomview; *Note GCL::. *Note
1309 `(load ...)': load. *Note `(new-geometry ...)': new-geometry.
1310 *Note `(read ...)': read.
1311
1312
1313 
1314 File: geomview, Node: Mouse Motions, Next: Appearance, Prev: Loading, Up: Interaction
1315
1316 3.5 Using the Mouse to Manipulate Objects
1317 =========================================
1318
1319 Geomview lets you manipulate objects with the mouse. There are six
1320 different mouse motion modes: _Rotate_, _Translate_, _Cam Fly_, _Cam
1321 Zoom_, _Geom Scale_, and _Cam Orbit_. The tools panel has a button for
1322 each of these modes; to switch modes, click on the corresponding
1323 button. You can also select these through the _Motion Mode_ browser on
1324 the _Main_ panel.
1325
1326 This section describes basic mouse interaction. For details, *note
1327 Commands::.
1328
1329 Figure 3.4: The Tools Panel.
1330
1331 Each of the motion modes uses a common paradigm for how the motion is
1332 applied. In particular, each depends on the current _target_ object
1333 and the current _center_ object. These are explained in the following
1334 paragraphs.
1335
1336 The current target object is shown in the _Target_ field in the
1337 _Tools_ panel. This is the same as the selected object in the
1338 _Targets_ browser in the _Main_ panel, and you can change it by either
1339 selecting a new object in the browser, by typing a new entry in the
1340 field, or by picking an object in a camera window by double-clicking
1341 the right mouse button with the cursor over the object.
1342
1343 The current center object is shown in the _Center_ field in the
1344 _Tools_ panel. Its default value is the special word "target", which
1345 means that the center object is whatever the target object is. You can
1346 change the center to any object by typing it in the _Center_ field.
1347 The origin of the center object is held fixed in _Rotate_ and _Orbit_
1348 modes. Normally the center object is one of the existing geoms listed
1349 in the _Targets_ browser, and the actual center of rotations is the
1350 origin of that object's coordinate system. It is possible, however, to
1351 select an arbitrary point of interest on an object as the center. For
1352 details, *note Point of Interest::.
1353
1354 It is also possible to toggle the button _BBox Center_ to set the
1355 center of motion to the center of the current object's bounding box.
1356 Once toggled, the active geometry's bounding box center will become the
1357 center of motion. If you select another object, then the center of
1358 motion will become the center of that object's bounding box. Nothing
1359 changes when a camera or the _World_ is selected; you have to type in
1360 the word `target' in the _Center_ field to reset to the default.
1361
1362 You apply a mouse motion by holding down either the left or middle
1363 mouse button with the cursor in a camera window and moving the mouse.
1364 Most of the modes have _inertia_, which means that if you let go of the
1365 button while moving the mouse, the motion will continue. It may be
1366 helpful to imagine the mouse cursor as being a gripper; when you hold a
1367 mouse button down, it grips the target object and you can move it. When
1368 you let go of the mouse button, the gripper releases the object.
1369 Letting go of the mouse button while moving the mouse is like throwing
1370 the object -- the object continues moving independent of the mouse.
1371 Inertia can be turned off; see the _Main_ panel's _Motion_ menu,
1372 described below.
1373
1374 Generally, the left mouse button controls motion in the screen plane,
1375 while the middle mouse controls motion along or around the forward
1376 direction.
1377
1378 Pressing the shift key while dragging with left or middle mouse
1379 buttons in most motion modes gives slow-speed motions, useful for fine
1380 adjustment.
1381
1382 You can pick any point on an object (not just its origin) as the
1383 center of motion by holding down the shift key while clicking the right
1384 mouse button; this chooses a point of interest.
1385
1386 _Rotate_
1387 In _Rotate_ mode, hold the left mouse button down to rotate the
1388 target object about the center object. Rotation proceeds in the
1389 direction that you move the mouse. Specifically, the axis of
1390 rotation passes through the origin of the center object, is
1391 parallel to the camera view plane, and is perpendicular to the
1392 direction of motion of the mouse. When the center is "target",
1393 this means that the target object rotates about its own origin.
1394
1395 The middle mouse button in _Rotate_ mode rotates the target object
1396 about an axis perpendicular to the view plane.
1397
1398 _Translate_
1399 In _Translate_ mode, hold the left mouse button down to translate
1400 the target object in the direction of mouse motion. The middle
1401 mouse button translates the target along an axis perpendicular to
1402 the view plane.
1403
1404 In Euclidean space, the center object is essentially irrelevant for
1405 translations. In hyperbolic and spherical spaces, where
1406 translations have a unique axis, this axis is chosen to go through
1407 the origin of the center object.
1408
1409 _Cam Fly_
1410 _Cam Fly_ is a crude flight simulator that lets you fly around the
1411 scene. It works by moving the camera. Move the mouse while
1412 holding the left mouse button down to point the camera in a
1413 different direction. To move forward or backward, hold down the
1414 middle button and move the mouse vertically. Both of these
1415 motions have inertia; typically the easiest way to fly around a
1416 scene is to give the camera a slight forward push by letting go of
1417 the middle button while moving the mouse upward, and then using
1418 the left button to steer.
1419
1420 _Cam Fly_ affects the camera window that the mouse is in; it
1421 ignores the target object and the center object.
1422
1423 _Cam Orbit_
1424 _Cam Orbit_ mode lets you rotate the current camera around the
1425 current center. The left mouse button does this rotation. The
1426 middle mouse button in _Cam Orbit_ mode acts as in _Cam Fly_ mode:
1427 it moves the camera forward or backward.
1428
1429 In general _Cam Orbit_ does not move the target object, although
1430 if the current camera is selected as the target and the center is
1431 also the target, it will pivot that camera about itself just as in
1432 _Cam Fly_ mode.
1433
1434 _Cam Zoom_
1435 _Cam Zoom_ mode lets you change the current camera's field of view
1436 with the mouse; hold the left mouse button down and move the mouse
1437 to change it. The numeric value of the field of view is shown in
1438 the _FOV_ field in the _Camera_ panel.
1439
1440 _Geom Scale_
1441 _Geom Scale_ mode lets you enlarge or shrink a geom. It operates
1442 on the target object if that object is a geom. If the target is a
1443 camera, _Geom Scale_ operates on the geom that was most recently
1444 the target object. Moving the mouse while holding down the left
1445 mouse button scales the object either up or down, depending on the
1446 direction of mouse motion. The center of the applied scaling
1447 transformation is the center object.
1448
1449 Scaling is meaningful only in Euclidean space; attempts to scale
1450 are ignored in other spaces.
1451
1452 _Geom Scale_ mode does not have inertia.
1453
1454
1455 The _Stop_, _Look At_, _Center_, and _Reset_ buttons on the _Tools_
1456 panel perform actions related to motions but do not change the current
1457 motion mode.
1458
1459 _Stop_
1460 The _Stop_ button causes all motions to stop. It affects all
1461 moving objects, not just the target object. Its keyboard shortcut
1462 is `H'.
1463
1464 The keyboard command `h', which does not correspond to a panel
1465 button, stops the current motion for the target object only.
1466
1467 _Look At_
1468 The _Look At_ button causes the current camera to be moved to a
1469 position such that it is looking at the target object, and such
1470 that the target object more or less fills the window.
1471
1472 The Look At command is unreliable in non-Euclidean spaces.
1473
1474 _Center_
1475 The _Center_ button undoes the target object's transformation,
1476 moving it back to its home position, which is where it was when you
1477 originally loaded it into Geomview.
1478
1479 _Reset_
1480 The _Reset_ button stops all motion and causes all objects to move
1481 back to their home positions.
1482
1483
1484 The _Tools_ panel also sports a _Main_ button, to invoke the main
1485 panel in case it was dismissed or buried, and a _Done_ button to close
1486 the _Tools_ panel.
1487
1488 The _Main_ panel's _Motion_ menu has special controls affecting how
1489 mouse motions are interpreted; the toggles are also accessible through
1490 a GCL command. *Note `(ui-motion ...)': ui-motion.
1491
1492 _[ui] Inertia_
1493 Normally, moving objects have inertia: if the mouse is still moving
1494 when the button is released, the selected object continues to move.
1495 When _Inertia_ is off, objects cease to move as soon as you release
1496 the mouse.
1497
1498 _[uc] Constrain Motion_
1499 It's sometimes handy to move an object in a direction aligned with
1500 a coordinate axis: exactly horizontally or vertically. Selecting
1501 _Constrain Motion_ changes the interpretation of mouse motions to
1502 allow this; approximately-horizontal or approximately-vertical
1503 mouse dragging becomes exactly horizontal or vertical motion.
1504 Note that the motion is still along the X or Y axes of the camera
1505 in which you move the mouse, not necessarily the object's own
1506 coordinate system.
1507
1508 _[uo] Own Coordinates_
1509 It's sometimes handy to move objects with respect to the
1510 coordinate system where they were defined, rather than with
1511 respect to some camera's view. While _Own Coordinates_ is
1512 selected, all motions are interpreted that way: dragging the mouse
1513 rightward in translate mode moves the object in its own +X
1514 direction, and so on. May be especially useful in conjunction with
1515 the _Constrain Motion_ button.
1516
1517
1518 * Menu:
1519
1520 * Point of Interest:: Point of Interest.
1521
1522 
1523 File: geomview, Node: Point of Interest, Prev: Mouse Motions, Up: Mouse Motions
1524
1525 3.5.1 Selecting a Point of Interest
1526 -----------------------------------
1527
1528 It is sometimes useful to specify a particular point on some object in a
1529 geomview window as the center point for mouse motions. You can do this
1530 by shift-clicking the right mouse button (i.e. click it once while
1531 holding down the shift key on the keyboard) with the cursor over the
1532 desired point. This point then becomes the _point of interest_. The
1533 point of interest must be on an existing object.
1534
1535 Selecting a point of interest simplifies examining a small portion
1536 of a larger object. Shift-right-click on an interesting point, and
1537 select _Orbit_ mode. Use the middle mouse button to approach, and the
1538 left mouse to orbit the point, examining the region from different
1539 directions.
1540
1541 When you have selected a point of interest, the current center object
1542 changes to an object named "CENTER", which is an invisible object
1543 located at the point of interest. In addition, mouse motions for the
1544 window in which you made the selection are adjusted so that the point of
1545 interest follows the mouse.
1546
1547 You can change the point of interest at any time by selecting a new
1548 one by shift-clicking the right mouse button again. You can cancel the
1549 point of interest altogether by shift-clicking the right mouse button
1550 with the cursor on the background (i.e. not on any object). This
1551 changes the center object back to its default value, "target".
1552
1553 The object named "CENTER", which serves as the center object for the
1554 point of interest, is a special kind of geom called an "alien". It does
1555 not appear in the _Targets_ browser. By default it has no geometry
1556 associated with it and hence is invisible. You can, however, explicitly
1557 give it some geometry using a GCL command, causing it to appear. Use
1558 the `geometry' command for this: `(geometry CENTER GEOMETRY)', where
1559 GEOMETRY is any valid geometry. For example, `(geometry CENTER { <
1560 xyz.vect })' causes the file `xyz.vect', which is one of the standard
1561 example files distributed with geomview, to be used at the geometry for
1562 CENTER. *Note `(geometry ...)': geometry.
1563
1564 What happens internally when you select a point of interest is that
1565 the center is set to the object called CENTER, and that object is
1566 positioned at the point of interest. In addition, in order for mouse
1567 motions to track the point of interest, the current camera's focal
1568 length is set to be the distance from the camera to the point of
1569 interest. You can accomplish this via GCL with the following commands:
1570 (if (real-id CENTER) nil (new-alien CENTER {}))
1571 (ui-center CENTER)
1572 (transform-set CENTER universe universe translate X Y Z)
1573 (merge camera CAM-ID { focus D })
1574 where `(X,Y,Z)' are the (universe) coordinates of the point of
1575 interest, and D is the distance from that point to the current camera,
1576 CAM-ID. The first command above creates the "alien" CENTER if it does
1577 not yet exist.
1578
1579 
1580 File: geomview, Node: Appearance, Next: Cameras, Prev: Mouse Motions, Up: Interaction
1581
1582 3.6 Changing the Way Things Look
1583 ================================
1584
1585 Geomview uses a hierarchy of appearances to control the way things look.
1586 An "appearance" is a specification of information about how something
1587 should be drawn. This can include many things such things as color,
1588 lighting, material properties, and more. Appearances work in a
1589 hierarchal manner: if a certain appearance property, for example face
1590 color, is not specified in a particular object's appearance, that object
1591 is drawn using that property from the parent appearance. If both the
1592 parent and the child appearance specify a property, the child's setting
1593 takes precedence unless the parent appearance is set to override.
1594
1595 Every geom in Geomview has an appearance associated with it. There
1596 is also an appearance associated with the "World" geom, which serves as
1597 the parent of each individual geom's appearance. Finally, there is a
1598 global "base" appearance, which is the parent of the World appearance.
1599
1600 The base appearance specifies reasonable values for all appearance
1601 information, and by default none of the other appearances specify
1602 anything, which means they inherit their values from the base
1603 appearance. This means that by default all objects are drawn using the
1604 base appearance.
1605
1606 If you change a certain appearance property for a geom, that property
1607 is used in drawing that geom. The parent appearance is used for any
1608 properties that you do not explicitly set.
1609
1610 Geomview has three panels which let you modify appearances.
1611
1612 * Menu:
1613
1614 * Appearance Panel:: Color etc.
1615 * Materials Panel:: Surface Material properties.
1616 * Lighting Panel:: Lighting Parameters.
1617
1618 
1619 File: geomview, Node: Appearance Panel, Next: Materials Panel, Prev: Appearance, Up: Appearance
1620
1621 3.6.1 The Appearance Panel
1622 --------------------------
1623
1624 The _Appearance_ panel lets you change most common appearance
1625 properties of the target object.
1626 [image src="figs/ap.png"]
1627
1628 Figure 3.5: The Appearance Panel.
1629
1630 If the target is an individual geom, then changes you make in the
1631 appearance panel apply to that geometry's appearance. If the target is
1632 the World, then appearance panel changes apply to the World appearance
1633 _and_ to all individual geom appearances. (Users have found that this
1634 is more desirable than having the changes only apply to the World
1635 appearance.) If the target is a camera, then appearance panel changes
1636 apply to the geom that was most recently the target.
1637
1638 The five buttons near the upper left corner under the word _Show_
1639 control what parts of the target geom are drawn.
1640
1641 _Faces_
1642 This button specifies whether faces are drawn.
1643
1644 _Edges_
1645 This button specifies whether edges are drawn.
1646
1647 _BBox_
1648 This button specifies whether the bounding box is drawn.
1649
1650 _Vects_
1651 This button specifies whether VECT objects are drawn. VECTs are a
1652 type of OOGL object that represent points and line segments in
1653 3-space; they are distinct from edges of other kinds of objects,
1654 and it is sometimes desirable to have separate control over
1655 whether they are drawn.
1656
1657 _Normals_
1658 This button specifies whether surface normal vectors are drawn.
1659
1660
1661 The four buttons under _Color_ labeled _Faces_, _Edges_, _Normals_,
1662 and _BBox_ let you specify the color of the corresponding aspect of the
1663 target geom. Clicking on one of them brings up a color chooser panel.
1664 Figure 3.6: Color Chooser Panel.
1665
1666 This panel offers two sets of sliders: H(ue) S(aturation) V(alue), or
1667 R(ed) G(reen) B(lue), each in the range 0 through 1. The square shows
1668 the current color, which is given numerically in both HSV and RGB
1669 systems in the corresponding text boxes.
1670
1671 In the HSV color system, hue H runs from red at 0, green at .333,
1672 blue at .667, and back to red at 1.0. Saturation gives the fraction of
1673 white mixed into the color, from 0 for pure gray to 1 for pure color.
1674 Value gives the brightness, from 0 for black to 1 for full brightness.
1675
1676 Pressing the _RGB_ or _HSV_ button at top center switches the
1677 sliders to the other color system. You can adjust colors either via
1678 the sliders, or by typing in either the RGB or HSV text boxes.
1679
1680 Click _OK_ to accept the color that you have chosen, or _Cancel_ to
1681 retain the previous color setting.
1682
1683 The _SHADING_ browser lets you specify the shading model that
1684 Geomview uses to paint the target geom.
1685
1686 `Constant'
1687 Every face of the object is drawn with a constant color which does
1688 not depend on the location of the face, the camera, or the light
1689 sources. If the object does not contain per-face or per-vertex
1690 colors, the diffuse color of the object's appearance is used. If
1691 the object contains per-face colors, they are used. If the object
1692 contains per-vertex colors, each face is painted using the color
1693 of its first vertex.
1694
1695 `Flat'
1696 Each face of the object is drawn with a color that depends on the
1697 relative location of the face, the camera, and the light sources.
1698 The color is constant across the face but may change as the face,
1699 camera, or lights move.
1700
1701 `Smooth'
1702 Each face of the object is drawn with smoothly interpolated colors
1703 based on the normal vectors at each vertex. If the object does
1704 not contain per-vertex normals, this has the same effect as flat
1705 shading. If the object has reasonable per-vertex normals, the
1706 effect is to smooth over the edges between the faces.
1707
1708 `CSmooth'
1709 Each face of the object is drawn with exactly the specified
1710 color(s), independent of lighting, orientation, and material
1711 properties. If the object is defined with per-vertex colors, the
1712 colors are interpolated smoothly across the face; otherwise the
1713 effect is the same as in Constant shading style.
1714
1715 `VCflat'
1716 A combination of `CSmooth' and `Flat' shading. So the shading is
1717 constant on each face, depending on the relative orientation of the
1718 light sources, the camera and the surface normal of the face.
1719
1720
1721 The _Facing Normals_ button on the _Appearance_ panel indicates
1722 whether or not Geomview should arrange that normal vectors always face
1723 the viewer. If a normal vector points away from the viewer the color
1724 of the corresponding face or vertex usually is darker than is desired.
1725 Geomview can avoid this by using the opposite normal in shading
1726 calculations. This is the default. Using _Facing Normals_ can give
1727 strange flickering dark or light shading effects, though, near the
1728 horizon of a fairly smooth facetted object. Press this button to use
1729 the normals given with the object.
1730
1731 The three text fields in the lower left corner of the _Appearance_
1732 panel are:
1733
1734 _Line Width_
1735 The width, in pixels, for lines drawn by Geomview.
1736
1737 _Normal Length_
1738 This is actually a scale factor; when normal vectors are drawn,
1739 Geomview draws them to have a length that is their natural length
1740 times this number.
1741
1742 _Patch Dicing_
1743 Geomview draws Bezier patches by first converting them to meshes.
1744 This parameter specifies the resolution of the mesh: if _Patch
1745 Dicing_ is N, then an N by N mesh is used to draw each Bezier
1746 patch. if _Patch Dicing_ is 1, the resolution reverts to a
1747 built-in default value.
1748
1749
1750 The _Revert_ button on the _Appearance_ panel undoes all settings in
1751 the target appearance. This causes the target geom to inherit all its
1752 appearance properties from its parent.
1753
1754 The _Appearance_ panel's _Override_ button determines whether
1755 appearance controls should override settings in the objects themselves -
1756 for example, setting the face color will affect all faces of objects
1757 with multi-colored facets. Otherwise, appearance controls only provide
1758 settings which the objects themselves do not specify. By default,
1759 _Override_ is enabled. This button applies to all objects, and to all
1760 appearance-related panels.
1761
1762 Normalization is a kind of scaling; Geomview can scale an object so
1763 that it fits within a certain region. The main point of normalization
1764 is to allow you to easily view all of an object without having to worry
1765 about how big it is. We are gradually replacing Geomview's
1766 normalization feature with more robust camera positioning features. In
1767 general, the best way to make sure you are seeing all of an object is
1768 to use the _Look At_ button on the _Tools_ panel. Normalization may be
1769 completely replaced by this and other features in a future version of
1770 Geomview.
1771
1772 Normalization is a property that applies to each geom separately.
1773 The _NORMALIZE GEOMETRY_ browser affects the normalization property of
1774 target geom. If the target geom is "World", it affects all geoms.
1775
1776 _None_
1777 Do no normalization.
1778
1779 _Individual_
1780 Normalize this geom to fit within a unit sphere.
1781
1782 _Sequence_
1783 This resembles "Individual", except when an object is changing.
1784 Then, "Individual" tightly fits the bounding box around the object
1785 whenever it changes and normalizes accordingly, while "Sequence"
1786 normalizes the union of all variants of the object and normalizes
1787 accordingly.
1788
1789 _Keep_
1790 This leaves the current normalization transform unchanged when the
1791 object changes. It may be useful to apply "Individual" or
1792 "Sequence" normalization to the first version of a changing object
1793 to bring it in view, then switch to "Keep".
1794
1795
1796 
1797 File: geomview, Node: Materials Panel, Next: Lighting Panel, Prev: Appearance Panel, Up: Appearance
1798
1799 3.6.2 The Materials Panel
1800 -------------------------
1801
1802 The _Materials_ panel controls material properties of surfaces. It
1803 works with the target object in the same way that the _Appearance_
1804 panel does.
1805 Figure 3.7: The Materials Panel.
1806
1807 _Translucent_
1808 This button determines whether translucency is enabled. Geomview
1809 supports three different flavours of translucency:
1810
1811 _Alpha-blending with BSP-tree depth-sorting_
1812 This is the most accurate flavour for online viewing, but
1813 consumes vast amounts of computation time and memory. In this
1814 mode single translucent objects are displayed correctly with
1815 respect to themselves; however multiple translucent objects
1816 may appear in the wrong order on the screen. The notion
1817 _object_ means here: top-level geometries as displayed in the
1818 geometry target browser.
1819
1820 _Screen Door Translucency_
1821 If the machine support OpenGL then there is support for
1822 kind-of translucency by masking out (completely) transparent
1823 pixels by means of a stipple mask. This is currently very
1824 experimental, and the result is somewhat ugly, but fast.
1825
1826 _Alphe-blending without depth-sorting_
1827 This is the old naive way of doing quick and dirty
1828 translucency. It is fast, but the results are completely
1829 incorrect.
1830
1831 When transparency is enabled, a RenderMan snapshot will contain the
1832 alpha information, a RenderMan compliant renderer can then generate
1833 high-quality pictures, including correct translucency.
1834
1835 _Alpha_
1836 This slider determines the opacity/transparency when transparency
1837 is enabled. 0 means totally transparent, 1 means totally opaque.
1838
1839 _Diffuse Reflectance_
1840 This slider controls the diffuse reflectance of a surface. This
1841 has to do with how much the surface scatters light that it
1842 reflects.
1843
1844 _Shininess_
1845 This slider controls how shiny a surface is. This determines the
1846 size of specular highlights on the surface. Lower values give the
1847 surface a duller appearance.
1848
1849 _Ambient Reflectance_
1850 This slider controls how much of the ambient light a surface
1851 reflects.
1852
1853 _Specular Reflectance_
1854 This slider controls the specular reflectance of a surface. This
1855 has to do with how directly the surface reflects light rays.
1856 Higher values give brighter specular highlights.
1857
1858 _Done_
1859 This button dismisses the _Materials_ panel.
1860
1861
1862 
1863 File: geomview, Node: Lighting Panel, Prev: Materials Panel, Up: Appearance
1864
1865 3.6.3 The Lighting Panel
1866 ------------------------
1867
1868 The _Lights_ panel controls the number, position, and color of the
1869 light sources used in shading.
1870 [image src="figs/light.png"]
1871
1872 The Lighting Panel.
1873
1874 The _Lighting_ panel is different from the _Appearance_ and
1875 _Material_ panels in that it always works with the base appearance.
1876 This is because it usually makes sense to use the same set of lights
1877 for drawing all objects in your scene.
1878
1879 _LIGHTS_
1880 The _LIGHTS_ browser shows the currently selected light. Changes
1881 made using the other widgets on this panel apply to this light.
1882 There is always at least one light, the ambient light.
1883
1884 _Intensity_
1885 This slider controls the intensity of the current light.
1886
1887 _Color_
1888 This button brings up a color chooser which lets you select the
1889 color of the current light.
1890
1891 _Add_
1892 This button adds a light.
1893
1894 _Delete_
1895 This button deletes the current light.
1896
1897 _Show Lights_
1898 This button lets you see and change the positions of the light
1899 sources in a camera window. Each light is drawn as long cylinder
1900 which is supposed to remind you of a light beam. When you click
1901 on the _Show Lights_ button Geomview goes into "light edit" mode,
1902 during which you can rotate current light by holding down the left
1903 mouse button and moving the mouse. Lights placed in this way are
1904 infinitely distant, so what you are changing is the angular
1905 position. Click on the _Show Lights_ button again to return to
1906 the previous motion mode and to quit drawing the light beams.
1907
1908 _Done_
1909 This button dismisses the _Lighting_ panel.
1910
1911
1912 Geomview's _Appearance_, _Materials_, and _Lighting_ panels are
1913 constructed to allow you to easily do most of the appearance related
1914 things that you might want to do. The appearance hierarchy that
1915 Geomview supports internally, however, is very complex and there are
1916 certain operations that you cannot do with the panels. The Geomview
1917 command language (GCL) provides complete support for appearance
1918 operations. In particular, the `merge-baseap' command can be used to
1919 change the base appearance (which, except for lighting, cannot be
1920 changed by Geomview's panels). The `merge-ap' command can be used to
1921 change an individual geom's appearance. Appearances can also be
1922 specified in OOGL files; for details, *note Appearances::. *Note
1923 `(merge-baseap ...)': merge-baseap. *Note `(merge-ap ...)': merge-ap.
1924
1925 
1926 File: geomview, Node: Cameras, Next: Saving, Prev: Appearance, Up: Interaction
1927
1928 3.7 Cameras
1929 ===========
1930
1931 A camera in Geomview is the object that corresponds to a camera window.
1932 By default there is only one camera, but it is possible to have as many
1933 as you want. You can control certain aspects of the way the world is
1934 drawn in each camera window via the _Cameras_ panel.
1935 Figure 3.8: The Cameras Panel.
1936
1937 If the target object is a camera, the _Cameras_ panel affects that
1938 camera. If the target object is not a camera, the _Cameras_ panel
1939 affects the "current camera". The current camera is the camera of the
1940 window that the mouse cursor is in, or was in most recently if the
1941 cursor is not in a camera window. Thus, if you use the keyboard
1942 shortcuts for the actions in the _Cameras_ panel while the cursor is in
1943 a camera window, the actions apply to that camera, unless you have
1944 explicitly selected another camera.
1945
1946 To create new camera windows, use the `v+' keyboard shortcut, or see
1947 the _File_ menu on the _Main_ panel.
1948
1949 _Single-Buffering_
1950 Normally, geomview windows are _double-buffered_: geomview draws
1951 the next picture into a hidden window, then switches buffers to
1952 make it visible all at once. On many systems, the memory for the
1953 hidden buffer comes from stealing half the bits in each screen
1954 pixel, reducing the color resolution. When single-buffering is
1955 enabled, the window flickers as each scene is being drawn, but you
1956 may get smoother images with reduced grainy dithering artifacts.
1957 Single-buffering is possible if Geomview is compiled with GL or
1958 OpenGL, but not with plain-X graphics.
1959
1960 _Dither_
1961 Many displays offer less than the 24 bits per pixel (8 bits each
1962 of red, green, and blue) conventionally needed to show smooth
1963 gradations of color. When trying to show a color not accurately
1964 available on the display, Geomview normally _dithers_, choosing
1965 pixel colors sometimes brighter, sometimes darker than the desired
1966 value, so that the average color over an area is a better
1967 approximation to the true color than a single pixel could be.
1968 Effectively this loses spatial resolution to gain color resolution.
1969 This isn't always desirable, though. Turning _Dither_ off gives
1970 less grainy, but less accurately colored, images.
1971
1972 _Software Shading_
1973 This button controls whether Geomview does shading calculations in
1974 software. The default is to let the hardware handle them, and in
1975 Euclidean space this is almost certainly best because it is
1976 faster. In hyperbolic and spherical space, however, the shading
1977 calculations that the hardware does are incorrect. Click this
1978 button to turn on correct but slower software shading.
1979
1980 _Background Color_
1981 This button brings up a color chooser which you can use to set the
1982 background color of the camera's window.
1983
1984 _PROJECTION_
1985 This browser lets you pick between perspective and orthogonal
1986 projection for this camera.
1987
1988 _Near clip_
1989 This determines the distance in world coordinates of the near
1990 clipping plane from the eye point. It must be a positive number.
1991
1992 _Far clip_
1993 This determines the distance in world coordinates of the far
1994 clipping plane from the eye point. It must be a positive number
1995 and in general should be larger than the _Near clip_ value.
1996
1997 _FOV_
1998 This is the camera's field of view, measured in its shorter
1999 direction. In perspective mode, it is an angle in degrees. In
2000 orthographic mode, it is the linear size of the field of view.
2001 This number can be modified with the mouse in _Cam Zoom_ mode.
2002
2003 _Focal Length_
2004 The focal length is intended to suggest the distance from the
2005 camera to an imaginary plane of interest. Its value is used when
2006 switching between orthographic and perspective views (and during
2007 stereo viewing), so as to preserve apparent size of objects lying
2008 at the focal distance from the camera. Focal length also affects
2009 interpretation of mouse-based translational motions. Speed of
2010 forward motion (in translate, fly and orbit modes) is proportional
2011 to focal length; and objects lying at the focal distance from the
2012 camera translate laterally at the same rate as the mouse cursor.
2013 Finally, in N-D projection mode, cameras are displaced back by the
2014 focal distance from the 3-D projection of the world origin.
2015
2016 _Lines Closer_
2017 This number has to do with the way lines are drawn. Normally
2018 Geomview's z-buffering algorithm can get confused when drawing
2019 lines that lie exactly on surfaces (such as the edges of an
2020 object); due to machine round-off error, sometimes the lines
2021 appear to be in front of the surface and sometimes they appear
2022 behind it. The _Lines Closer_ value is a fudge factor -- Geomview
2023 nudges all the lines that it draws closer to the camera by this
2024 amount. The number should be a small integer; try 5 or 10. 0
2025 turns this feature off completely. Choosing too large a value
2026 will make lines visible even though they should be hidden.
2027
2028 _SPACE MODEL_
2029 This determines the model used to draw the world. It is most
2030 useful in hyperbolic and spherical spaces. You probably don't
2031 need to touch this browser if you stay in Euclidean space. For
2032 more information about these models, *note Non-Euclidean
2033 Geometry::.
2034 _Virtual_
2035 This is the default model and represents the natural view
2036 from inside the space.
2037
2038 _Projective_
2039 The projective model of hyperbolic and spherical space.
2040 Geoms move under isometries of the space, and cameras move by
2041 Euclidean motions. By default in the projective model, the
2042 Euclidean unit sphere is drawn. In hyperbolic space this is
2043 the sphere at infinity. In Euclidean space the projective
2044 model is the same as the virtual model except that the sphere
2045 is drawn by default.
2046
2047 _Conformal_
2048 The conformal model of hyperbolic and spherical space. Geoms
2049 move under isometries of the space, and cameras move by
2050 Euclidean motions. In Euclidean space, the conformal model
2051 amounts to inverting everything in the unit sphere.
2052
2053 _Draw Sphere_
2054 This controls whether Geomview draws the unit sphere. By default
2055 the unit sphere appears in the projective and conformal models. In
2056 hyperbolic space this is the sphere at infinity. In spherical
2057 space it is the equatorial sphere.
2058
2059 _Done_
2060 This button dismisses the _Cameras_ panel.
2061
2062
2063 
2064 File: geomview, Node: Saving, Next: Commands, Prev: Cameras, Up: Interaction
2065
2066 3.8 Saving your work
2067 ====================
2068
2069 Geomview's _Save_ panel lets you store Geomview objects and other
2070 information in files that you can read back into Geomview or other
2071 programs.
2072 Figure 3.9: The Save Panel.
2073
2074 To use the _Save_ panel you select the desired format in the browser
2075 next to the word _Save_, enter the name of the object you want to save
2076 in the text field next to the word _for_, and enter the name of the
2077 file you wish to save to in the long text field next to the word _in_.
2078 You can then either hit `<Enter>' or click on the _OK_ button. When
2079 the file has been written, the _Save_ panel disappears. If you want to
2080 dismiss the _Save_ panel without writing a file, click the _Cancel_
2081 button.
2082
2083 If you specify `-' as the file name, Geomview will write the file to
2084 standard output, i.e. in the shell window from which you invoked
2085 Geomview.
2086
2087 The possible formats are given below. The kind of object that can
2088 be written with each format is given in parentheses.
2089
2090 _Commands (any object)_
2091 This write a file of GCL commands containing all information about
2092 the object. Loading this file later will restore the object as
2093 well as all other information about it, such as appearance,
2094 transformations, etc.
2095
2096 _Geometry alone (geom)_
2097 This writes an OOGL file containing just the geometry of the
2098 object.
2099
2100 _Geometry [in world] (geom)_
2101 This writes an OOGL file containing just the geometry of the
2102 object, transformed under Geomview's current transformation for
2103 this object. Use this if you have moved the object from its
2104 initial position and want to save the new position relative to the
2105 world.
2106
2107 _Geometry [in universe] (geom)_
2108 This writes an OOGL file containing just the geometry of the geom,
2109 transformed under both the object's transformation and the world's
2110 transformation.
2111
2112 _RMan [->tiff] (camera)_
2113 Writes a RenderMan file which when rendered creates a tiff image.
2114 Transparency and texturing (the latter only to some extent) will
2115 be available.
2116
2117 _RMan [->frame] (camera)_
2118 Writes a RenderMan file which when rendered causes an image to
2119 appear in a window on the screen. Transparency and texturing (the
2120 latter only to some extent) will be available.
2121
2122 _SGI snapshot (camera)_
2123 Write an SGI raster file. A bell rings when the snapshot is
2124 complete. Only available on SGI systems.
2125
2126 _PPM GLX-offscreen snapshot (camera)_
2127 Render the complete scene anew into off-screen memory; GLX
2128 provides the means to use a Pixmap as rendering area. The
2129 advantage of rendering into _off_-screen memory over taking screen
2130 snapshot is that the camera windows need not be mapped and even
2131 raised at the time the snapshot is taken. So with off-screen
2132 snapshot one can safely iconify the camera window (but do not
2133 close it!), activate the screen-saver and go to bed while some
2134 script advances the scenes and takes snapshots.
2135
2136 _PPM Screen snapshot (camera)_
2137 Take a snapshot of the given window and save it as a PPM image.
2138 If you specify a string beginning with a vertical bar (`|') as the
2139 file name, it's interpreted as a Bourne shell command to which the
2140 PPM data should be piped, as in `| pnmtotiff > snap.tiff' or `|
2141 convert -geometry 50% ppm:- snap.gif'.
2142
2143 PPM screen snapshots are only available with GL and Open GL, not
2144 plain X graphics. The window should be entirely on the screen.
2145 Geomview will ensure that no other windows cover it while the
2146 snapshot is taken. It is probably a better idea to use
2147 GLX-_off-screen_ snapshots, as explained above.
2148
2149 _PPM software snapshot (camera)_
2150 Writes a snapshot of that window's current view, as a PPM image,
2151 to the given file. The file name may be a Bourne shell command
2152 preceded by a vertical bar (`|'), as with the PPM screen snapshot.
2153 The software snapshot, though, is produced by using a built-in
2154 software renderer (related to the X-windows renderer). It doesn't
2155 matter whether the window is visible or not, and doesn't depend on
2156 GL or OpenGL. It also doesn't support some features, such as
2157 texture mapping.
2158
2159 _Postscript snapshot (camera)_
2160 Writes a Postscript snapshot of the camera's view. It's made by
2161 breaking up the scene into lines and polygons, sorting by depth,
2162 and generating Postscript lines and polygons for each one.
2163 Advantages over pixel-based snapshot images: resolution is very
2164 high, so edges look sharp even on high-resolution printers, or
2165 comparable-resolution images are typically much more compact.
2166 Disadvantages: depth-sorting gives good results on some scenes,
2167 but can be wildly wrong as a hidden-surface removal algorithm for
2168 other scenes. Also, Postscript doesn't offer smoothly
2169 interpolated shading, only flat shading for each facet.
2170
2171 _Camera (camera)_
2172 Writes an OOGL file of a camera.
2173
2174 _Transform [to world] (any object)_
2175 Writes an OOGL transform file giving Geomview's transform for the
2176 object.
2177
2178 _Transform [to universe] (any object)_
2179 Writes an OOGL transform file giving a transform which is the
2180 composition of Geomview's transform for the object and the
2181 transform for the world.
2182
2183 _Window (camera)_
2184 Writes an OOGL window file for a camera.
2185
2186 _Panels_
2187 Writes a GCL file containing commands which record the state of
2188 all the Geomview panels. Loading this file later will restore the
2189 positions of all the panels.
2190
2191
2192 
2193 File: geomview, Node: Commands, Next: Keyboard Shortcuts, Prev: Saving, Up: Interaction
2194
2195 3.9 The Commands Panel
2196 ======================
2197
2198 The _Commands_ panel lets you type in a GCL command. When you hit
2199 `<Enter>', Geomview interprets the command and prints any resulting
2200 output or error messages on standard output. You can edit the text and
2201 hit `<Enter>' as many times as you like, in general, whenever you hit
2202 `<Enter>' with the cursor in the _Commands_ panel, Geomview tries to
2203 interpret whatever text you have typed in the text field as a command.
2204 [image src="figs/command.png"]
2205
2206 Figure 3.10: The Commands Panel.
2207
2208 
2209 File: geomview, Node: Keyboard Shortcuts, Prev: Commands, Up: Interaction
2210
2211 3.10 Keyboard Shortcuts
2212 =======================
2213
2214 Most actions that you can do through Geomview's panels have equivalent
2215 keyboard shortcuts so that you can do the same action by typing a
2216 sequence of keys on the keyboard. This is useful for advanced users who
2217 are familiar with Geomview's capabilities and want to work quickly
2218 without having to have lots of panels cluttering up the screen.
2219 Keyboard shortcuts usually are indicated in square brackets ([ ]) near
2220 the corresponding item in a panel. For example, the keyboard shortcut
2221 for _Rotate_ mode is 'r'; this is indicated by "[r]" appearing before
2222 the word "Rotate" in the _MOTION MODE_ browser. To use this keyboard
2223 shortcut just hit the `r' key while the mouse cursor is in any Geomview
2224 window. You don't need to press the `<Enter>' or `<SPACE>' keys.
2225
2226 Some keyboard shortcuts consist of more than one key. In these cases
2227 just type the keys one after the other, with no `<Enter>' afterwards.
2228 Keyboard shortcuts are case sensitive. You can cancel a multi-key
2229 keyboard shortcut that you have started by typing any invalid key, for
2230 example the space bar.
2231
2232 Keyboard commands apply while the cursor is in any camera window and
2233 most control panels.
2234
2235 Many keyboard shortcuts allow numeric arguments which you type as a
2236 prefix to the command key(s). For example, the shortcut for _Near
2237 clip_ in the camera panel is `v n'. To set the near clip plane to
2238 `0.5', type `0.5vn'. Commands that don't take a numeric prefix toggle
2239 or reset the current value.
2240
2241 Most commands allow one of the following selection prefixes. If
2242 none is provided the command applies to the target object.
2243
2244 `g'
2245 world geom
2246
2247 `g#'
2248 #'th geom
2249
2250 `g*'
2251 All geoms
2252
2253 `c'
2254 current camera
2255
2256 `c#'
2257 #'th camera
2258
2259 `c*'
2260 All cameras
2261
2262 For example, `g4af' means toggle the face drawing of object _g4_.
2263
2264 Simply typing a selection prefix, like `g4', doesn't yet select an
2265 object; that only happens when a command, like `ae', follows the prefix.
2266 To select an object as the target without doing anything else to it,
2267 use the `p' command. So `g3p' selects object g3.
2268
2269 The text field in the upper left corner of the _Main_ panel shows
2270 the state of the current keyboard shortcut.
2271
2272 In addition to the keyboard shortcuts for the panel commands, there
2273 is also a shortcut for picking a target object: type the short name of
2274 the object followed by `p'. For example, to select object _g3_, type
2275 `g 3 p'. This only works with the short names -- the ones that appear
2276 in square brackets ([ ]) in the _Targets_ browser of the _Main_ panel.
2277
2278 Below is a summary of all keyboard shortcuts.
2279
2280 Draw
2281
2282 `af'
2283 Faces
2284
2285 `ae'
2286 Edges
2287
2288 `an'
2289 Normals
2290
2291 `ab'
2292 Bounding Boxes
2293
2294 `aV'
2295 Vectors
2296
2297 Shading
2298
2299 `0as'
2300 Constant
2301
2302 `1as'
2303 Flat
2304
2305 `2as'
2306 Smooth
2307
2308 `3as'
2309 Smooth, non-lighted
2310
2311 `aT'
2312 allow transparency
2313
2314 `at'
2315 texture mapping
2316
2317 Other
2318
2319 `av'
2320 eVert normals: always face viewer
2321
2322 `#aw'
2323 Line Width (pixels)
2324
2325 `aC'
2326 handle concave polygons
2327
2328 `#vc'
2329 edges Closer than faces (try 5-100)
2330
2331 Color
2332
2333 `Cf'
2334 faces
2335
2336 `Ce'
2337 edges
2338
2339 `Cn'
2340 normals
2341
2342 `Cb'
2343 bounding boxes
2344
2345 `CB'
2346 background
2347
2348 Motions
2349
2350 `r'
2351 rotate
2352
2353 `t'
2354 translate
2355
2356 `z'
2357 zoom FOV
2358
2359 `f'
2360 fly
2361
2362 `o'
2363 orbit
2364
2365 `s'
2366 scale
2367
2368 `w'
2369 recenter target
2370
2371 `W'
2372 recenter all
2373
2374 `h'
2375 halt
2376
2377 `H'
2378 halt all
2379
2380 `@'
2381 select center of motion (e.g. `g 3 @')
2382
2383 `L'
2384 Look At object
2385
2386 Viewing
2387
2388 `0vp'
2389 Orthographic view
2390
2391 `1vp'
2392 Perspective view
2393
2394 `vd'
2395 Draw other views' cameras
2396
2397 `#vv'
2398 field of View
2399
2400 `#vn'
2401 near clip distance
2402
2403 `#vf'
2404 far clip distance
2405
2406 `v+'
2407 add new camera
2408
2409 `vx'
2410 cursor on/off
2411
2412 `vb'
2413 backfacing poly cull on/off
2414
2415 `#vl'
2416 focal length
2417
2418 `v~'
2419 Software shading on/off
2420
2421 Panels
2422
2423 `Pm'
2424 Main
2425
2426 `Pa'
2427 Appearance
2428
2429 `Pl'
2430 Lighting
2431
2432 `Po'
2433 Obscure
2434
2435 `Pt'
2436 Tools
2437
2438 `Pc'
2439 Cameras
2440
2441 `PC'
2442 Commands
2443
2444 `Pf'
2445 Files
2446
2447 `Ps'
2448 Save
2449
2450 `P-'
2451 read commands from tty
2452
2453 `PA'
2454 Credits ("about")
2455
2456 Lights
2457
2458 `ls'
2459 show lights
2460
2461 `le'
2462 edit lights
2463
2464 Space
2465
2466 `me'
2467 Euclidean
2468
2469 `mh'
2470 Hyperbolic
2471
2472 `ms'
2473 Spherical
2474
2475 Model
2476
2477 `mv'
2478 Virtual
2479
2480 `mp'
2481 Projective
2482
2483 `mc'
2484 Conformal
2485
2486 Other
2487
2488 `0N'
2489 normalization: none
2490
2491 `1N'
2492 normalization: each
2493
2494 `2N all'
2495 normalization: all
2496
2497 `ui'
2498 motion: Inertia
2499
2500 `uc'
2501 motion: Constrain to axis
2502
2503 `uo'
2504 motion: object's Own coordinates
2505
2506 `<'
2507
2508 `Pf'
2509 load geometry/command file
2510
2511 `dd'
2512 delete target object
2513
2514 `>'
2515
2516 `Ps'
2517 save state to file
2518
2519 `TV'
2520 NTSC mode toggle
2521
2522 `p'
2523 pick as target object (e.g. `g 3 p') With no prefix,
2524 selects the object under the mouse cursor (like
2525 double-clicking the right mouse)
2526
2527 
2528 File: geomview, Node: OOGL File Formats, Next: Customization, Prev: Interaction, Up: Top
2529
2530 4 OOGL File Formats
2531 *******************
2532
2533 The objects that you can load into Geomview are called OOGL objects.
2534 OOGL stands for "Object Oriented Graphics Library"; it is the library
2535 upon which Geomview is built.
2536
2537 There are many different kinds of OOGL objects. This chapter gives
2538 syntactic descriptions of file formats for OOGL objects.
2539
2540 Examples of most file types live in Geomview's `data/geom' directory.
2541
2542 * Menu:
2543
2544 * Conventions:: Conventions and general remarks.
2545 * Object File Formats:: Object File Formats.
2546 * Non-geometric objects:: Non-geometric objects.
2547
2548 
2549 File: geomview, Node: Conventions, Next: Object File Formats, Prev: OOGL File Formats, Up: OOGL File Formats
2550
2551 4.1 Conventions
2552 ===============
2553
2554 * Menu:
2555
2556 * Common syntax:: Syntax Common to All OOGL File Formats.
2557 * File names:: File Names.
2558 * Vertices:: Vertices.
2559 * ND-Vertices:: N-dimensional Vertices.
2560 * Surface normal directions:: Surface normal directions.
2561 * Transformation matrices:: Transformation matrices.
2562 * ND Transformation matrices:: N-dimensional transformation matrices.
2563 * Binary format:: Binary format.
2564 * References:: Embedded objects and external-object references.
2565 * Appearances:: Appearances.
2566 * Texture Mapping:: Texture mapping.
2567
2568 
2569 File: geomview, Node: Common syntax, Next: File names, Prev: Conventions, Up: Conventions
2570
2571 4.1.1 Syntax Common to All OOGL File Formats
2572 --------------------------------------------
2573
2574 Most OOGL object file formats are free-format ASCII -- any amount of
2575 white space (blanks, tabs, newlines) may appear between tokens (numbers,
2576 key words, etc.). Line breaks are almost always insignificant, with a
2577 couple of exceptions as noted. Comments begin with # and continue to
2578 the end of the line; they're allowed anywhere a newline is.
2579
2580 Binary formats are also defined for several objects; *Note Binary
2581 format::, and the individual object descriptions.
2582
2583 Typical OOGL objects begin with a key word designating object type,
2584 possibly with modifiers indicating presence of color information etc.
2585 In some formats the key word is optional, for compatibility with file
2586 formats defined elsewhere. Object type is then determined by guessing
2587 from the file suffix (if any) or from the data itself.
2588
2589 Key words are case sensitive. Some have optional prefix letters
2590 indicating presence of color or other data; in this case the order of
2591 prefixes is significant, e.g. `CNMESH' is meaningful but `NCMESH' is
2592 invalid.
2593
2594 
2595 File: geomview, Node: File names, Next: Vertices, Prev: Common syntax, Up: Conventions
2596
2597 4.1.2 File Names
2598 ----------------
2599
2600 When OOGL objects are read from disk files, the OOGL library uses the
2601 file suffix to guess at the file type.
2602
2603 If the suffix is unrecognized, or if no suffix is available (e.g.
2604 for an object being read from a pipe, or embedded in another OOGL
2605 object), all known types of objects are tried in turn until one accepts
2606 the data as valid.
2607
2608 
2609 File: geomview, Node: Vertices, Next: ND-Vertices, Prev: File names, Up: Conventions
2610
2611 4.1.3 Vertices
2612 --------------
2613
2614 Several objects share a common style of representing vertices with
2615 optional per-vertex surface-normal and color. All vertices within an
2616 object have the same format, specified by the header key word.
2617
2618 All data for a vertex is grouped together (as opposed to e.g. giving
2619 coordinates for all vertices, then colors for all vertices, and so on).
2620
2621 The syntax is
2622
2623 `X Y Z'
2624 (3-D floating-point vertex coordinates) or
2625
2626 `X Y Z W'
2627 (4-D floating-point vertex coordinates)
2628
2629 optionally followed by
2630
2631 `NX NY NZ'
2632 (normalized 3-D surface-normal if present)
2633
2634 optionally followed by
2635
2636 `R G b A'
2637 (4-component floating-point color if present, each component in
2638 range 0..1. The A (alpha) component represents opacity: 0
2639 transparent, 1 opaque.)
2640
2641 optionally followed by
2642
2643 `S T'
2644
2645 `or'
2646
2647 `S T U'
2648
2649 (two or three texture-coordinate values).
2650
2651 Values are separated by white space, and line breaks are immaterial.
2652
2653 Letters in the object's header key word must appear in a specific
2654 order; that's the reverse of the order in which the data is given for
2655 each vertex. So a `CN4OFF' object's vertices contain first the
2656 4-component space position, then the 3-component normal, finally the
2657 4-component color. You can't change the data order by changing the
2658 header key word; an `NCOFF' is just not recognized.
2659
2660 
2661 File: geomview, Node: ND-Vertices, Next: Surface normal directions, Prev: Vertices, Up: Conventions
2662
2663 4.1.4 N-dimensional Vertices
2664 ----------------------------
2665
2666 Several objects share a common style of representing vertices with
2667 optional per-vertex surface-normal and color. All vertices within an
2668 object have the same format, specified by the header key word.
2669
2670 All data for a vertex is grouped together (as opposed to e.g. giving
2671 coordinates for all vertices, then colors for all vertices, and so on).
2672
2673 The syntax for N-dimensional vertices (N > 3) is
2674
2675 `X[1] X[2] X[3] X[4] ...'
2676 (N floating-point vertex coordinates) or
2677
2678 `X[0] X[1] X[2] X[3] X[4] ...'
2679 ((N+1) floating-point vertex coordinates, if the `4' modifier has
2680 been specified in the object's header line)
2681
2682 Note, however, that N-dimensional objects internally always have
2683 (N+1)-dimensional points; the first component X[0] - if present in the
2684 object file - is used as homogeneous divisor. This is different from
2685 the ordinary 3D case where the `4' modifier generates a 4D object where
2686 the homogeneous component implicitly is set to 1.
2687
2688 Color components usually can be specified like for 3D vertices,
2689 *note Vertices::, while specifying normals does not make sense.
2690
2691 
2692 File: geomview, Node: Surface normal directions, Next: Transformation matrices, Prev: ND-Vertices, Up: Conventions
2693
2694 4.1.5 Surface normal directions
2695 -------------------------------
2696
2697 Geomview uses normal vectors to determine how an object is shaded. The
2698 direction of the normal is significant in this calculation.
2699
2700 When normals are supplied with an object, the direction of the normal
2701 is determined by the data given.
2702
2703 When normals are not supplied with the object, Geomview computes
2704 normal vectors automatically; in this case normals point toward the
2705 side from which the vertices appear in counterclockwise order.
2706
2707 On parametric surfaces (Bezier patches), the normal at point P(u,v)
2708 is in the direction dP/du cross dP/dv.
2709
2710 
2711 File: geomview, Node: Transformation matrices, Next: ND Transformation matrices, Prev: Surface normal directions, Up: Conventions
2712
2713 4.1.6 Transformation matrices
2714 -----------------------------
2715
2716 Some objects incorporate 4x4 real matrices for homogeneous object
2717 transformations. These matrices act by multiplication on the right of
2718 vectors. Thus, if p is a 4-element row vector representing homogeneous
2719 coordinates of a point in the OOGL object, and A is the 4x4 matrix, then
2720 the transformed point is p' = p A. This matrix convention is common in
2721 computer graphics; it's the transpose of that often used in mathematics,
2722 where points are column vectors multiplied on the right of matrices.
2723
2724 Thus for Euclidean transformations, the translation components
2725 appear in the fourth row (last four elements) of A. A's last column
2726 (4th, 8th, 12th and 16th elements) are typically 0, 0, 0, and 1
2727 respectively.
2728
2729 
2730 File: geomview, Node: ND Transformation matrices, Next: Binary format, Prev: Transformation matrices, Up: Conventions
2731
2732 4.1.7 ND Transformation matrices
2733 --------------------------------
2734
2735 In the context of N-dimensional space (N > 3) some objects incorporate
2736 (N+1)x(N+1) real matrices for homogeneous object transformations.
2737 These matrices act by multiplication on the right of vectors. Thus, if
2738 p is an (N+1)-element row vector representing homogeneous coordinates
2739 of a point in the OOGL object, and A (N+1)x(N+1) is the matrix, then
2740 the transformed point is p' = p A.
2741
2742 Note that (unlike for the 4x4 transformation matrices, *note
2743 Transformation matrices::) the homogeneous component is located at
2744 index zero, so the translation components for Euclidean transformations
2745 appear in the zero-th row (first (N+1) elements). A's first column (at
2746 column index zero) is typically 1, 0, ..., 0.
2747
2748 
2749 File: geomview, Node: Binary format, Next: References, Prev: ND Transformation matrices, Up: Conventions
2750
2751 4.1.8 Binary format
2752 -------------------
2753
2754 Many OOGL objects accept binary as well as ASCII file formats. These
2755 files begin with the usual ASCII token (e.g. `CQUAD') followed by the
2756 word `BINARY'. Binary data begins at the byte following the first
2757 newline after `BINARY'. White space and a single comment may
2758 intervene, e.g.
2759
2760 OFF BINARY # binary-format "OFF" data follows
2761
2762 Binary data comprise 32-bit integers and 32-bit IEEE-format floats,
2763 both in big-endian format (i.e., with most significant byte first).
2764 This is the native format for 'int's and 'float's on Sun-3's, Sun-4's,
2765 and Irises, among others.
2766
2767 Binary data formats resemble the corresponding ASCII formats, with
2768 ints and floats in just the places you'd expect. There are some
2769 exceptions though, specifically in the `QUAD', `OFF' and `COMMENT' file
2770 formats. Details are given in the individual file format descriptions.
2771 *Note QUAD::, *Note OFF::, and *Note COMMENT::.
2772
2773 Binary OOGL objects may be freely mixed in ASCII object streams:
2774
2775 LIST
2776 { = MESH BINARY
2777 ... binary data for mesh here ...
2778 }
2779 { = QUAD
2780 1 0 0 0 0 1 0 1 0 0 1 0
2781 }
2782
2783 Note that ASCII data resumes immediately following the last byte of
2784 binary data.
2785
2786 Naturally, it's impossible to embed comments inside a binary-format
2787 OOGL object, though comments may appear in the header before the
2788 beginning of binary data.
2789
2790 
2791 File: geomview, Node: References, Next: Appearances, Prev: Binary format, Up: Conventions
2792
2793 4.1.9 Embedded objects and external-object references
2794 -----------------------------------------------------
2795
2796 Some object types (`LIST', `INST') allow references to other OOGL
2797 objects, which may appear literally in the data stream, be loaded from
2798 named disk files, or be communicated from elsewhere via named objects.
2799 GCL commands also accept geometry in these forms.
2800
2801 The general syntax is
2802
2803 <oogl-object> ::=
2804 [ "{" ]
2805 [ "define" `symbolname' ]
2806 [ ["="] `object-keyword' ...
2807 | "<" `filename'
2808 | ":" `symbolname' ]
2809 [ "}" ]
2810
2811 where "quoted" items are literal strings (which appear without the
2812 quotes), [bracketed] items are optional, and | denotes alternatives.
2813 Curly braces, when present, must match; the outermost set of curly
2814 braces is generally required when the object is in a larger context,
2815 e.g. when it is part of a larger object or embedded in a Geomview
2816 command stream.
2817
2818 For example, each of the following three lines:
2819 { define fred QUAD 1 0 0 0 0 1 0 1 0 1 0 0 }
2820
2821 { define fred = QUAD 1 0 0 0 0 1 0 1 0 1 0 0 }
2822
2823 { appearance { +edge } LIST { < "file1" } { : fred } }
2824
2825 VECT 1 2 0 2 0 0 0 0 1 1 2
2826 is a valid OOGL object. The last example is only valid when it is
2827 delimited unambiguously by residing in its own disk file.
2828
2829 The ":" construct allows references to symbols, created with
2830 `define'. A symbol's initial value is a null object. When a symbol is
2831 (re)defined, all references to it are automatically changed.
2832
2833 The "`define' NAME" construct allows to define a global symbol for
2834 the given object. If "NAME" already references an object, then the old
2835 object is discarded and replaced by the new definition. *Note `(read
2836 ...)': read. *Note `(hdefine ...)': hdefine.
2837
2838 The "<" construct causes a disk file to be read. Note that this
2839 isn't a general textual "include" mechanism; a complete OOGL object
2840 must appear in the referenced file.
2841
2842 Files read using "<" are sought first in the directory of the file
2843 which referred to them, if any; failing that, the normal search path
2844 (*note `(load-path ...)': load-path.) is used. The default search
2845 looks first in the current directory, then in the Geomview data
2846 directories.
2847
2848 Again, white space and line breaks are insignificant, and "#"
2849 comments may appear anywhere.
2850
2851 
2852 File: geomview, Node: Appearances, Next: Texture Mapping, Prev: References, Up: Conventions
2853
2854 4.1.10 Appearances
2855 ------------------
2856
2857 Geometric objects can have associated "appearance" information,
2858 specifying shading, lighting, color, wire-frame vs. shaded-surface
2859 display, and so on. Appearances are inherited through object
2860 hierarchies, e.g. attaching an appearance to a `LIST' means that the
2861 appearance is applied to all the `LIST''s members.
2862
2863 Some appearance-related properties are relegated to "material",
2864 "lighting" and "texture" substructures. Take care to note which
2865 properties belong to which structure. Any geometric object can be
2866 preceded by an appearance definition like in the following example:
2867
2868 {
2869 appearance { +edge }
2870 LIST { < "file1" } { QUAD 1 0 0 0 0 1 0 1 0 1 0 0 }
2871 }
2872
2873 Appearances are also OOGL objects in their own right and can be given
2874 symbolic names and referenced by them (*note References::). *Note
2875 Appearance objects: appearance objects.
2876
2877 Texture Mapping
2878 There is a separate section concerning the definition of textures
2879 (*note Texture Mapping::).
2880
2881 Transparency
2882 Rendering translucent objects is not supported by all drawing back
2883 ends. The OpenGL renderer has limited support for it: top-level
2884 objects (i.e. those which appear in the object browser of the main
2885 panel (*note The Main Panel: Basic Interaction.) are rendered
2886 correctly by means of alpha-blending). Also, the RenderMan
2887 snapshots will include opacity values.
2888
2889 Here's an example appearance structure including values for all
2890 attributes. Order of attributes is unimportant. As usual, white space
2891 is irrelevant. Boolean attributes may be preceded by "+" or "-" to turn
2892 them on or off; "+" is assumed if only the attribute name appears.
2893 Other attributes expect values.
2894
2895 A "*" prefix on any attribute, e.g. "*+edge" or "*linewidth 2" or
2896 "material { *diffuse 1 1 .25 }", selects "override" status for that
2897 attribute.
2898
2899 appearance {
2900 +face # (Do) draw faces of polygons. On by default.
2901 -edge # (Don't) draw edges of polygons
2902 +vect # (Do) draw VECTs. On by default.
2903 transparent screendoor
2904 # (Enable) transparency. Enabling transparency
2905 # does not (necessarily) result in a correct Geomview
2906 # pictures, but alpha values are used in RenderMan
2907 # snapshots.
2908 # The allowed keywords are ``screendoor'' (masking out
2909 # out pixels by means of a stipple pattern),
2910 # ``blending'' for alpha-blending with BSP-tree
2911 # space paritioning and depth-sorting (slow) and
2912 # ``naive'' for alpha-blending without even
2913 # depth-sorting, not to talk about space
2914 # partioning. Omitting the keyword will default to
2915 # alpha-blending with BSP-tree space-partioning
2916 # and depth-sorting.
2917 -normal # (Do) draw surface-normal vectors
2918 normscale 1 # ... with length 1.0 in object coordinates
2919
2920 +evert # do evert polygon normals where needed so as
2921 # to always face the camera
2922
2923 +texturing # (Enable) texture mapping
2924 +linear # (Enable) linear average of closest texture elements
2925 +mipmap # (Enable) texture mip-mapping
2926 +mipinterp # (Enable) linear mip-mapping
2927 -backcull # (Don't) discard clockwise-oriented faces
2928 -concave # (Don't) expect and handle concave polygons
2929 -shadelines # (Don't) shade lines as if they were lighted cylinders
2930 # These four are only effective where the graphics system
2931 # supports them, namely on GL and Open GL.
2932
2933 -keepcolor # Normally, when N-D positional coloring is enabled as
2934 # with geomview's (ND-color ...) command, all
2935 # objects' colors are affected. But, objects with the
2936 # "+keepcolor" attribute are immune to N-D coloring.
2937
2938 shading smooth # or ``shading constant'' or ``shading flat'' or
2939 # or ``shading csmooth'' or ``shading vcflat''.
2940 # smooth = Gouraud shading, flat = faceted,
2941 # csmooth = smoothly interpolated but unlighted,
2942 # vcflat = flat shading, but smoothly interpolated colors.
2943
2944 linewidth 1 # lines, points, and edges are 1 pixel wide.
2945
2946 patchdice 10 10 # subdivide Bezier patches this finely in u and v
2947
2948 material { # Here's a material definition;
2949 # it could also be read from a file as in
2950 # ``material < file.mat''
2951
2952 ka 1.0 # ambient reflection coefficient.
2953 ambient .3 .5 .3 # ambient color (red, green, blue components)
2954 # The ambient contribution to the shading is
2955 # the product of ka, the ambient color,
2956 # and the color of the ambient light.
2957
2958 kd 0.8 # diffuse-reflection coefficient.
2959 diffuse .9 1 .4 # diffuse color.
2960 # (In ``shading constant'' mode, the surface
2961 # is colored with the diffuse color.)
2962
2963 ks 1.0 # specular reflection coefficient.
2964 specular 1 1 1 # specular (highlight) color.
2965 shininess 25 # specular exponent; larger values give
2966 # sharper highlights.
2967
2968 backdiffuse .7 .5 0 # back-face color for two-sided surfaces
2969 # If defined, this field determines the diffuse
2970 # color for the back side of a surface.
2971 # It's implemented by the software shader, and
2972 # by hardware shading on GL systems which support
2973 # two-sided lighting, and under Open GL.
2974
2975 alpha 1.0 # opacity; 0 = transparent (invisible), 1 = opaque.
2976 # Ignored when transparency is disabled.
2977
2978 edgecolor 1 1 0 # line & edge color
2979
2980 normalcolor 0 0 0 # color for surface-normal vectors
2981 }
2982
2983 lighting { # Lighting model
2984
2985 ambient .3 .3 .3 # ambient light
2986
2987 replacelights # ``Use only the following lights to
2988 # illuminate the objects under this
2989 # appearance.''
2990 # Without "replacelights", any lights listed
2991 # are added to those already in the scene.
2992
2993 # Now a collection of sample lights:
2994 light {
2995 color 1 .7 .6 # light color
2996 position 1 0 .5 0 # light position [distant light]
2997 # given in homogeneous coordinates.
2998 # With fourth component = 0,
2999 # this means a light coming from
3000 # direction (1,0,.5).
3001 }
3002
3003 light { # Another light.
3004 color 1 1 1
3005 position 0 0 .5 1 # light at finite position ...
3006 location camera # specified in camera coordinates.
3007 # (Since the camera looks toward -Z,
3008 # this example places the light
3009 # .5 unit behind the eye.)
3010 # Possible "location" keywords:
3011 # global light position is in world (well, universe) coordinates
3012 # This is the default if no location specified.
3013 # camera position is in the camera's coordinate system
3014 # local position is in the coordinate system where
3015 # the appearance was defined
3016 }
3017 } # end lighting model
3018 texture {
3019 clamp st # or ``s'' or ``t'' or ``none''
3020 file lump.tiff # file supplying texture-map image
3021 alphafile mask.pgm.Z # file supplying transparency-mask image
3022 apply blend # or ``modulate'' or ``decal''
3023 transform 1 0 0 0 # surface (s,t,0,1) * tfm -> texture coords
3024 0 1 0 0
3025 0 0 1 0
3026 .5 0 0 1
3027
3028 background 1 0 0 1 # relevant for ``apply blend''
3029 }
3030 } # end appearance
3031
3032 There are rules for inheritance of appearance attributes when several
3033 are imposed at different levels in the hierarchy.
3034
3035 For example, Geomview installs a backstop appearance which provides
3036 default values for most parameters; its control panels install other
3037 appearances which supply new values for a few attributes; user-supplied
3038 geometry may also contain appearances.
3039
3040 The general rule is that the child's appearance (the one closest to
3041 the geometric primitives) wins. Further, appearance controls with
3042 "override" status (e.g. `*+face or material { *diffuse 1 1 0 }') win
3043 over those without it.
3044
3045 Geomview's appearance controls use the "override" feature so as to be
3046 effective even if user-supplied objects contain their own appearance
3047 settings. However, if a user-supplied object contains an appearance
3048 field with override status set, that property will be immune to
3049 Geomview's controls.
3050
3051 
3052 File: geomview, Node: Texture Mapping, Prev: Appearances, Up: Conventions
3053
3054 4.1.11 Texture Mapping
3055 ----------------------
3056
3057 Some rendering back-ends support texture-mapped objects, actually only
3058 the OpenGL and the RenderMan interface at the time of this writing.
3059 There are also some issues with the RMan interface when using an
3060 alpha-channel in the texture image. Those rendering back-ends which
3061 don't support texturing silently ignore attempts to use texture
3062 mapping. A texture is specified as part of an appearance structure
3063 (*note Appearances::). Briefly, one provides a texture image (*note
3064 Image objects: image.), which is considered to lie in a square in
3065 `(s,t)' parameter space in the range 0 <= s <= 1, 0 <= t <= 1. Then
3066 one provides a geometric primitive, with each vertex tagged with
3067 `(s,t)' texture coordinates. If texturing is enabled, the appropriate
3068 portion of the texture image is pasted onto each face of the textured
3069 object.
3070
3071 There is (currently) no provision for inheritance of part of a
3072 texture structure; if the `texture' keyword is mentioned in an
3073 appearance, it supplants any other texture specification.
3074
3075 The appearance attribute `texturing' controls whether textures are
3076 used; there's no performance penalty for having texture { ... } fields
3077 defined when texturing is off.
3078
3079 The available fields are:
3080
3081 clamp none -or- s -or- t -or- st
3082 Determines the meaning of texture coordinates outside the range 0..1.
3083 With `clamp none', the default, coordinates are interpreted
3084 modulo 1, so (s,t) = (1.25,0), (.25,0), and (-.75,0) all refer to
3085 the same point in texture space. With `s' or `t' or
3086 `st', either or both of s- or t-coordinates less than 0 or
3087 greater than 1 are clamped to 1 or 0, respectively.
3088
3089 image { <image specification> (*note Image objects: image.) }
3090 Specify the actual texture image. Images can have 1, 2, 3 or 4 channels:
3091 1 channel: luminance
3092 2 channels: luminance and alpha
3093 3 channels: RGB data
3094 4 channels: RGBA data
3095
3096 *Note Image objects: image, for the actual definition of image
3097 objects. The alpha-channel is only interpreted as mask: where the mask
3098 is zero, pixels are simply not drawn. An exception is the case where
3099 _apply_ is equal to _modulate_ and translucency is enabled:
3100 in this case the resulting alpha value is the result of the
3101 multiplication of the surface color with the alpha value of the
3102 texture's alpha channel.
3103
3104 file filename
3105 alphafile filename
3106 _This is considered obsolete, and only kept for compatibility,
3107 the modern way is to use the new OOGL image object. *Note Image objects: image.
3108 The stuff documented here should still work, though_
3109
3110 Specifies image file(s) containing the texture.
3111
3112 The _file_ keyword specifies a file with color or lightness information;
3113 _alphafile_ if present, specifies a transparency ("alpha") mask;
3114 where the mask is zero, pixels are simply not drawn.
3115 Several image file formats are available; the file type must be
3116 indicated by the last few characters of the file name:
3117 .ppm or .ppm.Z or .ppm.gz 24-bit 3-color image in PPM format
3118 .pgm or .pgm.Z or .pgm.gz 8-bit grayscale image in PGM format
3119 .sgi or .sgi.Z or .sgi.gz 8-bit, 24-bit, or 32-bit SGI image
3120 .tiff 8-bit or 24-bit TIFF image
3121 .gif GIF image
3122 For this feature to work, some programs must be available in
3123 geomview's search path:
3124 zcat for .Z files
3125 gzip for .gz files
3126 tifftopnm for .tiff files
3127 giftoppm for .gif files
3128
3129 If an `alphafile' image is supplied, it must be the same size
3130 as the `file' image.
3131
3132 _Image objects provide a more flexible way to specify texture
3133 data. *Note Image objects: image._
3134
3135 apply modulate -or- blend -or- decal
3136 Indicates how the texture image is applied to the surface.
3137 Here the "surface color" means the color the surface would have
3138 in the absence of texture mapping.
3139
3140 With `modulate', the default, the texture color (or lightness,
3141 if textured by a gray-scale image) is multiplied by the surface color.
3142
3143 With `blend', texture blends between the `background' color
3144 and the surface color. The `file' parameter must specify a
3145 gray-scale image. Where the texture image is 0, the surface color is
3146 unaffected; where it's 1, the surface is painted in the color given
3147 by `background'; and color is interpolated for intermediate values.
3148
3149 With `decal', the `file' parameter must specify a
3150 3-color image. If an `alphafile' parameter is present,
3151 its value interpolates between the surface color (where alpha=0)
3152 and the texture color (where alpha=1). Lighting does not affect the
3153 texture color in `decal' mode; effectively the texture is
3154 constant-shaded.
3155
3156 background R G B A
3157 Specifies a 4-component color, with R, G, B, and A floating-point
3158 numbers normally in the range 0..1, used when `apply blend'
3159 is selected.
3160
3161 transform `transformation-matrix'
3162 Expects a list of 16 numbers, or one of the other ways of representing
3163 a transformation (`: handlename' or `< filename').
3164 The 4x4 transformation matrix is applied to texture coordinates,
3165 in the sense of a 4-component row vector (s,t,0,1) multiplied on
3166 the left of the matrix, to produce new coordinates (s',t')
3167 which actually index the texture.
3168
3169 
3170 File: geomview, Node: Object File Formats, Next: Non-geometric objects, Prev: Conventions, Up: OOGL File Formats
3171
3172 4.2 Object File Formats
3173 =======================
3174
3175 * Menu:
3176
3177 * QUAD:: List of quadrilaterals.
3178 * MESH:: Rectangularly-connected mesh.
3179 * BBOX:: Simple bounding-boxes.
3180 * BBP and BEZ:: List of Bezier surface patches.
3181 * OFF:: Polyhedra: polygons with shared vertices.
3182 * VECT:: List of points and lines.
3183 * SKEL:: List of points and lines, with shared vertices.
3184 * SPHERE:: Sphere
3185 * INST:: Transformed Instance of another object.
3186 * LIST:: List of other objects.
3187 * TLIST:: Collection of 4x4 transformation matrices.
3188 * GROUP:: Obsolete format for collections of objects.
3189 * DISCGRP:: Discrete Group objects.
3190 * COMMENT:: Comment object, for caching information.
3191
3192 
3193 File: geomview, Node: QUAD, Next: MESH, Prev: Object File Formats, Up: Object File Formats
3194
3195 4.2.1 QUAD: collection of quadrilaterals
3196 ----------------------------------------
3197
3198 The conventional suffix for a `QUAD' file is `.quad'.
3199
3200 The file syntax is
3201
3202 [C][N][4]QUAD -or- [C][N][4]POLY # Key word
3203 VERTEX VERTEX VERTEX VERTEX # 4*N vertices for some N
3204 VERTEX VERTEX VERTEX VERTEX
3205 ...
3206
3207 The leading key word is `[C][N][4]QUAD' or `[C][N][4]POLY', where
3208 the optional `C' and `N' prefixes indicate that each vertex includes
3209 colors and normals respectively. That is, these files begin with one
3210 of the words
3211
3212 `QUAD' `CQUAD' `NQUAD' `CNQUAD' `POLY' `CPOLY' `NPOLY' `CNPOLY'
3213
3214 (but not `NCQUAD' or `NCPOLY'). `QUAD' and `POLY' are synonymous;
3215 both forms are allowed just for compatibility with ChapReyes.
3216
3217 Following the key word is an arbitrary number of groups of four
3218 vertices, each group describing a quadrilateral. See the Vertex syntax
3219 above. The object ends at end-of-file, or with a close-brace if
3220 incorporated into an object reference (see above).
3221
3222 A `QUAD BINARY' file format is accepted; *Note Binary format::. The
3223 first word of binary data must be a 32-bit integer giving the number of
3224 quads in the object; following that is a series of 32-bit floats,
3225 arranged just as in the ASCII format.
3226
3227 
3228 File: geomview, Node: MESH, Next: BBOX, Prev: QUAD, Up: Object File Formats
3229
3230 4.2.2 MESH: rectangularly-connected mesh
3231 ----------------------------------------
3232
3233 The conventional suffix for a `MESH' file is `.mesh'.
3234
3235 The file syntax is
3236
3237 [U][C][N][Z][4][u][v][n]MESH # Key word
3238 [NDIM] # Space dimension, present only if nMESH
3239 NU NV # Mesh grid dimensions
3240 # NU*NV vertices, in format specified
3241 # by initial key word
3242 VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU-1,0)
3243 VERTEX(0,1) ... VERTEX(NU-1,1)
3244 ...
3245 VERTEX(0,NV-1) ... VERTEX(NU-1,NV-1)
3246
3247 The key word is `[U][C][N][Z][4][u][v][n]MESH'. The optional
3248 prefix characters mean:
3249
3250 `U'
3251 Each vertex includes a 3-component texture space parameter. The
3252 first two components are the usual `S' and `T' texture parameters
3253 for that vertex; the third should be specified as zero.
3254
3255 `C'
3256 Each vertex (see Vertices above) includes a 4-component color.
3257
3258 `N'
3259 Each vertex includes a surface normal vector.
3260
3261 `Z'
3262 Of the 3 vertex position values, only the Z component is present;
3263 X and Y are omitted, and assumed to equal the mesh (u,v)
3264 coordinate so X ranges from 0 .. (Nu-1), Y from 0 .. (Nv-1) where
3265 Nu and Nv are the mesh dimensions - see below.
3266
3267 `4'
3268 Vertices are 4D, each consists of 4 floating values. `Z' and `4'
3269 cannot both be present.
3270
3271 `u'
3272 The mesh is wrapped in the u-direction, so the (0,v)'th vertex is
3273 connected to the (NU-1,v)'th for all v.
3274
3275 `v'
3276 The mesh is wrapped in the v-direction, so the (u,0)'th vertex is
3277 connected to the (u,NV-1)'th for all u. Thus a u-wrapped or
3278 v-wrapped mesh is topologically a cylinder, while a uv-wrapped
3279 mesh is a torus.
3280
3281 `n'
3282 Specifies a mesh whose vertices live in a higher dimensional space.
3283 The dimension follows the "MESH" keyword. Each vertex then has
3284 NDIM components.
3285
3286 Note that the order of prefix characters is significant; a colored,
3287 u-wrapped mesh is a `CuMESH' not a `uCMESH'.
3288
3289 Following the mesh header are integers NU and NV, the dimensions of
3290 the mesh.
3291
3292 Then follow NU*NV vertices, each in the form given by the header.
3293 They appear in v-major order, i.e. if we name each vertex by (u,v) then
3294 the vertices appear in the order
3295
3296 (0,0) (1,0) (2,0) (3,0) ... (NU-1,0)
3297 (0,1) (1,1) (2,1) (3,1) ... (NU-1,1)
3298 ...
3299 (0,Nv-1) ... (NU-1,NV-1)
3300
3301 A `MESH BINARY' format is accepted; *Note Binary format::. The
3302 values of NU and NV are 32-bit integers; all other values are 32-bit
3303 floats.
3304
3305 
3306 File: geomview, Node: BBOX, Next: BBP and BEZ, Prev: MESH, Up: Object File Formats
3307
3308 4.2.3 BBOX: simple bounding boxes
3309 ---------------------------------
3310
3311 This is a very simple toy-object: it takes 2 vertices and draws a
3312 (hyper-) cube which is the bounding box of the two vertices.
3313
3314 Syntax:
3315
3316 BBOX
3317 X[0] Y[0] Z[0]
3318 X[1] Y[1] Z[1]
3319
3320 or
3321
3322 4BBOX
3323 X[0] Y[0] Z[0] W[0]
3324 X[1] Y[1] Z[1] W[1]
3325
3326 or
3327
3328 nBBOX
3329 NDIM # > 3
3330 X[0] Y[0] Z[0] W[0] ...
3331 X[1] Y[1] Z[1] W[1] ...
3332
3333 or
3334
3335 4nBBOX
3336 NDIM # > 3
3337 D[0] X[0] Y[0] Z[0] W[0] ...
3338 D[0] X[1] Y[1] Z[1] W[1] ...
3339
3340 There is no BBOX binary format. The `4' modifyer has different
3341 meanings depending on the dimension of the bounding box: `4BBOX' means
3342 that the 4 components of the vertices make up a 4-dimensional
3343 bounding-box. Using `4' in conjunction with `n' - `4nBBOX NDIM' - means
3344 that the vertices specified in the file have NDIM+1 components, but the
3345 component at index 0 is the homogeneous divisor (in contrast to the
3346 ordinary 3d case where the homogeneous divisor would be the `w' - the
3347 third - component).
3348
3349 
3350 File: geomview, Node: BBP and BEZ, Next: OFF, Prev: BBOX, Up: Object File Formats
3351
3352 4.2.4 Bezier Surfaces
3353 ---------------------
3354
3355 The conventional file suffixes for Bezier surface files are `.bbp' or
3356 `.bez'. A file with either suffix may contain either type of patch.
3357
3358 Syntax:
3359
3360 [ST]BBP -or- [C]BEZ<NU><NV><ND>[_ST]
3361 # NU, NV are u- and v-direction
3362 # polynomial degrees in range 1..6
3363 # ND = dimension: 3->3-D, 4->4-D (rational)
3364 # (The '<' and '>' do not appear in the input.)
3365 # NU,NV,ND are each a single decimal digit.
3366 # BBP form implies NU=NV=ND=3 so BBP = BEZ333.
3367
3368 # Any number of patches follow the header
3369 # (NU+1)*(NV+1) patch control points
3370 # each 3 or 4 floats according to header
3371 VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU,0)
3372 VERTEX(0,1) ... VERTEX(NU,1)
3373 ...
3374 VERTEX(0,NV) ... VERTEX(NU,NV)
3375
3376 # ST texture coordinates if mentioned in header
3377 `S'(u=0,v=0) `T'(0,0) `S'(0,NV) `T'(0,NV)
3378 `S'(NU,0) `T'(NU,0) `S'(NU,NV) `T'(NU,NV)
3379
3380 # 4-component float (0..1) R G B A colors
3381 # for each patch corner if mentioned in header
3382 `RGBA'(0,0) `RGBA'(0,NV)
3383 `RGBA'(NU,0) `RGBA'(NU,NV)
3384
3385 These formats represent collections of Bezier surface patches, of
3386 degrees up to 6, and with 3-D or 4-D (rational) vertices.
3387
3388 The header keyword has the forms `[ST]BBP' or
3389 `[C]BEZ<NU><NV><ND>[_ST]' (the '<' and '>' are not part of the keyword.
3390
3391 The `ST' prefix on `BBP', or `_ST' suffix on `BEZuvn', indicates
3392 that each patch includes four pairs of floating-point texture-space
3393 coordinates, one for each corner of the patch.
3394
3395 The `C' prefix on `BEZuvn' indicates a colored patch, including four
3396 sets of four-component floating-point colors (red, green, blue, and
3397 alpha) in the range 0..1, one color for each corner.
3398
3399 NU and NV, each a single digit in the range 1..6, are the patch's
3400 polynomial degree in the u and v direction respectively.
3401
3402 ND is the number of components in each patch vertex, and must be
3403 either `3' for 3-D or `4' for homogeneous coordinates, that is,
3404 rational patches.
3405
3406 `BBP' patches are bicubic patches with 3-D vertices, so `BBP' =
3407 `BEZ333' and `STBBP' = `BEZ333_ST'.
3408
3409 Any number of patches follow the header. Each patch comprises a
3410 series of patch vertices, followed by optional (s,t) texture
3411 coordinates, followed by optional (r,g,b,a) colors.
3412
3413 Each patch has (NU+1)*(NV+1) vertices in v-major order, so that if we
3414 designate a vertex by its control point indices (u,v) the order is
3415 (0,0) (1,0) (2,0) ... (NU,0)
3416 (0,1) (1,1) (2,1) ... (NU,1)
3417 ...
3418 (0,NV) ... (NU,NV)
3419 with each vertex containing either 3 or 4 floating-point numbers as
3420 specified by the header.
3421
3422 If the header calls for ST coordinates, four pairs of floating-point
3423 numbers follow: the texture-space coordinates for the (0,0), (NU,0),
3424 (0,NV), and (NU,NV) corners of the patch, respectively.
3425
3426 If the header calls for colors, four four-component (red, green,
3427 blue, alpha) floating-point colors follow, one for each patch corner.
3428
3429 The series of patches ends at end-of-file, or with a closebrace if
3430 incorporated in an object reference.
3431
3432 
3433 File: geomview, Node: OFF, Next: VECT, Prev: BBP and BEZ, Up: Object File Formats
3434
3435 4.2.5 OFF Files
3436 ---------------
3437
3438 The conventional suffix for `OFF' files is `.off'.
3439
3440 Syntax:
3441
3442 [ST][C][N][4][n]OFF # Header keyword
3443 [NDIM] # Space dimension of vertices, present only if nOFF
3444 NVERTICES NFACES NEDGES # NEdges not used or checked
3445
3446 X[0] Y[0] Z[0] # Vertices, possibly with normals,
3447 # colors, and/or texture coordinates, in that order,
3448 # if the prefixes `N', `C', `ST'
3449 # are present.
3450 # If 4OFF, each vertex has 4 components,
3451 # including a final homogeneous component.
3452 # If nOFF, each vertex has NDIM components.
3453 # If 4nOFF, each vertex has NDIM+1 components.
3454 ...
3455 X[NVERTICES-1] Y[NVERTICES-1] Z[NVERTICES-1]
3456
3457 # Faces
3458 # NV = # vertices on this face
3459 # V[0] ... V[NV-1]: vertex indices
3460 # in range 0..NVERTICES-1
3461 NV V[0] V[1] ... V[NV-1] COLORSPEC
3462 ...
3463 # COLORSPEC continues past V[NV-1]
3464 # to end-of-line; may be 0 to 4 numbers
3465 # nothing: default
3466 # integer: colormap index
3467 # 3 or 4 integers: RGB[A] values 0..255
3468 # 3 or 4 floats: RGB[A] values 0..1
3469
3470 `OFF' files (name for "object file format") represent collections of
3471 planar polygons with possibly shared vertices, a convenient way to
3472 describe polyhedra. The polygons may be concave but there's no
3473 provision for polygons containing holes.
3474
3475 An `OFF' file may begin with the keyword `OFF'; it's recommended but
3476 optional, as many existing files lack this keyword.
3477
3478 Three ASCII integers follow: NVERTICES, NFACES, and NEDGES. These
3479 are the number of vertices, faces, and edges, respectively. Current
3480 software does not use nor check NEDGES; it needn't be correct but must
3481 be present.
3482
3483 The vertex coordinates follow: dimension * NVERTICES floating-point
3484 values. They're implicitly numbered 0 through NVERTICES-1. dimension
3485 is either 3 (default) or 4 (specified by the key character `4' directly
3486 before `OFF' in the keyword).
3487
3488 Following these are the face descriptions, typically written with
3489 one line per face. Each has the form
3490 N VERT1 VERT2 ... VERTN [COLOR]
3491 Here N is the number of vertices on this face, and VERT1 through
3492 VERTN are indices into the list of vertices (in the range
3493 0..NVERTICES-1).
3494
3495 The optional COLOR may take several forms. Line breaks are
3496 significant here: the COLOR description begins after VERTN and ends
3497 with the end of the line (or the next # comment). A COLOR may be:
3498
3499 nothing
3500 the default color
3501
3502 one integer
3503 index into "the" colormap; see below
3504
3505 three or four integers
3506 RGB and possibly alpha values in the range 0..255
3507
3508 three or four floating-point numbers
3509 RGB and possibly alpha values in the range 0..1
3510
3511 For the one-integer case, the colormap is currently read from the
3512 file `cmap.fmap' in Geomview's `data' directory. Some better mechanism
3513 for supplying a colormap is likely someday.
3514
3515 The meaning of "default color" varies. If no face of the object has
3516 a color, all inherit the environment's default material color. If some
3517 but not all faces have colors, the default is gray (R,G,B,A=.666).
3518
3519 A `[ST][C][N][n]OFF BINARY' format is accepted; *Note Binary
3520 format::. It resembles the ASCII format in almost the way you'd expect,
3521 with 32-bit integers for all counters and vertex indices and 32-bit
3522 floats for vertex positions (and texture coordinates or vertex colors or
3523 normals if `COFF'/`NOFF'/`CNOFF'/`STCNOFF'/etc. format).
3524
3525 Exception: each face's vertex indices are followed by an integer
3526 indicating how many color components accompany it. Face color
3527 components must be floats, not integer values. Thus a colorless
3528 triangular face might be represented as
3529
3530 int int int int int
3531 3 17 5 9 0
3532
3533 while the same face colored red might be
3534
3535 int int int int int float float float float
3536 3 17 5 9 4 1.0 0.0 0.0 1.0
3537
3538 
3539 File: geomview, Node: VECT, Next: SKEL, Prev: OFF, Up: Object File Formats
3540
3541 4.2.6 VECT Files
3542 ----------------
3543
3544 The conventional suffix for `VECT' files is `.vect'.
3545
3546 Syntax:
3547
3548 [4]VECT
3549 NPOLYLINES NVERTICES NCOLORS
3550
3551 NV[0] ... NV[NPOLYLINES-1] # number of vertices
3552 # in each polyline
3553
3554 NC[0] ... NC[NPOLYLINES-1] # number of colors supplied
3555 # in each polyline
3556
3557 VERT[0] ... VERT[NVERTICES-1] # All the vertices
3558 # (3*NVertices floats)
3559
3560 COLOR[0] ... COLOR[NCOLORS-1] # All the colors
3561 # (4*NColors floats, RGBA)
3562
3563 `VECT' objects represent lists of polylines (strings of connected
3564 line segments, possibly closed). A degenerate polyline can be used to
3565 represent a point.
3566
3567 A `VECT' file begins with the key word `VECT' or `4VECT' and three
3568 integers: NLINES, NVERTICES, and NCOLORS. Here NLINES is the number of
3569 polylines in the file, NVERTICES the total number of vertices, and
3570 NCOLORS the number of colors as explained below.
3571
3572 Next come NLINES 16-bit integers
3573
3574 NV[0] NV[1] NV[2] ... NV[NLINES-1]
3575
3576 giving the number of vertices in each polyline. A negative number
3577 indicates a closed polyline; 1 denotes a single-pixel point. The sum
3578 (of absolute values) of the NV[I] must equal NVERTICES.
3579
3580 Next come NLINES more 16-bit integers NC[I]: the number of colors in
3581 each polyline. Normally one of three values:
3582
3583 0
3584 No color is specified for this polyline. It's drawn in the same
3585 color as the previous polyline.
3586
3587 1
3588 A single color is specified. The entire polyline is drawn in that
3589 color.
3590
3591 abs(NV[I])
3592 Each vertex has a color. Either each segment is drawn in the
3593 corresponding color, or the colors are smoothly interpolated along
3594 the line segments, depending on the implementation.
3595
3596 Next come NVERTICES groups of 3 or 4 floating-point numbers: the
3597 coordinates of all the vertices. If the keyword is 4VECT then there
3598 are 4 values per vertex. The first abs(NV[0]) of them form the first
3599 polyline, the next abs(NV[1]) form the second and so on.
3600
3601 Finally NCOLORS groups of 4 floating-point numbers give red, green,
3602 blue and alpha (opacity) values. The first NC[0] of them apply to the
3603 first polyline, and so on.
3604
3605 A VECT BINARY format is accepted; *note Binary format::. The binary
3606 format exactly follows the ASCII format, with 32-bit Big-Endian
3607 integers where ordinary integer numbers appear, and with 16-bit
3608 Big-Endian integers where 16-bit integers appear; 32-bit Big-Endian
3609 floats where real values appear. BIG FAT NOTE: The vertex counts NV[I]
3610 and the color counts NC[I] are 16-bit Big-Endian integers.
3611
3612 
3613 File: geomview, Node: SKEL, Next: SPHERE, Prev: VECT, Up: Object File Formats
3614
3615 4.2.7 SKEL Files
3616 ----------------
3617
3618 `SKEL' files represent collections of points and polylines, with shared
3619 vertices. The conventional suffix for `SKEL' files is `.skel'.
3620
3621 Syntax:
3622
3623 [C][4][n]SKEL
3624 [NDIM] # Vertex dimension, present only if nSKEL
3625 NVERTICES NPOLYLINES
3626
3627 X[0] Y[0] Z[0] # Vertices
3628 # if 4SKEL, each vertex has 4 components
3629 # if nSKEL, each vertex has NDim components
3630 # if C[4][n]SKEL vertex coordinates are
3631 # followed by an RGBA color specification
3632 ...
3633 X[NVERTICES-1] Y[NVERTICES-1] Z[NVERTICES-1]
3634
3635 # Polylines
3636 # NV = vertices on this polyline (1 = point)
3637 # V[0] ... V[NV-1]: vertex indices
3638 # in range 0..NVERTICES-1
3639 NV V[0] V[1] ... V[NV-1] [COLORSPEC]
3640 ...
3641 # COLORSPEC continues past V[NV-1]
3642 # to end-of-line; may be nothing, or 3 or 4 numbers.
3643 # nothing: default color
3644 # 3 or 4 floats: RGB[A] values 0..1
3645
3646 The syntax resembles that of `OFF' files, with a table of vertices
3647 followed by a sequence of polyline descriptions, each referring to
3648 vertices by index in the table. Each polyline has an optional color.
3649
3650 For `nSKEL' objects, each vertex has NDIM components. For `4nSKEL'
3651 objects, each vertex has NDIM+1 components; the final component is the
3652 homogeneous divisor.
3653
3654 A [4][N]SKEL BINARY format is accepted; *Note Binary format::. It
3655 resembles the ASCII format in almost the way you'd expect, with 32-bit
3656 integers for all counters and vertex indices and 32-bit floats for
3657 vertex positions.
3658
3659 Exception: each polyline's vertex indices are followed by an integer
3660 indicating how many color components accompany it. Polyline color
3661 components must be floats, not integer values. Thus a colorless
3662 polyline with 3 vertices might be represented as
3663
3664 int int int int int
3665 3 17 5 9 0
3666
3667 while the same polyline colored red might be
3668
3669 int int int int int float float float float
3670 3 17 5 9 4 1.0 0.0 0.0 1.0
3671
3672 
3673 File: geomview, Node: SPHERE, Next: INST, Prev: SKEL, Up: Object File Formats
3674
3675 4.2.8 SPHERE Files
3676 ------------------
3677
3678 The conventional suffix for `SPHERE' files is `.sph'.
3679
3680 [ST][E|H|S]SPHERE # Keyword
3681 # auto-generated texture co-ordinates, only allowed with _ST_SPHERE objects
3682 [SINUSOIDAL|CYLINDRICAL|RECTANGULAR|STEREOGRAPHIC|ONEFACE]
3683 # next four fields are required
3684 RADIUS
3685 XCENTER YCENTER ZCENTER
3686
3687 The key word is `[ST][E|H|S]SPHERE'. The optional prefix
3688 characters mean:
3689
3690 `ST'
3691 The sphere carries automatically generated texture co-ordinates.
3692 See below.
3693
3694 `E'
3695 The sphere lives in Euclidean space.
3696
3697 `H'
3698 The sphere lives in Hyperbolic space. *Note Non-Euclidean
3699 Geometry::.
3700
3701 `S'
3702 The sphere lives in spherical space. *Note Non-Euclidean
3703 Geometry::.
3704
3705 Sphere objects are drawn using meshes which are rectangular in a
3706 polar co-ordinate system, with the equatorial plane parallel to the
3707 `x,y'-plane. Their smoothness, and the time taken to draw them, depends
3708 on the setting of the dicing level, 10x10 by default. From Geomview,
3709 the Appearance panel, the `<N>ad' keyboard command, or a `dice nu nv'
3710 Appearance attribute sets this.
3711
3712 Texture co-ordinates are generated for `STSPHERE' objects; the
3713 keyword following the initial `STSPHERE' keyword defines the way this
3714 is done. It follows the conventions of the `mktxmesh' Perl-script which
3715 comes with the _Orrery_.
3716
3717 SINUSOIDAL
3718 sinusoidal equal-area projection
3719
3720 CYLINDRICAL
3721 cylindrical proj: S is the longitude, T is the latitude
3722
3723 RECTANGULAR
3724 rectangular proj: S is the longitude, T is `sin(latitude)' (i.e.
3725 `z' co-ordinate in the sphere's co-ordinate system)
3726
3727 STEREOGRAPHIC
3728 stereographic projection from the south (`z=-1') pole
3729
3730 ONEFACE
3731 stretch orthographic view of `+y' hemisphere over both, mirroring
3732
3733 
3734 File: geomview, Node: INST, Next: LIST, Prev: SPHERE, Up: Object File Formats
3735
3736 4.2.9 INST Files
3737 ----------------
3738
3739 The conventional suffix for a `INST' file is `.inst'.
3740
3741 There is no INST BINARY format.
3742
3743 An `INST' applies a 4x4 (or (N+1)x(N+1) in the context of
3744 ND-viewing) transformation to another OOGL object. It begins with
3745 `INST' followed by these sections which may appear in any order:
3746 geom OOGL-OBJECT
3747 specifies the OOGL object to be instantiated. *Note References::,
3748 for the syntax of an OOGL-OBJECT. The keyword `unit' is a synonym for
3749 `geom'.
3750 transform ["{"] `4x4 transform' ["}"]
3751 specifies a single transformation matrix. Either the matrix may
3752 appear literally as 16 numbers, or there may be a reference to a
3753 "transform" object, i.e.
3754 "<" file-containing-4x4-matrix
3755 or
3756 ":" symbol-representing-transform-object
3757 Another way to specify the transformation is
3758 transforms
3759 OOGL-OBJECT
3760 The OOGL-OBJECT must be a `TLIST' object (list of transformations)
3761 object, or a `LIST' whose members are ultimately `TLIST' objects. In
3762 effect, the `transforms' keyword takes a collection of 4x4 matrices and
3763 replicates the `geom' object, making one copy for each 4x4 matrix.
3764
3765 If no `transform' nor `transforms' keyword appears, no
3766 transformation is applied (actually the identity is applied). You could
3767 use this for, e.g., wrapping an appearance around an externally-supplied
3768 object, though a single-membered LIST would do this more efficiently.
3769
3770 *Note Transformation matrices::, for the matrix format.
3771
3772 When replicating a single geometry by means of a `TLIST' object (see
3773 `transforms' above) it may be useful to transform texture co-ordinates
3774 by another list of transformations; that list can be specified by
3775 txtransforms
3776 TLIST-OBJECT
3777 The number of texture transformations must match the number of
3778 geometry transformations. The `SPHERE' object (*note Sphere Objects:
3779 SPHERE.) uses this technique to generate an entire textured sphere out
3780 of some fraction of a sphere (usually one octant).
3781
3782 A single (N+1)-dimensional transformation can be specified by
3783
3784 ntransform ["{"] N+1 N+1 `(N+1)x(N+1) floats' ["}"]
3785 This gives a single N+1-dimensional transformation matrix. Either
3786 the matrix may appear literally as (N+1)x(N+1) numbers, or there may be
3787 a reference to an `ntransform' object, i.e.
3788 "<" file-containing-(N+1)x(N+1)-matrix
3789 or
3790 ":" symbol-representing-ntransform-object
3791
3792 *Note ND Transformation matrices::, for the matrix format.
3793
3794 Two more INST fields are accepted: `location' and `origin'.
3795
3796 Note that `location' as well as `origin' are ignored if this `INST'
3797 object carries an `ntransform'. Also, if ND-viewing is active
3798 (`ND-axes' command, *note GCL::) then `INST' objects with `origin'
3799 unequal to `local' will not be drawn, though the `location' stuff may
3800 work (or not).
3801
3802 location [global or camera or ndc or screen or local]
3803 Normally an INST specifies a position relative to its parent object;
3804 the `location' field allows putting an object elsewhere.
3805 * `location global' attaches the object to the global (a.k.a.
3806 universe) coordinate system - the same as that in which geomview's
3807 World objects, alien geometry, and cameras are placed.
3808
3809 * `location camera' places the object relative to the camera. (Thus
3810 if there are multiple views, it may appear in a different spatial
3811 position in each view.) The center of the camera's view is along
3812 its negative Z axis; positive X is rightward, positive Y upward.
3813 Normally the units of camera space are the same as global
3814 coordinates. When a camera is reset, the global origin is at
3815 (0,0,-3.0).
3816
3817 * `location ndc' places the object relative to the normalized unit
3818 cube into which the camera's projection (perspective or
3819 orthographic) maps the visible world. X, Y, and Z are each in the
3820 range from -1 to +1, with Z = -1 the near and Z = +1 the far
3821 clipping plane, and X and Y increasing rightward and upward
3822 respectively. Thus something like
3823 INST transform 1 0 0 0 0 1 0 0 0 0 1 0 -.9 -.9 -.999 1
3824 location ndc
3825 geom < label.vect
3826 pastes `label.vect' onto the lower left corner of each window, and
3827 in front of nearly everything else, assuming `label.vect''s
3828 contents lie in the positive quadrant of the X-Y plane. It's
3829 tempting to use -1 rather than -.999 as the Z component of the
3830 position, but that may put the object just nearer than the near
3831 clipping plane and make it (partially) invisible, due to
3832 floating-point error.
3833
3834 * `location screen' places the object in screen coordinates. The
3835 range of Z is still -1 through +1 as for ndc coordinates; X and Y
3836 are measured in pixels, and range from (0,0) at the _lower left_
3837 corner of the window, increasing rightward and upward.
3838
3839 `location local' is the default; the object is positioned relative
3840 to its parent.
3841
3842 origin [global or camera or ndc or screen or local] x y z
3843 The `origin' field translates the contents of the INST to place the
3844 origin at the specified point of the given coordinate system. Unlike
3845 `location', it doesn't change the orientation, only the choice of
3846 origin. Both `location' and `origin' can be used together.
3847
3848 So for example
3849 { INST
3850 location screen
3851 origin ndc 0 0 -.99
3852 geom { < xyz.vect }
3853 transform { 100 0 0 0 0 100 0 0 0 0 -.009 0 0 0 0 1 }
3854 }
3855
3856 places xyz.vect's origin in the center of the window, just beyond the
3857 near clipping plane. The unit-length X and Y edges are scaled to be
3858 just 100 screen units - pixels - long, regardless of the size of the
3859 window.
3860
3861 * Menu:
3862
3863 * INST Examples:: Some example of `INST' Files.
3864
3865 
3866 File: geomview, Node: INST Examples, Prev: INST, Up: INST
3867
3868 4.2.9.1 INST Examples
3869 .....................
3870
3871 Here are some examples of `INST' files
3872
3873 INST
3874 unit < xyz.vect
3875 transform {
3876 1 0 0 0
3877 0 1 0 0
3878 0 0 1 0
3879 1 3 0 1
3880 }
3881
3882 { appearance { +edge material { edgecolor 1 1 0 } }
3883 INST geom < mysurface.quad }
3884
3885 {INST transform {: T} geom {<dodec.off}}
3886
3887 { INST
3888 transforms
3889 { LIST
3890 { < some-matrices.prj }
3891 { < others.prj }
3892 { TLIST <still more of them> }
3893
3894 }
3895 geom
3896 { # stuff replicated by all the above matrices
3897 ...
3898 }
3899 }
3900
3901 This one resembles the `origin' example in the section above, but
3902 makes the X and Y edges be 1/4 the size of the window (1/4, not 1/2,
3903 since the range of ndc X and Y coordinates is -1 to +1).
3904 { INST
3905 location ndc
3906 geom { < xyz.vect }
3907 transform { .5 0 0 0 0 .5 0 0 0 0 -.009 0 0 0 -.99 1 }
3908 }
3909
3910 
3911 File: geomview, Node: LIST, Next: TLIST, Prev: INST, Up: Object File Formats
3912
3913 4.2.10 LIST Files
3914 -----------------
3915
3916 The conventional suffix for a `LIST' file is `.list'.
3917
3918 A list of OOGL objects
3919
3920 Syntax:
3921
3922 LIST
3923 OOGL-OBJECT
3924 OOGL-OBJECT
3925 ...
3926
3927 Note that there's no explicit separation between the oogl-objects, so
3928 they should be enclosed in curly braces ({ }) for sanity. Likewise
3929 there's no explicit marker for the end of the list; unless appearing
3930 alone in a disk file, the whole construct should also be wrapped in
3931 braces, as in:
3932
3933 { LIST { QUAD ... } { < xyz.quad } }
3934
3935 A `LIST' with no elements, i.e. `{ LIST }', is valid, and is the
3936 easiest way to create an empty object. For example, to remove a
3937 symbol's definition you might write
3938
3939 { define somesymbol { LIST } }
3940
3941 
3942 File: geomview, Node: TLIST, Next: GROUP, Prev: LIST, Up: Object File Formats
3943
3944 4.2.11 TLIST Files
3945 ------------------
3946
3947 The conventional suffix for a `TLIST' file is `.grp' ("group") or
3948 `.prj' ("projective" matrices).
3949
3950 Collection of 4x4 matrices, used in the `transforms' section of and
3951 `INST' object.
3952
3953 Syntax:
3954
3955 TLIST # key word
3956 <4x4 matrix (16 floats)>
3957 ... # any number of 4x4 matrices
3958 transform { # reference to a transform object
3959 <transform object (can be a handle)>
3960 }
3961 tlist { # nested TLIST
3962 <TLIST OOGL object (can be a handle)>
3963 }
3964
3965 `TLIST's are used only within the `transforms' clause of an `INST'
3966 object. They cause the `INST's `geom' object to be instantiated once
3967 under each of the transforms in the `TLIST'. The effect is like that
3968 of a `LIST' of `INST's each with a single transform, and all referring
3969 to the same object, but is more efficient.
3970
3971 `TLIST's can be nested: effectively this means that all
3972 transformations in each nested `TLIST' object are multiplied (from the
3973 left) by the transformations in the outer `TLIST' object.
3974
3975 Be aware that a `TLIST' is a kind of geometry object, distinct from a
3976 `transform' object. Some contexts expect one type of object, some the
3977 other. For example in
3978 INST transform { : MYT } geom { ... }
3979 MYT must be a transform object, which might have been created with
3980 the GCL
3981 (read transform { define myT 1 0 0 1 ... })
3982 while in
3983 INST transforms { : MYTS } geom { ... }
3984 or
3985 INST transforms { LIST {: MYTS} {< more.prj} } geom { ... }
3986 MYTS must be a geometry object, defined e.g. with
3987 (read geometry { define MYTS { TLIST 1 0 0 1 ... } })
3988
3989 A `TLIST BINARY' format is accepted. Binary data begins with a
3990 32-bit integer giving the number of transformations, followed by that
3991 number of 4x4 matrices in 32-bit floating-point format. The order of
3992 matrix elements is the same as in the ASCII format.
3993
3994 
3995 File: geomview, Node: GROUP, Next: DISCGRP, Prev: TLIST, Up: Object File Formats
3996
3997 4.2.12 GROUP Files
3998 ------------------
3999
4000 This format is obsolete, but is still accepted. It combined the
4001 functions of `INST' and `TLIST', taking a series of transformations and
4002 a single Geom (`unit') object, and replicating the object under each
4003 transformation.
4004
4005 GROUP ... < matrices > ... unit { OOGL-OBJECT }
4006
4007 is still accepted and effectively translated into
4008
4009 INST
4010 transforms { TLIST ... <matrices> ... }
4011 unit { OOGL-OBJECT }
4012
4013 
4014 File: geomview, Node: DISCGRP, Next: COMMENT, Prev: GROUP, Up: Object File Formats
4015
4016 4.2.13 DISCGRP Files
4017 --------------------
4018
4019 This format is for discrete groups, such as appear in the theory of
4020 manifolds or in symmetry patterns. This format has its own man page.
4021 See discgrp(5).
4022
4023 
4024 File: geomview, Node: COMMENT, Prev: DISCGRP, Up: Object File Formats
4025
4026 4.2.14 COMMENT Objects
4027 ----------------------
4028
4029 The COMMENT object is a mechanism for encoding arbitrary data within an
4030 OOGL object. It can be used to keep track of data or pass data back and
4031 forth between external modules.
4032
4033 Syntax:
4034
4035 COMMENT # key word
4036
4037 NAME TYPE # individual name and type specifier
4038 { ... } # arbitrary data
4039
4040 The data, which must be enclosed by curly braces, can include
4041 anything except unbalanced curly braces. The TYPE field can be used to
4042 identify data of interest to a particular program through naming
4043 conventions.
4044
4045 `COMMENT' objects are intended to be associated with other objects
4046 through inclusion in a `LIST' object. (*Note LIST::.) The "#" OOGL
4047 comment syntax does not suffice for data exchange since these comments
4048 are stripped when an OOGL object is read in to Geomview. The `COMMENT'
4049 object is preserved when loaded into Geomview and is written out intact.
4050
4051 Here is an example associating a WorldWide Web URL with a piece of
4052 geometry:
4053
4054 { LIST
4055 { < Tetrahedron}
4056 {COMMENT GCHomepage HREF { http://www.geomview.org/ }}
4057 }
4058
4059 A binary `COMMENT' format is accepted. Its format is not consistent
4060 with the other OOGL binary formats. *Note Binary format::. The `name'
4061 and `type' are followed by
4062
4063 N BYTE1 BYTE2 ... BYTEN
4064
4065 instead of data enclosed in curly braces.
4066
4067 
4068 File: geomview, Node: Non-geometric objects, Prev: Object File Formats, Up: OOGL File Formats
4069
4070 4.3 Non-geometric objects
4071 =========================
4072
4073 The syntax of these objects is given in the form used in *Note
4074 References::, where "quoted" items should appear literally but without
4075 quotes, square bracketed ([ ]) items are optional, and | separates
4076 alternative choices.
4077
4078 * Menu:
4079
4080 * appearance objects:: Appearance objects.
4081 * image objects:: Image objects.
4082 * transform objects:: Transformation matrices.
4083 * ntransform objects:: N-dimensional transformation matrices.
4084 * camera objects:: Cameras.
4085 * window objects:: Windows.
4086
4087 
4088 File: geomview, Node: appearance objects, Next: image objects, Prev: Non-geometric objects, Up: Non-geometric objects
4089
4090 4.3.1 Appearance Objects
4091 ------------------------
4092
4093 Appearances are OOGL objects of their own right, which simply means that
4094 it is possible to give them symbolic names (*note References::). There
4095 are other sections dealing with appearance details. *Note Appearances::.
4096
4097 
4098 File: geomview, Node: image objects, Next: transform objects, Prev: appearance objects, Up: Non-geometric objects
4099
4100 4.3.2 Image Objects
4101 -------------------
4102
4103 Image objects are used to specify pixmap data for either textures
4104 (*note Texture Mapping::), or for background images of cameras (*note
4105 Camera objects: camera.).
4106
4107 At the time of this writing images are comprised of 1 to 4 channels,
4108 a channel provides a single number in the range from 0 to `maxval' for
4109 each pixel; and `maxval' is tied to 255. The interpretation of the
4110 image data depending on the number of channels is like follows:
4111
4112 #Channels Channel No. Interpretation
4113 --------------------------------------------------------------------------
4114 1 1 greyscale or luminance data
4115 2 1 greyscale or luminance data
4116 ` ' 2 alpha channel (0: transparent, `maxval':
4117 opaque)
4118 3 1 red channel
4119 `' 2 green channel
4120 `' 3 blue channel
4121 4 1 red channel
4122 `' 2 green channel
4123 `' 3 blue channel
4124 `' 4 alpha channel (0: transparent, `maxval':
4125 opaque)
4126
4127 Image data can be specified inline (embedded into the current data
4128 stream) or via file references; in both cases the data is read in and
4129 interpreted at the time the image object is parsed. _This is different
4130 from the old (and deprecated) texture image specification, where the
4131 the image data on-disk would eventually be re-read by Geomview_.
4132
4133 The general syntax of image objects is like follows:
4134 <image> ::=
4135 [ "{" ] (curly brace, generally needed to make
4136 the end of the object unambiguous.)
4137 [ "image" ] (optional keyword; unnecessary if the type
4138 is determined by the context, which it
4139 usually is.)
4140 [ "define" <name> ]
4141 (defines an image named <name>, setting
4142 its value from the stuff which follows)
4143 |
4144 "<" <filename> (meaning: read image from that file)
4145 |
4146 ":" <name> (meaning: use variable NAME,
4147 defined elsewhere; if undefined the image
4148 carries no data)
4149 |
4150 (actual stuff defining the image; image data
4151 must come last, after defining the width and
4152 height and number of channels)
4153
4154 "width" (width of the image, auto-detected from image data
4155 if possible)
4156
4157 "height" (height of the image, auto-detected from image data
4158 if possible)
4159
4160 "channels" (number of channels, auto-detected from image data
4161 and `data' specifications, if possible)
4162
4163 "maxval" (unsupported, must be `255' if specified)
4164
4165 "data DESTMASK [FILTER] [{] < FILENAME [}]"
4166 "data DESTMASK [FILTER] DATASIZE [{][\n]LITERAL_IMAGE_DATA[}]"
4167 (either external or embedded image data, see below
4168 for a detailed description of the meaning of
4169 _MASK_ and _FILTER_. An image can (and
4170 has, in general) multiple data sections.)
4171
4172 [ "}" ] (matching curly brace)
4173
4174 Details concerning the image data specification:
4175
4176 `DESTMASK'
4177 This is a bit-field describing where the specified image data
4178 should be placed in the destination pixmap. The bit-field is
4179 specified by an integer in one of the known formats (decimal,
4180 octal, hexadecimal). The channels of the source data are always
4181 enumbered consecutively. If, e.g. `FILENAME' or
4182 `LITERAL_IMAGE_DATA' specify a three-channel (probably RGB ...)
4183 image and `DESTMASK' equals `0xD' (i.e. bit 1 is 0), then the 3rd
4184 channel of the source pixmap would be placed in the 4th channel of
4185 the destination image object (the alpha channel), the 2nd source
4186 channel would determine the `blue' destination value and the 1st
4187 source channel the `red' destination value.
4188
4189 The number of channels of the source data always has to match the
4190 number of bits set in `DESTMASK'. Exception: if the source pixmap
4191 has only one channel, then it can be used to fill any number of
4192 destination channels; all channels specified in `DESTMASK' are
4193 filled with the data of the single channel source pixmap.
4194
4195 Geomview knows the following symbolic constants, which can be used
4196 instead of specifying the `DESTMASK' bit-field numerically:
4197 `LUMINANCE'
4198 same as `1', `0x1', `\01'
4199
4200 `LUMINANCE_ALPHA'
4201 same as `3', `0x3', `\03'
4202
4203 `RGB'
4204 same as `7', `0x7', `\07'
4205
4206 `RGBA'
4207 same as `15', `0xf', `\017'
4208
4209 `ALPHA'
4210 depends on the context: the absolute number of channels must
4211 be known; i.e. `data ALPHA ...' must be prepended by
4212 something determining the number of channels of the image,
4213 e.g.
4214 ...
4215 data RGB ...
4216 data ALPHA
4217 ...
4218 is valid, but
4219 <no other channel or image data specification>
4220 data ALPHA ...
4221 <whatever else ...>
4222 is not valid, because Geomview has not means to determine the
4223 destination channel from the context.
4224
4225 `AUTO'
4226 PGM image data is interpreted as single grey-scale channel,
4227 RGB PNM data as RGB image data. `AUTO' cannot work with `raw'
4228 image data.
4229
4230 `FILTER'
4231 The `FILTER' specification is optional. If it is missing, then
4232 Geomview tries to determine the image type from the `FILENAME'
4233 suffix. If there is no suffix or the suffix is unknown, or for
4234 embedded image data, Geomview is able to auto-detectc SGI image
4235 file formats (for historical reasons ...) and NetPBM image formats
4236 (for practical reasons). The auto-detection of NetPBM formats
4237 includes the new "PAM" image format which allows (among other
4238 things) to store an alpha channel together with the luminance or
4239 RGB data. Likewise, the final output of any of the specified
4240 filters must either be in SGI image file format, or specify a PAM,
4241 PNM or PGM image. If the image file format cannot be determined
4242 by either the filenmae suffix or the filter specification or by
4243 auto-deteciong of SGI or NetPBM data, then Geomview assume that it
4244 is raw-data. See below.
4245
4246 The decompression filters may be prepended to either one of the
4247 know image formats or an explicitly specified filter, e.g. the
4248 following is valid:
4249 data LUMINANCE raw.gzip { < gzippedgreymapfile }
4250 The above should be equivalent to
4251 data LUMINANCE raw { < greymapfile },
4252 provided that the decompressed data carries single channel data,
4253 with the first pixel corresponding to the lower-left corner
4254 (because of the `raw' image format, see below).
4255
4256 Geomview has builtin knowledge for the following filters/suffixes:
4257 Data Decompression
4258
4259 `z'
4260
4261 `gz'
4262
4263 `gzip'
4264 data is piped through `gzip -dc'
4265
4266 `bz2'
4267
4268 `bzip2'
4269 data is piped through `bzip2 -dc'
4270
4271 Image Formats
4272
4273 `tiff'
4274
4275 `tif'
4276 `TIFF' image file format. Only supported if the
4277 `tifftopnm' executable can be fond in the current
4278 excution path.
4279
4280 `png'
4281 `PNG' image file format. Only supported if the `pngtopnm'
4282 executable can be fond in the current excution path.
4283
4284 `jpg'
4285
4286 `jpeg'
4287 `JPEG' image file format. Only supported if the
4288 `jpegtopnm' executable can be fond in the current
4289 excution path.
4290
4291 `gif'
4292 `GIF' image file format. Only supported if the `giftoppm'
4293 executable can be fond in the current excution path.
4294
4295 `raw'
4296 Raw image data; the number of channels must match the
4297 number of bits set in `DESTMASK'. Pixels are specified
4298 with 1 byte per channel. The pixels are organized in
4299 rows as `liminance[-alpha]' or `RGB[A]' samples. The
4300 left-most pixel is the first pixel in each data-row, the
4301 top-most image row must come first (this is just the same
4302 as the NetPBM convention, the image co-ordinate systems
4303 has its origin in the left/top corner, as usual).
4304
4305 Explicitly Specified Filters
4306 If none of the suffixes specified above should match, then the
4307 suffix/filter is interpreted as an external filter program;
4308 the filter program must read from `STDIN' and write to
4309 `STDOUT'. The output must either be in SGI image format, or
4310 in PNM or PGM format. Otherwise the output data is
4311 interpreted as raw image data (see above).
4312
4313 Something like the following should work, provided that the
4314 program `${HOME}/bin/bububfilter' exists, is executable and
4315 does something useful:
4316 ...
4317 data RGB "${HOME}/bin/bububfilter.bzip2" 7 { # binary data follows
4318 bububub
4319 }
4320 ...
4321
4322 Note that - prior to feeding the data to the `bububfilter' -
4323 Geomview will try to decompress the stuff with `bzip2 -dc'.
4324
4325
4326
4327 Missing image data: Normally, the number of image channels is
4328 determined automatically from the image `data' specifications; if the
4329 image specification carries an explicit number of channels via the
4330 `channels' keyword which exceeds the number of channels found in the
4331 image `data' specifications, or if the union of all `DESTMASK'
4332 specfications has holes, then missing luminance and RGB channels are
4333 initialized to 0, and a missing alpha-channel is initialized to
4334 `maxval', i.e. omitting the alpha channel data for an RGBA image is
4335 just the same as defining an RGB image.
4336
4337 
4338 File: geomview, Node: transform objects, Next: ntransform objects, Prev: image objects, Up: Non-geometric objects
4339
4340 4.3.3 Transform Objects
4341 -----------------------
4342
4343 Where a single 4x4 matrix is expected - as in the `INST' `transform'
4344 field, the camera's `camtoworld' transform and the Geomview `xform*'
4345 commands - use a transform object.
4346
4347 Note that a transform is distinct from a `TLIST', which is a type of
4348 geometry. `TLIST's can contain one or more 4x4 transformations;
4349 "transform" objects must have exactly one.
4350
4351 Why have both? In many places - e.g. camera positioning - it's only
4352 meaningful to have a single transform. Using a separate object type
4353 enforces this.
4354
4355 Syntax for a transform object is
4356
4357 <transform> ::=
4358 [ "{" ] (curly brace, generally needed to make
4359 the end of the object unambiguous.)
4360
4361 [ "transform" ] (optional keyword; unnecessary if the type
4362 is determined by the context, which it
4363 usually is.)
4364 [ "define" <name> ]
4365 (defines a transform named <name>, setting
4366 its value from the stuff which follows)
4367
4368 <sixteen floating-point numbers>
4369 (interpreted as a 4x4 homogeneous transform
4370 given row by row, intended to apply to a
4371 row vector multiplied on its LEFT, so that e.g.
4372 Euclidean translations appear in the bottom row)
4373 |
4374 "<" <filename> (meaning: read transform from that file)
4375 |
4376 ":" <name> (meaning: use variable <name>,
4377 defined elsewhere; if undefined the initial
4378 value is the identity transform)
4379
4380 [ "}" ] (matching curly brace)
4381
4382 The whole should be enclosed in { braces }. Braces are not essential
4383 if exactly one of the above items is present, so e.g. a 4x4 array of
4384 floats standing alone may but needn't have braces.
4385
4386 Some examples, in contexts where they might be used:
4387
4388 # Example 1: A GCL command to define a transform
4389 # called "fred"
4390
4391 (read transform { transform define fred
4392 1 0 0 0
4393 0 1 0 0
4394 0 0 1 0
4395 -3 0 1 1
4396 }
4397 )
4398
4399 # Example 2: A camera object using transform
4400 # "fred" for camera positioning
4401 # Given the definition above, this puts the camera at
4402 # (-3, 0, 1), looking toward -Z.
4403
4404 { camera
4405 halfyfield 1
4406 aspect 1.33
4407 camtoworld { : fred }
4408 }
4409
4410 
4411 File: geomview, Node: ntransform objects, Next: camera objects, Prev: transform objects, Up: Non-geometric objects
4412
4413 4.3.4 ND-Transform Objects
4414 --------------------------
4415
4416 Where - in the context of ND-viewing - a single (N+1)x(N+1) matrix is
4417 expected - as in the `INST' `ntransform' field, or the `ND-xform*'
4418 (*note GCL::) commands - use an `ntransform' object.
4419
4420 `ntransform' are NROWS x NCOLS transformation matrix where usually
4421 NROWS = N+1 in the context of N-dimensional objects and viewing. The
4422 homogeneous component of an `ntransform' sits at column zero (in
4423 contrast to ordinary `transform' objects where it is located at column
4424 three). `ntransform' objects operate on points of any dimension: if a
4425 point is to be transformed by an `ntransform' object and the dimension
4426 of the point does not match the number of rows of the `ntransform'
4427 object, then either the point is implicitly padded with zeros to match
4428 NROWS or the matrix is implicitly padded with ones down its diagonal
4429 (and zeros everywhere else) such that it will operate as identity on
4430 the excess dimensions of the input point.
4431
4432 Syntax for an `ntransform' object is
4433
4434 <ntransform> ::=
4435 [ "{" ] (curly brace, generally needed to make
4436 the end of the object unambiguous.)
4437
4438 [ "ntransform" ] (optional keyword; unnecessary if the type
4439 is determined by the context, which it
4440 usually is.)
4441
4442 [ "define" <name> ]
4443 (defines a transform named <name>, setting
4444 its value from the stuff which follows)
4445
4446 NROWS NCOLS
4447 (number of rows and columns of the matrix,
4448 typically N+1 N+1, but any dimensions
4449 are possible)
4450 <NROWS x NCOLS floating-point numbers>
4451 (interpreted as a NROWS x NCOLS
4452 homogeneous transform given row by row, intended
4453 to apply to a row vector multiplied on its LEFT,
4454 so that e.g. Euclidean translations appear in the
4455 top row -- in contrast to the ordinary
4456 transform objects where the translations appear
4457 in the bottom row)
4458 |
4459 "<" <filename> (meaning: read transform from that file)
4460 |
4461 ":" <name> (meaning: use variable <name>,
4462 defined elsewhere; if undefined the initial
4463 value is the identity transform)
4464
4465 [ "}" ] (matching curly brace)
4466
4467 The whole should be enclosed in { braces }. Braces are not
4468 necessarily essential, so e.g. two integers - NROWS NCOLS - followed by
4469 a NROWS x NCOLS array of floats standing alone may but needn't have
4470 braces.
4471
4472 Some examples, in contexts where they might be used:
4473
4474 # Example 1: A GCL command to define a `6x6' transform called
4475 # "fred", a mere translation by the vector `-3 0 1 1 0'. This
4476 # transform is meant for a five dimensional space, with an homogeneous
4477 # component a index zero.
4478
4479 (read ntransform { ntransform define fred
4480 6 6
4481 1 -3 0 1 1 0
4482 0 1 0 0 0 0
4483 0 0 1 0 0 0
4484 0 0 0 1 0 0
4485 0 0 0 0 1 0
4486 0 0 0 0 0 1
4487 }
4488 )
4489
4490 # Example 2: Set the ND-xform of an object -- a geometry or a camera
4491 # cluster. Given the definition above, this puts the object at (-3 0 1 1
4492 # 0) in the five dimensional space.
4493
4494 (ND-xform-set focus : fred)
4495
4496 # or
4497
4498 (ND-xform-set g1 : fred)
4499
4500 
4501 File: geomview, Node: camera objects, Next: window objects, Prev: ntransform objects, Up: Non-geometric objects
4502
4503 4.3.5 cameras
4504 -------------
4505
4506 A camera object specifies the following properties of a camera:
4507
4508 position and orientation
4509 specified by either a camera-to-world or world-to-camera
4510 transformation; this transformation does not include the
4511 projection, so it's typically just a combination of translation
4512 and rotation. Specified as a transform object, typically a 4x4
4513 matrix.
4514
4515 "focus" distance
4516 Intended to suggest a typical distance from the camera to the
4517 object of interest; used for default camera positioning (the
4518 camera is placed at (X,Y,Z) = (0,0,focus) when reset) and for
4519 adjusting field-of-view when switching between perspective and
4520 orthographic views.
4521
4522 window aspect ratio
4523 True aspect ratio in the sense <Xsize>/<Ysize>. This normally
4524 should agree with the aspect ratio of the camera's window.
4525 Geomview normally adjusts the aspect ratio of its cameras to match
4526 their associated windows.
4527
4528 near and far clipping plane distances
4529 Note that both must be strictly greater than zero. Very large
4530 <far>/<near> distance ratios cause Z-buffering to behave badly;
4531 part of an object may be visible even if somewhat more distant
4532 than another.
4533
4534 field of view
4535 Specified in either of two forms.
4536 `fov'
4537 is the field of view - in degrees if perspective, or linear
4538 distance if orthographic - in the _shorter_ direction.
4539
4540 `halfyfield'
4541 is half the projected Y-axis field, in world coordinates (not
4542 angle!), at unit distance from the camera. For a perspective
4543 camera, halfyfield is related to angular field:
4544
4545 halfyfield = tan( Y_axis_angular_field / 2 )
4546
4547 while for an orthographic one it's simply:
4548
4549 halfyfield = Y_axis_linear_field / 2
4550
4551 This odd-seeming definition is (a) easy to calculate with and (b)
4552 well-defined in both orthographic and perspective views.
4553
4554 background color
4555 Arguably not a property of a camera, but of the scene.
4556 Nevertheless, as there is no "background" OOGL object, and the
4557 background color should not be a property of the drawing device,
4558 it can be specified here. At the time of this writing, however,
4559 the GUI always overrides the background color with its own
4560 settings.
4561
4562 background image
4563 Same reasoning as above, only that the GUI does not override this
4564 setting. The image is centered at NDC co-ordinates `(0,0,-1)'; it
4565 is not resized, just painted behind everything else as is. *Note
4566 Image objects: image.
4567
4568
4569 The syntax for a camera is:
4570
4571 <camera> ::=
4572
4573 [ "camera" ] (optional keyword)
4574 [ "{" ] (opening brace, generally required)
4575 [ "define" <name> ]
4576
4577 "<" <filename>
4578 |
4579 ":" <name>
4580 |
4581 (or any number of the following,
4582 in any order...)
4583
4584 "perspective" {"0" | "1"} (default 1)
4585 (otherwise orthographic)
4586
4587 "stereo" {"0" | "1"} (default 0)
4588 (otherwise mono)
4589
4590 "worldtocam" <transform> (see transform syntax above)
4591
4592 "camtoworld" <transform>
4593 (no point in specifying both
4594 camtoworld and worldtocam; one is
4595 constrained to be the inverse of the other)
4596
4597 "halfyfield" <half-linear-Y-field-at-unit-distance>
4598 (default tan 40/2 degrees)
4599
4600 "fov" (angular field-of-view if perspective,
4601 linear field-of-view otherwise.
4602 Measured in whichever direction is smaller,
4603 given the aspect ratio. When aspect ratio
4604 changes -- e.g. when a window is reshaped --
4605 "fov" is preserved.)
4606
4607 "frameaspect" <aspect-ratio> (X/Y) (default 1.333)
4608
4609 "near" <near-clipping-distance> (default 0.1)
4610
4611 "far" <far-clipping-distance> (default 10.0)
4612
4613 "focus" <focus-distance> (default 3.0)
4614
4615 "bgcolor" <float RGB(A) color> (default 1/3 1/3 1/3 1)
4616
4617 "bgimage" { <image specification> } (default no background image)
4618
4619 [ "}" ] (matching closebrace)
4620
4621 
4622 File: geomview, Node: window objects, Prev: camera objects, Up: Non-geometric objects
4623
4624 4.3.6 window
4625 ------------
4626
4627 A window object specifies size, position, and other window-system
4628 related information about a window in a device-independent way.
4629
4630 The syntax for a window object is:
4631
4632 window ::=
4633
4634 [ "window" ] (optional keyword)
4635 [ "{" ] (curly brace, often required)
4636
4637 (any of the following, in any order)
4638
4639 "size" <xsize> <ysize>
4640 (size of the window)
4641
4642 "position" <xmin> <xmax> <ymin> <ymax>
4643 (position & size)
4644
4645
4646 "noborder"
4647 (specifies the window should
4648 have no window border)
4649
4650 "pixelaspect" <aspect>
4651 (specifies the true visual aspect ratio
4652 of a pixel in this window in the sense
4653 xsize/ysize, normally 1.0.
4654 For stereo hardware which stretches the
4655 display vertically by a factor of 2,
4656 ``pixelaspect 0.5'' might do.
4657 The value is used when computing the
4658 projection of a camera associated with
4659 this window.)
4660
4661 [ "}" ] (matching closebrace)
4662
4663 Window objects are used in the Geomview `window' and `ui-panel'
4664 commands to set default properties for future windows or to change
4665 those of an existing window. *Note `(window ...)': window. *Note
4666 `(ui-panel ...)': ui-panel.
4667
4668 
4669 File: geomview, Node: Customization, Next: Modules, Prev: OOGL File Formats, Up: Top
4670
4671 5 Customization: `.geomview' files
4672 **********************************
4673
4674 When Geomview is started, it loads and executes commands in a
4675 system-wide startup file named `.geomview'. This file is in the `data'
4676 subdirectory of the Geomview distribution directory and contains GCL
4677 commands to configure Geomview in a way common to all users on the
4678 system.
4679
4680 Next, Geomview looks for the file `~/.geomview' (`~' stands for your
4681 home directory). You can use this to configure your own default
4682 Geomview behavior to suit your tastes.
4683
4684 After reading `~/.geomview', Geomview looks for a file named
4685 `.geomview' in the current directory. If such a file exists Geomview
4686 reads it, unless it is the same as `~/.geomview' (which would be the
4687 case if you are running Geomview from your home directory). You can
4688 use the current directory's `.geomview' to create a Geomview
4689 customization specific to a certain project.
4690
4691 You can use `.geomview' files to control all kinds of things about
4692 Geomview. They can contain any valid GCL statements. Especially useful
4693 is the `ui-panel' command which controls the initial placement of
4694 Geomview's panels. For an example see the system-wide `.geomview' file
4695 mentioned above. *Note GCL::. *Note `(ui-panel ...)': ui-panel.
4696
4697 It is a good idea to enclose all the commands you put in a
4698 `.geomview' file in a `progn' statement in order to cause Geomview to
4699 execute them all at once. Otherwise Geomview might execute them
4700 sequentially over the first few refresh cycles after starting up.
4701
4702 To change, e.g. the focus policy of the camera window such that they
4703 pick up the focus policy of the window manager (instead of being
4704 activated when the mouse cursor crosses the window), you could put the
4705 following in your `~/.geomview' file:
4706
4707 (progn
4708 (ui-cam-focus focus-change)
4709 ... # other stuff
4710 )
4711
4712 You can put any valid `GCL' command into your `.geomview'
4713 files,*note GCL::. *Note `(progn ...)': progn. *Note `(ui-cam-focus
4714 ...)': ui-cam-focus.
4715
4716 
4717 File: geomview, Node: Modules, Next: GCL, Prev: Customization, Up: Top
4718
4719 6 External Modules
4720 ******************
4721
4722 An external module is a program that interacts with Geomview. A module
4723 communicates with Geomview through GCL and can control any apsect of
4724 Geomview that you can control through Geomview's user interface.
4725
4726 In many cases an external module is a specialized program that
4727 implements some mathematical algorithm that creates a geometric object
4728 that changes shape as the algorithm progresses. The module informs
4729 Geomview of the new object shape at each step, so the object appears to
4730 evolve with time in the Geomview window. In this way Geomview serves
4731 as a _display engine_ for the module.
4732
4733 An external module may be interactive. It can respond to mouse and
4734 keyboard events that take place in a Geomview window, thus extending
4735 the capability of Geomview itself.
4736
4737 * Menu:
4738
4739 * Interface:: How External Modules Interface with Geomview.
4740 * Example1:: Simple External Module.
4741 * Example2:: Simple External Module with FORMS Control Panel.
4742 * XForms:: The XForms library.
4743 * Example3:: External Module with Bi-Directional Communication.
4744 * Example4:: Simple Tcl/Tk Module Demonstrating Picking.
4745 * Module Installation:: Module Installation.
4746
4747 
4748 File: geomview, Node: Interface, Next: Example1, Prev: Modules, Up: Modules
4749
4750 6.1 How External Modules Interface with Geomview
4751 ================================================
4752
4753 External modules appear in the _Modules_ browser in Geomview's _Main_
4754 panel. To run a module, click the left mouse button on the module's
4755 entry in the browser. While the module is running, an additional line
4756 for that module will appear in the browser. This line begins with a
4757 number in brackets, which indicates the _instace_ number of the module.
4758 (For some modules it makes sense to have more than one instance of the
4759 module running at the same time.) You can kill an external module by
4760 clicking on its instance entry.
4761
4762 By default when Geomview starts, it displays all the modules that
4763 have been installed on your system.
4764
4765 For instructions on installing a module on your system so that it
4766 will appear in the _Modules_ browser every time Geomview is run by
4767 anyone on your system, *Note Module Installation::.
4768
4769 When Geomview invokes an external module, it creates pipes connected
4770 to the module's standard input and output. (Pipes are like files except
4771 they are used for communication between programs rather than for
4772 storing things on a disk.) Geomview interprets anything that the
4773 module writes to its standard output as a GCL command. Likewise, if
4774 the external module requests any data from Geomview, Geomview writes
4775 that data to the module's standard input. Thus all a module has to do
4776 in order to communicate with Geomview is write commands to standard
4777 output and (optionally) receive data on standard input. Note that this
4778 means that the module cannot use standard input and output for
4779 communicating with the user. If a module needs to communicate with the
4780 user it can do so either through a control panel of its own or else by
4781 responding to certain events that it finds out about from Geomview.
4782
4783 
4784 File: geomview, Node: Example1, Next: Example2, Prev: Interface, Up: Modules
4785
4786 6.2 Example 1: Simple External Module
4787 =====================================
4788
4789 This section gives a very simple external module which displays an
4790 oscillating mesh. To try out this example, make a copy of the file
4791 `example1.c' (it is distributed with Geomview in the `doc'
4792 subdirectory) in your directory and compile it with the command
4793
4794 cc -o example1 example1.c -lm
4795
4796 Then put the line
4797
4798 (emodule-define "Example 1" "./example1")
4799
4800 in a file called `.geomview' in your current directory. Then invoke
4801 Geomview; it is important that you compile the example program, create
4802 the `.geomview' file, and invoke Geomview all in the same directory.
4803 You should see "Example 1" in the _Modules_ browser of Geomview's
4804 _Main_ panel; click on this entry in the browser to start the module.
4805 A surface should appear in your camera window and should begin
4806 oscillating. You can stop the module by clicking on the "[1] Example
4807 1" line in the _Modules_ browser.
4808
4809 /*
4810 * example1.c: oscillating mesh
4811 *
4812 * This example module is distributed with the Geomview manual.
4813 * If you are not reading this in the manual, see the "External
4814 * Modules" chapter of the manual for more details.
4815 *
4816 * This module creates an oscillating mesh.
4817 */
4818
4819 #include <math.h>
4820 #include <stdio.h>
4821
4822 /* F is the function that we plot
4823 */
4824 float F(x,y,t)
4825 float x,y,t;
4826 {
4827 float r = sqrt(x*x+y*y);
4828 return(sin(r + t)*sqrt(r));
4829 }
4830
4831 main(argc, argv)
4832 char **argv;
4833 {
4834 int xdim, ydim;
4835 float xmin, xmax, ymin, ymax, dx, dy, t, dt;
4836
4837 xmin = ymin = -5; /* Set x and y */
4838 xmax = ymax = 5; /* plot ranges */
4839 xdim = ydim = 24; /* Set x and y resolution */
4840 dt = 0.1; /* Time increment is 0.1 */
4841
4842 /* Geomview setup. We begin by sending the command
4843 * (geometry example { : foo})
4844 * to Geomview. This tells Geomview to create a geom called
4845 * "example" which is an instance of the handle "foo".
4846 */
4847 printf("(geometry example { : foo })\n");
4848 fflush(stdout);
4849
4850 /* Loop until killed.
4851 */
4852 for (t=0; ; t+=dt) {
4853 UpdateMesh(xmin, xmax, ymin, ymax, xdim, ydim, t);
4854 }
4855 }
4856
4857 /* UpdateMesh sends one mesh iteration to Geomview. This consists of
4858 * a command of the form
4859 * (read geometry { define foo
4860 * MESH
4861 * ...
4862 * })
4863 * where ... is the actual data of the mesh. This command tells
4864 * Geomview to make the value of the handle "foo" be the specified
4865 * mesh.
4866 */
4867 UpdateMesh(xmin, xmax, ymin, ymax, xdim, ydim, t)
4868 float xmin, xmax, ymin, ymax, t;
4869 int xdim, ydim;
4870 {
4871 int i,j;
4872 float x,y, dx,dy;
4873
4874 dx = (xmax-xmin)/(xdim-1);
4875 dy = (ymax-ymin)/(ydim-1);
4876
4877 printf("(read geometry { define foo \n");
4878 printf("MESH\n");
4879 printf("%1d %1d\n", xdim, ydim);
4880 for (j=0, y = ymin; j<ydim; ++j, y += dy) {
4881 for (i=0, x = xmin; i<xdim; ++i, x += dx) {
4882 printf("%f %f %f\t", x, y, F(x,y,t));
4883 }
4884 printf("\n");
4885 }
4886 printf("})\n");
4887 fflush(stdout);
4888 }
4889
4890 The module begins by defining a function `F(x,y,t)' that specifies a
4891 time-varying surface. The purpose of the module is to animate this
4892 surface over time.
4893
4894 The main program begins by defining some variables that specify the
4895 parameters with which the function is to be plotted.
4896
4897 The next bit of code in the main program prints the following line
4898 to standard output
4899
4900 (geometry example { : foo })
4901
4902 This tells Geomview to create a geom called `example' which is an
4903 instance of the handle `foo'. _Handles_ are a part of the OOGL file
4904 format which allow you to name a piece of geometry whose value can be
4905 specified elsewhere (and in this case updated many times); for more
4906 information on handles, *Note OOGL File Formats::. In this case,
4907 `example' is the title by which the user will see the object in
4908 Geomview's object browser, and `foo' is the internal name of the handle
4909 that the object is a reference to.
4910
4911 We then do `fflush(stdout)' to ensure that Geomview receives this
4912 command immediately. In general, since pipes may be buffered, an
4913 external module should do this whenever it wants to be sure Geomview
4914 has actually received everything it has printed out.
4915
4916 The last thing in the main program is an infinite loop that cycles
4917 through calls to the procedure `UpdateMesh' with increasing values of
4918 `t'. `UpdateMesh' sends Geomview a command of the form
4919
4920 (read geometry { define foo
4921 MESH
4922 24 24
4923 ...
4924 })
4925
4926 where `...' is a long list of numbers. This command tells Geomview to
4927 make the value of the handle `foo' be the specified mesh. As soon as
4928 Geomview receives this command, the geom being displayed changes to
4929 reflect the new geometry.
4930
4931 The mesh is given in the format of an OOGL MESH. This begins with
4932 the keyword `MESH'. Next come two numbers that give the x and y
4933 dimensions of the mesh; in this case they are both 24. This line is
4934 followed by 24 lines, each containing 24 triples of numbers. Each of
4935 these triples is a point on the surface. Then finally there is a line
4936 with "`})'" on it that ends the "`{'" which began the `define'
4937 statement and the "`('" that began the command. For more details on
4938 the format of MESH data, *note MESH::.
4939
4940 This module could be written without the use of handles by having it
4941 write out commands of the form
4942
4943 (geometry example {
4944 MESH
4945 24 24
4946 ...
4947 })
4948
4949 This first time Geomview receives a command of this form it would create
4950 a geom called `example' with the given `MESH' data. Subsequent
4951 `(geometry example ...)' commands would cause Geomview to replace the
4952 geometry of the geom `example' with the new `MESH' data. If done in
4953 this way there would be no need to send the initial `(geometry example
4954 { : foo })' command as above. The handle technique is useful, however,
4955 because it can be used in more general situations where a handle
4956 represents only part of a complex geom, allowing an external module to
4957 replace only that part without having to retransmit the entire geom.
4958 For more information on handles, *note GCL::. *Note References::. *Note
4959 `(hdefine ...)': hdefine. *Note `(read ...)': read.
4960
4961 The module loops through calls to `UpdateMesh' which print out
4962 commands of the above form one after the other as fast as possible.
4963 The loop continues indefinitely; the module will terminate when the
4964 user kills it by clicking on its instance line in the _Modules_
4965 browser, or else when Geomview exits.
4966
4967 Sometimes when you terminate this module by clicking on its instance
4968 entry the _Modules_ browser, Geomview will kill it while it is in the
4969 middle of sending a command to Geomview. Geomview will then receive
4970 only a piece of a command and will print out a cryptic but harmless
4971 error message about this. When a module has a user interface panel it
4972 can use a "Quit" button to provide a more graceful way for the user to
4973 terminate the module. See the next example.
4974
4975 You can run this module in a shell window without Geomview to see the
4976 commands it prints out. You will have to kill it with `ctrl-C' to get
4977 it to stop.
4978
4979 
4980 File: geomview, Node: Example2, Next: XForms, Prev: Example1, Up: Modules
4981
4982 6.3 Example 2: Simple External Module with FORMS Control Panel
4983 ==============================================================
4984
4985 This section gives a new version of the above module -- one that
4986 includes a user interface panel for controlling the velocity of the
4987 oscillation. We use the FORMS library by Mark Overmars for the control
4988 panel. The FORMS library is a public domain user interface toolkit for
4989 IRISes. To try out this example, make a copy of the file `example2.c'
4990 (distributed with Geomview in the `doc' subdirectory) in your directory
4991 and compile it with the command
4992
4993 cc -I/u/gcg/ngrap/include -o example2 example2.c \
4994 -L/u/gcg/ngrap/lib/sgi -lforms -lfm_s -lgl_s -lm
4995
4996 You should replace the string `/u/gcg/ngrap' above with the pathname
4997 of the Geomview distribution directory on your system. (The forms
4998 library is distributed with Geomview and the `-I' and `-L' options above
4999 tell the compiler where to find it.)
5000
5001 Then put the line
5002
5003 (emodule-define "Example 2" "./example2")
5004
5005 in a file called `.geomview' in the current directory and invoke
5006 Geomview from that directory. Click on the "Example 2" entry in the
5007 _Modules_ browser to invoke the module. A small control panel should
5008 appear. You can then control the velocity of the mesh oscillation by
5009 moving the slider.
5010
5011 /*
5012 * example2.c: oscillating mesh with FORMS control panel
5013 *
5014 * This example module is distributed with the Geomview manual.
5015 * If you are not reading this in the manual, see the "External
5016 * Modules" chapter of the manual for an explanation.
5017 *
5018 * This module creates an oscillating mesh and has a FORMS control
5019 * panel that lets you change the speed of the oscillation with a
5020 * slider.
5021 */
5022
5023 #include <math.h>
5024 #include <stdio.h>
5025 #include <sys/time.h> /* for struct timeval below */
5026
5027 #include "forms.h" /* for FORMS library */
5028
5029 FL_FORM *OurForm;
5030 FL_OBJECT *VelocitySlider;
5031 float dt;
5032
5033 /* F is the function that we plot
5034 */
5035 float F(x,y,t)
5036 float x,y,t;
5037 {
5038 float r = sqrt(x*x+y*y);
5039 return(sin(r + t)*sqrt(r));
5040 }
5041
5042 /* SetVelocity is the slider callback procedure; FORMS calls this
5043 * when the user moves the slider bar.
5044 */
5045 void SetVelocity(FL_OBJECT *obj, long val)
5046 {
5047 dt = fl_get_slider_value(VelocitySlider);
5048 }
5049
5050 /* Quit is the "Quit" button callback procedure; FORMS calls this
5051 * when the user clicks the "Quit" button.
5052 */
5053 void Quit(FL_OBJECT *obj, long val)
5054 {
5055 exit(0);
5056 }
5057
5058 /* create_form_OurForm() creates the FORMS panel by calling a bunch of
5059 * procedures in the FORMS library. This code was generated
5060 * automatically by the FORMS designer program; normally this code
5061 * would be in a separate file which you would not edit by hand. For
5062 * simplicity of this example, however, we include this code here.
5063 */
5064 create_form_OurForm()
5065 {
5066 FL_OBJECT *obj;
5067 FL_FORM *form;
5068 OurForm = form = fl_bgn_form(FL_NO_BOX,380.0,120.0);
5069 obj = fl_add_box(FL_UP_BOX,0.0,0.0,380.0,120.0,"");
5070 VelocitySlider = obj = fl_add_valslider(FL_HOR_SLIDER,20.0,30.0,
5071 340.0,40.0,"Velocity");
5072 fl_set_object_lsize(obj,FL_LARGE_FONT);
5073 fl_set_object_align(obj,FL_ALIGN_TOP);
5074 fl_set_call_back(obj,SetVelocity,0);
5075 obj = fl_add_button(FL_NORMAL_BUTTON,290.0,75.0,70.0,35.0,"Quit");
5076 fl_set_object_lsize(obj,FL_LARGE_FONT);
5077 fl_set_call_back(obj,Quit,0);
5078 fl_end_form();
5079 }
5080
5081 main(argc, argv)
5082 char **argv;
5083 {
5084 int xdim, ydim;
5085 float xmin, xmax, ymin, ymax, dx, dy, t;
5086 int fdmask;
5087 static struct timeval timeout = {0, 200000};
5088
5089 xmin = ymin = -5; /* Set x and y */
5090 xmax = ymax = 5; /* plot ranges */
5091 xdim = ydim = 24; /* Set x and y resolution */
5092 dt = 0.1; /* Time increment is 0.1 */
5093
5094 /* Forms panel setup.
5095 */
5096 foreground();
5097 create_form_OurForm();
5098 fl_set_slider_bounds(VelocitySlider, 0.0, 1.0);
5099 fl_set_slider_value(VelocitySlider, dt);
5100 fl_show_form(OurForm, FL_PLACE_SIZE, TRUE, "Example 2");
5101
5102
5103 /* Geomview setup.
5104 */
5105 printf("(geometry example { : foo })\n");
5106 fflush(stdout);
5107
5108 /* Loop until killed.
5109 */
5110 for (t=0; ; t+=dt) {
5111 fdmask = (1 << fileno(stdin)) | (1 << qgetfd());
5112 select(qgetfd()+1, &fdmask, NULL, NULL, &timeout);
5113 fl_check_forms();
5114 UpdateMesh(xmin, xmax, ymin, ymax, xdim, ydim, t);
5115 }
5116 }
5117
5118 /* UpdateMesh sends one mesh iteration to Geomview
5119 */
5120 UpdateMesh(xmin, xmax, ymin, ymax, xdim, ydim, t)
5121 float xmin, xmax, ymin, ymax, t;
5122 int xdim, ydim;
5123 {
5124 int i,j;
5125 float x,y, dx,dy;
5126
5127 dx = (xmax-xmin)/(xdim-1);
5128 dy = (ymax-ymin)/(ydim-1);
5129
5130 printf("(read geometry { define foo \n");
5131 printf("MESH\n");
5132 printf("%1d %1d\n", xdim, ydim);
5133 for (j=0, y = ymin; j<ydim; ++j, y += dy) {
5134 for (i=0, x = xmin; i<xdim; ++i, x += dx) {
5135 printf("%f %f %f\t", x, y, F(x,y,t));
5136 }
5137 printf("\n");
5138 }
5139 printf("})\n");
5140 fflush(stdout);
5141 }
5142
5143 The code begins by including some header files needed for the event
5144 loop and the FORMS library. It then declares global variables for
5145 holding a pointer to the slider FORMS object and the velocity `dt'.
5146 These are global because they are needed in the slider callback
5147 procedure `SetVelocity', which forms calls every time the user moves the
5148 slider bar. `SetVelocity' sets `dt' to be the new value of the slider.
5149
5150 `Quit' is the callback procedure for the _Quit_ button; it provides
5151 a graceful way for the user to terminate the program.
5152
5153 The procedure `create_panel' calls a bunch of FORMS library
5154 procedures to set up the control panel with slider and button. For more
5155 information on using FORMS to create interface panels see the FORMS
5156 documentation. In particular, FORMS comes with a graphical panel
5157 designer that lets you design your panels interactively and generates
5158 code like that in `create_panel'.
5159
5160 This example's main program is similar to the previous example, but
5161 includes extra code to deal with setting up and managing the FORMS
5162 panel.
5163
5164 To set up the panel we call the GL procedure `foreground' to cause
5165 the process to run in the foreground. By default GL programs run in the
5166 background, and for various reasons external modules that use FORMS
5167 (which is based on GL) need to run in the foreground. We then call
5168 `create_panel' to create the panel and `fl_set_slider_value' to set the
5169 initial value of the slider. The call to `fl_show_form' causes the
5170 panel to appear on the screen.
5171
5172 The first three lines of the main loop, starting with
5173 fdmask = (1 << fileno(stdin)) | (1 << qgetfd());
5174 check for and deal with events in the panel. The call to `select'
5175 imposes a delay on each pass through the main loop. This call returns
5176 either after a delay of 1/5 second or when the next GL event occurs, or
5177 when data appears on standard input, whichever comes first. The
5178 `timeout' variable specifies the amount of time to wait on this call;
5179 the first member (0 in this example) gives the number of seconds, and
5180 the second member (200000 in this example) gives the number of
5181 microseconds. Finally, `fl_check_forms()' checks for and processes any
5182 FORMS events that have happened; in this case this means calling
5183 `SetVelocity' if the user has moved the slider or calling `Quit' if the
5184 user has clicked on the _Quit_ button.
5185
5186 The purpose of the delay in the loop is to keep the program from
5187 using excessive amounts of CPU time running around its main loop when
5188 there are no events to be processed. This is not so crucial in this
5189 example, and in fact may actually slow down the animation somewhat, but
5190 in general with external modules that have event loops it is important
5191 to do something like this because otherwise the module will needlessly
5192 take CPU cycles away from other running programs (such as Geomview!)
5193 even when it isn't doing anything.
5194
5195 The last line of the main loop in this example, the call to
5196 `UpdateMesh', is the same as in the previous example.
5197
5198 
5199 File: geomview, Node: XForms, Next: Example3, Prev: Example2, Up: Modules
5200
5201 6.4 The XForms Library
5202 ======================
5203
5204 XForms is a handy and relatively simple user interface toolkit for X11.
5205 Many Geomview external modules, including the examples in this manual,
5206 use XForms to create and manage control panels. XForms is available from
5207 `http://www.nongnu.org/xforms/'. XForms is free-ware. If you wish you
5208 may use any other interface toolkit instead of XForms in an external
5209 module. We chose FORMS because it is free and relatively simple.
5210
5211 There is a complete autoconf'ed package `gvemod-xforms-example'
5212 available from Geomview's Sourceforge.NET
5213 (http://geomview.sourceforge.net) page.
5214
5215 
5216 File: geomview, Node: Example3, Next: Example4, Prev: XForms, Up: Modules
5217
5218 6.5 Example 3: External Module with Bi-Directional Communication
5219 ================================================================
5220
5221 The previous two example modules simply send commands to Geomview and do
5222 not receive anything from Geomview. This section describes a module
5223 that communicates in both directions. There are two types of
5224 communication that can go from Geomview to an external module. This
5225 example shows _asynchronous_ communication -- the module needs to be
5226 able to respond at any moment to expressions that Geomview may emit
5227 which inform the module of some change of state within Geomview.
5228
5229 (The other type of communication is _synchronous_, where a module
5230 sends a request to Geomview for some piece of information and waits for
5231 a response to come back before doing anything else. The main GCL
5232 command for requesting information of this type is *note `(write ...)':
5233 write. This module does not do any synchronous communication.)
5234
5235 In ansynchronous communication, Geomview sends expressions that are
5236 essentially echoes of GCL commands. The external module sends Geomview
5237 a command expressing interest in a certain command, and then every time
5238 Geomview executes that command, the module receives a copy of it. This
5239 happens regardless of who sent the command to Geomview; it can be the
5240 result of the user doing something with a Geomview panel, or it may
5241 have come from another module or from a file that Geomview reads. This
5242 is how a module can find out about and act on things that happen in
5243 Geomview.
5244
5245 This example uses the OOGL lisp library to parse and act on the
5246 expressions that Geomview writes to the module's standard input. This
5247 library is actually part of Geomview itself -- we wrote the library in
5248 the process of implementing GCL. It is also convenient to use it in
5249 external modules that must understand a of subset of GCL --
5250 specifically, those commands that the module has expressed interest in.
5251
5252 This example shows how a module can receive user pick events, i.e.
5253 when the user clicks the right mouse button with the cursor over a geom
5254 in a Geomview camera window. When this happens Geomview generates an
5255 internal call to a procedure called `pick'; the arguments to the
5256 procedure give information about the pick, such as what object was
5257 picked, the coordinates of the picked point, etc. If an external module
5258 has expressed interest in calls to `pick', then whenever `pick' is
5259 called Geomview will echo the call to the module's standard input. The
5260 module can then do whatever it wants with the pick information.
5261
5262 This module is the same as the _Nose_ module that comes with
5263 Geomview. Its purpose is to illustrate picking. Whenever you pick on a
5264 geom by clicking the right mouse button on it, the module draws a little
5265 box at the spot where you clicked. Usually the box is yellow. If you
5266 pick a vertex, the box is colored magenta. If you pick a point on an
5267 edge of an object, the module will also highlight the edge by drawing
5268 cyan boxes at its endpoints and drawing a yellow line along the edge.
5269
5270 Note that in order for this module to actually do anything you must
5271 have a geom loaded into Geomview and you must click the right mouse
5272 button with the cursor over a part of the geom.
5273
5274 /*
5275 * example3.c: external module with bi-directional communication
5276 *
5277 * This example module is distributed with the Geomview manual.
5278 * If you are not reading this in the manual, see the "External
5279 * Modules" chapter of the manual for an explanation.
5280 *
5281 * This module is the same as the "Nose" program that is distributed
5282 * with Geomview. It illustrates how a module can find out about
5283 * and respond to user pick events in Geomview. It draws a little box
5284 * at the point where a pick occurrs. The box is yellow if it is not
5285 * at a vertex, and magenta if it is on a vertex. If it is on an edge,
5286 * the program also marks the edge.
5287 *
5288 * To compile:
5289 *
5290 * cc -I/u/gcg/ngrap/include -g -o example3 example3.c \
5291 * -L/u/gcg/ngrap/lib/sgi -loogl -lm
5292 *
5293 * You should replace "/u/gcg/ngrap" above with the pathname of the
5294 * Geomview distribution directory on your system.
5295 */
5296
5297 #include <stdio.h>
5298 #include "lisp.h" /* We use the OOGL lisp library */
5299 #include "pickfunc.h" /* for PICKFUNC below */
5300 #include "3d.h" /* for 3d geometry library */
5301
5302 /* boxstring gives the OOGL data to define the little box that
5303 * we draw at the pick point. NOTE: It is very important to
5304 * have a newline at the end of the OFF object in this string.
5305 */
5306 char boxstring[] = "\
5307 INST\n\
5308 transform\n\
5309 .04 0 0 0\n\
5310 0 .04 0 0\n\
5311 0 0 .04 0\n\
5312 0 0 0 1\n\
5313 geom\n\
5314 OFF\n\
5315 8 6 12\n\
5316 \n\
5317 -.5 -.5 -.5 # 0 \n\
5318 .5 -.5 -.5 # 1 \n\
5319 .5 .5 -.5 # 2 \n\
5320 -.5 .5 -.5 # 3 \n\
5321 -.5 -.5 .5 # 4 \n\
5322 .5 -.5 .5 # 5 \n\
5323 .5 .5 .5 # 6 \n\
5324 -.5 .5 .5 # 7 \n\
5325 \n\
5326 4 0 1 2 3\n\
5327 4 4 5 6 7\n\
5328 4 2 3 7 6\n\
5329 4 0 1 5 4\n\
5330 4 0 4 7 3\n\
5331 4 1 2 6 5\n";
5332
5333 progn()
5334 {
5335 printf("(progn\n");
5336 }
5337
5338 endprogn()
5339 {
5340 printf(")\n");
5341 fflush(stdout);
5342 }
5343
5344 Initialize()
5345 {
5346 extern LObject *Lpick(); /* This is defined by PICKFUNC below but must */
5347 /* be used in the following LDefun() call */
5348 LInit();
5349 LDefun("pick", Lpick, NULL);
5350
5351 progn(); {
5352 /* Define handle "littlebox" for use later
5353 */
5354 printf("(read geometry { define littlebox { %s }})\n", boxstring);
5355
5356 /* Express interest in pick events; see Geomview manual for explanation.
5357 */
5358 printf("(interest (pick world * * * * nil nil nil nil nil))\n");
5359
5360 /* Define "pick" object, initially the empty list (= null object).
5361 * We replace this later upon receiving a pick event.
5362 */
5363 printf("(geometry \"pick\" { LIST } )\n");
5364
5365 /* Make the "pick" object be non-pickable.
5366 */
5367 printf("(pickable \"pick\" no)\n");
5368
5369 /* Turn off normalization, so that our pick object will appear in the
5370 * right place.
5371 */
5372 printf("(normalization \"pick\" none)\n");
5373
5374 /* Don't draw the pick object's bounding box.
5375 */
5376 printf("(bbox-draw \"pick\" off)\n");
5377
5378 } endprogn();
5379 }
5380
5381 /* The following is a macro call that defines a procedure called
5382 * Lpick(). The reason for doing this in a macro is that that macro
5383 * encapsulates a lot of necessary stuff that would be the same for
5384 * this procedure in any program. If you write a Geomview module that
5385 * wants to know about user pick events you can just copy this macro
5386 * call and change the body to suit your needs; the body is the last
5387 * argument to the macro and is delimited by curly braces.
5388 *
5389 * The first argument to the macro is the name of the procedure to
5390 * be defined, "Lpick".
5391 *
5392 * The next two arguments are numbers which specify the sizes that
5393 * certain arrays inside the body of the procedure should have.
5394 * These arrays are used for storing the face and path information
5395 * of the picked object. In this module we don't care about this
5396 * information so we declare them to have length 1, the minimum
5397 * allowed.
5398 *
5399 * The last argument is a block of code to be executed when the module
5400 * receives a pick event. In this body you can refer to certain local
5401 * variables that hold information about the pick. For details see
5402 * Example 3 in the Extenal Modules chapter of the Geomview manual.
5403 */
5404 PICKFUNC(Lpick, 1, 1,
5405 {
5406 handle_pick(pn>0, &point, vn>0, &vertex, en>0, edge);
5407 },
5408 /* version for picking Nd-objects (not documented here) */)
5409
5410 handle_pick(picked, p, vert, v, edge, e)
5411 int picked; /* was something actually picked? */
5412 int vert; /* was the pick near a vertex? */
5413 int edge; /* was the pick near an edge? */
5414 HPoint3 *p; /* coords of pick point */
5415 HPoint3 *v; /* coords of picked vertex */
5416 HPoint3 e[2]; /* coords of endpoints of picked edge */
5417 {
5418 Normalize(&e[0]); /* Normalize makes 4th coord 1.0 */
5419 Normalize(&e[1]);
5420 Normalize(p);
5421 progn(); {
5422 if (!picked) {
5423 printf("(geometry \"pick\" { LIST } )\n");
5424 } else {
5425 /*
5426 * Put the box in place, and color it magenta if it's on a vertex,
5427 * yellow if not.
5428 */
5429 printf("(xform-set pick { 1 0 0 0 0 1 0 0 0 0 1 0 %g %g %g 1 })\n",
5430 p->x, p->y, p->z);
5431 printf("(geometry \"pick\"\n");
5432 if (vert) printf("{ appearance { material { diffuse 1 0 1 } }\n");
5433 else printf("{ appearance { material { diffuse 1 1 0 } }\n");
5434 printf(" { LIST { :littlebox }\n");
5435
5436 /*
5437 * If it's on an edge and not a vertex, mark the edge
5438 * with cyan boxes at the endpoins and a black line
5439 * along the edge.
5440 */
5441 if (edge && !vert) {
5442 e[0].x -= p->x; e[0].y -= p->y; e[0].z -= p->z;
5443 e[1].x -= p->x; e[1].y -= p->y; e[1].z -= p->z;
5444 printf("{ appearance { material { diffuse 0 1 1 } }\n\
5445 LIST\n\
5446 { INST transform 1 0 0 0 0 1 0 0 0 0 1 0 %f %f %f 1 geom :littlebox }\n\
5447 { INST transform 1 0 0 0 0 1 0 0 0 0 1 0 %f %f %f 1 geom :littlebox }\n\
5448 { VECT\n\
5449 1 2 1\n\
5450 2\n\
5451 1\n\
5452 %f %f %f\n\
5453 %f %f %f\n\
5454 1 1 0 1\n\
5455 }\n\
5456 }\n",
5457 e[0].x, e[0].y, e[0].z,
5458 e[1].x, e[1].y, e[1].z,
5459 e[0].x, e[0].y, e[0].z,
5460 e[1].x, e[1].y, e[1].z);
5461 }
5462 printf(" }\n }\n)\n");
5463 }
5464
5465 } endprogn();
5466
5467 }
5468
5469 Normalize(HPoint3 *p)
5470 {
5471 if (p->w != 0) {
5472 p->x /= p->w;
5473 p->y /= p->w;
5474 p->z /= p->w;
5475 p->w = 1;
5476 }
5477 }
5478
5479 main()
5480 {
5481 Lake *lake;
5482 LObject *lit, *val;
5483 extern char *getenv();
5484
5485 Initialize();
5486
5487 lake = LakeDefine(stdin, stdout, NULL);
5488 while (!feof(stdin)) {
5489
5490 /* Parse next lisp expression from stdin.
5491 */
5492 lit = LSexpr(lake);
5493
5494 /* Evaluate that expression; this is where Lpick() gets called.
5495 */
5496 val = LEval(lit);
5497
5498 /* Free the two expressions from above.
5499 */
5500 LFree(lit);
5501 LFree(val);
5502 }
5503 }
5504
5505 The code begins by defining procedures `progn()' and `endprogn()'
5506 which begin and end a Geomview `progn' group. The purpose of the
5507 Geomview `progn' command is to group commands together and cause
5508 Geomview to execute them all at once, without refreshing any graphics
5509 windows until the end. It is a good idea to group blocks of commands
5510 that a module sends to Geomview like this so that the user sees their
5511 cumulative effect all at once.
5512
5513 Procedure `Initialize()' does various things needed at program
5514 startup time. It initializes the lisp library by calling `LInit()'.
5515 Any program that uses the lisp library should call this once before
5516 calling any other lisp library functions. It then calls `LDefun' to
5517 tell the library about our `pick' procedure, which is defined further
5518 down with a call to the `PICKFUNC' macro. Then it sends a bunch of
5519 setup commands to Geomview, grouped in a `progn' block. This includes
5520 defining a handle called `littlebox' that stores the geometry of the
5521 little box. Next it sends the command
5522
5523 (interest (pick world * * * * nil nil nil nil nil))
5524
5525 which tells Geomview to notify us when a pick event happens.
5526
5527 The syntax of this `interest' statement merits some explanation. In
5528 general `interest' takes one argument which is a (parenthesized)
5529 expression representing a Geomview function call. It specifies a type
5530 of call that the module is interested in knowing about. The arguments
5531 can be any particular argument values, or the special symbols `*' or
5532 `nil'. For example, the first argument in the `pick' expression above
5533 is `world'. This means that the module is interested in calls to
5534 `pick' where the first argument, which specifies the coordinate system,
5535 is `world'. A `*' is like a wild-card; it means that the module is
5536 interested in calls where the corresponding argument has any value.
5537 The word `nil' is like `*', except that the argument's value is not
5538 reported to the module. This is useful for cutting down on the amount
5539 of data that must be transmitted in cases where there are arguments
5540 that the module doesn't care about.
5541
5542 The second, third, fourth, and fifth arguments to the `pick' command
5543 give the name, pick point coordinates, vertex coordinates, and edge
5544 coordinates of a pick event. We specify these by `*''s above. The
5545 remaining five arguments to the `pick' command give other information
5546 about the pick event that we do not care about in this module, so we
5547 specify these with `nil''s. For the details of the arguments to
5548 `pick', *Note GCL::.
5549
5550 The `geometry' statement defines a geom called `pick' that is
5551 initially an empty list, specified as ` { LIST } '; this is the best
5552 way of specifying a null geom. The module will replace this with
5553 something useful by sending Geomview another `geometry' command when
5554 the user picks something. Next we arrange for the `pick' object to be
5555 non-pickable, and turn normalization off for it so that Geomview will
5556 display it in the size and location where we put it, rather than
5557 resizing and relocating it to fit into the unit cube.
5558
5559 The next function in the file, `Lpick', is defined with a strange
5560 looking call to a macro called `PICKFUNC', defined in the header file
5561 `pickfunc.h'. This is the function for handling pick events. The
5562 reason we provide a macro for this is that that macro encapsulates a
5563 lot of necessary stuff that would be the same for the pick-handling
5564 function in any program. If you write a Geomview module that wants to
5565 know about user pick events you can just copy this macro call and change
5566 it to suit yours needs.
5567
5568 In general the syntax for `PICKFUNC' is
5569 PICKFUNC(NAME, BLOCK, NDBLOCK)
5570 where NAME is the name of the procedure to be defined, in this case
5571 `Lpick'. The next argument, BLOCK, is a block of code to be executed
5572 when a pick event occurs. If BLOCK contains a return statement, then
5573 the returned value must be a pointer to a Lisp-object, that is of type
5574 `LObject *'. The last argument has the same functionality as the BLOCK
5575 argument, but is only invoked when picking objects in a higher
5576 dimensional world.
5577
5578 `PICKFUNC' declares certain local variables in the body of the
5579 procedure. When the module receives a `(pick ...)' statement from
5580 Geomview, the procedure assigns values to these variables based on the
5581 information in the `pick' call (variables corresponding to `nil''s in
5582 the `(interest (pick ...))' are not given values).
5583
5584 There is also a second variant of the `PICKFUNC' macro with a
5585 slightly different syntax:
5586 DEFPICKFUNC(HELPSTR, COORDSYS, ID,
5587 POINT, PN, VERTEX, VN, EDGE, EN, FACE, FN, PPATH, PPN,
5588 VI, EI, EIN, FI,
5589 BODY, NDBODY)
5590 `DEFPICKFUNC' can be used as well as `PICKFUNC', there is no
5591 functional difference with the exception that the name of the C-function
5592 is tied to `Lpick' when using `DEFPICKFUNC' and that the `(help pick)'
5593 GCL-command (*note `(help ...)': help.) would respond with echoing
5594 HELPSTR.
5595
5596 The table below lists all variables defined in `PICKFUNC' In the
5597 context of ND-viewing `float' variants of the arguments apply: the BODY
5598 execution block sees the `HPoint3' variables, and the NDBODY block sees
5599 only flat one-dimensional arrays of `float'-type.
5600
5601 In the ND-viewing context the co-ordinates passed to the pick
5602 function are still the 3-dimensional co-ordinates of the camera
5603 view-port where the pick occurred, but padded with zeroes on
5604 transformed back to the co-ordinate system specified by the second
5605 argument of the `pick' command.
5606
5607 `char *coordsys;'
5608 A string specifying the coordinate system in which coordinates are
5609 given. In this example, this will always be `world' because of
5610 the `interest' call above.
5611
5612 `char *id;'
5613 A string specifying the name of the picked geom.
5614
5615 `HPoint3 point; int pn;'
5616
5617 `float *point; int pn;'
5618 `point' is an `HPoint3' structure giving the coordinates of the
5619 picked point. `HPoint3' is a homogeneous point coordinate
5620 representation equivalent to an array of 4 floats. `pn' tells how
5621 many coordinates have been written into this array; it will always
5622 be either `0', `4' or greater than `4'. If it is greater than `4',
5623 then the NDBODY instruction block is invoked and in this case
5624 `point' is a flat array of `pn' many `float's. A value of zero
5625 means no point was picked, i.e. the user clicked the right mouse
5626 button while the cursor was not pointing at a geom. In this case
5627 the ordinary BLOCK 3d instruction block is executed.
5628
5629 `HPoint3 vertex; int vn;'
5630
5631 `float *vertex; int vn;'
5632 `vertex' is an `HPoint3' structure giving the coordinates of the
5633 picked vertex, if the pick point was near a vertex. `vn' tells
5634 how many coordinates have been written into this array; it will
5635 always be either `0' or greater equal `4'. A value of zero means
5636 the pick point was not near a vertex. In the context of ND-viewing
5637 `vertex' will be an array of `vn' `float's and `vn' will be equal
5638 to `pn'.
5639
5640 `HPoint3 edge[2]; int en;'
5641
5642 `float *edge; int en;'
5643 `edge' is an array of two `HPoint3' structures giving the
5644 coordinates of the endpoints of the picked edge, if the pick point
5645 was near an edge. `en' tells how many coordinates have been
5646 written into this array; it will always be `0' or greater equal
5647 `8'. A value of zero means the pick point was not near an edge.
5648 In the context of ND-viewing `edge' will be a flat one-dimensional
5649 array of `en' many `float's: the first `pn' `float's define the
5650 first vertex, and the second `pn' many `float's define the second
5651 vertex; `en' will be two times `pn'.
5652
5653
5654 In this example module, the remaining variables will never be given
5655 values because their values in the `interest' statement were specified
5656 as `nil'.
5657
5658 `HPoint3 face[]; int fn;'
5659
5660 `float *face; int fn;'
5661 `face' is a variable length array of FN `HPoint3''s. `face' gives
5662 the coordinates of the vertices of the picked face. `fn' tells
5663 how many coordinates have been written into this array; it will
5664 always be either `0' or a multiple of `pn'. A value of zero means
5665 the pick point was not near a face. In the context of ND-viewing
5666 `face' is a flat one-dimensional array of `fn' many floats of
5667 which each vertex occupies `pn' many components.
5668
5669 `int ppath[]; int ppn;'
5670 `ppath' is an array of MAXPATHLEN `int''s. `ppath' gives the path
5671 through the OOGL heirarchy to the picked primitive. `pn' tells
5672 how many integers have been written into this array; it will be at
5673 most MAXPATHLEN. A path of {3,1,2}, for example, means that the
5674 picked primitive is "subobject number 2 of subobject number 1 of
5675 object 3 in the world".
5676
5677 `int vi;'
5678 `vi' gives the index of the picked vertex in the picked primitive,
5679 if the pick point was near a vertex.
5680
5681 `int ei[2]; int ein'
5682 The `ei' array gives the indices of the endpoints of the picked
5683 edge, if the pick point was near a vertex. `ein' tells how many
5684 integers were written into this array. It will always be either 0
5685 or 2; a value of 0 means the pick point was not near an edge.
5686
5687 `int fi;'
5688 `fi' gives the index of the picked face in the picked primitive, if
5689 the pick point was near a face.
5690
5691
5692 The `handle_pick' procedure actually does the work of dealing with
5693 the pick event. It begins by normalizing the homogeneous coordinates
5694 passed in as arguments so that we can assume the fourth coordinate is 1.
5695 It then sends GCL commands to define the `pick' object to be whatever
5696 is appropriate for the kind of pick recieved. See *note OOGL File
5697 Formats::, and *note GCL::, for an explanation of the format of the
5698 data in these commands.
5699
5700 The main program, at the bottom of the file, first calls
5701 `Initialize()'. Next, the call to `LakeDefine' defines the `Lake' that
5702 the lisp library will use. A `Lake' is a structure that the lisp
5703 library uses internally as a type of communiation vehicle. (It is like
5704 a unix stream but more general, hence the name.) This call to
5705 `LakeDefine' defines a `Lake' structure for doing I/O with `stdin' and
5706 `stdout'. The third argument to `LakeDefine' should be `NULL' for
5707 external modules (it is used by Geomview). Finally, the program enters
5708 its main loop which parses and evaluates expressions from standard
5709 input.
5710
5711 
5712 File: geomview, Node: Example4, Next: Module Installation, Prev: Example3, Up: Modules
5713
5714 6.6 Example 4: Simple Tcl/Tk Module Demonstrating Picking
5715 =========================================================
5716
5717 It's not necessary to write a Geomview module in C. The only
5718 requirement of an external module is that it send GCL commands to its
5719 standard output and expect responses (if any) on its standard input.
5720 An external module can be written in C, perl, tcl/tk, or pretty much
5721 anything.
5722
5723 As an example, assuming you have Tcl/Tk version 4.0 or later, here's
5724 an external module with a simple GUI which demonstrates interaction with
5725 geomview. This manual doesn't discuss the Tcl/Tk language; see the
5726 good book on the subject by its originator John Ousterhout, published
5727 by Addison-Wesley, titled _Tcl and the Tk Toolkit_.
5728
5729 The `#!' on the script's first line causes the system to interpret
5730 the script using the Tcl/Tk `wish' program; you might have to change its
5731 first line if that's in some location other than /usr/local/bin/wish4.0.
5732 Or, you could define it as a module using
5733 (emodule-define "Pick Demo" "wish pickdemo.tcl")
5734 in which case `wish' could be anywhere on the UNIX search path.
5735
5736 #! /usr/local/bin/wish4.0
5737
5738 # We use "fileevent" below to have "readsomething" be called whenever
5739 # data is available from standard input, i.e. when geomview has sent us
5740 # something. It promises to include a trailing newline, so we can use
5741 # "gets" to read the geomview response, then parse its nested parentheses
5742 # into tcl-friendly {} braces.
5743
5744 proc readsomething {} {
5745 if {[gets stdin line] < 0} {
5746 puts stderr "EOF on input, exiting..."
5747 exit
5748 }
5749 regsub -all {\(} $line "\{" line
5750 regsub -all {\)} $line "\}" line
5751 # Strip outermost set of braces
5752 set stuff [lindex $line 0]
5753 # Invoke handler for whichever command we got. Could add others here,
5754 # if we asked geomview for other kinds of data as well.
5755 switch [lindex $stuff 0] {
5756 pick {handlepick $stuff}
5757 rawevent {handlekey $stuff}
5758 }
5759 }
5760
5761 # Fields of a "pick" response, from geomview manual:
5762 # (pick COORDSYS GEOMID G V E F P VI EI FI)
5763 # The pick command is executed internally in response to pick
5764 # events (right mouse double click).
5765 #
5766 # COORDSYS = coordinate system in which coordinates of the following
5767 # arguments are specified. This can be:
5768 # world: world coord sys
5769 # self: coord sys of the picked geom (GEOMID)
5770 # primitive: coord sys of the actual primitive within
5771 # the picked geom where the pick occurred.
5772 # GEOMID = id of picked geom
5773 # G = picked point (actual intersection of pick ray with object)
5774 # V = picked vertex, if any
5775 # E = picked edge, if any
5776 # F = picked face
5777 # P = path to picked primitive [0 or more]
5778 # VI = index of picked vertex in primitive
5779 # EI = list of indices of endpoints of picked edge, if any
5780 # FI = index of picked face
5781
5782 # Report when user picked something.
5783 #
5784 proc handlepick {pick} {
5785 global nameof selvert seledge order
5786 set obj [lindex $pick 2]
5787 set xyzw [lindex $pick 3]
5788 set fv [lindex $pick 6]
5789 set vi [lindex $pick 8]
5790 set ei [lindex $pick 9]
5791 set fi [lindex $pick 10]
5792
5793 # Report result, converting 4-component homogeneous point into 3-space point.
5794 set w [lindex $xyzw 3]
5795 set x [expr [lindex $xyzw 0]/$w]
5796 set y [expr [lindex $xyzw 1]/$w]
5797 set z [expr [lindex $xyzw 2]/$w]
5798 set s "$x $y $z "
5799 if {$vi >= 0} {
5800 set s "$s vertex #$vi"
5801 }
5802 if {$ei != {}} {
5803 set s "$s edge [lindex $ei 0]-[lindex $ei 1]"
5804 }
5805 if {$fi != -1} {
5806 set s "$s face #$fi ([expr [llength $fv]/3]-gon)"
5807 }
5808 msg $s
5809 }
5810
5811
5812 # Having asked for notification of these raw events, we report when
5813 # the user pressed these keys in the geomview graphics windows.
5814
5815 proc handlekey {event} {
5816 global lastincr
5817 switch [lindex $event 1] {
5818 32 {msg "Pressed space bar"}
5819 8 {msg "Pressed backspace key"}
5820 }
5821 }
5822
5823
5824 #
5825 # Display a message on the control panel, and on the terminal where geomview
5826 # was started. We use ``puts stderr ...'' rather than simply ``puts ...'',
5827 # since Geomview interprets anything we send to standard output
5828 # as a GCL command!
5829 #
5830 proc msg {str} {
5831 global msgtext
5832 puts stderr $str
5833 set msgtext $str
5834 update
5835 }
5836
5837 # Load object from file
5838 proc loadobject {fname} {
5839 if {$fname != ""} {
5840 puts "(geometry thing < $fname)"
5841 # Be sure to flush output to ensure geomview receives this now!
5842 flush stdout
5843 }
5844 }
5845
5846
5847 # Build simple "user interface"
5848
5849 # The message area could be a simple label rather than an entry box,
5850 # but we want to be able to use X selection to copy text from it.
5851 # The default mouse bindings do that automatically.
5852
5853 entry .msg -textvariable msgtext -width 45
5854 pack .msg
5855
5856 frame .f
5857
5858 label .f.l -text "File to load:"
5859 pack .f.l -side left
5860
5861 entry .f.ent -textvariable fname
5862 pack .f.ent -side left -expand true -fill x
5863 bind .f.ent <Return> { loadobject $fname }
5864
5865 pack .f
5866
5867
5868 # End UI definition.
5869
5870
5871 # Call "readsomething" when data arrives from geomview.
5872
5873 fileevent stdin readable {readsomething}
5874
5875 # Geomview initialization
5876
5877 puts {
5878 (interest (pick primitive))
5879 (interest (rawevent 32)) # Be notified when user presses space
5880 (interest (rawevent 8)) # or backspace keys.
5881 (geometry thing < hdodec.off)
5882 (normalization world none)
5883 }
5884 # Flush to ensure geomview receives this.
5885 flush stdout
5886
5887 wm title . {Sample external module}
5888
5889 msg "Click right mouse in graphics window"
5890
5891 
5892 File: geomview, Node: Module Installation, Prev: Example4, Up: Modules
5893
5894 6.7 Module Installation
5895 =======================
5896
5897 This section tells how to install an external module so you can invoke
5898 it within Geomview. There are two ways to install a module: you can
5899 install a _private_ module so that the module is available to you
5900 whenever you run Geomview, or you can install a _system_ module so that
5901 the module is available to all users on your system whenever they run
5902 Geomview.
5903
5904 * Menu:
5905
5906 * Private Module Installation:: Per-user modules.
5907 * System Module Installation:: System-wide modules.
5908
5909 
5910 File: geomview, Node: Private Module Installation, Next: System Module Installation, Prev: Module Installation, Up: Module Installation
5911
5912 6.7.1 Private Module Installation
5913 ---------------------------------
5914
5915 The `emodule-define' command arranges for a module to appear in
5916 Geomview's _Modules_ browser. The command takes two string arguments;
5917 the first is the name that will appear in the _Modules_ browser. The
5918 second is the shell command for running the module; it may include
5919 arguments (*note `(emodule-define ...)': emodule-define.). Geomview
5920 executes this command in a subshell when you click on the module's
5921 entry in the browser. For example
5922
5923 (emodule-define "Foo" "/u/home/modules/foo -x")
5924
5925 adds a line labeled "Foo" to the _Modules_ browser which causes the
5926 command "/u/home/modules/foo -x" to be executed when selected.
5927
5928 You may put `emodule-define' commands in your `~/.geomview' file to
5929 arrange for certain modules to be available every time you run
5930 Geomview; *Note Customization::. You can also execute `emodule-define'
5931 commands from the _Commands_ panel to add a module to an already
5932 running copy of Geomview.
5933
5934 There are several other GCL commands for controlling the entries in
5935 the _Modules_ browser; for details, *Note GCL::.
5936
5937 
5938 File: geomview, Node: System Module Installation, Prev: Private Module Installation, Up: Module Installation
5939
5940 6.7.2 System Module Installation
5941 --------------------------------
5942
5943 To install a module so that it is available to all Geomview users do
5944 the following
5945
5946 1.
5947 Create a file called `.geomview-MODULE' where `MODULE' is the name
5948 of the module. This file should contain a single line which is an
5949 `emodule-define' command for that module:
5950 (emodule-define "New Module" "newmodule")
5951 The first argument, `"New Module"' above, is the string that will
5952 appear in the _Modules_ browser. The second string, `"newmodule"'
5953 above, is the Bourne shell command for invoking the module. It
5954 may include arguments, and you may assume that the module is on the
5955 $PATH searched by the shell.
5956
5957 2.
5958 Put a copy of the `.geomview-MODULE' and the module executable
5959 itself in `/usr/local/libexec/geomview' directory.
5960
5961
5962 After these steps, the new module should appear, in alphabetical
5963 position, in the _Modules_ browser of Geomview's _Main_ panel next time
5964 Geomview is run. The reason this works is that when Geomview is
5965 invoked it processes all the `.geomview-*' files in its `modules'
5966 directory. It also remembers the pathname of this directory and
5967 prepends that path to the $PATH of the shell in which it invokes such a
5968 module.
5969
5970 
5971 File: geomview, Node: GCL, Next: Non-Euclidean Geometry, Prev: Modules, Up: Top
5972
5973 7 GCL: the Geomview Command Language
5974 ************************************
5975
5976 GCL has the syntax of lisp - i.e. an expression of the form (f a b ...)
5977 means pass the values of a, b, ... to the function f. GCL is very
5978 limited and is by no means an implementation of lisp. It is simply a
5979 language for expressing commands to be executed in the order given,
5980 rather than a programming language. It does not support variable or
5981 function definition.
5982
5983 GCL is the language that Geomview understands for files that it loads
5984 as well as for communication with other programs. To execute a GCL
5985 command interactively, you can bring up the _Commands_ panel which lets
5986 you type in a command; Geomview executes the command when you hit the
5987 <Enter> key. Output from such commands is printed to standard output.
5988 Alternately, you can invoke Geomview as `geomview -c -' which causes it
5989 to read GCL commands from standard input.
5990
5991 GCL functions return a value, and you can nest function calls in ways
5992 which use this returned value. For example
5993 (f (g a b))
5994 evaluates `(g a b)' and then evaluates `(f x)' where `x' is the
5995 result returned by `(g a b)'. Geomview maintains these return values
5996 internally but does not normally print them out. To print out a return
5997 value pass it to the `echo' function. For example the
5998 `geomview-version' function returns a string representing the version
5999 of Geomview that is running, and
6000 (echo (geomview-version))
6001 prints out this string.
6002
6003 Many functions simply return `t' for success or `nil' for failure;
6004 this is the case if the documentation for the function does not
6005 indicate otherwise. These are the lisp symbols for true and false,
6006 respectively. (They correspond to the C variables `Lt' and `Lnil'
6007 which you are likely to see if you look at the source code for Geomview
6008 or some of the external modules.)
6009
6010 In the descriptions of the commands below several references are
6011 made to "OOGL" formats. OOGL is the data description language that
6012 Geomview uses for describing geometry, cameras, appearances, and other
6013 basic objects. For details of the OOGL formats, *Note OOGL File
6014 Formats::. (Or equivalently, see the oogl(5) manual page, distributed
6015 with Geomview in the file /share/man/man5/oogl.5gv.
6016
6017 The GCL commands and argument types are listed below. Most of the
6018 documentation in this section of the manual is available within
6019 Geomview via the `?' and `??' commands. The command `(? COMMAND)'
6020 causes Geomview to print out a one-line summary of the syntax of
6021 COMMAND, and `(?? COMMAND)' prints out an explanation of what COMMAND
6022 does. You can include the wild-card character `*' in COMMAND to print
6023 information for a group of commands matching a pattern. For example,
6024 `(?? *emodule*)' will print all information about all commands
6025 containing the string `emodule'. `(? *)' will print a short list of
6026 all commands.
6027
6028 * Menu:
6029
6030 * Argument Conventions:: Conventions used in describing argument types.
6031 * GCL Reference:: Documentation for each GCL command.
6032
6033 
6034 File: geomview, Node: Argument Conventions, Next: GCL Reference, Prev: GCL, Up: GCL
6035
6036 7.1 Conventions Used In Describing Argument Types
6037 =================================================
6038
6039 The following symbols are used to describe argument types in the
6040 documentation for GCL functions.
6041
6042 `APPEARANCE'
6043 is an OOGL appearance specification.
6044
6045 `CAM-ID'
6046 is an ID that refers to a camera.
6047
6048 `CAMERA'
6049 is an OOGL camera specification.
6050
6051 `GEOM-ID'
6052 is an ID that refers to a geometry.
6053
6054 `GEOMETRY'
6055 is an OOGL geometry specification.
6056
6057 `ID'
6058 is a string which names a geometry or camera. Besides those you
6059 create, valid ones are:
6060
6061 ``World, world, worldgeom, g0''
6062 the collection of all geom's
6063
6064 `target'
6065 selected target object (cam or geom)
6066
6067 `center'
6068 selected center-of-motion object
6069
6070 `targetcam'
6071 last selected target camera
6072
6073 `targetgeom'
6074 last selected target geom
6075
6076 `focus'
6077 camera where cursor is (or most recently was)
6078
6079 `allgeoms'
6080 all geom objects
6081
6082 `allcams'
6083 all cameras
6084
6085 ``default, defaultcam, prototype''
6086 future cameras inherit default's settings
6087
6088
6089 The following IDs are used to name coordinate systems, e.g. in
6090 `pick' and `write' commands:
6091
6092 ``World, world, worldgeom, g0''
6093 the world, within which all other geoms live.
6094
6095 `universe'
6096 the universe, in which the World, lights and cameras live.
6097 Cameras' world2cam transforms might better be called
6098 universe2cam, etc.
6099
6100 `self'
6101 "this Geomview object". Transform from an object to `self'
6102 is the identity; writing its geometry gives the object itself
6103 with no enclosing transform; picked points appear in the
6104 object's coordinates.
6105
6106 `primitive'
6107 (for `pick' only) Picked points appear in the coordinate
6108 system of the lowest-level OOGL primitive.
6109
6110
6111 A name is also an acceptable id. Given names are made unique by
6112 appending numbers if necessary (i.e. `foo<2>'). Every geom is also
6113 named g[n] and every camera is also named c[n] (`g0' is always the
6114 worldgeom): this name is used as a prefix to keyboard commands and
6115 can also be used as a GCL id. Numbers are reused after an object
6116 is deleted. Both names are shown in the Object browser.
6117
6118 `STATEMENT'
6119 represents a function call. Function calls have the form `(func
6120 arg1 arg2 ... )', where `func' is the name of the function and
6121 `arg1', `arg2', ... are the arguments.
6122
6123 `TRANSFORM'
6124 is an OOGL 4x4 transformation matrix.
6125
6126 `NTRANSFORM'
6127 is an OOGL (N+1)x(N+1) transformation matrix.
6128
6129 `WINDOW'
6130 is an OOGL window specification.
6131
6132
6133 
6134 File: geomview, Node: GCL Reference, Prev: Argument Conventions, Up: GCL
6135
6136 7.2 GCL Reference Guide
6137 =======================
6138
6139 * Menu:
6140
6141 * shell-shortcut:: `(! SHELLCOMMAND)'
6142 * lt:: `(< EXPR1 EXPR2)'
6143 * eq:: `(= EXPR1 EXPR2)'
6144 * gt:: `(> EXPR1 EXPR2)'
6145 * mul:: `(* EXPR1 EXPR2)'
6146 * div:: `(/ EXPR1 EXPR2)'
6147 * add:: `(+ EXPR1 EXPR2)'
6148 * sub:: `(- EXPR1 EXOR2)'
6149 * help-shortcut:: `(? COMMAND)'
6150 * morehelp-shortcut:: `(?? COMMAND)'
6151 * emodule-run-shortcut:: `(| NAME)'
6152 * all:: `(all geometry|camera|emodule)'
6153 * and:: `(and EXPR1 EXPR2)'
6154 * ap-override:: `(ap-override [on|off])'
6155 * backcolor:: `(backcolor CAM-ID R G B)'
6156 * background-image:: `(background-image CAM-ID [FILENAME])'
6157 * bbox-color:: `(bbox-color GEOM-ID R G B)'
6158 * bbox-draw:: `(bbox-draw GEOM-ID [yes|no])'
6159 * camera:: `(camera CAM-ID [CAMERA])'
6160 * camera-draw:: `(camera-draw CAM-ID [yes|no])'
6161 * camera-prop:: `(camera-prop { geometry object } [projective])'
6162 * camera-reset:: `(camera-reset CAM-ID)'
6163 * car:: `(car LIST)'
6164 * cdr:: `(cdr LIST)'
6165 * clock:: `(clock)'
6166 * command:: `(command INFILE [OUTFILE])'
6167 * cons:: `(cons EXPR LIST)'
6168 * copy:: `(copy [ID] [name])'
6169 * cursor-still:: `(cursor-still [INT])'
6170 * cursor-twitch:: `(cursor-twitch [INT])'
6171 * defun:: `(defun NAME ARGS [DOC] BODY)'
6172 * delete:: `(delete ID)'
6173 * dice:: `(dice GEOM-ID N)'
6174 * dimension:: `(dimension [N])'
6175 * dither:: `(dither CAM-ID {on|off|toggle})'
6176 * draw:: `(draw CAM-ID)'
6177 * dump-handles:: `(dump-handles)'
6178 * echo:: `(echo ...)'
6179 * emodule-clear:: `(emodule-clear)'
6180 * emodule-define:: `(emodule-define NAME SHELL-COMMAND ...)'
6181 * emodule-defined:: `(emodule-defined `modulename')'
6182 * emodule-isrunning:: `(emodule-isrunning NAME)'
6183 * emodule-path:: `(emodule-path)'
6184 * emodule-run:: `(| NAME)'
6185 * emodule-sort:: `(emodule-sort)'
6186 * emodule-start:: `(emodule-start NAME)'
6187 * emodule-transmit:: `(emodule-transmit NAME LIST)'
6188 * escale:: `(escale GEOM-ID FACTOR)'
6189 * eval:: `(eval EXPR)'
6190 * event-keys:: `(event-keys {on|off})'
6191 * event-mode:: `(event-mode MODESTRING)'
6192 * event-pick:: `(event-pick {on|off})'
6193 * evert:: `(evert GEOM-ID [yes|no])'
6194 * exit:: `(exit)'
6195 * ezoom:: `(ezoom GEOM-ID FACTOR)'
6196 * freeze:: `(freeze CAM-ID)'
6197 * geometry:: `(geometry GEOM-ID [GEOMETRY])'
6198 * geomview-version:: `(geomview-version)'
6199 * hdefine:: `(hdefine geometry|camera|... NAME VALUE)'
6200 * hdelete:: `(hdelete [geometry|camera|...] name)'
6201 * help:: `(? COMMAND)'
6202 * hmodel:: `(hmodel CAMID {virtual|projective|conformal})'
6203 * hsphere-draw:: `(hsphere-draw CAMID [yes|no])'
6204 * if:: `(if TEST EXPR1 [EXPR2])'
6205 * inhibit-warning:: `(inhibit-warning STRING)'
6206 * input-translator:: `(input-translator "#pfx" "sh-command")'
6207 * interest:: `(interest (COMMAND [args]))'
6208 * lambda:: `(lambda ARGS BODY)'
6209 * let:: `(let (ARGS) BODY)'
6210 * lines-closer:: `(lines-closer CAM-ID DIST)'
6211 * load:: `(load filename [command|geometry|camera])'
6212 * load-path:: `(load-path)'
6213 * look:: `(look [objectID] [camID])'
6214 * look-encompass:: `(look-encompass [objID] [camID])'
6215 * look-encompass-size:: `(look-encompass-size [view clip near far])'
6216 * look-recenter:: `(look-recenter [objID] [camID])'
6217 * look-toward:: `(look-toward [objID] [camID] [origin|center])'
6218 * merge:: `(merge {window|camera} CAM-ID { WIN or CAM ... })'
6219 * merge-ap:: `(merge-ap GEOM-ID APPEARANCE)'
6220 * merge-base-ap:: `(merge-base-ap APPEARANCE)'
6221 * merge-baseap:: `(merge-baseap APPEARANCE)'
6222 * mod:: `(mod NUMERATOR DENOMINATOR)'
6223 * morehelp:: `(?? COMMAND)'
6224 * name-object:: `(name-object ID NAME)'
6225 * ND-axes:: `(ND-axes CAMID [CLUSTER [Xidx Yidx Zidx [Widx]]])'
6226 * ND-color:: `(ND-color CAMID ...'
6227 * ND-xform:: `(ND-xform OBJID [ntransform { ... }])'
6228 * ND-xform-get:: `(ND-xform-get ID [from-ID])'
6229 * ND-xform-set:: `(ND-xform-set OBJID [ntransform { ... }])'
6230 * new-alien:: `(new-alien name [GEOMETRY])'
6231 * new-camera:: `(new-camera name [CAMERA])'
6232 * new-center:: `(new-center [id])'
6233 * new-geometry:: `(new-geometry name [GEOMETRY])'
6234 * new-reset:: `(new-reset)'
6235 * NeXT:: `(NeXT)'
6236 * normalization:: `(normalization GEOM-ID {each|none|all|keep})'
6237 * not:: `(not EXPR)'
6238 * or:: `(or EXPR1 EXPR2)'
6239 * pick:: `(pick COORDSYS GEOMID G V E F P VI EI FI)'
6240 * pick-invisible:: `(pick-invisible [yes|no])'
6241 * pickable:: `(pickable GEOM-ID {yes|no})'
6242 * position:: `(position objectID otherID)'
6243 * position-at:: `(position-at objectID otherID [center | origin])'
6244 * position-toward:: `(position-toward objID othID [center|origin])'
6245 * process-events:: `(process-events)'
6246 * progn:: `(progn STATEMENT [ ... ])'
6247 * quit:: `(quit)'
6248 * quote:: `(quote EXPR)'
6249 * rawevent:: `(rawevent dev val x y t)'
6250 * rawpick:: `(rawpick CAMID X Y)'
6251 * read:: `(read geometry|camera|... {GEOM or CAM or ...})'
6252 * real-id:: `(real-id ID)'
6253 * redraw:: `(redraw CAM-ID)'
6254 * regtable:: `(regtable)'
6255 * rehash-emodule-path:: `(rehash-emodule-path)'
6256 * replace-geometry:: `(replace-geometry GEOM-ID PART GEOMETRY)'
6257 * rib-display:: `(rib-display [frame|tiff] FILEPREFIX)'
6258 * rib-snapshot:: `(rib-snapshot CAM-ID [filename])'
6259 * scale:: `(scale GEOM-ID FACTOR [FACTORY FACTORZ])'
6260 * scene:: `(scene CAM-ID [GEOMETRY])'
6261 * set-clock:: `(set-clock TIME)'
6262 * set-conformal-refine:: `(set-conformal-refine CMX [N [EDGES]])'
6263 * set-emodule-path:: `(set-emodule-path (PATH1 ... PATHN))'
6264 * set-load-path:: `(set-load-path (PATH1 ... PATHN))'
6265 * set-motionscale:: `(set-motionscale X)'
6266 * setenv:: `(setenv name string)'
6267 * setq:: `(setq SYM EXPR)'
6268 * sgi:: `(sgi)'
6269 * shell:: `(! SHELLCOMMAND)'
6270 * sleep-for:: `(sleep-for TIME)'
6271 * sleep-until:: `(sleep-until TIME)'
6272 * snapshot:: `(snapshot CAM-ID FILENAME [FORMAT [XSIZE [YSIZE]]])'
6273 * soft-shader:: `(soft-shader CAM-ID {on|off|toggle})'
6274 * space:: `(space {euclidean|hyperbolic|spherical})'
6275 * stereowin:: `(stereowin CAM-ID [no|horizontal|...] [gap])'
6276 * time-interests:: `(time-interests delta initial prefix [suffix])'
6277 * transform:: `(transform objectID centerID frameID [rotate|...] ...)'
6278 * transform-incr:: `(transform-incr objectID centerID frameID ...)'
6279 * transform-set:: `(transform-set objectID centerID frameID ...)'
6280 * truncate:: `(truncate NUMBER)'
6281 * ui-cam-focus:: `(ui-cam-focus {focus-change|mouse-cross})'
6282 * ui-center:: `(ui-center ID)'
6283 * ui-center-origin:: `(ui-center-origin {origin|bbox-center})'
6284 * ui-emotion-program:: `(ui-emotion-program PROGRAM)'
6285 * ui-emotion-run:: `(ui-emotion-run EMODULE)'
6286 * ui-freeze:: `(ui-freeze {on|off})'
6287 * ui-html-browser:: `(ui-html-browser BROWSER)'
6288 * ui-motion:: `(ui-motion {inertia|...} {on|off})'
6289 * ui-panel:: `(ui-panel PANELNAME {on|off} [WINDOW])'
6290 * ui-pdf-viewer:: `(ui-pdf-viewer VIEWER)'
6291 * ui-target:: `(ui-target ID [yes|no])'
6292 * uninterest:: `(uninterest (COMMAND [args]))'
6293 * update:: `(update [timestep_in_seconds])'
6294 * update-draw:: `(update-draw CAM-ID [timestep_in_seconds])'
6295 * while:: `(while TEST BODY)'
6296 * window:: `(window CAM-ID WINDOW)'
6297 * winenter:: `(winenter CAM-ID)'
6298 * write:: `(write command|geometry|... FILENAME ...)'
6299 * write-comments:: `(write-comments FILENAME GEOMID PICKPATH)'
6300 * write-handle:: `(write-handle PREFIX FILENAME HANDLE)'
6301 * write-sexpr:: `(write-sexpr FILENAME LISPOBJECT)'
6302 * xform:: `(xform ID TRANSFORM)'
6303 * xform-incr:: `(xform-incr ID TRANSFORM)'
6304 * xform-set:: `(xform-set ID TRANSFORM)'
6305 * zoom:: `(zoom CAM-ID FACTOR)'
6306
6307 
6308 File: geomview, Node: shell-shortcut, Next: lt, Prev: GCL Reference, Up: GCL Reference
6309
6310 7.2.1 !
6311 -------
6312
6313 `!'
6314 is a synonym for `shell'. *Note shell::.
6315
6316 
6317 File: geomview, Node: lt, Next: eq, Prev: shell-shortcut, Up: GCL Reference
6318
6319 7.2.2 <
6320 -------
6321
6322 `(< EXPR1 EXPR2)'
6323 Returns t if EXPR1 is less than EXPR2. EXPR1 and EXPR2 should be
6324 either both integers or floats, or both strings.
6325
6326 
6327 File: geomview, Node: eq, Next: gt, Prev: lt, Up: GCL Reference
6328
6329 7.2.3 =
6330 -------
6331
6332 `(= EXPR1 EXPR2)'
6333 Returns t if EXPR1 is equal to EXPR2. EXPR1 and EXPR2 should be
6334 either both integers or floats, or both strings.
6335
6336 
6337 File: geomview, Node: gt, Next: mul, Prev: eq, Up: GCL Reference
6338
6339 7.2.4 >
6340 -------
6341
6342 `(> EXPR1 EXPR2)'
6343 Returns t if EXPR1 is greater than EXPR2. EXPR1 and EXPR2 should
6344 be either both integers or floats, or both strings.
6345
6346 
6347 File: geomview, Node: mul, Next: div, Prev: gt, Up: GCL Reference
6348
6349 7.2.5 *
6350 -------
6351
6352 `(* EXPR1 EXPR2)'
6353 Multiplies EXPR1 and EXPR2 and returns the result.
6354
6355 
6356 File: geomview, Node: div, Next: add, Prev: mul, Up: GCL Reference
6357
6358 7.2.6 /
6359 -------
6360
6361 `(/ EXPR1 EXPR2)'
6362 Divides EXPR1 by EXPR2 and returns the result.
6363
6364 
6365 File: geomview, Node: add, Next: sub, Prev: div, Up: GCL Reference
6366
6367 7.2.7 +
6368 -------
6369
6370 `(+ EXPR1 EXPR2)'
6371 Adds EXPR1 and EXPR2 and returns the result.
6372
6373 
6374 File: geomview, Node: sub, Next: help-shortcut, Prev: add, Up: GCL Reference
6375
6376 7.2.8 -
6377 -------
6378
6379 `(- EXPR1 EXPR2)'
6380 Substracts EXPR2 from EXPR1 and returns the result.
6381
6382 
6383 File: geomview, Node: help-shortcut, Next: morehelp-shortcut, Prev: sub, Up: GCL Reference
6384
6385 7.2.9 ?
6386 -------
6387
6388 `(? [command])'
6389 Gives one-line usage summary for `command'. Command may include
6390 `*'s as wildcards; see also *note `(?? ...)': morehelp. One-line
6391 command help; lists names only if multiple commands match. `?' is
6392 a synonym for *note `(help ...)': help.
6393
6394 
6395 File: geomview, Node: morehelp-shortcut, Next: emodule-run-shortcut, Prev: help-shortcut, Up: GCL Reference
6396
6397 7.2.10 ??
6398 ---------
6399
6400 `(?? command)'
6401 `command' may include `*' wildcards. Prints more info than `(?
6402 command)'. `??' is a synonym for *note `morehelp': morehelp.
6403
6404 
6405 File: geomview, Node: emodule-run-shortcut, Next: all, Prev: morehelp-shortcut, Up: GCL Reference
6406
6407 7.2.11 |
6408 --------
6409
6410 `|'
6411 `|' is a synonym for `emodule-run'.
6412
6413 
6414 File: geomview, Node: all, Next: and, Prev: emodule-run-shortcut, Up: GCL Reference
6415
6416 7.2.12 all
6417 ----------
6418
6419 `(all geometry)'
6420 returns a list of names of all geometry objects. Use e.g. `(echo
6421 (all geometry))' to print such a list.
6422
6423 `(all camera)'
6424 returns a list of names of all cameras.
6425
6426 `(all emodule defined)'
6427 returns a list of all defined external modules.
6428
6429 `(all emodule running)'
6430 returns a list of all running external modules.
6431
6432 
6433 File: geomview, Node: and, Next: ap-override, Prev: all, Up: GCL Reference
6434
6435 7.2.13 and
6436 ----------
6437
6438 `(and EXPR1 EXPR2)'
6439 Evaluate `EXPR1' and `EXPR2' and return `t' if both return
6440 non-`nil', otherwise return `nil'.
6441
6442 
6443 File: geomview, Node: ap-override, Next: backcolor, Prev: and, Up: GCL Reference
6444
6445 7.2.14 ap-override
6446 ------------------
6447
6448 `(ap-override [on|off])'
6449 Selects whether appearance controls should override objects' own
6450 settings. On by default. With no arguments, returns current
6451 setting.
6452
6453 
6454 File: geomview, Node: backcolor, Next: background-image, Prev: ap-override, Up: GCL Reference
6455
6456 7.2.15 backcolor
6457 ----------------
6458
6459 `(backcolor CAM-ID R G B)'
6460 Set the background color of CAM-ID; R G B are numbers between 0
6461 and 1.
6462
6463 
6464 File: geomview, Node: background-image, Next: bbox-color, Prev: backcolor, Up: GCL Reference
6465
6466 7.2.16 background-image
6467 -----------------------
6468
6469 `(background-image CAM-ID [FILENAME])'
6470 Use the given image as the background of camera CAM-ID (which must
6471 be a real camera, not `default' or `allcams'). Centers the image on
6472 the window area. Works only with GL and OpenGL graphics. Use ""
6473 for filename to remove background. With no filename argument,
6474 returns name of that window's current background image, or "".
6475 Any file type acceptable as a texture is allowed, e.g. .ppm.gz,
6476 .sgi, etc.
6477
6478 
6479 File: geomview, Node: bbox-color, Next: bbox-draw, Prev: background-image, Up: GCL Reference
6480
6481 7.2.17 bbox-color
6482 -----------------
6483
6484 `(bbox-color GEOM-ID R G B)'
6485 Set the bounding-box color of GEOM-ID; R G B are numbers between 0
6486 and 1.
6487
6488 
6489 File: geomview, Node: bbox-draw, Next: camera, Prev: bbox-color, Up: GCL Reference
6490
6491 7.2.18 bbox-draw
6492 ----------------
6493
6494 `(bbox-draw GEOM-ID [yes|no])'
6495 Say whether GEOM-ID's bounding-box should be drawn; defaults to
6496 `yes' if second argument is omitted.
6497
6498 
6499 File: geomview, Node: camera, Next: camera-draw, Prev: bbox-draw, Up: GCL Reference
6500
6501 7.2.19 camera
6502 -------------
6503
6504 `(camera CAM-ID [CAMERA])'
6505 Specify data for CAM-ID; CAMERA is a string giving an OOGL camera
6506 specification. If no camera CAM-ID exists, it is created; in this
6507 case, the second argument is optional, and if omitted, a default
6508 camera is used. *Note `(new-camera ...)': new-camera.
6509
6510 
6511 File: geomview, Node: camera-draw, Next: camera-prop, Prev: camera, Up: GCL Reference
6512
6513 7.2.20 camera-draw
6514 ------------------
6515
6516 `(camera-draw CAM-ID [yes|no])'
6517 Say whether or not cameras should be drawn in CAM-ID; `yes' if
6518 omitted.
6519
6520 
6521 File: geomview, Node: camera-prop, Next: camera-reset, Prev: camera-draw, Up: GCL Reference
6522
6523 7.2.21 camera-prop
6524 ------------------
6525
6526 `(camera-prop { geometry object } [projective])'
6527 Specify the object to be shown when drawing other cameras. By
6528 default, this object is drawn with its origin at the camera, and
6529 with the camera looking toward the object's -Z axis. With the
6530 `projective' keyword, the camera's viewing projection is also
6531 applied to the object; this places the object's Z=-1 and Z=+1 at
6532 near and far clipping planes, with the viewing area -1<={X,Y}<=+1.
6533 Example: (camera-prop { < cube } projective)
6534
6535 
6536 File: geomview, Node: camera-reset, Next: car, Prev: camera-prop, Up: GCL Reference
6537
6538 7.2.22 camera-reset
6539 -------------------
6540
6541 `(camera-reset CAM-ID)'
6542 Reset CAM-ID to its default value.
6543
6544 
6545 File: geomview, Node: car, Next: cdr, Prev: camera-reset, Up: GCL Reference
6546
6547 7.2.23 car
6548 ----------
6549
6550 `(car LIST)'
6551 returns the first element of LIST.
6552
6553 
6554 File: geomview, Node: cdr, Next: clock, Prev: car, Up: GCL Reference
6555
6556 7.2.24 cdr
6557 ----------
6558
6559 `(cdr LIST)'
6560 returns the list obtained by removing the first element of LIST.
6561
6562 
6563 File: geomview, Node: clock, Next: command, Prev: cdr, Up: GCL Reference
6564
6565 7.2.25 clock
6566 ------------
6567
6568 `(clock)'
6569 Returns the current time, in seconds, as shown by this stream's
6570 clock. *Note `(set-clock ...)': set-clock. *Note `(sleep-until
6571 ...)': sleep-until.
6572
6573 
6574 File: geomview, Node: command, Next: cons, Prev: clock, Up: GCL Reference
6575
6576 7.2.26 command
6577 --------------
6578
6579 `(command INFILE [OUTFILE])'
6580 Read commands from INFILE; send corresponding responses (e.g.
6581 anything written to filename `-') to OUTFILE, stdout by default.
6582
6583 
6584 File: geomview, Node: cons, Next: copy, Prev: command, Up: GCL Reference
6585
6586 7.2.27 cons
6587 -----------
6588
6589 `(cons EXPR LIST)'
6590 Returns the list obtained by adding EXPR as first element of LIST.
6591 Note that the second argument has to be a list.
6592
6593 
6594 File: geomview, Node: copy, Next: cursor-still, Prev: cons, Up: GCL Reference
6595
6596 7.2.28 copy
6597 -----------
6598
6599 `(copy [ID] [name])'
6600 Copies an object or camera. If ID is not specified, it is assumed
6601 to be targetgeom. If name is not specified, it is assumed to be
6602 the same as the name of ID.
6603
6604 
6605 File: geomview, Node: cursor-still, Next: cursor-twitch, Prev: copy, Up: GCL Reference
6606
6607 7.2.29 cursor-still
6608 -------------------
6609
6610 `(cursor-still [INT])'
6611 Sets the number of microseconds for which the cursor must not move
6612 to register as holding still. If INT is not specified, the value
6613 will be reset to the default.
6614
6615 
6616 File: geomview, Node: cursor-twitch, Next: defun, Prev: cursor-still, Up: GCL Reference
6617
6618 7.2.30 cursor-twitch
6619 --------------------
6620
6621 `(cursor-twitch [INT])'
6622 Sets the distance which the cursor must not move (in x or y) to
6623 register as holding still. If INT is not specified, the value
6624 will be reset to the default.
6625
6626 
6627 File: geomview, Node: defun, Next: delete, Prev: cursor-twitch, Up: GCL Reference
6628
6629 7.2.31 defun
6630 ------------
6631
6632 `(defun NAME (ARG1 ...) [DOCSTRING] EXPR1 ...)'
6633 Define a named lambda-expression, that is: define NAME to evaluate
6634 to the lambda-expression `(lambda (ARG1 ...) (EXPR1 ...))' when
6635 called as a function. Also, install DOCSTRING as response to the
6636 commands `(help NAME)' and `(morehelp NAME)'. Note that DOCSTRING
6637 need not contain the command-synopsis, it is generated
6638 automatically. EXPR1 cannot be a string if `DOCSTRING' is
6639 omitted; it would be interpreted as the doc-string. The return
6640 value of `(defun ...)' is the function name. Functions can be
6641 recursive and self-modifying. It is possible to redefine
6642 builtin-functions, in this case the old definition is still
6643 available under the name `-builtin-OLDNAME-'. Argument values may
6644 be altered by `setq'; the new binding is discarded after
6645 evaluation of the surrounding `defun'-body. The special keywords
6646 `&optional' and `&rest' have the same meaning as for anonymous
6647 lambda-expression, see there. *Note `(lambda ...)': lambda. *Note
6648 `(setq ...)': setq. *Note `(let ...)': let.
6649
6650 
6651 File: geomview, Node: delete, Next: dice, Prev: defun, Up: GCL Reference
6652
6653 7.2.32 delete
6654 -------------
6655
6656 `(delete ID)'
6657 Delete object or camera ID.
6658
6659 
6660 File: geomview, Node: dice, Next: dimension, Prev: delete, Up: GCL Reference
6661
6662 7.2.33 dice
6663 -----------
6664
6665 `(dice GEOM-ID N)'
6666 Dice any Bezier patches within GEOM-ID into NxN meshes; default
6667 10. See also the appearance attribute *note `patchdice':
6668 Appearances, which makes this command obsolete.
6669
6670 
6671 File: geomview, Node: dimension, Next: dither, Prev: dice, Up: GCL Reference
6672
6673 7.2.34 dimension
6674 ----------------
6675
6676 `(dimension [N])'
6677 Sets or reads the space dimension for N-dimensional viewing.
6678 (Since calculations are done using homogeneous coordinates, this
6679 means matrices are (N+1)x(N+1).) With no arguments, returns the
6680 current dimension, or 0 if N-dimensional viewing has not been
6681 enabled.
6682
6683 
6684 File: geomview, Node: dither, Next: draw, Prev: dimension, Up: GCL Reference
6685
6686 7.2.35 dither
6687 -------------
6688
6689 `(dither CAM-ID {on|off|toggle})'
6690 Turn dithering on or off in that camera.
6691
6692 
6693 File: geomview, Node: draw, Next: dump-handles, Prev: dither, Up: GCL Reference
6694
6695 7.2.36 draw
6696 -----------
6697
6698 `(draw CAM-ID)'
6699 Draw the view in CAM-ID, if it needs redrawing. *Note `(redraw
6700 ...)': redraw.
6701
6702 
6703 File: geomview, Node: dump-handles, Next: echo, Prev: draw, Up: GCL Reference
6704
6705 7.2.37 dump-handles
6706 -------------------
6707
6708 `(dump-handles)'
6709 Dump the list of currently active handles to stdout. This function
6710 is intended for internal debugging use only.
6711
6712 
6713 File: geomview, Node: echo, Next: emodule-clear, Prev: dump-handles, Up: GCL Reference
6714
6715 7.2.38 echo
6716 -----------
6717
6718 `(echo ...)'
6719 Write the given data to the special file `-'. Strings are written
6720 literally; lisp expressions are evaluated and their values written.
6721 If received from an external program, `echo' sends to the program's
6722 input. Otherwise writes to geomview's own standard output
6723 (typically the terminal).
6724
6725 
6726 File: geomview, Node: emodule-clear, Next: emodule-define, Prev: echo, Up: GCL Reference
6727
6728 7.2.39 emodule-clear
6729 --------------------
6730
6731 `(emodule-clear)'
6732 Clears the geomview application (external module) browser.
6733
6734 
6735 File: geomview, Node: emodule-define, Next: emodule-defined, Prev: emodule-clear, Up: GCL Reference
6736
6737 7.2.40 emodule-define
6738 ---------------------
6739
6740 `(emodule-define NAME SHELL-COMMAND ...)'
6741 Define an external module called NAME, which then appears in the
6742 external-module browser. The SHELL-COMMAND string is a UNIX shell
6743 command which invokes the module. See *note `(emodule-run ...)':
6744 emodule-run. for discussion of external modules.
6745
6746 
6747 File: geomview, Node: emodule-defined, Next: emodule-isrunning, Prev: emodule-define, Up: GCL Reference
6748
6749 7.2.41 emodule-defined
6750 ----------------------
6751
6752 `(emodule-defined `modulename')'
6753 If the given external-module name is known, returns the name of
6754 the program invoked when it's run as a quoted string; otherwise
6755 returns nil. `(echo (emodule-defined `name'))' prints the string.
6756
6757 
6758 File: geomview, Node: emodule-isrunning, Next: emodule-path, Prev: emodule-defined, Up: GCL Reference
6759
6760 7.2.42 emodule-isrunning
6761 ------------------------
6762
6763 `(emodule-isrunning NAME)'
6764 Returns Lt if the emodule NAME is running, or Lnil if it is not
6765 running. NAME is searched for in the names as they appear in the
6766 browser and in the shell commands used to execute the external
6767 modules (not including arguments).
6768
6769 
6770 File: geomview, Node: emodule-path, Next: emodule-run, Prev: emodule-isrunning, Up: GCL Reference
6771
6772 7.2.43 emodule-path
6773 -------------------
6774
6775 `(emodule-path)'
6776 Returns the current search path for external modules. Note: to
6777 actually see the value returned by this function you should wrap
6778 it in a call to echo: `(echo (emodule-path))'. *Note
6779 `(set-emodule-path ...)': set-emodule-path.
6780
6781 
6782 File: geomview, Node: emodule-run, Next: emodule-sort, Prev: emodule-path, Up: GCL Reference
6783
6784 7.2.44 emodule-run
6785 ------------------
6786
6787 `(emodule-run SHELL-COMMAND ARGS...)'
6788 Runs the given SHELL-COMMAND (a string containing a UNIX shell
6789 command) as an external module. The module's standard output is
6790 taken as geomview commands; responses (written to filename `-')
6791 are sent to the module's standard input. The shell command is
6792 interpreted by /bin/sh, so e.g. I/O redirection may be used; a
6793 program which prompts the user for input from the terminal could
6794 be run with:
6795 (emodule-run yourprogram <&2)
6796 If not already set, the environment variable $MACHTYPE is set to
6797 the name of the machine type. Input and output connections to
6798 geomview are dropped when the shell command terminates. Clicking
6799 on a running program's module-browser entry sends the signal
6800 SIGHUP to the program. For this to work, programs should avoid
6801 running in the background; those using FORMS or GL should call
6802 foreground() before the first FORMS or winopen() call. *Note
6803 `(emodule-define ...)': emodule-define. *Note `(emodule-start
6804 ...)': emodule-start.
6805
6806 
6807 File: geomview, Node: emodule-sort, Next: emodule-start, Prev: emodule-run, Up: GCL Reference
6808
6809 7.2.45 emodule-sort
6810 -------------------
6811
6812 `(emodule-sort)'
6813 Sorts the modules in the application browser alphabetically.
6814
6815 
6816 File: geomview, Node: emodule-start, Next: emodule-transmit, Prev: emodule-sort, Up: GCL Reference
6817
6818 7.2.46 emodule-start
6819 --------------------
6820
6821 `(emodule-start NAME)'
6822 Starts the external module NAME, defined by emodule-define.
6823 Equivalent to clicking on the corresponding module-browser entry.
6824
6825 
6826 File: geomview, Node: emodule-transmit, Next: escale, Prev: emodule-start, Up: GCL Reference
6827
6828 7.2.47 emodule-transmit
6829 -----------------------
6830
6831 `(emodule-transmit NAME LIST)'
6832 Places LIST into external module NAME's standard input. NAME is
6833 searched for in the names of the modules as they appear in the
6834 External Modules browser and then in the shell commands used to
6835 execute the external modules. Does nothing if the module NAME is
6836 not running.
6837
6838 
6839 File: geomview, Node: escale, Next: eval, Prev: emodule-transmit, Up: GCL Reference
6840
6841 7.2.48 escale
6842 -------------
6843
6844 `(escale GEOM-ID FACTOR)'
6845 Same as scale but multiplies by exp(scale). Obsolete.
6846
6847 
6848 File: geomview, Node: eval, Next: event-keys, Prev: escale, Up: GCL Reference
6849
6850 7.2.49 eval
6851 -----------
6852
6853 `(eval EXPR)'
6854 Evaluate a lisp expression. If EXPR is an unevaluated S-expression
6855 as returned by the `(quote ...)' command then the effect will be
6856 as if calling the un-quoted expression directly. It is also
6857 possible to evaluate S-expression constructed via `car', `cdr' and
6858 `cons'. *Note `(car ...)': car. *Note `(cdr ...)': cdr. *Note
6859 `(cons ...)': cons.
6860
6861 
6862 File: geomview, Node: event-keys, Next: event-mode, Prev: eval, Up: GCL Reference
6863
6864 7.2.50 event-keys
6865 -----------------
6866
6867 `(event-keys {on|off})'
6868 Turn keyboard events on or off to enable/disable keyboard
6869 shortcuts.
6870
6871 
6872 File: geomview, Node: event-mode, Next: event-pick, Prev: event-keys, Up: GCL Reference
6873
6874 7.2.51 event-mode
6875 -----------------
6876
6877 `(event-mode MODESTRING)'
6878 Set the mouse event (motion) mode; MODESTRING should be one of the
6879 following strings:
6880 1. `"[r] Rotate"'
6881
6882 2. `"[t] Translate"'
6883
6884 3. `"[z] Cam Zoom"'
6885
6886 4. `"[s] Geom Scale"'
6887
6888 5. `"[f] Cam Fly"'
6889
6890 6. `"[o] Cam Orbit"'
6891
6892 7. `"[le] Edit Lights"'
6893
6894 
6895 File: geomview, Node: event-pick, Next: evert, Prev: event-mode, Up: GCL Reference
6896
6897 7.2.52 event-pick
6898 -----------------
6899
6900 `(event-pick {on|off})'
6901 Turn picking on or off.
6902
6903 
6904 File: geomview, Node: evert, Next: exit, Prev: event-pick, Up: GCL Reference
6905
6906 7.2.53 evert
6907 ------------
6908
6909 `(evert GEOM-ID [yes|no])'
6910 Set the normal eversion state of GEOM-ID. If the second argument
6911 is omitted, toggle the eversion state.
6912
6913 
6914 File: geomview, Node: exit, Next: ezoom, Prev: evert, Up: GCL Reference
6915
6916 7.2.54 exit
6917 -----------
6918
6919 `(exit)'
6920 Terminates geomview.
6921
6922 
6923 File: geomview, Node: ezoom, Next: freeze, Prev: exit, Up: GCL Reference
6924
6925 7.2.55 ezoom
6926 ------------
6927
6928 `(ezoom GEOM-ID FACTOR)'
6929 Same as zoom but multiplies by exp(zoom). Obsolete.
6930
6931 
6932 File: geomview, Node: freeze, Next: geometry, Prev: ezoom, Up: GCL Reference
6933
6934 7.2.56 freeze
6935 -------------
6936
6937 `(freeze CAM-ID)'
6938 Freeze CAM-ID; drawing in this camera's window is turned off until
6939 it is explicitly redrawn with `(redraw CAM-ID)', after which time
6940 drawing resumes as normal.
6941
6942 
6943 File: geomview, Node: geometry, Next: geomview-version, Prev: freeze, Up: GCL Reference
6944
6945 7.2.57 geometry
6946 ---------------
6947
6948 `(geometry GEOM-ID [GEOMETRY])'
6949 Specify the geometry for GEOM-ID. GEOMETRY is a string giving an
6950 OOGL geometry specification. If no object called GEOM-ID exists,
6951 it is created; in this case the GEOMETRY argument is optional, and
6952 if omitted, the new object GEOM-ID is given an empty geometry.
6953
6954 
6955 File: geomview, Node: geomview-version, Next: hdefine, Prev: geometry, Up: GCL Reference
6956
6957 7.2.58 geomview-version
6958 -----------------------
6959
6960 `(geomview-version)'
6961 Returns a string representing the version of geomview that is
6962 running.
6963
6964 
6965 File: geomview, Node: hdefine, Next: hdelete, Prev: geomview-version, Up: GCL Reference
6966
6967 7.2.59 hdefine
6968 --------------
6969
6970 `(hdefine `geometry'|`camera'|`window'|`appearance'|`image'|`transform'|`ntransform' name value)'
6971 Sets the value of a handle of a given type.
6972 (hdefine <type> <name> <value>)
6973 is generally equivalent to
6974 (read <type> { define <name> <value> })
6975 except that the assignment is done when hdefine is executed,
6976 (possibly not at all if inside a conditional statement), while the
6977 `read ... define' performs assignment as soon as the text is read.
6978 *Note References::. *Note `(read ...)': read. *Note `(hdelete
6979 ...)': hdelete.
6980
6981 
6982 File: geomview, Node: hdelete, Next: help, Prev: hdefine, Up: GCL Reference
6983
6984 7.2.60 hdelete
6985 --------------
6986
6987 `(hdelete [`geometry'|`camera'|`window'|`appearance'|`image'|`transform'|`ntransform'] name)'
6988 Deletes the given handle. Note that the handle will not actually be
6989 deleted in case there are still other objects referring to the
6990 handle, but once those objects are gone, the handle will also
6991 automatically go away. The object the handle referes to (if any)
6992 will only be deleted if there are no other references to that
6993 object.
6994
6995 If the optional first argument is omitted, then the first handle
6996 matching NAME will be deleted, regardless of the type of the
6997 object it is attached to. It is not an error to call this function
6998 with a non-existent handle, but it is an error to call this
6999 funcion with the name of a non-global handle, i.e. one that was
7000 not created by `(hdefine ...)' or `(read ... { define ...})'.
7001 *Note References::. *Note `(read ...)': read. *Note `(hdefine
7002 ...)': hdefine.
7003
7004 
7005 File: geomview, Node: help, Next: hmodel, Prev: hdelete, Up: GCL Reference
7006
7007 7.2.61 help
7008 -----------
7009
7010 `(help [command])'
7011 Command may include `*'s as wildcards; see also *note `(?? ...)':
7012 help. One-line command help; lists names only if multiple
7013 commands match.
7014
7015 
7016 File: geomview, Node: hmodel, Next: hsphere-draw, Prev: help, Up: GCL Reference
7017
7018 7.2.62 hmodel
7019 -------------
7020
7021 `(hmodel CAMID {virtual|projective|conformal})'
7022 Set the model used to display geometry in this camera. *Note
7023 `(space ...)': space.
7024
7025 
7026 File: geomview, Node: hsphere-draw, Next: if, Prev: hmodel, Up: GCL Reference
7027
7028 7.2.63 hsphere-draw
7029 -------------------
7030
7031 `(hsphere-draw CAMID [yes|no])'
7032 Say whether to draw a unit sphere: the sphere at infinity in
7033 hyperbolic space, and a reference sphere in Euclidean and spherical
7034 spaces. If the second argument is omitted, `yes' is assumed.
7035
7036 
7037 File: geomview, Node: if, Next: inhibit-warning, Prev: hsphere-draw, Up: GCL Reference
7038
7039 7.2.64 if
7040 ---------
7041
7042 `(if TEST EXPR1 [EXPR2])'
7043 Evaluates TEST; if TEST returns a non-nil value, returns the value
7044 of EXPR1. If TEST returns nil, returns the value of EXPR2 if
7045 EXPR2 is present, otherwise returns nil.
7046
7047 
7048 File: geomview, Node: inhibit-warning, Next: input-translator, Prev: if, Up: GCL Reference
7049
7050 7.2.65 inhibit-warning
7051 ----------------------
7052
7053 `(inhibit-warning STRING)'
7054 Inhibit warning inhbits geomview from displaying a particular
7055 warning message determined by STRING. At present there are no
7056 warning messages that this applies to, so this command is rather
7057 useless.
7058
7059 
7060 File: geomview, Node: input-translator, Next: interest, Prev: inhibit-warning, Up: GCL Reference
7061
7062 7.2.66 input-translator
7063 -----------------------
7064
7065 `(input-translator "#prefix_string" "Bourne-shell-command")'
7066 Defines an external translation program for special input types.
7067 When asked to read a file which begins with the specified string,
7068 geomview invokes that program with standard input coming from the
7069 given file. The program is expected to emit OOGL geometric data
7070 to its standard output. In this implementation, only prefixes
7071 beginning with # are recognized. Useful as in
7072 (input-translator "#VRML" "vrml2oogl")
7073
7074 
7075 File: geomview, Node: interest, Next: lambda, Prev: input-translator, Up: GCL Reference
7076
7077 7.2.67 interest
7078 ---------------
7079
7080 `(interest (COMMAND [args]))'
7081 Allows you to express interest in a command. When geomview
7082 executes that command in the future it will echo it to the
7083 communication pool from which the interest command came. COMMAND
7084 can be any command. Args specify restrictions on the values of
7085 the arguments; if args are present in the interest command,
7086 geomview will only echo calls to the command in which the
7087 arguments match those given in the interest command. Two special
7088 argument values may appear in the argument list. `*' matches any
7089 value. `nil' matches any value but supresses the reporting of that
7090 value; its value is reported as `nil'.
7091
7092 The purpose of the interest command is to allow external modules
7093 to find out about things happening inside geomview. For example,
7094 a module interested in knowing when a geom called `foo' is deleted
7095 could say `(interest (delete foo))' and would receive the string
7096 `(delete foo)' when foo is deleted.
7097
7098 Picking is a special case of this. For most modules interested in
7099 pick events the command `(interest (pick world))' is sufficient.
7100 This causes geomview to send a string of the form `(pick world
7101 ...)' every time a pick event (right mouse double click). See
7102 the *note `(pick ...)': pick. command for details.
7103
7104 
7105 File: geomview, Node: lambda, Next: let, Prev: interest, Up: GCL Reference
7106
7107 7.2.68 lambda
7108 -------------
7109
7110 `(lambda (ARG1 ...) EXPR1 ... EXPRN)'
7111 A lambda expression is like a function. To "call" a lambda
7112 expression, it has to be evoked like a function: `((lambda (arg)
7113 (+ 1 arg)) 2)'. In this example, the value of the entire
7114 expression would be 3. In general, the value of the call will be
7115 the value of EXPRN. The first list serves to define formal
7116 parameters. The lambda expression itself is just a list, starting
7117 with the key-word lambda, followed by several quoted lists. *Note
7118 `(defun ...)': defun. *Note `(setq ...)': setq. *Note `(let
7119 ...)': let. Note the argument list may contain the special
7120 keywords
7121 `&optional'
7122 giving values to the following identifiers is optional, their
7123 default value will be `nil'
7124
7125 `&rest'
7126 all excess arguments will be collected in a list, and that
7127 list will be assigned to the following argument, like so:
7128 ((lambda (&rest rest) (echo rest)) a b c d)
7129 The output would be `(a b c d)'.
7130
7131 
7132 File: geomview, Node: let, Next: lines-closer, Prev: lambda, Up: GCL Reference
7133
7134 7.2.69 let
7135 ----------
7136
7137 `(let ARGUMENTS EXPR1 ... EXPRN)'
7138 Generate a lambda expression from EXRP1 ... EXPRN, with the
7139 argument bindings described by ARGUMENTS. ARGUMENTS is a list of
7140 symbols (bound to `nil' by default) or lists of the form `(ARG
7141 VALUE)' where ARG is a symbol and not evaluated and VALUE is an
7142 S-expression which is first evaluated, then its value is bound to
7143 ARG. The entire expression evaluates to the value of EXPRN, the
7144 last expression in the body of the statement. The argument list
7145 must be present, but can be empty; in the latter case the `(let ()
7146 ...)' statement is equivalent to a `(progn ...)'. *Note `(lambda
7147 ...)': lambda. *Note `(defun ...)': defun. *Note `(setq ...)':
7148 setq.
7149
7150 
7151 File: geomview, Node: lines-closer, Next: load, Prev: let, Up: GCL Reference
7152
7153 7.2.70 lines-closer
7154 -------------------
7155
7156 `(lines-closer CAM-ID DIST)'
7157 Draw lines (including edges) closer to the camera than polygons by
7158 DIST / 10^5 of the Z-buffer range. DIST = 3.0 by default. If
7159 DIST is too small, a line lying on a surface may be dotted or
7160 invisible, depending on the viewpoint. If DIST is too large,
7161 lines may appear in front of surfaces that they actually lie
7162 behind. Good values for DIST vary with the scene, viewpoint, and
7163 distance between near and far clipping planes. This feature is a
7164 kludge, but can be helpful.
7165
7166 
7167 File: geomview, Node: load, Next: load-path, Prev: lines-closer, Up: GCL Reference
7168
7169 7.2.71 load
7170 -----------
7171
7172 `(load filename [command|geometry|camera])'
7173 Loads the given file into geomview. The optional second argument
7174 specifies the type of data it contains, which may be `command'
7175 (geomview commands), `geometry' (OOGL geometric data), or `camera'
7176 (OOGL camera definition). If omitted, attempts to guess about the
7177 file's contents. Loading geometric data creates a new visible
7178 object; loading a camera opens a new window; loading a command
7179 file executes those commands.
7180
7181 
7182 File: geomview, Node: load-path, Next: look, Prev: load, Up: GCL Reference
7183
7184 7.2.72 load-path
7185 ----------------
7186
7187 `(load-path)'
7188 Returns the current search path for command, geometry, files, etc.
7189 Note: to actually see the value returned by this function you
7190 should wrap it in a call to echo: `(echo (load-path))'. *Note
7191 `(set-load-path ...)': set-load-path.
7192
7193 
7194 File: geomview, Node: look, Next: look-encompass, Prev: load-path, Up: GCL Reference
7195
7196 7.2.73 look
7197 -----------
7198
7199 `(look [objectID] [cameraID])'
7200 Rotates the named camera to point toward the center of the
7201 bounding box of the named object (or the origin in hyperbolic or
7202 spherical space). In Euclidean space, moves the camera forward or
7203 backward until the object appears as large as possible while still
7204 being entirely visible. Equivalent to
7205 progn (
7206 (look-toward [objectID] [cameraID] {center | origin})
7207 [(look-encompass [objectID] [cameraID])]
7208 )
7209 If objectID is not specified, it is assumed to be World. If
7210 cameraID is not specified, it is assumed to be targetcam.
7211
7212 
7213 File: geomview, Node: look-encompass, Next: look-encompass-size, Prev: look, Up: GCL Reference
7214
7215 7.2.74 look-encompass
7216 ---------------------
7217
7218 `(look-encompass [objectID] [cameraID])'
7219 Moves cameraID backwards or forwards until its field of view
7220 surrounds objectID. This routine works only in Euclidean space.
7221 If objectID is not specified, it is assumed to be the world. If
7222 cameraID is not specified, it is assumed to be the targetcam.
7223 *Note `(look-encompass-size ...)': look-encompass-size.
7224
7225 
7226 File: geomview, Node: look-encompass-size, Next: look-recenter, Prev: look-encompass, Up: GCL Reference
7227
7228 7.2.75 look-encompass-size
7229 --------------------------
7230
7231 `(look-encompass-size [view-fraction clip-ratio near-margin far-margin])'
7232 Sets/returns parameters used by (look-encompass). view-fraction
7233 is the portion of the camera window filled by the object,
7234 clip-ratio is the max allowed ratio of near-to-far clipping planes.
7235 The near clipping plane is 1/near-margin times closer than the near
7236 edge of the object, and the far clipping plane is far-margin times
7237 further away. Returns the list of current values. Defaults: .75
7238 100 0.1 4.0
7239
7240 
7241 File: geomview, Node: look-recenter, Next: look-toward, Prev: look-encompass-size, Up: GCL Reference
7242
7243 7.2.76 look-recenter
7244 --------------------
7245
7246 `(look-recenter [objectID] [cameraID])'
7247 Translates and rotates the camera so that it is looking in the -z
7248 direction (in objectID's coordinate system) at the center of
7249 objectID's bounding box (or the origin of the coordinate system in
7250 non-Eudlidean space). In Euclidean space, the camera is also
7251 moved as close as possible to the object while allowing the entire
7252 object to be visible. Also makes sure that the y-axes of objectID
7253 and cameraID are parallel.
7254
7255 
7256 File: geomview, Node: look-toward, Next: merge, Prev: look-recenter, Up: GCL Reference
7257
7258 7.2.77 look-toward
7259 ------------------
7260
7261 `(look-toward [objectID] [cameraID] [origin | center])'
7262 Rotates the named camera to point toward the origin of the
7263 object's coordinate system, or the center of the object's bounding
7264 box (in non-Euclidean space, the origin will be used
7265 automatically). Default objectID is the world, default camera is
7266 targetcam, default location to point towards is the center of the
7267 bounding box.
7268
7269 
7270 File: geomview, Node: merge, Next: merge-ap, Prev: look-toward, Up: GCL Reference
7271
7272 7.2.78 merge
7273 ------------
7274
7275 `(merge {window|camera} CAM-ID { WINDOW or CAMERA ... })'
7276 Modify the given window or camera, changing just those properties
7277 specified in the last argument. E.g.
7278 (merge camera `Camera' { far 20 })
7279 sets Camera's far clipping plane to 20 while leaving other
7280 attributes untouched.
7281
7282 
7283 File: geomview, Node: merge-ap, Next: merge-base-ap, Prev: merge, Up: GCL Reference
7284
7285 7.2.79 merge-ap
7286 ---------------
7287
7288 `(merge-ap GEOM-ID APPEARANCE)'
7289 Merge in some appearance characteristics to GEOM-ID. Appearance
7290 parameters include surface and line color, shading style, line
7291 width, and lighting.
7292
7293 
7294 File: geomview, Node: merge-base-ap, Next: merge-baseap, Prev: merge-ap, Up: GCL Reference
7295
7296 7.2.80 merge-base-ap
7297 --------------------
7298
7299 `(merge-base-ap APPEARANCE)'
7300 `merge-base-ap' is a synonym for *note `merge-baseap':
7301 merge-baseap.
7302
7303 
7304 File: geomview, Node: merge-baseap, Next: mod, Prev: merge-base-ap, Up: GCL Reference
7305
7306 7.2.81 merge-baseap
7307 -------------------
7308
7309 `(merge-baseap APPEARANCE)'
7310 Merge in some appearance characteristics to the base default
7311 appearance (applied to every geom before its own apperance).
7312 Lighting is typically included in the base appearance.
7313
7314 
7315 File: geomview, Node: mod, Next: morehelp, Prev: merge-baseap, Up: GCL Reference
7316
7317 7.2.82 mod
7318 ----------
7319
7320 `(mod EXPR1 EXPR2)'
7321 Divides EXPR1 by EXPR2 and returns the remainder.
7322
7323 
7324 File: geomview, Node: morehelp, Next: name-object, Prev: mod, Up: GCL Reference
7325
7326 7.2.83 morehelp
7327 ---------------
7328
7329 `(morehelp command)'
7330 `command' may include `*' wildcards. Prints more info than *note
7331 `(help command)': help.
7332
7333 
7334 File: geomview, Node: name-object, Next: ND-axes, Prev: morehelp, Up: GCL Reference
7335
7336 7.2.84 name-object
7337 ------------------
7338
7339 `(name-object ID NAME)'
7340 Assign a new NAME (a string) to ID. A number is appended if that
7341 name is in use (for example, `foo' -> `foo<2>'). The new name,
7342 possibly with number appended, may be used as object's id
7343 thereafter.
7344
7345 
7346 File: geomview, Node: ND-axes, Next: ND-color, Prev: name-object, Up: GCL Reference
7347
7348 7.2.85 ND-axes
7349 --------------
7350
7351 `(ND-axes CAMID [CLUSTERNAME [Xindex Yindex Zindex [Windex]]])'
7352 In our model for N-D viewing (enabled by (dimension)), objects in
7353 N-space are viewed by N-dimensional _camera clusters_. Each real
7354 camera window belongs to some cluster, and shows & manipulates a
7355 3-D axis-aligned projected subspace of the N-space seen by its
7356 cluster. Moving one camera in a cluster affects its siblings.
7357
7358 The ND-axes command configures all this. It specifies a camera's
7359 cluster membership, and the set of N-space axes which become the
7360 3-D camera's X, Y, and Z axes. Axes are specified by their
7361 indices, from 1 to N for an N-dimensional space. Cluster
7362 CLUSTERNAME is implicitly created if not previously known.
7363
7364 In principle it is possible to map the homogeneous component of a
7365 conformal 4 point to some other index; this would be done by
7366 specifying 0 for one of `Xindex', `Yindex' or `Zindex' and giving
7367 `Windex' some positive value. This is probably not useful because
7368 Geomview does not support non-Euclidean geometries for in higher
7369 dimensions.
7370
7371 To read a camera's configuration, use `(echo (ND-axes CAMID))'.
7372 The return value is an array of 4 integers, the last one should 0.
7373