\chapter{The object viewer program}

\section{General}
The object viewer program bundled with this distrubtion of SISL is intended to be
a simple but handy tool for visualising curves and surfaces generated by SISL.  The
supported file format is the \verb/Go/ (\textbf{G}eometric \textbf{O}bject) format, 
which is a simple, ASCII-based format defined by SINTEF.  The viewer is based on OpenGL. 
The object(s) to be viewed are specified on the command line when starting the 
program.  Once the program is started, the user cannot open other files containing
SISL objects.  The viewer allows the user to zoom, pan and rotate the objects with
the mouse, and some other useful commands can be accessed through the keyboard.
\\
\\
In the viewer window, several curves and surfaces can be displayed simultaneously.
At all times, exactly \emph{one} surface and \emph{one} curve are defined as being
\emph{active} (the other ones being \emph{passive}).  With keyboard commands, the user
can change the currently active surface/curve.  An object just becoming active will
flash for a few seconds.  With other keyboard commands, the user can \emph{enable/disable}
surfaces and curves.  This refers to turning the display of these objects on or off.
For details, refer to the section on keyboard commands.

\section{Command line arguments}
When starting up the viewer, the options listed below can be used.  If no option is
specified, a short text listing the available options is printed on screen.

\begin{itemize}
\item[$\bullet$] \textbf{\verb/s/} \textit{filename} - view the surface(s) contained in
the file \textit{filename}.  Note: this command line option can be used repetitively if
the user wants to inspect several surfaces at once.
\item[$\bullet$] \textbf{\verb/c/} \textit{filename} - view the curve(s) contained in the
file \textit{filename}.  Note: this command can be used repetitively if the user wants
to inspect several curves at once.
\item[$\bullet$] \textbf{\verb/p/} \textit{filename} - view the point(s) contained in 
the file \textit{filename}.  Note: this command line option can be used repetitively if
the user wants to inspect several surfaces at once.
\item[$\bullet$] \textbf{\verb/r/} \textit{integer} set surface refinement factor 
(number of facets in each direction on the surface). Default value is 100.  Higher values
gives smoother drawing of the surface.  NB: this option has to \emph{precede} the 's' 
option!
\item[$\bullet$] \textbf{\verb/e/} \textit{string} the string contains keypresses to execute
directly upon start (see the section on keyboard control keys for details).
\item[$\bullet$] \textbf{\verb/hotkeys/} does not start the viewer, but displays a list 
of keyboard commands that can be used when viewing.
\end{itemize}

A file can contain one or several curves, or one or several surfaces.  Files containing
both curves and surfaces are not supported.  The viewer can read several files to be
viewed at once.  On the command line, each ``curve'' file should be preceded with the
letter 'c', and each ``surface'' file should be preceded with the letter 's'.  After 
launch, all the objects contained in the given files are shown simultaneously.  The user
can disable the view of certain curves and surfaces if he or she wants to.  

\section{User controls}

After program launch, the viewing of curves and surfaces can be controlled with the mouse
and keyboard.  The mouse is used to define viewing angle, direction and zoom factor, while
keyboard keys are used to turn on/off objects and to change certain view parameters.

\subsection{Mouse commands}
It is assumed that a 3-button mouse is used.  By dragging the mouse while holding down the
\emph{left button}, the user can rotate the current view in an intuitive way.  By dragging
with a certain speed, the view will continue to rotate even after the left button is released.
The \emph{middle button} is used for zooming.  Hold down this button and move the mouse 
forwards and backwards in order to zoom in and out.  Holding down the \emph{right button}
while dragging the mouse moves the view up and down.

\subsection{Keyboard commands}

The available keyboard commands are:

\begin{itemize}
\item[$\bullet$] \textbf{\verb/q/} - quit the viewer program
\item[$\bullet$] \textbf{\verb/<space>/} - change the currently active curve 
(cycles through each of them)
\item[$\bullet$] \textbf{\verb/<tab>/} - change the currently active surface 
(cycles through each of them)
\item[$\bullet$] \textbf{\verb/w/} - turn on/off the wireframe display for surfaces
\item[$\bullet$] \textbf{\verb/B/} - toggle between black and white color for backgrounds
\item[$\bullet$] \textbf{\verb/A/} - toggle drawing of coordinate axes on/off
\item[$\bullet$] \textbf{\verb/S/} - toggle drawing of surfaces
\item[$\bullet$] \textbf{\verb/e/} - toggle visibility of currently active surface
\item[$\bullet$] \textbf{\verb/a/} - make all loaded surfaces visible
\item[$\bullet$] \textbf{\verb/d/} - hide all surfaces except the currently active one
\item[$\bullet$] \textbf{\verb/<ctrl>-e/} - toggle visibility of currently active curve
\item[$\bullet$] \textbf{\verb/<ctrl>-a/} - make all loaded curves visible
\item[$\bullet$] \textbf{\verb/<ctrl>-d/} - hide all curves except the currently active one
\item[$\bullet$] \textbf{\verb/O/} - center all objects around origo, and rescale objects
so that they fit inside the unit volume (does not preserve aspect ratio)
\item[$\bullet$] \textbf{\verb/o/} - center all objects around origo, no rescaling
\item[$\bullet$] \textbf{\verb/+/} - increase thickness of axes
\item[$\bullet$] \textbf{\verb/-/} - decrease thickness of axes
\item[$\bullet$] \textbf{\verb/>/} - increase size of points
\item[$\bullet$] \textbf{\verb/</} - decrease size of points
\item[$\bullet$] \textbf{\verb-/-} - decrease length of axes
\item[$\bullet$] \textbf{\verb/<esc>-w-[n]/} - store viewpoint in slot [n], where [n]
is a number from 0 to 9.  The viewpoint will be saved to file, and can such be preserved
from one session to another.
\item[$\bullet$] \textbf{\verb/<esc>-r-[n]/} - load a previously saved viewpoint from
slot [n], where [n] is a number from 0 to 9.
\end{itemize}
