.TL
.nr VS 12
.nr PS 10
.ps 16
.vs 16
SG3d
.br
.ps 10
.vs 12
Supporting Information
.NH 1
Description
.LP
.I
SG3d
.R
is meant to be used as a tool for viewing a data surface in three 
dimensions using \fBGRASS\fR on \fISilicon Graphics IRIS\fR computers.
Hardware requirements are a Z-buffer and 24 bit graphics OR a 24 bit
graphic emulator, such as that on the \fIIRIS Indigo\fR.
.LP
\fISG3d\fR requires a raster file to use as "elevation" and another
raster file to use for surface color (or three files for Red, Green and
Blue components of color).  While a true elevation data file used as
elevation will produce the most realistic surfaces, users are encouraged
to be creative in selecting other types of data to be represented by 
the vertical dimension.  Most continuous (as opposed to discrete) data
types will result in a visualization that makes sense.  While developing
the program, we used chemical concentrations as the elevation file
with good visual results.
.LP
Emphasis during development was on ease and speed of viewer positioning
and flexibility for using a wide range of data values and sizes.  Since a 
wire grid can be drawn very quickly,  such a grid is used to provide 
real-time viewer positioning capabilities.  Similarly, a lighting "model"
provides real-time feedback as the user adjusts lighting.  Grid and
polygon resolution control allows the user to further refine drawing
speed and detail as needed.  Continuous scaling of elevation values from
1.0ee-7 to 1.0ee+7 provides the ability to use various data types 
for the vertical dimension.
.LP
In this release, we upgraded \fISG3d\fR to allow interactive
lighting specifications,
vector draping, data querying (see \fIWhat's here?\fR), easier viewer 
positioning,
an option to save current settings in a \fBGRASS\fR database (\fI3d.view\fR) 
file, animation capabilities, scale objects, labeling, an option to display
lat-long data wrapped around a sphere, the ability to save images in
\fIIRIS\fR rgb format files,
and a few less dramatic changes such as background color options and
an \fIanimate display type\fR option that allows the user to view a fully
rendered image while adjusting viewer positioning (see \fIOptions...\fR).
.LP
.NH 1
General Notes
.LP
Environment variables \fISG3D_WIDTH\fR and \fISG3D_HEIGHT\fR  may be set
to define
the width and height (in pixels) of the graphics window at startup.
All \fISG3d\fR windows may be resized using the window manager's normal
controls at any time.  Text in the control panels is not scalable, however,
so the text will disappear if the panel is sized too small.
.LP
Before starting the program, check your current \fBGRASS\fR region
resolution and
dimensions.  The  current resolution will determine the \fIbest\fR resolution
available in \fISG3d\fR.  Large dimensions such as 1000 x 1000 rows and columns
may cause the program to run slower.  Try starting out with a smaller
(i.e. 300 x 300 or less) region until you get more comfortable and
experienced using the program.
.LP
After starting the program, place your \fBGRASS\fR window where it can 
be seen and
typed into, as it is used to issue prompts and warnings and to input
filenames.
.LP
Any sliders and dials used in the control panels have a FINE ADJUSTMENT:
Hold down the \fBCtrl\fR key while manipulating the dial or slider for 
\fBfine\fR control.
.LP
.NH 2
Compilation
.LP
Before compiling \fISG3d\fR, compile the panel library and the image library
by typing \fImake\fR in src.contrib/CERL/SGI/panel/9.6 and
src.contrib/CERL/SGI/libimage.
.LP
When compiling under IRIX 3.x, comment out the line
.I
#define FOUR_OH
.R
in the externs.h file.  If compiling under IRIX 4.0, leave the line in 
(default).
.LP
.NH 2
Startup
.LP
The syntax for starting the program is:
.IP
\fBSG3d [-w] [-z] \fIelevfile\fB color=\fIcolorfile(s)\fB [vect=\fIvectfile\fB] [script=\fIscriptfile\fB] [sites=\fIsitesfile\fB] [3dview=\fI3dviewfile\fB] 
.in +.5i
.IP \fB-w\fR 18
\fRenables writing to a script file\fB
.IP \fB-z\fR 18
\fRUses site category value as Z value (height) when displaying sites\fB
.IP \fBelevfile\fR 18
\fRname of a \fBGRASS\fR raster file to use as elevation\fB
.IP \fBcolorfile\fR 18
\fRname of a \fBGRASS\fR raster file to use for surface color.
Three raster files may be used for red, green, and blue
components of color instead of a single file: 
.IP
\fBco=\fR\fIred_filename,green_filename,blue_filename\fB    
.IP \fBvectfile\fR 18
\fR(optional) name of a \fBGRASS\fR vector file.\fB
.IP \fBscriptfile\fR 18
\fR(optional) automatically run this script file at startup.  Script file
must be in user's current directory.
.IP \fBsitesfile\fR 18
\fR(optional) name of a \fBGRASS\fR sites list file.\fB
.IP \fB3dviewfile\fR 18
\fR(optional) name of a \fBGRASS\fR 3D viewing parameters file.\fB
.in -.5i
.LP
If the user types \fISG3d\fR on the command line without any arguments,
the program will prompt the user for the arguments.     
.LP
.NH 1
Panels
.LP
\fISG3d\fR starts up with one graphics window and three panel windows
visible.  There are four additional panel windows that pop up when 
their appropriate toggle button is clicked in the \fIMenus\fR panel.
To hide the pop up windows, click again on their toggle button in the
\fIMenus\fR panel - using the \fIQuit\fR or \fIClose\fR options from the
window manager's menu bar will cause the program to exit.
.NH 2
Movement Panel 
.LP
Use the \fBMovement\fR panel to position the viewer over the data and 
to indicate
viewing direction and perspective.  As options in this panel are changed,
a wire grid of the surface is redrawn (\fIfast display mode\fR) to 
immediately show the results of the changes.
.LP
.LP
.in +.5i
\fBXY position:\fR The \fIXY position\fR box contains a star-shaped 
puck which represents the viewer.
Click on the puck and drag to move the viewer around.  The data may
be thought of as always lying in the center of the box, with north
at the top.  The puck also has a dial attached to it that always points
in the direction the viewer is looking.
.LP
\fBHeight:\fR  Adjusts the viewer's height.
.LP
\fBlook here:\fR  Allows the user to click on a spot on the data
surface which will remain centered as the viewer position changes.
Clicking on \fIhere\fR results in a prompt in the \fBGRASS\fR window:
.IP
LEFT MOUSE BUTTON to mark new center of view
.IP
ESCAPE key to cancel
.LP
After clicking on the surface, the new center is automatically set
and the surface is redrawn.
.LP
\fBlook center:\fR  Automatically fixes new center of view at the \fIcenter of
the graphics window\fR (not the center of the data).  If there is not a
surface point at the center of the window, \fIlook center\fR chooses the
centroid of the visible surface for the new center.  Requires no mouse
input, so may be used in scripting. (see \fIscript...\fR)
.LP
\fBlook cancel:\fR  Clicking on \fIcancel\fR allows the user to move 
over the surface
with no fixed center of view (default).
.LP
\fBZ exag:\fR  Exaggerates the vertical dimension of the surface.
An exaggeration of 1.0 represents the surface with x, y, and z units
all being equal.  For example, if the easting and northing units are in
meters and the elevation in feet, a Z exaggeration of .305 would be the 
\fItrue\fR exaggeration for the surface.  For most geographical applications,
greater than true exaggeration produces more visually pleasing images.
.LP
\fBZ Scale:\fR  May be thought of as a course adjustment for Z exaggeration.
Originally included to handle data sets with vastly different
units or scales used for elevation, the program now does a decent job
of guessing the desired \fIZ scale\fR at startup.
.LP
\fBPerspective:\fR  Adjusts the viewer's angle of view.
.LP
\fBOrtho:\fR  Uses an orthographic projection instead of perspective.  This
type of projection tends to give an image less feeling of depth, but it
can be useful when perspective causes too much distortion.  If the 
\fIPerspective\fR slider is activated while \fIOrtho\fR is toggled on,
\fIOrtho\fR is automatically cancelled.
.LP
\fBView Dir., Twist, and View Incline:\fR adjust the viewing direction.
Adjusting the \fIView Dir.\fR or \fIView Incline\fR dials when the \fIlook\fR
option
(fixed center of view) is on will result in the \fIlook\fR option being
cancelled, as if you clicked on \fIlook cancel\fR first.
.LP
\fBReset:\fR  Sets all settings to their startup values.
.LP
.in -.5i
.NH 2
Control Panel
.LP
Use \fBControl\fR panel options to select the type of surface to be drawn.
Most of these options are toggle buttons that are enabled by clicking 
once and disabled by clicking again.  After options are set, click on
\fIDraw\fR to see the results.  Clicking on \fICancel\fR while the surface or
vectors are being drawn cancels the drawing.  Clicking on a button other
than \fICancel\fR while drawing will produce unexpected results.
.LP
.LP
.in +.5i
\fBGrid Resolution:\fR  sets number of cells between grid lines when drawing
wire grids (in both \fIfast display mode\fR and \fIDraw\fR mode).  A larger
grid resolution number produces a more sparse grid.
.LP
\fBPoly Resolution:\fR  sets number of cells to be used as dimensions of each
polygon drawn when drawing polygons.  Each drawn polygon actually 
represents (Poly Res x Poly Res) cells.
.LP
\fBPolygon:\fR  draw surface using filled polygons (most realistic).
.LP
\fBWire/Poly:\fR  draw surface as polygons, but with wire mesh draped over it.
.LP
\fBWire:\fR  draw surface with a wire mesh.  This differs from the mesh drawn
in \fIfast display mode\fR in that hidden lines are not drawn.
.LP
\fBCol Wire:\fR  same as Wire, but use colors from raster file for wires.  Also 
affects grid drawn in \fIfast display mode\fR - useful when trying to position
over a specific data area more identifiable by color than by elevation.
.LP
\fBGouraud:\fR  smooth shade surface to blend individual cell colors together.
.LP
\fBFringe:\fR  draw fringe around outside edges of surface.
.LP
\fBLights:\fR  use lighting to show surface relief.
.LP
\fBSurface Only:\fR  (when using lights) show surface without color from
raster file (renders using color from lights).
.LP
\fBWhat's here?\fR  Like the \fBGRASS\fR program \fId.what.rast\fR, you 
are prompted to
use the mouse to mark spots on the surface that you would like more 
information about.  After clicking on the surface, data prints to the 
\fBGRASS\fR window.  First, the geographical coordinates are printed.  Then, 
elevation is bilinearly interpolated from the current polygon resolution 
and this is printed (setting the resolution to 1 will produce the
most accurate elevation).  Then one line for each data file used to 
create the surface (two or four files, depending on number of files 
used for color) is printed displaying the file name, mapset, value
(not interpolated, only to the nearest cell), and category.
Each time you select a point, a small x is drawn on the surface at
the point selected.  To stop selecting points you must
click the \fIright mouse\fR button.
.LP
\fBTriangulate:\fR  Under IRIX 3.x, using the \fItriangulate\fR feature 
will slightly
improve drawing speed.  Under IRIX 4.0, there is no performance gain.
When \fItriangulate\fR is selected, polygons are always broken into triangles
along the same diagonal.  Without \fItriangulate\fR, polygons are still drawn
as triangles when all four vertices of the polygon do not lie in the same
plane, but the diagonal used is determined by the surface normals at the
vertices, resulting in a more natural looking surface.  This option may
be deleted in future versions.
.LP
\fBNo Zeros:\fR  do not draw surface where elevation data values are zero.
.LP
\fBDraw:\fR  draw the currently defined surface.
.LP
\fBCancel:\fR  cancel any drawing that is currently underway.
.LP
\fBVect:\fR  draw the currently defined vector file.  If no vector file has been
specified, this button is disabled.  (also see \fBVect...\fR)
.LP
\fBSites:\fR  draw the currently defined sites file.  If no sites file has been
specified, this button is disabled.  When drawn, sites appear as small
(X)s draped over the surface.  Using the \fI-z\fR option at startup causes
sites to be drawn using the site category value as elevation instead of
draping the sites on the surface.  \fISG3d\fR uses the current
\fIPoly Resolution\fR to determine
the size of the (X)s; for bigger (X)s, increase the \fIPoly Resolution\fR
after drawing the surface but before drawing the sites. 
(also see \fBOptions...\fR)
.LP
\fBQuit:\fR  exit the program.
.LP
\fBImg Dump:\fR  Prompts user in the \fBGRASS\fR window for a name to be
used for an IRIS rgb format image file, then writes the contents of the
graphics window to that file.  This is basically a screen dump of the
portion of the screen defined by the boundaries of the graphics window, so
if any panel windows or windows from other applications are partially
covering the graphics window, they will appear in the saved image as well.
To view the image files, you can use the SGI programs \fIipaste\fR and
\fIimgview\fR.  SGI
also provides many programs to convert rgb image files to other formats:
\fItoppm, totarga, tosun, tops,\fR etc. 
.LP
.in -.5i
.NH 2
Menus
.LP
The \fBMenus\fR panel contains buttons that toggle six additional pop-up
panels.  To make a hidden window visible, click once on the desired 
button.  To hide the window, click again on the button.
.LP
.NH 2
Lights...
.LP
The \fBLights\fR panel contains adjustments and options to control the 
position, color and brightness of the lights and the reflectivity
(shininess) of the surface.  There are actually two lights:  one dim white
light remains directly above the surface at all times and serves as fill
light. The main light, which the user controls, is a "local" light which
is positioned much like the view position.  When lights are being adjusted,
a sphere appears on the surface and is continuously redrawn to show the
effects of lighting changes.  The lighting adjustments do not affect the
appearance of the surface until it is redrawn.  Neither light is directional;
light is emitted equally in all directions.
.LP
.LP
.in +.5i
\fBFollow Viewpoint:\fR  By default, the light position is near the viewing
position and the light moves with the viewer.  Toggling this option off
will keep the light fixed in one position as the viewer position 
changes.  Adjusting the \fIHeight\fR or \fIXY position\fR of the light
automatically
toggles \fIFollow Viewpoint\fR off.
.LP
\fBShow Model:\fR  The sphere showing current lighting effects can be removed by
toggling this option off.
.LP
\fBHeight:\fR  Adjusts light height.
.LP
\fBXY position:\fR  Adjusts light position over surface; north is always at the top.
.LP
\fBLight Brightness:\fR  Adjusts the brightness of the light.
.LP
\fBR, G, B:\fR  Adjusts the Red, Green and Blue components of the main light.
.LP
\fBAmbient Light:\fR  Adjusts the ambient light associated with the main 
light and
the brightness of the fill light.
.LP
\fBSurface Reflectivity:\fR  Adjusts the shininess of the surface.
.LP
.in -.5i
.NH 2
Vect...
.LP
The \fBVectors\fR panel contains adjustments for displaying vector files
on the surface.  After selecting options in this window, select \fIVect\fR
in the \fBControl\fR panel to draw the vector file.
.LP
.LP
.in +.5i
\fBNew Vect:\fR  Prompts user in the \fBGRASS\fR window for the name of a 
new vector 
file.  Only one vector file is "current" at any given time, but there
is no limit to the number of files that may be loaded and drawn on the
same surface one at a time.  
.LP
\fBDrape, Flat, Vect Z:\fR  If \fIDrape\fR is selected (default), 
lines are draped
over the surface and \fIVect Z\fR controls the distance above the surface that
the vector lines "float".  e.g., if vector lines appear to be buried
under the surface in spots, try increasing the \fIVect Z\fR.  
If \fIFlat\fR is selected,
lines are drawn in a single plane and \fIVect Z\fR controls the vertical 
position of the plane.  Adjusting \fIVect Z\fR in \fIflat\fR mode causes 
an outline
of the plane to be drawn to help the user position the level of the plane.
.LP
\fBLine Width:\fR  Width (in pixels) to draw vector lines.
.LP
\fBcolor, Darker:\fR  Select color used to draw vector lines.  Toggling 
\fIDarker\fR
will use the selected color at a lower intensity.
.LP
.in -.5i
.NH 2
Options...
.LP
.LP
.in +.5i
\fBSave Current 3d View:\fR  Prompts user in the \fBGRASS\fR window for the name of a file in
which to save the current position and control settings.
.LP
\fBLoad 3d View:\fR  Prompts user in the \fBGRASS\fR window for the 
name of a \fI3d.view\fR
file in which position and control settings have been saved, loads the
file and resets dials and buttons.  If loading a view that was saved when
viewing a different region,  a warning is printed describing the percentage
of the region from which the view was saved that is overlapped by the
current region.  In such cases, loaded settings may produce unexpected 
results.  \fI3d.view\fR files are \fBGRASS 4.1\fR database files, and the
region may be changed using \fIg.region 3dview=viewfilename\fR
(\fISG3d\fR would then need to be restarted).  The 
\fI3d.view\fR files
used by this program are compatible with \fI3d.view\fR files used by 
the \fBGRASS\fR program \fId.3d\fR, but minor differences in the view may occur 
due to the different ways the two programs interpret parameters.
.LP
\fBNew Sites File:\fR  Prompts user in \fBGRASS\fR window for a new sites file.
.LP
\fBsites color:\fR  Select color for sites. 
.LP
\fBNew Cell (color) File:\fR  Prompts user in \fBGRASS\fR window for one or three new
raster files to use for surface color.  The program allows the user to
use a single raster file for surface color or three separate raster files
for the red, green, and blue color components.  The first prompt will ask 
\fIChoose single cell file  OR  RED file:\fR.  If you want to use a single
raster file for surface color, enter that filename and press RETURN, then
press RETURN again at the second prompt \fIChoose GREEN file or <RETURN> for
single file\fR.
.LP
\fBNew Elevation File:\fR  Prompts user in \fBGRASS\fR window for a new
raster file to use for elevation.  After loading the file, the new surface
is immediately drawn using the current drawing mode, without erasing the
screen first.  This is not a bug.  Due to memory usage, \fISG3d\fR
does not allow more than one surface to be in memory at one time, but
drawing the new surface in the same visual space as the previous surface
enables a careful user to
view multiple surfaces simultaneously.  If you only wish to view
the new elevation file, you may cancel the drawing of
the new surface by clicking on the \fICancel\fR button, just below the
\fIDraw\fR button.  Any subsequent drawing will only show the new surface.
If the range of data in the new elevation file is different
than the range of the previous elevation file, it may be necessary
to select \fIReset\fR from the \fBMovement\fR panel for the surface to
be rescaled for easier viewing.
When displaying multiple surfaces, 
if you want to use a different raster file for color you must load the
new color file first, then the new elevation file.  
There is no limit to the number of surfaces that can be displayed
in succession, but once \fIDraw\fR is selected and the surfaces are erased,
only the latest surface is available.
.LP
\fBanimate display type:\fR  Toggling this button will cause the current display
type (\fIPolygon\fR, \fIWire/Poly\fR, or \fIWire\fR) to be drawn instead 
of the \fIfast display
mode\fR wire grid when the user is adjusting \fBMovement\fR panel controls.  
These drawing
modes take considerably more time and the display is double buffered, so 
drawing progress is not shown.  When \fIanimate display type\fR is toggled on,
the program checks currently specified resolution and issues a warning
if drawing time will be very slow.  This button was hidden on the
\fBOptions\fR pop-up panel to prevent its accidental use because it can
be time consuming and frustrating if you have the resolution set too
fine and try to animate a fully rendered surface of say a quarter
of a million polygons (500 x 500).  However, including this option
allows those with very fast graphics systems to take advantage of their
hardware.  One further note:  double buffering
causes available color bitplanes to be halved, so the image quality while
animating will be degraded.  When you release your mouse button after
adjusting viewing position, the image is redrawn in single buffer mode 
utilizing all color bitplanes.  This effect is especially noticeable on 
systems with only eight bitplanes.
.LP
\fBbackground color:\fR  select color for background.  The program chooses a 
contrasting color to use for the grid in \fIfast display mode\fR.
.LP
\fBmap lat-long to globe:\fR  This button only appears when the current 
\fBGRASS\fR location uses a latitude-longitude projection rather than
UTM or x-y.  Toggling this button ON causes the lat-long data to be 
mapped to a sphere.  
Drawing in this mode is noticeably
slower because each point has to be transformed to spherical coordinates.
This is a relatively new feature and still has some bugs.  
The following functions of SG3d are not available when the surface is
mapped to a sphere:  \fIlook here, What's here?, Fringe, \fRand none of 
the functions on the \fBScale\fR panel.  In addition, viewer positioning 
functions are not as intuitive in this mode.  By default, the viewer
looks toward the center of the sphere, but you may use \fIlook cancel\fR
followed by \fIView Incline\fR and \fIView Dir.\fR to
let you look in a different direction.  The \fIlook center\fR button 
always resets the center of view to the center of the sphere when using
this mode.
.LP
\fBScale... & Label...\fR  These two buttons toggle additional pop up 
panels. 
.LP
.in -.5i
.NH 2
Scale...
.LP
The \fBScale\fR panel contains adjustments for displaying a scale object
anywhere on the surface or ruler marks along the edges of the surface.
Scale objects available are wire outlines or solid representations of a 
square plane or a cube showing z-exaggeration effects and an arrow pointing
north.  This panel is disabled when using \fImap lat-long to globe\fR mode.
.in +.5i
.LP
\fBplace scale object:\fR Prompts user in the \fBGRASS\fR window to use
the left mouse button to mark center of scale.  Click with the left button in  
the graphics window at the point where you want to place the object.  If the
point is on the surface, the object will be placed so it is resting on
top of the surface.  If the point is off the surface, the object will be 
placed where the position clicked intersects with the plane of constant
z value at the minimum z value of the surface (or minimum non-zero, if
\fINo Zeros\fR is toggled ON).  This method of determining the 
elevation of the scale object may be overridden (see \fIelev\fR below).
.LP
\fBsolid, wire, north arrow, cube, plane:\fR  Combinations of these
toggle buttons determine the appearance of the scale object.
.LP
\fBdraw ruler:\fR  Draws ruler marks along the selected sides of the data
at intervals determined by the value of \fIsize\fR.  For a graded ruler:  
draw ruler once, reduce \fIsize\fR by an even multiple, 
draw ruler again, reduce \fIsize\fR, etc.
Note: The width of the ruler lines may be changed by adjusting \fILine 
Width\fR on the \fBVectors\fR panel.
.LP
\fBNW, SW, NE, SE:\fR  Determines which sides of the data the ruler will
be drawn on and the direction from which the scale marks begin.  For
example, if \fISW\fR is toggled on, ruler marks will appear on the south
and west sides of the surface, proceeding from the southwest corner.  
If both \fISW\fR and \fINE\fR are toggled on, ruler marks will appear
on all four sides of the surface, proceeding from the southwest
corner and northeast corner.
.LP
\fBelev, auto:\fR   When \fIauto\fR is toggled ON, the type-in box
displays the elevation, in units of the raster file used for elevation, 
at which the scale object was placed.  You may
type in a different elevation by clicking in the type-in box, entering
the elevation at which you want the object displayed, then pressing
return.  This automatically toggles \fIauto\fR off.  Subsequent placement
of scale objects will cause the object to be drawn resting on a plane of
constant z value at the new elevation (also see \fIplace scale object\fR).  
.LP
\fBsize:\fR  This type-in box determines the size of scale objects and
the distance between tick marks on the rulers, in units of the data 
(meters for UTM, degrees for lat-long).  By default, \fISG3d\fR chooses
some power of ten times 25, 50, or 100 which results in a desirable
scale size.
.LP
\fBcolor:\fR  Select color for scale object and ruler lines.
.in -.5i
.NH 2
Label...
.LP
The \fBLabel\fR panel contains adjustments for displaying a text string
in the graphics window.
.in +.5i
.LP
\fBplace label, undo:\fR  The \fIplace label\fR button prompts 
user in \fBGRASS\fR window to use 
the left mouse button to mark first letter of label.  
Click with the left button in
the graphics window at the point where you want to place the label.  
The bottom left corner of the first letter of the label will begin where you
click.  If you are not satisfied with the positioning or size, press the 
\fIundo\fR button and the label will be removed.
.LP
\fBtext:\fR  Enter the text you want to place in the graphics window in
this type-in box.
.LP
\fBsize:\fR  Enter the point size of the text you want to display.  \fISG3d\fR 
chooses the closest point size equal to or less than the size requested 
that is available in the font requested.   One inch is equal to 72 pts.
.LP
\fBcolor:\fR  Select color for label.
.LP
\fBTimes-Roman, Helvetica, Italic, Bold:\fR  Combinations of these toggle
buttons determine which of eight possible font styles is used.
.in -.5i
.NH 2
VectPath...
.LP
The \fBPath\fR panel contains controls for using a \fBGRASS\fR 
vector file to determine a path for viewer movement over the surface.
By default, \fISG3d\fR limits the number of points used from a vector file
to the first 1000 points.  This number is defined in path.c as 
MAX_PATHSTEPS, so may be changed if needed and the program recompiled.
The user may request any number (within reason) of total frames once 
the vector file points
are loaded; path points between vector points are interpolated using a 
cardinal cubic spline or simple linear interpolation, as requested by
the user.  Closed, looping paths are supported by both methods of
interpolation.  A path is considered to be a loop if the beginning
and ending points in the vector file are identical.
(Also see \fIKeyframe...\fR and \fB Hints - Animation\fR.)
.in +.5i
.LP
\fBnew vect path:\fR  Prompts user in \fBGRASS\fR window for the name of a
vector file from which to generate a path.  When the path is created,
the number of points used from the vector file is displayed in the
\fItotal frames\fR box (see \fItotal frames\fR).
.LP
\fBFollow Terrain, height, smoothing:\fR  With \fIFollow Terrain\fR toggled
on, the path uses the value in the \fIheight\fR type-in box to determine
the z value of the viewing position (z value = \fIheight\fR + elevation of
terrain under path position).  If \fIsmoothing\fR is
toggled on, the \fIheight\fR value is used to determine the z value of
the viewing position ONLY at the points along the path that were obtained
from the vector file; any interpolated path points have their z values
interpolated as well.
.LP
\fBConstant Elevation, elevation:\fR  With \fIConstant Elevation\fR
toggled on, the path uses the value in the \fIelevation\fR type-in box
as the z value of the viewing position.  By default, the maximum value
in the raster file used for elevation is placed in the type-in box.
.LP
\fBLook Forward, Tilt:\fR  With \fILook Forward\fR toggled on, the viewing
direction along the path is automatically set to look toward a forward 
point along the path.  The value in the type-in box below \fILook Forward\fR
is used to determine how many points ahead to look.  A negative value in
the type-in box may be used to look backward.  Use the \fITilt\fR dial
to look more toward the ground or the sky when looking forward.  Moving
the dial in a counterclockwise direction will set the looking position 
more toward the ground.  This effect is not displayed unless the path is
running.  If \fILook Forward\fR is toggled off, the direction of view is
determined by the settings in the \fBMovement\fR panel.
.LP
\fBstep, run, Frames:\fR  The \fIFrames\fR slider may be thought of as
a time line representing the path.  When a path has been loaded, clicking
on \fIrun\fR will move the viewer down the path, redrawing the wire frame
surface at each path step.  The user may cancel a running animation at any 
time by clicking on the \fICancel\fR button on the \fBControl\fR panel.
The \fIFrames\fR slider shows the progression
of the animation.  Use the \fIstep\fR arrows to step forward or backward
one frame at a time, or move the \fIFrames\fR slider to the desired point
in the animation.  The number to the right of the \fIstep\fR arrows
is the frame number being displayed.  
.LP
\fBtotal frames:\fR  The value in this type-in box is the total number of
frames in the animation.  When a vector file is first loaded, the number
of points in the file (up to 1000) will be the number of frames.  Typically,
to produce smooth animations, the user should use a vector file with 
10 - 50 points, then change total frames to 100 or more, depending on
the length of the animation desired. Requesting an excessive number of
frames (i.e., 500,000) may cause memory problems.
.LP
\fBshow path:\fR  Toggling this button ON will cause the path to be drawn
each time a new frame is drawn.  The color and thickness of the path line
may be changed using adjustments on the \fBVectors\fR pop up panel.  Showing
the path can be useful while previewing and adjusting the path.
.LP
\fBshow vect:\fR  Toggling this button ON will cause vectors to be drawn
each time a new frame is drawn, 
if a vector file has been loaded. (see also \fIVect...\fR).
.LP
\fBspline, linear, tension:\fR  These controls affect the interpolation
method used when the value of \fItotal frames\fR is different than the 
number of points in the original vector file used as the path.  The 
points from the vector file are always used as control points from
which the positioning information for the total number of requested frames
is derived.  If \fIspline\fR interpolation is selected, the user may adjust
spline tension (how much slack there is in the path) using the \fItension\fR
slider.  Toggling \fIshow path\fR ON prior to adjusting tension allows the
user to judge how much tension to use for a smoother path.
.LP
\fBsend path to keyframes:\fR  This button reads the currently defined vector
path and copies it to the \fBKeyframe\fR panel.  
Keyframes already defined in the 
\fBKeyframe\fR panel are overwritten.  (See \fBKeyframe...\fR.)
.LP
\fBrun and save images:\fR  Prompts user in the \fBGRASS\fR window for a 
prefix to be used to name a series of rgb format image files, one for each
frame.  The animation is
then run from the beginning, with each frame being fully rendered using the
current display type and resolution (see \fBControl\fR panel).  If \fIshow
vect\fR is toggled ON, the vector file is also drawn, then the finished 
frame is written to an rgb file. If files already exist with the same name,
they are overwritten.  You may cancel \fIrun and save images\fR at any time by
selecting \fICancel\fR from the \fBControl\fR panel (it may take several
clicks on \fICancel\fR).  This entire process may take several hours 
of computer time for a 100 frame animation of a complex surface, but requires
no further intervention from the user. 
The finished rendered animation files can 
be played back using SGI's \fImovie\fR program if it is a very short 
animation or you can capture the images on video. (Also see \fIImg Dump\fR
on the \fBControl\fR panel and \fBHints - Animation\fR.) 
.LP
.in -.5i
.NH 2
Keyframe...
.LP
The \fBKeyframe\fR panel contains controls for producing custom animations
by moving the viewer around the data surface. 
With keyframe animation, the user
precisely defines a few positions along a movement path (keyframes), 
specifies the total number of frames desired in the animation, and then
lets the computer generate the viewer position along the path for all the 
in-between frames, according to a selected interpolation method.
(Also see \fIVectPath...\fR and \fB Hints - Animation\fR.)
.LP
.in +.5i
\fBstep, run, Key Frames:\fR  The \fIKey Frames\fR slider may be thought of as
a time line representing the animation.  When three or more keyframes
have been defined (two or more if using linear interpolation), clicking
on \fIrun\fR will move the viewer along the path beginning from the
current position of the \fIKey Frame\fR slider bar, redrawing the wire frame
surface at each path step, and advancing the slider bar.
The user may cancel a running animation at any 
time by clicking on the \fICancel\fR button on the \fBControl\fR panel.
The number to the right of the \fIstep\fR arrows
is the frame number being displayed.  The \fIKey Frames\fR slider has small
black tick marks representing each frame of the animation and larger blue
arrows above the slider that represent keyframes (none of the latter exist
until keyframes are created - see \fIadd a keyframe\fR).  The keyframe arrows
can be grabbed with the mouse and moved along the slider. 
To delete a keyframe, grab the arrow representing the keyframe to be
deleted and slide it completely off the slider to the right-hand side, 
then release the mouse button.
Use the \fIstep\fR arrows to step forward or backward one frame 
at a time, or move the \fIKey Frames\fR slider bar to the desired point
in the animation. If the user clicks in the slider at a point to the left of 
the first keyframe or to the right of the last keyframe, or if there have not
been enough keyframes defined to specify a path, current viewer
positioning settings are not changed.
.LP
\fBtotal frames:\fR  This is a type-in box containing the number of total
frames requested.  To change, click in the box, edit the value using the
keyboard, and press return.  The path will be updated and the 
\fIKey Frames\fR slider will be redrawn showing the number of frames requested 
as black tick marks along the slider.
.LP
\fBadd a keyframe:\fR  Adds a keyframe 
at the point in the animation where the keyframe slider bar
is positioned.  If there is already a keyframe at that point, the user
will be asked in the \fBGRASS\fR window whether the old 
keyframe should be replaced.  
.LP
\fBclear all keyframes:\fR  Deletes all keyframes currently defined.
.LP
\fBshow path:\fR  When toggled ON, this button causes the currently defined
path to be drawn as a line with (X)s marking keyframes.  It also changes the
display to show orthographic views of the path from the top, south and east
in three separate viewports along the bottom of the graphics window.
The viewer's current
position is shown in these small viewports by a red dot.
The color and width of the line used to show the path can be changed 
using adjustments in the \fBVect...\fR panel.  
.LP
\fBshow vect:\fR  Toggling this button ON will cause vectors to be drawn
each time a new frame is drawn, 
if a vector file has been loaded. (see also \fIVect...\fR).
.LP
\fBlinear, spline, tension:\fR  These controls affect the interpolation
method used.  The keyframes are always used as control points from
which the positioning information for the total number of requested frames
is derived.  If \fIspline\fR interpolation is ON, the user may adjust
spline tension (how much slack there is in the path) using the \fItension\fR
slider.  Toggling \fIshow path\fR ON prior to adjusting tension allows the
user to judge how much tension to use for a smoother path.
.LP
\fBrun and save images:\fR  See \fIrun and save images\fR on
the \fBVectPath...\fR panel.  This button does the same thing, but for
the keyframe-defined path.
.LP
.in -.5i
.NH 2
Script...
.LP
The \fBscripting\fR panel contains controls for reading and (if enabled) 
writing
script files that contain commands to the panel system.  To enable 
writing use the \fB-w\fR option at startup or set 
the environment variable \fIWRITE\fR.
Script files are not \fBGRASS\fR database files, and are read from and
written to the current directory.
.LP
.LP
.in +.5i
\fBscript file:\fR  This is a type-in box that contains a default filename,
\fIpanel.script\fR.  To replace with your own filename, click in the box, edit
the name, and press return.
.LP
\fBbegin read, stop read:\fR  Use to read the script file indicated.  The 
program will perform the actions saved in the script with nearly the same 
pacing as when they were written to the file, as if somebody was using the 
mouse (but you don't see the mouse cursor move).  The \fIREADING\fR button will
be lit while the actions in the file are being displayed.  You may still
adjust settings with the mouse while a script is being read, but some actions
will produce unexpected results.  (e.g., if you pop up a panel then the script 
tries to pop up the same panel, it actually hides it instead)
.LP
\fBbegin write, begin append, stop write/append:\fR  Use \fIbegin write\fR
to begin a
new script file.  After clicking on \fIbegin write\fR, any mouse actions in
the panels will be recorded in the script file until \fIstop write/append\fR
is selected.  \fIBegin append\fR will cause mouse actions in the panels to
be appended to an existing specified script file until \fIstop write/append\fR
is
selected.  The \fRWRITING\fR button will be lit 
while the actions that occur in the
panels are being recorded.  When writing script files for demos, avoid 
actions that require user input (\fInew cell file\fR, \fInew vect\fR, 
\fIwhat's here\fR, \fIlook
here\fR, etc.), as only those actions that occur in the \fIPANELS\fR, not 
the graphics window
or \fBGRASS\fR window, are recorded in the script.  
Also it is a good idea to begin 
each script writing session by pressing \fIReset\fR, so that what you 
see as you
write the script will be the same as when it is read (no initial conditions
are assumed or reset when reading a script).
.LP
.in -.5i
.NH1
Hints
.LP
.NH 2
Lighting 
.LP
Lighting greatly enhances the level of detail that can be seen in the surface.
For good lighting effects, position the light so that it creates a tilted
half-moon on the sphere.  Usually placing the light in the N-W corner when
viewing from the south works well because of the way humans tend
to interpret shading.  To reveal very subtle gradual elevation changes,
experiment with light placement and surface reflectivity.  Keep resolution
higher (3 or 4) while adjusting viewing position and lighting so that 
drawing time is fast.  Then lower polygon resolution to 1 or 2 for the
final rendering of the surface.
.LP
When rendering frames for animation, it is usually better to position
lights so that they do not move with the viewer position (toggle 
\fIFollow Viewpoint\fR OFF).
.LP
.NH 2
Animation
.LP
Several methods of creating rendered frames for animation are 
available using \fISG3d\fR; you may define a vector path, use keyframes,
or use a panel script.  What follows are a couple of examples to help
you get started with animation.
.LP
.NH3
Keyframes
.LP
Using keyframes is one of
the easiest and most satisfying methods, it just takes some getting use 
to the \fIKey Frame\fR slider.  For practice, just try making a circular
path while always looking at the center of the data:
.in +.5i
.LP
1) use \fIlook here\fR to mark a fixed center of view in the 
middle of the surface.
.LP
2) move the
puck in the \fIXY position\fR box to the southeast corner, adjust 
\fIHeight\fR and \fIPerspective\fR until the data surface fills your
graphics window. 
.LP
3) pop up the \fBKeyframe\fR panel. 
.LP
4) Click on \fIadd a keyframe\fR. 
.LP
5) position the \fIKey Frame\fR slider bar to the
next place to add a keyframe by clicking a half inch or so farther
along the slider. 
.LP
6) move the \fIXY position\fR puck to the northeast corner.
.LP
7) Click on \fIadd a keyframe\fR and repeat step 5.
.LP
8) move the \fIXY position\fR puck to the northwest corner. 
.LP
9) Click on \fIadd a keyframe\fR. 
.LP
.in -.5i
You should now have enough keyframes
marked to define a path, so try clicking on \fIshow path\fR and 
then \fIrun\fR (NOT \fIrun and save images\fR).  If nothing happens,
clear all keyframes and
go back to step 1.  Now let's complete the circular path: 
.in +.5i
.LP
10) repeat step  5.
.LP
11) move the \fIXY position\fR puck to the southwest corner.
.LP
12) Click on \fIadd a keyframe\fR. 
.LP
13) Now to close the loop, move the \fIKey Frames\fR slider down to frame 1,
so that the first frame is displayed, release the mouse button, then click 
once on the slider in the empty part, past the last keyframe, and click on
\fIadd a keyframe\fR.  This essentially copies the first keyframe to the 
fifth & last keyframe.
.LP
.in -.5i
Now click on \fIrun\fR.  When the animation stops,
adjust the spline tension or use
linear interpolation, change the number of total frames, and run 
again.  If you wanted to render the animated frames to .rgb files, you
would now toggle \fIshow path\fR OFF and click on
\fIrun and save images\fR, but why not wait until
you get a little more creative - image files use a lot of disk space.
.LP
\fBChanging keyframes:\fR  With the above keyframes loaded, try
changing a keyframe as follows:
.LP
.in +.5i
1) Position the \fIKey Frames\fR slider so that it aligns with the
arrow marking the second keyframe.
.LP
2) Using the \fIHeight\fR adjustment in the \fBMovement\fR panel, raise your
viewing position.  Notice that if you have \fIshow path\fR toggled 
ON, you can see how your viewing position changes relative to
the defined path by watching the south or east path views.  The small red
dot represents your current position.
.LP
3) Click on \fIadd a keyframe\fR.  You will be asked in the \fBGRASS\fR
window if you want to replace the old keyframe: type 'y' and 'return'.
.LP
4) Run the animation again to see how the path has changed.
.LP
5) Delete the middle keyframe: grab its arrow marker (using your
left mouse button), drag the marker completely off the slider to the
right, and release the mouse button.  Run again to see how path has changed.
.LP
6) Set total frames to about 50, then one at a time, grab the center keyframe
markers and slide them toward the right so that they are spaced something
like:
.LP
1........2..3..4  Run again, notice how movement speed was affected.
.LP
7) Reverse the direction of travel by swapping the positions of the 
two interior keyframe markers.
.LP
.in -.5i
Parameters stored in the keyframe path include viewing position, 
looking direction,
twist, and perspective.  The looking direction will be overridden though,
when the path is running, if \fIlook here\fR is active.  To see this effect
with the above path loaded, select \fIlook here\fR and click on a corner
of the data, setting a new fixed center of view.  Now run the path again.
Click on \fIlook cancel\fR and run again.
Adjusting the \fITwist\fR parameter when creating a path will give your
animation more of a fly-by effect by simulating banking turns.
.LP
.NH3
Panel Scripts
.LP
While vector paths and keyframe animation are good for showing movement
around your data surface, often animation can also be used to show
change over time, or perhaps change in surface properties due to a changing
environmental parameter.  In such cases, you will be creating multiple 
grass data files to represent the change, using your own 
program or other \fBGRASS\fR data analysis tools.  
\fISG3d\fR can still be used to produce a 3d surface animation.  
.LP
Suppose you have generated 30 different raster files that
show diminishing rainforest cover over a period of years.  For this example,
we will assume you will always be draping them over the same elevation
file.  After setting a good viewing position and adjusting lights, 
you \fIcould\fR make an animation by this process:  
select \fINew Cell (color) File\fR from the 
\fBOptions\fR panel, load the file, \fIDraw\fR the image, 
select \fIImg Dump\fR, name the image file, and repeat (30 times).
.LP
An easier way to accomplish the same thing would be to produce a panel
script to do all the work for you.  But if you review the discussion of the
\fBScripting\fR panel, you'll notice that we said to avoid selecting
options that require user input (e.g. \fINew Cell File\fR) since
input in the \fBGRASS\fR window is not recorded in panel scripts.
The way around this is to know what questions the panel script will be asking
and provide all the answers in a text file that will be redirected as
input to \fISG3d\fR at startup.  This is kind of messy, but it works great 
if you're careful.  So for the above example, the text file would
look like this:
.LP
.in +.5i
rast01.file<return>
.LP
<return>
.LP
img01.rgb<return>
.LP
rast02.file<return>
.LP
<return>
.LP
img02.rgb<return> ...
.LP
rast30.file<return>
.LP
<return>
.LP
img30.rgb<return>
.in -.5i
.LP
For this example, you would create the panel script as follows:
Start \fISG3d\fR, using the -w option to allow script writing.  Pop
open the \fBscripting\fR panel and the \fBOptions\fR panel.  Enter a 
name for your script in the type-in box on the \fBscripting\fR panel.
Now click on \fIbegin write, New Cell (color) File, [<enter> in GRASS
window], [<enter> again in GRASS window], Draw\fR (wait for surface to
draw)\fI, Img Dump, [<enter> in GRASS window], begin read, stop write.\fR
This creates a panel script that is an infinite loop, but the program 
will terminate when EOF is received in standard input from your text file.
.LP
Finally, you would create the animation itself by starting the program with:
\fISG3d elev.file co=rast01.file < your.txt\fR.  Adjust lighting and
positioning (if you have a 3dview file you want to use instead,
load it at startup
with \fI3dview=file\fR because if you try to load it once a text file has
been redirected to the program, \fISG3d\fR will use the first line in the 
text file as input in the \fBGRASS\fR window).  Then pop-up the \fBscripting\fR
and \fBOptions\fR panels, enter the name of your panel script, click on
\fIbegin read\fR and take a lunch break.
.LP
You may want to save panel scripts created as above, since they could be
used with different text input files to create completely different animations.
On the other hand, once you've got the hang of it the panel scripts are 
quite easy to make.  Using this method, it is also possible to "morph"
a surface by loading changing elevation files instead of color files.  
Once you get used to this method, you can try adding multiple vector or
site files to your surface, animating multiple surfaces,
or combining movement with a changing surface.
.LP
.NH3
Vector Paths
.LP
The discussion of vector paths in section \fB3.9\fR is fairly detailed,
but here are a few more suggestions.  
.LP
Use the \fBGRASS\fR program 
\fIv.digit\fR to digitize a path you would like to follow, using a minimum
number of points.  Or, use \fIv.digit\fR to create a subset of a roads
or streams vector file, ending up with a single road or stream in a
new vector file to use for a path.  
.LP
Using \fILook Forward\fR with the
number of frames to look ahead set to 5 or 6 for a 50 frame animation gives
good results;  looking ahead only a frame or two will usually cause a lot
of jerkiness. 
.LP
Adjust the \fITilt\fR dial while previewing the running animation.
.LP
When adjusting spline tension with \fIshow path\fR toggled ON,
It may be necessary to temporarily adjust your viewing position
to a place well above your
surface, looking down, in order to get a good view of your path.
.LP
.NH3
Image File Management
.LP
Because .rgb image files can end up taking a lot of disk space,
users should be mindful of disk storage capacity when attempting to 
create an animation.  Keeping animation files and image dumps in 
directories dedicated for such files helps in management.
A single rgb image usually takes between 200K to 3M bytes of storage,
depending upon size and complexity.  To save disk space, use the 
SG3D_WIDTH and SG3D_HEIGHT environment variables to limit the 
graphics window to known dimensions.  If you use the SGI \fImovie\fR 
program to replay animations, each frame of the animation must have
been saved to files of identical dimensions; so especially if you are
creating an animation piecewise, at different sessions, it becomes
important to use the environment variables to maintain a consistent
size for the graphics window.  With the \fImovie\fR program and 
with other screen dump animating programs, there is a zoom
option to enlarge the animation images at time of playback.
So if you want the animation to fill your screen, you could set the
width and height of the graphics window to half or a third their playback
sizes when writing the image files, then use the zoom option (this will
cause a loss of resolution though, since the zoom just replicates pixels).
If you are making an animation to be recorded onto video tape, it may
be necessary to set the width and height to specific dimensions.
.LP
New SGI programs released with IRIX 4.0.5,
\fImoviemaker\fR and \fImovieplayer\fR, are also very useful for
animations. \fIMoviemaker\fR allows you to
create movie files from any number of rgb files at various frame rates.
With \fImovieplayer\fR, much longer animations may be replayed than with
\fImovie\fR since the
frames are read directly from disk at run time rather than having to be
loaded into memory.
.LP
.NH1
Credits
.LP
\fISG3d\fR written by Bill Brown and David Gerdes, U.S. Army Corps of
Engineers Research Laboratories, Champaign, Illinois.
.LP
This report written by Bill Brown, Fall 1992.  Your comments and 
suggestions are appreciated.  
.LP
*************************************
.LP
Bill Brown
.LP
USACERL - ECA	
.LP
PO Box 9005
.LP
Champaign, IL  61826-9005
.LP
e-mail: brown@zorro.cecer.army.mil
.LP
phone:  (217) 352-6511 ext 676
.LP
*************************************
.LP


