\section{Amrvis}

\subsection{Overview}

{\em Amrvis} is a visualization and data analysis tool for
examining data files generated by the Adaptive Mesh Refinement
({\bf AMR}) code.  The user can view color planar images of the data,
{\bf AMR} grid regions, data values in a chosen format, subregions, animations,
volumetric renderings, and output in postscript.  {\em Amrvis} works
for 2D and 3D data, requires no specialized graphics hardware, and
can run in parallel on both SMP and distributed memory parallel machines.

It also has batch capabilities for extracting arbitrary subregions
(including rectangular regions, planes, lines, and points) from data files and
preprocessing volume renderings.  Batch capabilities also work in parallel.

A separate tool, {\em AmrMovie}, can be used to view, animate, and output volume
renderings.  This tool can animate volume data (which has been preprocessed
with {\em Amrvis}) at arbitrary orientations and through time.

Another separate tool, {\em AmrDerive}, can be used to create additional
plot files from existing plot files.  The new plot files can consist of
data from the original plot file and quantities derived from data in 
the original plot file.  This creates a new plot file which can be
viewed with {\em Amrvis}.

\subsection{Using Amrvis}

\subsubsection{Command Line Interface and Utility Files}

From the command line, the user can start {\em amrvis} with or without
data (or plot) files and can perform batch operations
to extract data.  The simplest usage is to type {\em amrvis} at the command
line with no arguments.  This will start the main window from which
the user can open data files or quit the application.  Using the {\bf -help}
argument will cause {\em amrvis} to print a usage message and exit.  The usage
is currently

