This is geomview, produced by Makeinfo version 3.12h from geomview.texi.

INFO-DIR-SECTION Graphics Applications
START-INFO-DIR-ENTRY
* Geomview: (geomview).         The interactive 3D viewing program.
END-INFO-DIR-ENTRY


File: geomview,  Node: Tutorial,  Next: Interaction,  Prev: Overview,  Up: Top

Tutorial
********

   This chapter leads you through some of the basics of using Geomview.
Work through this chapter in front of a computer where you can try out
the examples given here to get a feel for what you can do with Geomview.

   To start Geomview, login to the computer and get a shell window.  A
shell window is a window in which you can type unix commands; the prompt
in the window usually ends with a '%'.  In the shell window (the mouse
cursor must be in the window) type the following (`<Enter>' here means
hit the "Enter" key):

     geomview tetra dodec <Enter>

   This command starts up Geomview and loads two example objects, a
tetrahedron and a dodecahedron.  After a few seconds three windows
should appear as shown in Figure 1.  (The figures in this document
appear only in the hardcopy version, not the Info version.)

   The panel on the left is Geomview's main control panel; it's called
the _Main_ panel.  The skinny panel in the middle is the _Tools_ panel
and is for selecting different kinds of motions.  The window on the
right is the camera window and in it you see a large tetrahedron and a
dodecahedron which is partially obscured by the tetrahedron.

   Geomview has lots of panels but by default it displays only these
three.  We'll describe some aspects of these and a couple of the others
in this tutorial.  You can read more about these and other panels in
the later chapters of this manual.

   Put the mouse cursor in the camera window and press down and hold the
left mouse button.  Now, while holding down the button, slowly move the
mouse around.  You should see the picture rotate in the direction you
move the mouse.    If you lift up on the mouse button while moving the
mouse, the picture continues rotating.  To stop it, hold the mouse very
still and click down and up on the left mouse button.

   Geomview uses the _glass sphere_ model for mouse-based motion.  This
means you are supposed to think of the object as being inside an
invisible sphere and the mouse cursor is a gripper outside the sphere.
When you hold down the left mouse button, the gripper grabs the sphere;
when you let go of the button, the gripper releases the sphere.  Moving
the mouse while holding the button down causes the sphere (and hence
the object) to move in the same direction as the mouse.

   In addition to the two solids you should also see two wireframe
boxes in the camera window.  These are the "bounding boxes" of the two
objects.  By default Geomview puts a bounding box around each object
that it displays so that you have an idea of how large it is.

   Notice that as you move the mouse around the tetrahedron and
dodecahedron move as a unit.  That is because by default what you are
actually moving is the "World".  To move an individual object instead of
the whole world, move the mouse cursor to the _Targets_ browser in the
_Main_ panel.  Click (any button) on the word _tetra_.  This makes the
tetrahedron be the "target object".  Now move the cursor back to the
camera window and you can rotate just the tetrahedron.

   The motion that you have been applying up to now has been rotation,
because that is the motion mode that is selected in the _Tools_ panel.
To translate instead, click on the _Translate_ button.  Now when you
move the mouse in the camera window while holding down the left button,
the tetrahedron (which should still be the target object from before)
will translate in the direction you move the mouse.  Notice that you
can translate it beyond the edge of the window as long as you keep
holding the left mouse button down.  If you lift up on the mouse button
while moving the mouse, the tetrahedron will keep going.  It moves
rather rapidly so it is very easy to lose track of where it is.

   If you accidentally lose the tetrahedron by translating it too far
out of the view of the window, you can get it back by clicking on the
_Center_ button in the _Tools_ panel.  This causes it to come back to
its initial position.

   Click on the _Center_ button to bring the tetrahedron home, and then
translate it off to one side so that you can completely see the
dodecahedron.

   Your world now has two objects in it that are beside each other.  You
should see the dodecahedron in the middle of the window and maybe part
of the tetrahedron off to one side.  Go back to the _Targets_ browser
in the _Main_ panel and click on "World" to select the whole world
again.  Now click on the _Look At_ button in the _Tools_ panel.  You
should see something like Figure 2 -- the dodecahedron and the
tetrahedron in the middle of the window next to each other.  The _Look
At_ button positions the camera in such a way that the target object is
centered in the window.

   Now put the cursor over the middle of the dodecahedron and
double-click the right mouse button.  This means click it down-and-up
two times in rapid succession.  Notice that the dodecahedron becomes
the target object; you can see this in the _Targets_ browser in the
_Main_ panel.  Double-clicking the right mouse button on an object is
another way to make it the target object.

   Go to the _Inspect_ menu at the top of the _Main_ panel and select
_Appearance_.  This brings up the _Appearance_ panel.  When it appears,
if it partially obscures another Geomview window you can move it off to
one side by dragging its frame with the middle mouse button down.

   The _Appearance_ panel lets you control various things about the way
Geomview draws objects.  Note the buttons labeled _[af] Faces_ and
_[ae] Edges_.  Click on the _[ae] Edges_ one, and notice that Geomview
is now drawing the edges of the dodecahedron.  Click on it again and
the edges go away.  Click several times and watch the edges come and
go.  When you've had enough of this, leave the edges on and click the
_[af] Faces_ button.  This toggles the faces on and off.  Click the
button again to turn them back on.

   Now click on the _[Cf] Faces_ button under the word _COLOR_.   A
color chooser panel like the one in Figure 4 should appear.

   Note the three sliders, _H_, _S_, and _V_, controlling the color's
hue, saturation, and value (lightness).  Clicking the _HSV_ button
gives a different set of sliders, one each for red, green, and blue.
Numerical values for both RGB and HSV color systems can be seen or
edited at the bottom of the panel.  The dodecahedron's previous colors
were specified in the file `dodec' that you loaded when we started
Geomview.  The color that you specify with the color panel overrides
the old colors.  You can adjust the intensity of the color with the
_Intensity_ slider.  When you find a color that you like, click the
_Done_ button.

   Now put the cursor somewhere over the gray background and
double-click the right mouse button; this picks "World" as the target
object.  Click the _Look At_ button to look at the world again.

   Notice that in the _Appearance_ panel the settings of the buttons
have changed from the way you left them with the dodecahedron.  That's
because the _Appearance_ panel always displays the settings for the
target object, which is now the world, which still has its default
settings.

   Click on the _[ab] BBox_ button under the word _Draw_.  The bounding
boxes go away.  Now put the cursor back in the camera window.  At the
keyboard, type the keys `a 'b.  Notice that the bounding boxes come
back.  `a 'b is the keyboard shortcut for the bounding box toggle
button; the string "[ab]" appears on the button to indicate this.  Most
of Geomview's buttons have keyboard shortcuts that you can use instead
if you want.  This is useful once you are familiar with Geomview and
don't want to have to move around among lots of panels.

   Now select the tetrahedron, either by double-clicking the right mouse
button on it, or by selecting "tetra" in the _Targets_ browser.  Then
click on the _Delete_ button in the _Main_ panel.  The tetrahedron
should disappear.  This is how you get rid of an object.

   You can also load objects from within Geomview.  Click on the _File_
menu in the _Main_ panel and choose _Open_.  The _Files_ panel will
appear.  Below the middle of this panel is a browser with three lines
in it; the second line is a directory with lots of Geomview example
files in it.  Click on that second line.  Your _Files_ panel should
then look something like Figure 5.  Scroll down in the list of files
until you see `tref.off'.  Click on that line, and then click on the
_Add_ button.  A large trefoil-shaped tube will appear in your window.
Click the _Done_ button in the _Files_ panel to dismiss the panel.

   Now click on the _Reset_ button in the _Tools_ panel.  This causes
everything to return to its home position.  You should see something
like Figure 6 at this point: a dodecahedron and a trefoil knot.

   Play around with the trefoil knot and the dodecahedron.  Experiment
with some of the other buttons in the _Tools_ panel.  Try coloring the
trefoil knot with the _Appearance_ panel.

   For a tutorial on how to create your own objects to load into
Geomview, see file `doc/oogltour' distributed with Geomview.  The
things in that file will be incorporated into a future version of this
manual.


File: geomview,  Node: Interaction,  Next: Starting Geomview,  Prev: Tutorial,  Up: Top

Interaction
***********

   This chapter describes how you interact with Geomview through the
mouse and keyboard.

* Menu:

* Starting Geomview::      Starting Geomview.
* Command Line Options::   Command Line Options.
* Basic Interaction::      Basic Interaction: The Main Panel.
* Loading::                Loading Objects Into Geomview.
* Mouse Motions::          Using the Mouse to Manipulate Objects.
* Appearance::             Changing the Way Things Look.
* Cameras::                Cameras.
* Saving::                 Saving your work.
* Commands::               The Commands Panel.
* Keyboard Shortcuts::     Keyboard Shortcuts.


File: geomview,  Node: Starting Geomview,  Next: Command Line Options,  Prev: Interaction,  Up: Interaction

Starting Geomview
=================

   The usual way to start Geomview is to type `geomview <Enter>' in a
shell window (<Enter> means hit the "Enter" key).  It may take Geomview
a few seconds to start up; one or more windows will appear and you can
begin interacting with Geomview immediately.

   It is also possible to specify actions for Geomview to perform at
startup time by giving arguments in the shell command line.  *Note
Command Line Options::.


File: geomview,  Node: Command Line Options,  Next: Basic Interaction,  Prev: Starting Geomview,  Up: Interaction

Command Line Options
====================

   Here are the command line options that Geomview allows:

`-b R G b'
     Set the window background color to the given R G b values.

`-c FILE'
     Interpret the gcl commands in FILE, which may be the special
     symbol `-' for standard input.  For a description of gcl, *Note
     GCL::.

`-c COMMAND'
     Commands may also be supplied literally, as in
          -c "(ui-panel main off)"
     Since COMMAND includes parentheses, which have special meaning to
     the shell, COMMAND must be quoted.  Multiple -C options are
     allowed.

`-wins NWINS'
     Causes Geomview to initially display NWINS camera windows.

`-wpos WIDTH,HEIGHT[@XMIN,YMIN]'
     Specifies the initial location and size of the first camera
     window.  The values for WIDTH, HEIGHT, XMIN, and YMIN are in
     screen (pixel) coordinates.

`-M OBJECTNAME'
     Display (possibly dynamically changing) geometry sent from the
     programs `geomstuff' or `togeomview'.  This actually listens to the
     named pipe `/tmp/geomview/objectname'; you can achieve the same
     effect with the shell commands:
          mkdir /tmp/geomview
          mknod /tmp/geomview/objectname p
     (assuming the directory and named pipe don't already exist), then
     executing the gcl command: `(geometry objectname  <
     /tmp/geomview/objectname)'

`-Mc PIPENAME'
     Like `-M' above, but expects gcl commands, rather than OOGL
     geometry data, on the connection.

`-nopanels'
     Start up displaying no panels, only graphics windows.  Panels may
     be invoked later as usual with the `Px' keyboard shortcuts or with
     the `ui-panel' command.

`-e MODULE'
     Start an external module; MODULE is the name associated with the
     module, appearing in the main panel's Applications browser, as
     defined by the `emodule-define' command.

`-start MODULE ARGS ...'
     Like -e but allows you to pass arguments to the external module.
     "-" signals the end of the argument list; the "-" may be omitted
     if it would be the last argument on the Geomview command line.

`-run SHELL-COMMAND ARGS ...'
     Like -start but takes the pathname of executable of the external
     module instead of the module's name.  The pathnames of all known
     module directories are appended to the UNIX search path when
     invoking SHELL-COMMAND.


File: geomview,  Node: Basic Interaction,  Next: Loading,  Prev: Command Line Options,  Up: Interaction

Basic Interaction: The Main Panel
=================================

   Normally when you invoke Geomview, three windows appear: the _Main_
panel, the _Tools_ panel, and one camera window.  Geomview has many
other windows but most things can be done with these three and so by
default the others do not appear.  This section of the manual
introduces some basic concepts that are used throughout the rest of the
manual and describes the _Main_ panel.

   Geomview can display an arbitrary number of objects simultaneously.
The _Targets_ browser in the _Main_ panel displays a list of all the
objects that Geomview currently knows about.  This browser has a line
for each object that you have loaded, plus some lines for other
objects.  One of the other objects is called `World' and corresponds to
the all the currently loaded objects, treated as if they were one
object.  Most of the operations that you can do to one object, such as
applying a motion or changing a color, can also be done to the "World"
object.

   The _Targets_ browser also has an entry for each camera.  By default
there is only one camera; it is possible to add more of them via the
_New Camera_ entry of the _Main_ panel's _File_ menu.  Geomview treats
cameras in much the same way as it does geometric objects.  For
example, you can move cameras around and add them and delete them just
as with geometric objects.  Cameras do not usually show up in the
display as an object that you see.  Each camera has a separate camera
window which displays the view as seen by that camera.  (It is possible
for each camera to display a geometric representation of other cameras.
*Note Cameras::.)

   Because Geomview treats cameras and geometric objects very similarly,
the term "object" in this documentation is used to refer to either one.
When we need to distinguish between the two kinds of objects, we use
the term "geom" to denote a geometric object and the word "camera" to
denote a camera.

   The object which is selected (highlighted) in the _Targets_ browser
is called the "target" object.  This is the object that receives any
actions that you do with the mouse or keyboard.  You can change the
target object by selecting a different line in the _Targets_ browser.
Another way to change the target object is to put the mouse cursor
directly over a geom in a camera window and rapidly double-click the
right mouse button.  This process is called "picking"; the picked
object becomes the new target.

   Geomview objects are all known by two names, both of which are shown
in the _Targets_ browser.  The first name given there, which appears in
square brackets ([ ]), is a short name assigned by Geomview when you
load the object.  It consists of the letter `g' for geoms and `c' for
cameras, followed by a number.  The second name is a longer more
descriptive name; by default this is the name of the file that the
object was loaded from.  The two names are equivalent as far as Geomview
is concerned; at any point where you need to specify a name you can give
either one.

   To manipulate an object, make sure you that the object you want to
move is the target object, and put the mouse cursor in a camera window.
Motions are applied by holding down either the left or middle mouse
button and moving the mouse.  There are several different motion
"modes", each for applying a different kind of motion.  The _MOTION
MODE_ browser in the _Main_ panel indicates the current motion mode.
The default is "Rotate".  You can change the current motion mode by
selecting a new one in the _MOTION MODE_ browser, or by using the
_Tools_ panel.  For more information about motion modes, *Note Mouse
Motions::.

   The _Modules_ browser lists Geomview external modules.  An external
module is a separate program that interacts with Geomview to extend its
functionality.  For information on external modules, *Note Modules::.

   The menu bar at the top of the main panel offers menus for common
operations.

   To create new windows, load new objects, save objects or other
information, or quit from geomview, see the _File_ menu.

   To copy or delete objects, see the _Edit_ menu.

   You can invoke any panel from the _Inspect_ menu.

   The _Space_ menu lets you choose whether geomview operates in
Euclidean, Hyperbolic, or Spherical mode.  Euclidean mode is selected
by default.  For details about using _Hyperbolic_ and _Spherical_
spaces, *Note Non-Euclidean Geometry::.

   Most actions that you can do through Geomview's panels have
equivalent keyboard shortcuts so that you can do the same action by
typing a sequence of keys on the keyboard.  This is useful for advanced
users who are familiar with Geomview's capabilities and want to work
quickly without having to have lots of panels cluttering up the screen.
Keyboard shortcuts are usually indicated in square brackets ([ ]) near
the corresponding item in a panel.  For example, the keyboard shortcut
for _Rotate_ mode is 'r'; this is indicated by "[r]" appearing before
the word "Rotate" in the _MOTION MODE_ browser.  To use this keyboard
shortcut, just hit the `r' key while the mouse cursor is in any
Geomview window.  Do not hit the `<Enter>' key afterwards.

   Some keyboard shortcuts consist of more than one key.  In these cases
just type the keys one after the other, with no `<Enter>' afterwards.
Keyboard shortcuts are case sensitive.

   Many keyboard shortcuts can be preceded by a numeric parameter.  For
example, typing `ae' toggles the state of drawing edges, while `1ae'
always enables edge drawing.

   The _keyboard_ field in the upper left corner of the _Main_ panel
echos the current state of keyboard shortcuts.

   For a list of all keyboard shortcuts, press the _`?'_ key.


File: geomview,  Node: Loading,  Next: Mouse Motions,  Prev: Basic Interaction,  Up: Interaction

Loading Objects Into Geomview
=============================

   There are several ways to load an object into Geomview.

the _Files_ panel
     If you click the _Load_ button in Geomview's _Main_ panel, the
     _Files_ panel will appear.

     This panel lets you select a file from a variety of directories.
     The top of the panel is a standard Motif file browser.  Below this
     is a list of directories on geomview's standard search path; click
     on one of these to browse files in that directory.

     To select a file, double-click on its name in the browser at upper
     right, or click on its name and press the <Enter> key, or type the
     file's name into the text box at the bottom of the browser and
     press <Enter>.

     If the selected file contains OOGL geometric data, it will be
     added to the geomview _Targets_ browser.  If it contains GCL
     commands instead, the file will be interpreted.  *Note GCL::.

     When the _Files_ panel first appears, the directory selected in the
     directory browser is the current directory -- the one from which
     you invoked Geomview.  The file browser shows _all_ the files in
     this directory, including ones that are not Geomview files.  If
     you try to load a file that doesn't contain either an OOGL object
     or Geomview commands, Geomview will print out an error message.

     The directory browser also lists a second and third directory in
     addition to the current directory.  The second one, which ends in
     `data/geom', is the Geomview example data directory.  This contains
     a wide variety of sample objects.  It also contains several
     subdirectories.  In particular, the `hyperbolic' and `spherical'
     subdirectories have sample hyperbolic and spherical objects,
     respectively.  Directory entries in the browser look just like
     file entries; to view a subdirectory, click on it.

     The third directory shown in the directory browser, which ends in
     `geom', contains several subdirectories with other Geomview files
     in them.  These are used less frequently than the ones in the
     `data/geom' directory.

     You can change the list of directories shown the _Files_ panel's
     directory browser by using the `set-load-path' command; *note
     GCL::..

the `<' keyboard shortcut:
     If you type `<' in any Geomview window, the _Load_ panel will
     appear.  This is a small version of the _Files_ panel; it contains
     a text field in which you can enter the name of a file to load (or
     a GCL command surrounded by parentheses).  After typing the name
     of the file to load, type `<Enter>'; Geomview will load the file
     as if you had loaded it with the _Add_ button in the _Files_
     panel.  If, after bringing up the small load panel with `<', you
     decide you want to use the larger _Files_ panel after all, press
     the _File Browser_ button.

geometry loading commands:
     The `load', `geometry', `new-geometry', and `read' gcl commands
     allow you to load an object into Geomview; *Note GCL::.


File: geomview,  Node: Mouse Motions,  Next: Point of Interest,  Prev: Loading,  Up: Interaction

Using the Mouse to Manipulate Objects
=====================================

   Geomview lets you manipulate objects with the mouse.  There are six
different mouse motion modes: _Rotate_, _Translate_, _Cam Fly_, _Cam
Zoom_, _Geom Scale_, and _Cam Orbit_.  The tools panel has a button for
each of these modes; to switch modes, click on the corresponding
button.  You can also select these through the _Motion Mode_ browser on
the _Main_ panel.

   This section describes basic mouse interaction.  For details, *note
Commands::..

   Each of the motion modes uses a common paradigm for how the motion is
applied.  In particular, each depends on the current _target_ object
and the current _center_ object.  These are explained in the following
paragraphs.

   The current target object is shown in the _Target_ field in the
_Tools_ panel.  This is the same as the selected object in the
_Targets_ browser in the _Main_ panel, and you can change it by either
selecting a new object in the browser, by typing a new entry in the
field, or by picking an object in a camera window by double-clicking
the right mouse button with the cursor over the object.

   The current center object is shown in the _Center_ field in the
_Tools_ panel.  Its default value is the special word "target", which
means that the center object is whatever the target object is.  You can
change the center to any object by typing it in the _Center_ field.
The origin of the center object is held fixed in _Rotate_ and _Orbit_
modes.  Normally the center object is one of the existing geoms listed
in the _Targets_ browser, and the actual center of rotations is the
origin of that object's coordinate system.  It is possible, however, to
select an arbitrary point of interest on an object as the center. For
details, *note Point of Interest::..

   You apply a mouse motion by holding down either the left or middle
mouse button with the cursor in a camera window and moving the mouse.
Most of the modes have _inertia_, which means that if you let go of the
button while moving the mouse, the motion will continue.  It may be
helpful to imagine the mouse cursor as being a gripper; when you hold a
mouse button down, it grips the target object and you can move it.  When
you let go of the mouse button, the gripper releases the object.
Letting go of the mouse button while moving the mouse is like throwing
the object -- the object continues moving independent of the mouse.
Inertia can be turned off; see the _Main_ panel's _Motion_ menu,
described below.

   Generally, the left mouse button controls motion in the screen plane,
while the middle mouse controls motion along or around the forward
direction.

   Pressing the shift key while dragging with left or middle mouse
buttons in most motion modes gives slow-speed motions, useful for fine
adjustment.

   You can pick any point on an object (not just its origin) as the
center of motion by holding down the shift key while clicking the right
mouse button; this chooses a point of interest.

_Rotate_
     In _Rotate_ mode, hold the left mouse button down to rotate the
     target object about the center object.  Rotation proceeds in the
     direction that you move the mouse.  Specifically, the axis of
     rotation passes through the origin of the center object, is
     parallel to the camera view plane, and is perpendicular to the
     direction of motion of the mouse.  When the center is "target",
     this means that the target object rotates about its own origin.

     The middle mouse button in _Rotate_ mode rotates the target object
     about an axis perpendicular to the view plane.

_Translate_
     In _Translate_ mode, hold the left mouse button down to translate
     the target object in the direction of mouse motion.  The middle
     mouse button translates the target along an axis perpendicular to
     the view plane.

     In Euclidean space, the center object is essentially irrelevant for
     translations.  In hyperbolic and spherical spaces, where
     translations have a unique axis, this axis is chosen to go through
     the origin of the center object.

_Cam Fly_
     _Cam Fly_ is a crude flight simulator that lets you fly around the
     scene.  It works by moving the camera.  Move the mouse while
     holding the left mouse button down to point the camera in a
     different direction.  To move forward or backward, hold down the
     middle button and move the mouse vertically.  Both of these
     motions have inertia; typically the easiest way to fly around a
     scene is to give the camera a slight forward push by letting go of
     the middle button while moving the mouse upward, and then using
     the left button to steer.

     _Cam Fly_ affects the camera window that the mouse is in; it
     ignores the target object and the center object.

_Cam Orbit_
     _Cam Orbit_ mode lets you rotate the current camera around the
     current center. The left mouse button does this rotation.  The
     middle mouse button in _Cam Orbit_ mode acts as in _Cam Fly_ mode:
     it moves the camera forward or backward.

     In general _Cam Orbit_ does not move the target object, although
     if the current camera is selected as the target and the center is
     also the target, it will pivot that camera about itself just as in
     _Cam Fly_ mode.

_Cam Zoom_
     _Cam Zoom_ mode lets you change the current camera's field of view
     with the mouse; hold the left mouse button down and move the mouse
     to change it.  The numeric value of the field of view is shown in
     the _FOV_ field in the _Camera_ panel.

_Geom Scale_
     _Geom Scale_ mode lets you enlarge or shrink a geom.  It operates
     on the target object if that object is a geom.  If the target is a
     camera, _Geom Scale_ operates on the geom that was most recently
     the target object.  Moving the mouse while holding down the left
     mouse button scales the object either up or down, depending on the
     direction of mouse motion.  The center of the applied scaling
     transformation is the center object.

     Scaling is meaningful only in Euclidean space; attempts to scale
     are ignored in other spaces.

     _Geom Scale_ mode does not have inertia.

   The _Stop_, _Look At_, _Center_, and _Reset_ buttons on the _Tools_
panel perform actions related to motions but do not change the current
motion mode.

_Stop_
     The _Stop_ button causes all motions to stop.  It affects all
     moving objects, not just the target object.  Its keyboard shortcut
     is `H'.

     The keyboard command `h', which does not correspond to a panel
     button, stops the current motion for the target object only.

_Look At_
     The _Look At_ button causes the current camera to be moved to a
     position such that it is looking at the target object, and such
     that the target object more or less fills the window.

     The Look At command is unreliable in non-Euclidean spaces.

_Center_
     The _Center_ button undoes the target object's transformation,
     moving it back to its home position, which is where it was when you
     originally loaded it into Geomview.

_Reset_
     The _Reset_ button stops all motion and causes all objects to move
     back to their home positions.

   The _Tools_ panel also sports a _Main_ button, to invoke the main
panel in case it was dismissed or buried, and a _Done_ button to close
the _Tools_ panel.

   The _Main_ panel's _Motion Style_ menu has special controls
affecting how mouse motions are interpreted.

_[ui] Inertia_
     Normally, moving objects have inertia: if the mouse is still moving
     when the button is released, the selected object continues to move.
     When _Inertia_ is off, objects cease to move as soon as you release
     the mouse.

_[uc] Constrain Motion_
     It's sometimes handy to move an object in a direction aligned with
     a coordinate axis: exactly horizontally or vertically.  Selecting
     _Constrain Motion_ changes the interpretation of mouse motions to
     allow this; approximately-horizontal or approximately-vertical
     mouse dragging becomes exactly horizontal or vertical motion.
     Note that the motion is still along the X or Y axes of the camera
     in which you move the mouse, not necessarily the object's own
     coordinate system.

_[uo] Own Coordinates_
     It's sometimes handy to move objects with respect to the
     coordinate system where they were defined, rather than with
     respect to some camera's view.  While _Own Coordinates_ is
     selected, all motions are interpreted that way: dragging the mouse
     rightward in translate mode moves the object in its own +X
     direction, and so on.  May be especially useful in conjunction with
     the _Constrain Motion_ button.


File: geomview,  Node: Point of Interest,  Next: Appearance,  Prev: Mouse Motions,  Up: Mouse Motions

Selecting a Point of Interest
-----------------------------

   It is sometimes useful to specify a particular point on some object
in a geomview window as the center point for mouse motions.  You can do
this by shift-clicking the right mouse button (i.e. click it once while
holding down the shift key on the keyboard) with the cursor over the
desired point.  This point then becomes the _point of interest_.  The
point of interest must be on an existing object.

   Selecting a point of interest simplifies examining a small portion
of a larger object.  Shift-right-click on an interesting point, and
select _Orbit_ mode.  Use the middle mouse button to approach, and the
left mouse to orbit the point, examining the region from different
directions.

   When you have selected a point of interest, the current center object
changes to an object named "CENTER", which is an invisible object
located at the point of interest.  In addition, mouse motions for the
window in which you made the selection are adjusted so that the point of
interest follows the mouse.

   You can change the point of interest at any time by selecting a new
one by shift-clicking the right mouse button again.  You can cancel the
point of interest altogether by shift-clicking the right mouse button
with the cursor on the background (i.e. not on any object).  This
changes the center object back to its default value, "target".

   The object named "CENTER", which serves as the center object for the
point of interest, is a special kind of geom called an "alien".  It does
not appear in the _Targets_ browser.  By default it has no geometry
associated with it and hence is invisible.  You can, however,
explicitly give it some geometry using a GCL command, causing it to
appear.  Use the `geometry' command for this: `(geometry CENTER
GEOMETRY)', where GEOMETRY is any valid geometry.  For example,
`(geometry CENTER { < xyz.vect })' causes the file `xyz.vect', which is
one of the standard example files distributed with geomview, to be used
at the geometry for CENTER.

   What happens internally when you select a point of interest is that
the center is set to the object called CENTER, and that object is
positioned at the point of interest.  In addition, in order for mouse
motions to track the point of interest, the current camera's focal
length is set to be the distance from the camera to the point of
interest.  You can accomplish this via GCL with the following commands:
     (if (real-id CENTER) nil (new-alien CENTER {}))
     (ui-center CENTER)
     (transform-set CENTER universe universe translate X Y Z)
     (merge camera CAM-ID { focus D })

where `(X,Y,Z)' are the (universe) coordinates of the point of
interest, and D is the distance from that point to the current camera,
CAM-ID.  The first command above creates the "alien" CENTER if it does
not yet exist.


File: geomview,  Node: Appearance,  Next: Appearance Panel,  Prev: Point of Interest,  Up: Interaction

Changing the Way Things Look
============================

   Geomview uses a hierarchy of appearances to control the way things
look.  An "appearance" is a specification of information about how
something should be drawn.  This can include many things such things as
color, lighting, material properties, and more.  Appearances work in a
hierarchal manner: if a certain appearance property, for example face
color, is not specified in a particular object's appearance, that object
is drawn using that property from the parent appearance.  If both the
parent and the child appearance specify a property, the child's setting
takes precedence unless the parent appearance is set to override.

   Every geom in Geomview has an appearance associated with it.  There
is also an appearance associated with the "World" geom, which serves as
the parent of each individual geom's appearance.  Finally, there is a
global "base" appearance, which is the parent of the World appearance.

   The base appearance specifies reasonable values for all appearance
information, and by default none of the other appearances specify
anything, which means they inherit their values from the base
appearance.  This means that by default all objects are drawn using the
base appearance.

   If you change a certain appearance property for a geom, that property
is used in drawing that geom.  The parent appearance is used for any
properties that you do not explicitly set.

   Geomview has three panels which let you modify appearances.

* Menu:

* Appearance Panel::	Color etc.
* Materials Panel::	Surface Material properties.
* Lighting Panel::	Lighting Parameters.


File: geomview,  Node: Appearance Panel,  Next: Materials Panel,  Prev: Appearance,  Up: Appearance

The Appearance Panel
--------------------

   The _Appearance_ panel lets you change most common appearance
properties of the target object.  If the target is an individual geom,
then changes you make in the appearance panel apply to that geom's
appearance.  If the target is the World, then appearance panel changes
apply to the World appearance _and_ to all individual geom appearances.
(Users have found that this is more desirable than having the changes
only apply to the World appearance.)  If the target is a camera, then
appearance panel changes apply to the geom that was most recently the
target.

   The five buttons near the upper right corner under the word _Draw_
control what parts of the target geom are drawn.

_Faces_
     This button specifies whether faces are drawn.

_Edges_
     This button specifies whether edges are drawn.

_BBox_
     This button specifies whether the bounding box is drawn.

_Vects_
     This button specifies whether VECT objects are drawn.  VECTs are a
     type of OOGL object that represent points and line segments in
     3-space; they are distinct from edges of other kinds of objects,
     and it is sometimes desirable to have separate control over
     whether they are drawn.

_Normals_
     This button specifies whether surface normal vectors are drawn.

   The four buttons under _Color_ labeled _Faces_, _Edges_, _Normals_,
and _BBox_ let you specify the color of the corresponding aspect of the
target geom.  Clicking on one of them brings up a color chooser panel.
This panel offers two sets of sliders: H(ue) S(aturation) V(alue), or
R(ed) G(reen) B(lue), each in the range 0 through 1.  The square shows
the current color, which is given numerically in both HSV and RGB
systems in the corresponding text boxes.

   In the HSV color system, hue H runs from red at 0, green at .333,
blue at .667, and back to red at 1.0.  Saturation gives the fraction of
white mixed into the color, from 0 for pure gray to 1 for pure color.
Value gives the brightness, from 0 for black to 1 for full brightness.

   Pressing the _RG_b or _HSV_ button at top center switches the
sliders to the other color system.  You can adjust colors either via
the sliders, or by typing in either the RGB or HSV text boxes.

   Click _OK_ to accept the color that you have chosen, or _Cancel_ to
retain the previous color setting.

   The _SHADING_ browser lets you specify the shading model that
Geomview uses to paint the target geom.

_Constant_
     Every face of the object is drawn with a constant color which does
     not depend on the location of the face, the camera, or the light
     sources.  If the object does not contain per-face or per-vertex
     colors, the diffuse color of the object's appearance is used.  If
     the object contains per-face colors, they are used.  If the object
     contains per-vertex colors, each face is painted using the color
     of its first vertex.

_Flat_
     Each face of the object is drawn with a color that depends on the
     relative location of the face, the camera, and the light sources.
     The color is constant across the face but may change as the face,
     camera, or lights move.

_Smooth_
     Each face of the object is drawn with smoothly interpolated colors
     based on the normal vectors at each vertex.  If the object does
     not contain per-vertex normals, this has the same effect as flat
     shading.  If the object has reasonable per-vertex normals, the
     effect is to smooth over the edges between the faces.

_CSmooth_
     Each face of the object is drawn with exactly the specified
     color(s), independent of lighting, orientation, and material
     properties.  If the object is defined with per-vertex colors, the
     colors are interpolated smoothly across the face; otherwise the
     effect is the same as in Constant shading style.

   The _Facing Normals_ button on the _Appearance_ panel indicates
whether or not Geomview should arrange that normal vectors always face
the viewer.  If a normal vector points away from the viewer the color
of the corresponding face or vertex usually is darker than is desired.
Geomview can avoid this by using the opposite normal in shading
calculations.  This is the default.  Using _Facing Normals_ can give
strange flickering dark or light shading effects, though, near the
horizon of a fairly smooth facetted object.  Press this button to use
the normals given with the object.

   The three text fields in the lower left corner of the _Appearance_
panel are:

_Line Width_
     The width, in pixels, for lines drawn by Geomview.

_Normal Length_
     This is actually a scale factor; when normal vectors are drawn,
     Geomview draws them to have a length that is their natural length
     times this number.

_Patch Dicing_
     Geomview draws Bezier patches by first converting them to meshes.
     This parameter specifies the resolution of the mesh: if _Patch
     Dicing_ is N, then an N by N mesh is used to draw each Bezier
     patch.  if _Patch Dicing_ is 1, the resolution reverts to a
     built-in default value.

   The _Revert_ button on the _Appearance_ panel undoes all settings in
the target appearance.  This causes the target geom to inherit all its
appearance properties from its parent.

   The _Appearance_ panel's _Override_ button determines whether
appearance controls should override settings in the objects themselves -
for example, setting the face color will affect all faces of objects
with multi-colored facets.  Otherwise, appearance controls only provide
settings which the objects themselves do not specify.  By default,
_Override_ is enabled.  This button applies to all objects, and to all
appearance-related panels.


File: geomview,  Node: Materials Panel,  Next: Lighting Panel,  Prev: Appearance Panel,  Up: Appearance

The Materials Panel
-------------------

   The _Materials_ panel controls material properties of surfaces.  It
works with the target object in the same way that the _Appearance_
panel does.

_Transparent_
     This button determines whether transparency is enabled.  Geomview
     itself does not fully support transparency yet and on some
     machines it does not work at all.  (The missing piece is
     implementation of a depth-sorting algorithm in the rendering
     engine; not difficult, but just not done yet.)  Use RenderMan if
     you want real transparency: when transparency is enabled, a
     RenderMan snapshot will contain the alpha information.

_Alpha_
     This slider determines the opacity/transparency when transparency
     is enabled.  0 means totally transparent, 1 means totally opaque.

_Diffuse Reflectance_
     This slider controls the diffuse reflectance of a surface.  This
     has to do with how much the surface scatters light that it
     reflects.

_Shininess_
     This slider controls how shiny a surface is.   This determines the
     size of specular highlights on the surface.  Lower values give the
     surface a duller appearance.

_Ambient Reflectance_
     This slider controls how much of the ambient light a surface
     reflects.

_Specular Reflectance_
     This slider controls the specular reflectance of a surface.  This
     has to do with how directly the surface reflects light rays.
     Higher values give brighter specular highlights.

_Done_
     This button dismisses the _Materials_ panel.


File: geomview,  Node: Lighting Panel,  Next: Cameras,  Prev: Materials Panel,  Up: Appearance

The Lighting Panel
------------------

   The _Lighting_ panel controls the number, position, and color of the
light sources used in shading.

   The _Lighting_ panel is different from the _Appearance_ and
_Material_ panels in that it always works with the base appearance.
This is because it usually makes sense to use the same set of lights
for drawing all objects in your scene.

_LIGHTS_
     The _LIGHTS_ browser shows the currently selected light.  Changes
     made using the other widgets on this panel apply to this light.
     There is always at least one light, the ambient light.

_Intensity_
     This slider controls the intensity of the current light.

_Color_
     This button brings up a color chooser which lets you select the
     color of the current light.

_Add_
     This button adds a light.

_Delete_
     This button deletes the current light.

_Show Lights_
     This button lets you see and change the positions of the light
     sources in a camera window.  Each light is drawn as long cylinder
     which is supposed to remind you of a light beam.  When you click
     on the _Show Lights_ button Geomview goes into "light edit" mode,
     during which you can rotate current light by holding down the left
     mouse button and moving the mouse.  Lights placed in this way are
     infinitely distant, so what you are changing is the angular
     position.  Click on the _Show Lights_ button again to return to
     the previous motion mode and to quit drawing the light beams.

_Done_
     This button dismisses the _Lighting_ panel.

   Geomview's _Appearance_, _Materials_, and _Lighting_ panels are
constructed to allow you to easily do most of the appearance related
things that you might want to do.  The appearance hierarchy that
Geomview supports internally, however, is very complex and there are
certain operations that you cannot do with the panels.  The Geomview
command language (gcl) provides complete support for appearance
operations.  In particular, the `merge-baseap' command can be used to
change the base appearance (which, except for lighting, cannot be
changed by Geomview's panels).  The `merge-ap' command can be used to
change an individual geom's appearance.  Appearances can also be
specified in OOGL files; for details, *note Appearances::..