\documentclass[letterpaper]{book}
\usepackage{ifpdf}
\usepackage{linuxdoc-sgml}
\usepackage{qwertz}
\usepackage{url}
%%\usepackage[@CHARSET@]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[colorlinks=true,urlcolor=blue,linkcolor=blue]{hyperref}
\pdfcompresslevel=9
\usepackage[english]{babel}
\usepackage{epsfig}
\usepackage{null}
\def\addbibtoc{
\addcontentsline{toc}{chapter}{\numberline{\mbox{}}\relax\bibname}
}
\pagestyle{headings}%end-preamble
\setcounter{page}{1}
\ifpdf
\newcommand{\aaaurl}{\url{http://graphics.stanford.edu/software/volpack/}}
\else
\urldef{\aaaurl} \url{http://graphics.stanford.edu/software/volpack/}
\fi

\ifpdf
\newcommand{\aaburl}{\url{http://www.gtk.org/}}
\else
\urldef{\aaburl} \url{http://www.gtk.org/}
\fi

\ifpdf
\newcommand{\aacurl}{\url{http://arxiv.org/abs/astro-ph/0412003}}
\else
\urldef{\aacurl} \url{http://arxiv.org/abs/astro-ph/0412003}
\fi

\ifpdf
\newcommand{\aadurl}{\url{http://space.mit.edu/cxc/isis/}}
\else
\urldef{\aadurl} \url{http://space.mit.edu/cxc/isis/}
\fi

\ifpdf
\newcommand{\aaeurl}{\url{http://ssc.spitzer.caltech.edu/archanaly/contributed/cubism}}
\else
\urldef{\aaeurl} \url{http://ssc.spitzer.caltech.edu/archanaly/contributed/cubism}
\fi

\title{ \\  {\ttfamily volview}:  A S-Lang Guilet For Volume Visualization \\ 
Reference Manual, Version 0.1.3}
\author{Michael S. Noble, {\ttfamily mnoble@space.mit.edu}}
\date{ Mar 10, 2009}


\begin{document}
\pagenumbering{roman}
\maketitle

\chapter*{Preface}

 
\begin{tscreen}
\begin{verbatim}
  Volview is an extension module which adds volume visulization
  capability to the S-Lang interpreter, using the Gtk widget set
  and volpack rendering library.

  Copyright (C) 2008 Massachusetts Institute of Technology
  Author: Michael S. Noble <mnoble@space.mit.edu>

  This software was developed with SLIRP at the MIT Kavli Institute
  for Astrophysics; it was funded in part by NASA and the Smithsonian
  Institution, through the AISRP grant NNG05GC23G and Smithsonian
  Astrophysical Observatory contract SV3-73016.

  Permission to use, copy, modify, distribute, and sell this software
  and its documentation for any purpose is hereby granted without fee,
  provided that the above copyright notice appear in all copies and
  that both that copyright notice and this permission notice appear in
  the supporting documentation, and that the name of the Massachusetts
  Institute of Technology not be used in advertising or publicity
  pertaining to distribution of the software without specific, written
  prior permission.  The Massachusetts Institute of Technology makes
  no representations about the suitability of this software for any
  purpose.  It is provided "as is" without express or implied warranty.
  
  THE MASSACHUSETTS INSTITUTE OF TECHNOLOGY DISCLAIMS ALL WARRANTIES
  WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL THE MASSACHUSETTS
  INSTITUTE OF TECHNOLOGY BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
  OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
\end{verbatim}
\end{tscreen}







\tableofcontents
\chapter{Introduction}
\pagenumbering{arabic}



{\ttfamily volview} is an extension module which adds volume visualization capability
to the S-Lang interpreter, using the {\ttfamily volpack} rendering library and Gtk
widget set (see 
{\em } {\tt \aaaurl}
 and 
{\em } {\tt \aaburl}
).  Like VWhere (
{\em } {\tt \aacurl}
),
{\ttfamily volview} is also an example of the notion of a {\itshape guilet\/} (pronounced
"gooey-let"), by which we
mean to connote visual interfaces of a small-ish, scriptable nature, that
may be easily embedded within -- and launched from -- other programs, even
applications with interactive command lines and no ostensible graphical
interface.  For example, {\ttfamily volview} is frequently used in ISIS (
{\em } {\tt \aadurl}
),
our platform for robust, high-performance astrophysical analysis and modeling,
whose main interface is an interactive {\ttfamily Matlab}(tm)-style command line
prompt.  Guilets fill an important software niche, the middle ground
between novice users -- who often argue that visual interfaces make
software easier to use -- and power users -- who frequently complain
that GUIs are more cumbersome and inflexible than command lines.
Experience suggests that the code size and development cycle of the typical
guilet is considerably smaller than that of traditional, monolithic GUIs
(by which we mean to connote applications coded from scratch, typically
in a compiled language such as C or C++, to have only a visual interface).
Moreover, given their scripting
heritage, guilets can be more amenable to changing requirements or ad-hoc
experimentation and customization by the end-user.  This is especially
important in the scientific and engineering research arenas.




\section{Building}



{\ttfamily volview} ships with a configure script generated by autoconf, and in most cases
can be built by issuing the following standard commands within a UNIX-like
(e.g. Linux or Cygwin) environment:
\begin{tscreen}
\begin{verbatim}
        ./configure [options]
        make
        make install
\end{verbatim}
\end{tscreen}

Beyond S-Lang itself, {\ttfamily volview} has three explicit dependencies: SLIRP, {\ttfamily volpack},
and SLgtk.
The latter two of these, if not present on your system, may be automatically
downloaded from our site and installed on your system by using the
{\ttfamily --enable-download} configure option.  Issue a {\ttfamily ./configure --help}
command for more information.
{\ttfamily volview} can be loaded at runtime into any suitably configured
application which embeds the S-Lang interpreter, using either
\begin{tscreen}
\begin{verbatim}
        require("volview");
\end{verbatim}
\end{tscreen}

or
\begin{tscreen}
\begin{verbatim}
        () = evalfile("volview");
\end{verbatim}
\end{tscreen}





\section{Examples}



Volumes are visualized from arrays, of either 3 or 4 dimensions, none
of which may be zero in length.  When a 4D array is given the first
element is selected as the 3D volume to be visualized (using a 4D array
to perform a 3D slideshow will be supported in the near future).
For example, this statement sequence
\begin{tscreen}
\begin{verbatim}
  variable volume = tan([1:8000]);
  reshape(volume,[20,20,20]);
  volview(volume);
\end{verbatim}
\end{tscreen}

yields
\begin{tscreen}
\begin{verbatim}
\end{verbatim}
\end{tscreen}

\ifpdf
\centerline{\epsfig{file=tan.png}}\fi

\begin{tscreen}
\begin{verbatim}
\end{verbatim}
\end{tscreen}

Since volumes are just arrays they may be read from virtually any
source.  For example, consider a classic brain MRI scan example,
stored in HDF5 format and read using the {\ttfamily slh5} module:
\begin{tscreen}
\begin{verbatim}
        require("h5");
        volview( h5_read("brain.h5"));


\end{verbatim}
\end{tscreen}

\ifpdf
\centerline{\epsfig{file=brain.png}}\fi

\begin{tscreen}
\begin{verbatim}
\end{verbatim}
\end{tscreen}

Here the HDF5 file was converted from a "raw volume" format used
by {\ttfamily volpack} (representing an MRI scan of a human head, derived from
public domain data provided by SoftLab at UNC Chapel Hill).

Our final example is drawn from astronomy, and utilizes a spectral
cube in the FITS file format, generated by CUBISM (
{\em } {\tt \aaeurl}
) from
Spitzer observation 3310 of the Cassiopeia A supernova remnant and
graciously provided by Dr. Tracey Delaney.  The visual is useful because
many popular astronomical visualization tools only support visualizing
2D slices of 3D images, which does not reveal interesting structure in
the 3rd dimension (e.g. here wavelength).  By visualizing the entire
volume as a single array
\begin{tscreen}
\begin{verbatim}
  require("fits");
  volview( fits_read_image("casa_ll2_s12.fits") );
\end{verbatim}
\end{tscreen}

we see instantly the clumpy areas which correspond to areas of strong
emission:

\ifpdf
\centerline{\epsfig{file=casa.png}}\fi





\chapter{Command Reference}



\begin{tscreen}
\begin{verbatim}
    volview

     SYNOPSIS
       Display a 3D volume array within a graphical user interface

     USAGE
       volview(3D_or_4D_volume_array [; x=<x0>, y=<y0>, z=<z0>])

     DESCRIPTION
       This function will launch a GUI in which the given volume will be
       displayed, using the optional x,y,z qualifiers to set the initial
       viewing angle.  From there the volume may be rotated along any
       axis, zoomed in or out, or saved to a variety of output file formats.

       Right-clicking on the image after rendering will launch a menu from
       which rendering parameters (e.g. colormap, opacity) may be modified.

     NOTES
       The input array may have either 3 or 4 dimensions, none of which may
       be zero in length.  When a 4D array is given the first element is
       selected as the 3D volume to be visualized.

     SEE ALSO
       volpack, SLgtk
    --------------------------------------------------------------
\end{verbatim}
\end{tscreen}




\end{document}