\begin{verbatim}
amrvis3d
       [<file type flag>] [-v]
       [-maxpixmapsize <max picture size in # of pixels>]
       [-xslice n] [-yslice n] [-zslice n] [-sliceallvars]
       [-boxslice xlo ylo zlo xhi yhi zhi]
       [-fabiosize nbits]
       [-maxlev n]
       [-palette palname] [-initialderived dername]
       [-lightingfile name]
       [-initialscale n] [-showboxes tf] [-numberformat fmt]
       [-lowblack]
       [-cliptoppalette]
       [-fixdenormals]
       [-boxcolor n]
       [-makeswf_light]
       [-makeswf_value]
       [-useminmax min max]
       [<filename(s)>]

  file type flags:   -fab, -multifab, -newplt (-newplt is the default)
  -v                 verbose.
  -maxpixmapsize n   specify maximum allowed picture size in pixels.
  -skippltlines n    skip n lines at head of the plt file.
  -boxcolor n        set volumetric box color value [0,255].
  -xslice n          write a fab slice at x = n (n at the finest level).
  -yslice n          write a fab slice at y = n (n at the finest level).
  -zslice n          write a fab slice at z = n (n at the finest level).
  -sliceallvars      write all fab variables instead of just initialderived.
  -boxslice _box_    write a fab on the box (box at the finest level).
                     box format:  lox loy loz hix hiy hiz.
                     example:  -boxslice 0 0 0 120 42 200.
                     Note:  slices are written in batch mode.
  -fabiosize nbits   write fabs with nbits (valid values are 8 and 32.
                     the default is native (usually 64).
  -maxlev n          specify the maximum drawn level.
  -palette palname   set the initial palette.
  -lightingfile name set the initial lighting parameter file.
  -initialderived dername   set the initial derived to dername.
  -initialscale n    set the initial scale to n.
  -showboxes tf      show boxes (the value of tf is true or false).
  -numberformat fmt  set the initial format to fmt (ex:  %4.2f).
  -lowblack          sets the lowest color in the palette to black.
  -cliptoppalette    do not use the top palette index (for exceed).
  -fixdenormals      always fix denormals when reading fabs.
  -makeswf_light     make volume rendering data using the
                     current transfer function and write data
                     to a file, using the lighting model.
                     note:  works in batch mode.
  -makeswf_value     same as above, with value model rendering.
  -useminmax min max use min and max as the global min max values
  <filename(s)>      must be included if box is specified.
\end{verbatim}


File type flags are as defined as follows.  Once a file type is specified,
it cannot be changed for that {\em amrvis} process.  For MultiFabs,
the name can be specified with or without the "\_H" in the name.

\begin{verbatim}
-newplt             The new directory based plotfile format (the default).
-fab                An FArrayBox.
-multifab           A MultiFab written with VisMF (multiple files).
\end{verbatim}

If the useminmax option is specified, the USERMINMAX range type is
set and the min amd max values are set to the user specified values
for the initialderived name (if set), or the first quantity in the
plot file if no initial derived value is used or if the initial derived
name is invalid.

{\em Amrvis} looks for a default definition file named  {\bf amrvis.defaults}
and if it exists, uses its options as defaults.
If the file does not exist, {\em amrvis} uses standard defaults.
See the section {\bf Files and Directories} for a complete description
of the default options.
The search path for {\bf amrvis.defaults} is (in this order):

\begin{verbatim}
  ./amrvis.defaults
  ~/amrvis.defaults
  ~/.amrvis.defaults
\end{verbatim}



\subsubsection{Interface Windows and Regions}

\begin{description}
\item[Main Window]  This is the small window used to open data files
or quit the main application.  It also prints messages on which file
is being read and values for clicked data points.  There is only one
of these windows per {\em amrvis} application.

\item[Data View Window]  This is the window used to view and interact
with a data file or subregion of a data file.  It contains the color image,
the palette, and data manipulation controls.

\item[Control Area]  This is the area at the top of the Data View Window
which contains controls for selecting current scale, current quantity,
datasets, subregions, and output.

\item[Data Image Area]  This area shows the color image of the dataset.
In 3D, this area is split into four sections--the three orthogonal
planes and an isometric view.

\item[Palette Area]  This area shows the palette which maps data values
to colors and shows the high and low data values that are currently mapped.

\item[Dataset Window]  This window shows data values and is invoked
with the Dataset button on the currently selected subregion.
Indicies are displayed for each available level.  If the user
clicks on a data point in the Dataset window, a box will be
drawn around the corresponding data point in the Data Image Area
(the color data image).

\item[Animation Control Area]  This area contains controls for animating
through data files and through planes in 3D.  It is in the lower right
part of the Data View Window below the Palette Area.  It also shows
plane axes.  The animation controls will only be visible in 3D or
if the Data View Window is used for 2D animation.

\item[Number Format Window]  This window is used to set the
format of displayed numbers and affects the palette, dataset,
point values, and the range window.

\item[Lights Window] This window allows the user to set the following
lighting parameters.

\begin{description}
\item [ambient]  Sets the ambient lighting value.

\item [diffuse]  Sets the diffuse lighting value.

\item [specular]  Sets the specular lighting value.

\item [shiny]  Sets the material shinyness.

\item [minRayOpacity]  Sets the minimum ray opacity cutoff.  The
minimum value for this parameter is 0.0.  A good value is 0.05.

\item [maxRayOpacity]  Sets the maximum ray opacity cutoff.  The
maximum value for this parameter is 1.0.  A good value is 0.95.
\end{description}

\end{description}


\subsubsection{Interface Controls}

\begin{description}
\item[Scale Menu]  This menu controls the current image scale.  At
scale 1, a datapoint at the finest displayed level is mapped to a pixel.
The {\em maxpixmapsize} variable largely determines the maximum scale available
in this menu.

\item[Level Menu] This menu allows viewing data on coarser levels.
The values shown are in the form {\em CurrentLevel/FinestPlotFileLevel}.
Note that the range of values for {\em CurrentLevel} may be greater than
zero on the low end and less than {\em FinestPlotFileLevel} on the high
end indicating that the maximum picture size is limiting the image sizes
and level range.  See the section on {\bf Subregions} for more details.

\item[Quantity Menu]  This menu allows the user to select the current
quantity and is built from information contained in the plot file.

\item[Dataset Button]  This button creates a Dataset Window for the
currently selected region.  {\em A region must be selected before
pressing this button.  If a region has not been selected, the dataset
will not appear.}

\item[Subregion Button]  This button creates a new Data View Window for the
data contained in the currently selected region.  {\em A region must be
selected before pressing this button.  If a region has not been selected,
the subregion will not appear.}

\item[Palette Button]  This button allows the user to select a new palette.

\item[Boxes Button]  This button toggles showing {\bf AMR} boxes.

\item[Output Menu]  This menu allows output of the current image(s) or
data to one of several formats.

\item[Contour Menu]  This menu controls how data is displayed.  Current
options are {\em raster}, {\em raster \& contours}, {\em color contours},
{\em b/w contours}, and {\em velocity vectors}.

\item[Number of Contour Lines]  This edit box allows the user to set
the number of contour lines or velocity vectors.

\item[Information Button]  This button displays a window with information
about the plot file.

\item[Close Button]  This button destroys the Data View Window.

\item[Set Range Button]  This button allows the user to set the color
mapping range of the data.

\item [Isometric View Buttons]  These control the view point and scaling
of the isometric image in 3D (boxes or volumetric rendering).

\begin{description}
    \item [0]           Reset the viewing angle to the original view.
    \item [XYZ]         Draw axis labels.
    \item [Draw]        Draw the volume rendered image.  This may entail
		        creating internal data structures and could take
		        several seconds to minutes for the first frame
			to draw.
    \item [Autodraw]    Automatically render the image while rotating.
			As with {\bf Draw}, the first image takes longer.
    \item [Trans]       Reread the transfer functions.
    \item [Lights]      Allows the user to set the rendering lighting parameters.
    \item[Light/Value]  This menu shows the volume rendering
                        model currently in effect.
    \item[PC/OT]        This menu affect how the volume rendering
                        stores data internally (PreClassified/OctTree).
			PreClassified provides the fastest volume rendering.
    \item [Detach]      Detach the isometric view into its own window.
    \item [Attach]      Attach the isometric view.
\end{description}

\end{description}


\subsubsection{Mouse Controls}

\begin{description}
\item [Left Button]  Selecting from menus, clicking buttons and animation controls,
drawing subregions in a view for datasets and subvolumes, spinning the image
in the isometric view, translating the image in the isometric view (with the
shift button pressed), and clicking a point for its data value.

\item [Middle Button]  Placing horizontal planar cutting lines in the
orthogonal image views and rotating around the eye point in the isometric view.

\item [Right Button]   Placing vertical planar cutting lines in the
orthogonal image views and zooming the isometric view (pull or push the mouse).

\end{description}


\subsubsection{Batch Functions}

\begin{description}
\item [Slices] The user can specify multiple slices and ranges on the command line.
For example:
{\em amrvis -newplt -xslice 7 -xslice 42 -yslice 19 -zslice 9 plt1010}.
This will create four fab files of the form
{\em pltnnnn.derived.slicename.slicenum.fab}
where derived is {\em initialderived} from {\bf amrvis.defaults}.
In this example, the
first file will be (assuming pressure) {\bf plt1010.pressure.xslice.7.fab}.
The user can also specify ranges with the syntax ``start-end''  For example:
{\em -yslice 7-42} will create a fab file for each slice in the range [7,42].
Slices are specified on the finest level problem domain.
The option {\em -sliceallvars} can be specified to write all fab variables
instead of just the {\em initialderived}.
The user can specify multiple plot files as usual:  plt05*
If a {\bf zslice} is specified in 2D, {\em amrvis} will use
zslice = 0 (regardless of the
slice number specified), which is the entire dataset for the current
derived quantity.  An {\bf xslice} or {\bf yslice} in 2D creates
a strip one cell wide.
Slices are supported for any type of data {\em amrvis} can read
including fabs, which includes fabs created by slicing.  This allows
extraction of planes, lines, and points from a dataset.
Fab slices have the same {\bf BL\_SPACEDIM} as the original dataset.  A slice from
a 3D dataset is a 3D fab one cell thick.
Note:  if a slice of a dataset is created then viewed with {\em amrvis -fab},
the picture may not look the same as the original
because the dynamic range of the fab might be smaller than that of
the entire data set.  The {\bf Set Range} button can be used to set
the same values in both images to get the same picture.
This feature operates in batch mode.
{\em amrvis} will write out all requested slices for all files then exit.

\item [Making Volumetric Data Files]  Use the {\bf -makeswf\_light}
and {\bf -makeswf\_value} options to write a data file for fast volume
rendering.  This option uses the transfer function from the palette and either the
value model or lighting model.  The files are postprocessed with
{\em AmrMovie}.

\end{description}



\subsection{Detailed Usage Notes}

\begin{description}
\item [Subregions] Subregions work functionally like the full region,
and the main region can be closed while retaining the subregion.
For deep files, the maximum level displayed is based on {\em maxpixmapsize}
and a smaller subregion must be selected to view finer levels.
A region must be selected before the {\bf Subregion} button is pressed.
{\em Amrvis} reference counts plot file data, so subregions do not
significantly increase maximum memory usage.  See the section on
demand driven I/O for more detail.

\item [Datasets]  The dataset will update its values when
the derived quantity changes.  The user can also select another region
and click on dataset (with a dataset window already showing) and it
will update that window.
A region must be selected before the {\bf Dataset} button is
pressed.  Clicking with the left mouse button on a value in the
dataset window will draw a box around the corresponding point in the
color image view.

\item [File Type]
Once a file type is specified (-fab, -multifab, -newplt), it cannot be
changed for that {\em amrvis} process.

\item [Animations] During animations, pressing the {\bf O} button
in the center of the animation controls will stop frame creation.
{\em amrvis} will automatically calculate the data range over
the file set or the range can be specified with the {\bf Set Range} button.
In {\bf Set Range} for animations, the {\em File} option sets
the minimum and maximum to the values for the current data file
instead of the values over the entire set of data files.
The arrows move single frames for single clicks and animate for double clicks.
Animation works with all supported formats and with subregions.
Animation across files within {\em amrvis} is supported in 2D only.
For 2D animations, the {\bf rgb} button will write an rgb file
for the current image and advance to the next frame (for single clicks)
or animate through the frames and write an rgb file for each frame
automatically (for double clicks) until the {\bf O} button is pressed.
File names are generated automatically and are of the form
{\em quantity.nnnn.rgb} where {\em quantity} is the current derived quantity and
{\em nnnn} is the plot file number (0123 for plt0123).
For animations across files in 3D, use {\em AmrMovie}.

\item [Palettes]
Palettes are in Non-interleaved Binary format and can be created
with tools such as {\em icol} from {\bf AHPCRC} or {\em ximage}
from {\bf NCSA}.  The transfer function (which specifies transparency
in the volumetric rendering) is included in the palette (they were
formerly set in {\bf vpramps.dat}).
The {\bf CCSE} version of {\em icol} must be used to create palettes
with transfer functions.
If the palette does not contain the transfer function values,
a default will be used.


\item [Number Format] The format for numbers (which is set in the
{\bf Number Format} window) affects numbers in the dataset, the set range
dialog box, and the palette.  The format value can be any valid {\bf printf}
string.  Hit the {\bf return} key after editing the string to apply.

\item [Partial colormap support]   The {\em reservesystemcolors} keyword
in {\bf amrvis.defaults} lets the user decide how many colors
to reserve from the palette.   Experiment with the terminal
to determine a satisfying number, try 20 to start.  This works
by chopping off the lower parts of the palette and remapping the
image to the new colormap.

\item [Visual support]
{\em amrvis} uses an eight bit Pseudocolor visual, regardless of the
current default visual.

\end{description}



\subsection{Files and Directories}

{\em Amrvis} looks for the file {\bf amrvis.defaults} to set default values.
If this file does not exist, {\em amrvis} will use standard default values.
The {\bf amrvis.defaults} file has the following structure and options
(in general: {\em keyword   value}).


\begin{verbatim}
palette               Palette
initialderived        density
initialscale          4
numberformat          %7.5f
maxpixmapsize         1000000
reservesystemcolors   20
showboxes             TRUE
windowheight          650
windowwidth           900
filetype              fab
filetype              newplt
cliptoppalette
\end{verbatim}


Invalid values are ignored.  The {\em initialderived} specifies the
quantity that is displayed first and must be spelled
exactly as it appears in the data file or the value will default to
the first derived quantity.  {\em numberformat} affects the dataset and
palette values and can be any valid {\bf printf} string.
{\em windowheight} and {\em windowwidth} define the size
of the {\bf Data View Window} with arguments in number of pixels.
{\em showboxes} affects initial drawing of {\bf AMR} grid boxes.  Valid
values are {\bf TRUE} or {\bf FALSE}.
{\em filetype} specifies the type of file (same values as the command line).
{\em cliptoppalette} forces {\em amrvis} to not use the top palette entry
(this option is for exceed users).
For duplicate keywords, the last one in the file is used (for example, {\bf newplt}
will be the {\em filetype} in the above file).  Command line settings
override settings in {\bf amrvis.defaults}.

The search path for {\bf amrvis.defaults} is (in this order):

\begin{verbatim}
  ./amrvis.defaults
  ~/amrvis.defaults
  ~/.amrvis.defaults
\end{verbatim}


{\em Amrvis} also looks for the file {\bf amrvis.lighting} in the
current directory to set default lighting values for volume rendering.  If
this file does not exist, {\em amrvis} will use standard default
values.  The name of this file can be specified on the command line.  An example
file might look like the following.

\begin{verbatim}
ambient 0.42
diffuse 0.41
specular 0.40
shiny 12.0
minRayOpacity 0.04
maxRayOpacity 0.96
\end{verbatim}

Note:  For volume rendering, the {\em VolPack} library from Stanford University
must be linked with {\em amrvis}.  It currently can be obtained from

\begin{verbatim}
http://www-graphics.stanford.edu/software/volpack
\end{verbatim}

{\em Amrvis} has been tested with {\bf VolPack} version 1.0beta3 (the
latest release).


\subsection{Examples}

Typical usage is as follows.  Be sure to use the correct file type flag.

\begin{verbatim}
amrvis <return>           opens the main window with default file type (-newplt).
amrvis -newplt <return>   opens the main window with file type set to -newplt.
amrvis -newplt plt1560    opens plt1560 (which is a new plot file).
amrvis -fab *.fab         opens multiple fab files in separate windows.
amrvis -a plt*            opens an animation for plt* (2D only).
\end{verbatim}



\subsection{Technical Details}

\subsubsection{Parallel Implementation}

{\em amrvis} runs in parallel on both shared memory an distributed
memory multiprocessor architectures using parallel BoxLib and the
SPMD programming model.  The interface runs on processor zero
(the I/O processor) and parallel DataServices runs on all processors
and handles data requests from the {\em amrvis} interface.



\subsubsection{Demand Driven I/O}

Data from a plot file is read from disk only when required to create
an image in {\em amrvis}.  The granularity for I/O is a single quantity
of an FArrayBox within a MultiFab.  Within {\em amrvis}, data on a grid for the
current quantity is read from disk only if it intersect the current
image plane within the current subvolume, is less than or equal to the
maximum available level, and has not already been read (FABs are cached).


\subsection{Efficiency Notes}

\begin{itemize}
\item For best performance of {\em amrvis} (and in general when
accessing files), copy data files to local disk instead
of relying on a slow network connection.

\item In 3D, select a subregion to volume render so
{\em amrvis} can render fewer points.

\end{itemize}


\subsection{FAQ}

\begin{itemize}

\item For data sets and subregions, a region must be selected (with
the left mouse button) before clicking on {\bf Dataset} or {\bf Subregion.}
    
\item If {\em amrvis} hangs trying to read a plot file, make sure the file type
flag is set correctly for your plot files.

\item Once you pick a file type (-fab, -multifab, -newplt), you cannot
change it for that {\em amrvis} process.

\item Plot files have a new directory based format.  The old single file
format is not supported.

\item Names in the quantiy list (density, xmom, etc.) must be unique.

\item If you change the user defined min or max values in the range
window, you must also select the {\bf User} radio button before you
press the {\bf Apply} button or the user range will not be set.

\item {\em amrvis} takes background and lettering colors from
the {\bf .Xdefaults} file.
To modify these, add the following lines to {\bf .Xdefaults}

\begin{verbatim}
#ifdef COLOR
amrvis*Background:    black
amrvis*Foreground:    white
#endif
\end{verbatim}

then type

\begin{verbatim}
xrdb ~/.Xdefaults
\end{verbatim}

to update the X database.  This will turn the {\em amrvis} background to black
and the lettering white (or whatever colors are chosen).

\end{itemize}


\subsection{Known Problems}

\begin{itemize}
\item The numbers in the Palette can go off the right edge of the window
for long formats.

\item There is a resource allocation issue to be aware of--
{\bf amrvis.defaults} defines {\em initialscale} and {\em maxpixmapsize}.
{\em maxpixmapsize} defines the maximum number of bytes allowed to allocate
on the xterm for a pixmap (where the color picture lives) and {\em amrvis}
uses this to decide the finest level it can display.  It finds displayLevel
by:  \( (probDomain(displayLevel).numPts() * {scale^{2}}) \leq maxpixmapsize \)
The problem is this:  if the pixmap size is below but close to the
available server memory, the pixmap may be allocated properly but other
{\bf X} allocations, such as server memory for a button or menu, may fail.
This causes {\em amrvis} to die unpredictably with a core dump or an {\bf X}
message about unavailable resources.  So if this behavior happens, adjust
{\em maxpixmapsize} and {\em initialscale} values to about half
of the xterm's available memory.

\item Animations for plot files with different finest levels of refinement
do not work properly.
  
\item If you specify the wrong plot file type, the behavior is undefined.
Usually, {\em amrvis} will do one of three things:  open the file with
bad numbers (Reals interpreted with the wrong byte ordering), crash, or
hang by trying to read the file forever.
  
\item When the file range for animations is set and the user derives
a different quantity, the global range value contains the value for
the current file and not the set of files in the animation.
  
\item A fatal error with a single plot file will cause the whole application
to exit.
  
\item There are several places where redundant exposure events cause poor
performance.
  
\item The selection box does not persist during animations.

\item The colormap does not always install properly when using twm.

\end{itemize}
