\documentclass[12pt,onecolumn,a4paper]{article} % document style report

%\usepackage {t1enc}                                  % use DC-Font with 8 bit
%\usepackage [latin1]{inputenc}                       % Codepage latin1

\usepackage[centertags]{amsmath}                      % include ams-packages
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{amsthm}
\usepackage{longtable}
\usepackage{array}
\usepackage{float}
\usepackage{overcite}                                 % superscript notation of references
\usepackage{xcolor}                                 % superscript notation of references
\usepackage{multirow}
\usepackage[pdftex]{graphicx}                  % Grafikpaket für Bilder laden
\usepackage[colorlinks=true]{hyperref}                  % Für Referenzerstellung
\usepackage{xspace}

\newcommand{\rb}[2]{\raisebox{#1ex}{#2}}
\newcommand{\meshal}{\textbf{\emph{M\rb{-.25}{e}\rb{-.35}{s}\rb{-.45}{h}}}%
\textsf{\rb{-0.3}{a}\rb{-.15}{l}y}%
\texttt{\rb{.2}{\reflectbox{Z}}\rb{.1}{e}r}\xspace}
\renewcommand{\floatpagefraction}{0.7}

\renewcommand{\sectionautorefname}{\S}
\renewcommand{\subsectionautorefname}{\S}
\renewcommand{\subsubsectionautorefname}{\S}

% literal 
\newcommand{\lit}[1]{``\texttt{#1}''}

\begin{document}

\begin{titlepage}

\DeclareGraphicsExtensions{.png,.pdf,.jpg}
{
\renewcommand{\baselinestretch}{1.5} \small\normalsize

\begin{center}
{\Huge \meshal}
\\ \vspace{2cm} {\Large Mesh Display and Analysis} 
\\ \vspace{1cm} Manual Version 2.0
\end{center}
}
\end{titlepage}

\tableofcontents
 
\titlepage
\section{Introduction}

\subsection{Purpose}
\meshal is a program for displaying unstructured grids, visualizing data on the
grid, as well as examining the structure of the grid.
It is an ever changing and ongoing project that has been in development since 2001.
Certain file schemes and names may bear a vague resemblance to those used by
\emph{Cool Graphics}, a program developed by Jamey Eason, but it's only because he
thought too loudly when he was beside me in the office.

\subsection{System requirements}
To compile the code, the following software components are needed. Most should be
automatically installed or available via your local package mananger.
\begin{description} \itemsep1pt \parskip0pt \parsep0pt
  \item[C++ compiler] gcc will probably work best since it is the choice of development.
      \texttt{clang} works on Mac but \texttt{OpenMP} should be installed.
  \item[FLTK 1.3] This is the widget set responsible for all the windows. It is recommended to 
    download this from \texttt{www.fltk.org} and compile it yourself. 1.3 is the minimum version
    but generally the newest 1.X version works.
  \item[libpng] Needed for producing PNG format files.
  \item[GLUT] This is needed for offscreen rendering on a graphics card on non-Macs.
  \item[HDF5] This is optional software and not very well developed at this point.
  \item[doxygen] This is only needed for developers wanting to browse the source.
  \item[OpenMP] This is recommended but needs to be installed on Macs.
  \item[OSMesa] Optional but required for offscreen rendering in software.
\end{description}

\section{Input Files}

\meshal assumes that there is a model, defined by a set of vertices,
which is to be displayed.
Beyond that, everything is optional.
The vertices may be connected to form structures, specifically
triangular elements, quadrilaterals, tetrahedra,hexahedra, prisms, 
or simple line segments.
Scalar data may be associated with every point on the grid and 
may be used to colour
any of the connected structures.
An auxiliary set of points may also be defined on which to display vector data,

Furthermore, the points may be divided into different 
regions which may have their
attributes independently manipulated.
Regions are delimited by tagged volume elements (see \autoref{sec:voleles}),
or may be specified by
a range of vertices (see~\autoref{sec:regfile}),
As well, all the structures formed by those vertices are part of the
region.
Vertices may belong to more than one region,
and there is at least one region in a grid.
If a region is not specified, all structures belong to the default region.
If there is a element direction file (\texttt{.lon} file), and no 
volume elements are tagged, elements with no direction will be region~0, 
and other elements will be region~1.

Surfaces may be formed from collections of two-dimensional elements.
Surfaces are defined by surface element files (see \S\ref{sec:surffile}).
Also, surfaces are defined if there are any 2D elements in an \texttt{elem}
file (see \S\ref{sec:elem}). 
In the latter case, 
the 2D elements are placed in different surfaces based on their region number.
Surfaces are independent of regions, and the relationship between the points
and model structures is described in the Fig.~\ref{fig:UML}.
\begin{figure}
\centerline{\includegraphics[width=13cm]{UML}}
\caption{Relationship between vertices (Points) and other structures.}
\label{fig:UML}
\end{figure}

All files (except IGB described below) are ASCII files.
They may be \emph{gzipped} 
in which case \lit{.gz} should be appended to the extensions given below.
Note that files are scanned line by line 
and that extra information on each line is ignored by \meshal.

\subsection{Vertices}
\label{sec:pts}
The file defining vertices in the model is the only mandatory file.
It must have the extension \lit{.pts} with the following format:
\begin{verbatim}
number_points
pt0.x pt0.y pt0.z
pt1.x pt1.y pt1.z
.
.
.
ptn.x ptn.y ptn.z
\end{verbatim}
The base name of this file, i.e., without the extension, is
used as the base name for cables, connections, triangles,
tetrahedra files, and shells files.

\subsection{Connections}
\label{sec:cnnx}
Connections are line segments between vertices.
The file defining the connections
has the extension \lit{.cnnx} with the following format:
\begin{verbatim}
number_connections
vertex#1 vertex#2
vertex#1 vertex#2
.
.
.
vertex#1 vertex#2
\end{verbatim}
where, again, base-0 vertex indices are used.
\emph{Note that successive connections which share a vertex are treated as part of a line.}
Sharing a vertex means that \texttt{vertex\#2} of connection \texttt{n} is also
\texttt{vertex\#1} of connection \texttt{n+1}.
This is important when drawing connections as 3D elements. 
In this case,
all connections of a line will be smoothly connected without gaps. See \autoref{fig:joint}.
Connections are defined in mixed element (\autoref{sec:elem}) files by \texttt{Ln}.  
The same rule regarding lines holds in the mixed element files.
A line is an entity which can be highlighted.

\begin{figure}
    \centerline{ \includegraphics[width=4cm]{linejoint}
                 \includegraphics[width=4cm]{twoSeg}}
    \caption{\textbf{Left}: Joint between two segments when part of a line. \textbf{Right}: Two independent segments.}
    \label{fig:joint}
\end{figure}

\subsection{Cables}
\label{sec:cabs}
\textcolor{red}{The use of cable files is deprecated. }
Cables are sets of contiguous connections and are treated as such.
The points in a cable must be contiguous in the points file.
The file defining the cables
has the extension \lit{.cables} with the following format:
\begin{verbatim}
number_cables
first_vertex_in_first_cable
first_vertex_in_second_cable
first_vertex_in_third_cable
.
.
.
first_vertex_in_last_cable
one_past_last_point_in_last_cable
\end{verbatim}
where the point indices are specified.
A cable will contain all points from the first specified in the cable until the
point before the first of the next cable.
Connections (see the preceding section) will be formed to construct the cables as lines.

\subsection{Surface Elements}

\label{sec:surffile}
These files have the suffix \lit{.surf} and
may define several surfaces in one file.
Any 2-dimensional element can be specified.
Labels are any sequence of characters not including white space.
The file has the following format:
\begin{verbatim}
number_elements_in_surface0 label_for_surface0 [label]
Tr vertex0 vertex1 vertex2 float
Qd vertex0 vertex1 vertex2 vertex3 float
.
.
.
Qd vertex0 vertex1 vertex2 vertex3 float
number_eleemnts_in_surface1 label_for_surface1 [label]
Tr vertex0 vertex1 vertex2 float
Tr vertex0 vertex1 vertex2 float
.
.
.
number_elements_in_surfaceN label_for_surfaceN [label]
Qd vertex0 vertex1 vertex2 vertex3 float
Tr vertex0 vertex1 vertex2 float
.
.
.
Tr vertex0 vertex1 vertex2 float
\end{verbatim}
where label is string without spaces which will be used to identify the surface in the list of surfaces.

\subsubsection{Triangles}
\label{sec:tris}
\textcolor{red}{Triangle files are deprecated. }
They are defined in a file with the extension \lit{.tris} or \lit{.tri}
which has the following format:
\begin{verbatim}
number_triangles_in_surface0 label_for_surface0
vertex0 vertex1 vertex2 float
vertex0 vertex1 vertex2 float
.
.
.
vertex0 vertex1 vertex2 float
number_triangles_in_surface1 label_for_surface1
vertex0 vertex1 vertex2 float
vertex0 vertex1 vertex2 float
.
.
.
number_triangles_in_surfaceN label_for_surfaceN
vertex0 vertex1 vertex2 float
vertex0 vertex1 vertex2 float
.
.
.
vertex0 vertex1 vertex2 float
\end{verbatim}
Thus, this file implicitly defines the number of shells in a model.
Currently, the fourth entry of the line is intended to be 
a material property indicator but it is unused.

\subsection{Volume Elements}
\label{sec:voleles}
There are two formats for defining volume elements, either the deprecated
tetrahedral file or the newer general element file. Details follow.

\subsubsection{Mixed element files}
\label{sec:elem}
Volume elements are specified by files with the \lit{.elem} extension.
The element types and node orderings are given in Fig.~\ref{fg:voleledef}.
The file format is as follows:
\begin{verbatim}
number_elements
Hx n1 n2 n3 n4 n5 n6 n7 n8 [region]
Py n1 n2 n3 n4 n5 [region]
Pr n1 n2 n3 n4 n5 n6 [region]
Tt n1 n2 n3 n4 [region]
Tr n1 n2 n3 [region [region_label]]
Ln n1 n2 [region]
Qd n1 n2 n3 n4 [region [region_label]]
Ln n1 n2 [region]
.
.
.
\end{verbatim}
where \texttt{Hx, Py, Pr, Tt, Tr, Qd, Ln}
stand for Hexahedron, Pyramid, Prism,
Tetrahedron, Triangle, Quadrilateral, and Line respectively.
Each line of the file may be any of the element types.
For surface elements, a region label string may also be specified as one word using any characters but spaces. 
It need only be defined
once in the file per region.
\begin{figure}
\centerline{\includegraphics[width=10cm]{volelemdef}}
\caption{Volume elements\label{fg:voleledef}}
\end{figure}

\subsubsection{Tetrahedra}
\label{sec:tets}
Tetrahedra are defined in a file with a \lit{.tetras} extension and the following
format:
\begin{verbatim}
number_tetrahedra
vertex0 vertex1 vertex2 vertex3 [region]
vertex0 vertex1 vertex2 vertex3 [region]
.
.
.
vertex0 vertex1 vertex2 vertex3 [region]
\end{verbatim}
The fifth entry of the line is a integer specifying a region. All nodes
of the tetrahedron belong to the region so nodes may belong to several
regions. If no region is specified, nodes are assigned to region 0.

\subsection{Regions}
\label{sec:regfile}
Regions may be explicitly specified in a separate file with the extention 
\lit{.region}
with the following format:
\begin{verbatim}
number_regions
first_vertex_in_region0 last_vertex_in_region0
first_vertex_in_region1 last_vertex_in_region1
.
.
.
first_vertex_in_regionN last_vertex_in_regionN
\end{verbatim}

\subsection{Scalar Data}
Scalar data can be associated with each vertex or with each element.
although not all operations may be available for elementally defined data.
Data can be time dependent or time independent.

\subsubsection{ASCII format}
A data file typically has the extension \lit{.dat} or \lit{.out} but these extensions
are suggested and not required.
The file simply contains lines with one entry per line, the data value for the
vertex or element.
There is no separation between time frames, so if there are N points or elements, and 10 times,
there will be 10N lines in the file. 
The data is interpreted as vertex data if the number of lines in the file is a multiple of the
number of vertices, or the number of lines is not a multiple of the number of elements.

\subsubsection{IGB format}
\label{sec:IGB}
IGB is a format developed at the University of Montreal and used in a 
visualization program called flounder, for regularly spaced data.

The file is composed of a 1024-byte long header followed by binary data.
For irregular grids, the individual dimensions are meaningless but xdim$\times$ ydim$\times$ zdim should be equal to the number of vertices/elements.
The header is composed of strings of the format below, separated by
white space.
\centerline{ \texttt{KeyWord:value} }
Note that the header must be padded to 1024 bytes.
The first block of key words need to be specified. The rest are optional.

\begin{longtable}{|l|l|p{0.7\textwidth}|}\hline
	KeyWord & Type & Description \\  \hline \endhead
    \hline \endfoot
    x       & int    & number of samples in x \\
	y       & int    & number of samples in y \\
	z       & int    & number of samples in z \\
	t       & int    & number of samples in t \\
	systeme & string & \texttt{big\_endian} or \texttt{little\_endian} \\
	type    & string & binary data type: byte, char, short, long,
	                   float, double, int, uint, vec3f, vec4f,
					   vec3d, vec4d\\ \hline
	unites  & string & units of data \\
	facteur & float & scaling factor for data \\
	zero    & float & data zero: true value =
	                            IGB\_data*\texttt{facteur}+\texttt{zero} \\
    org\_x  & float & lower right x coordinate       \\
	org\_y  & float & lower right y coordinate       \\
	org\_z  & float & lower right z coordinate       \\
	org\_t  & float & time of first slice            \\
	inc\_x  & float & distance between x samples \\
	inc\_y  & float & distance between y samples \\
	inc\_z  & float & distance between z samples \\
	inc\_t  & float & time between samples \\
	dim\_x  & float & extent in x \\
	dim\_y  & float & extent in y \\
	dim\_z  & float & extent in z \\
	dim\_t  & float & duration \\
	unites\_x & string & units of measure for spatial x dimension \\
	unites\_y & string & units of measure for spatial y dimension \\
	unites\_z & string & units of measure for spatial z dimension \\
	unites\_t & string & units of measure for time \\
    comment   & string & arbitrary comment \\
	aut\_name & string & author's name     \\
    transparent & hex & value for no data  
\end{longtable}
Note that for unstructured grids, $x$, $y$ and $z$ specific values 
are meaningless.

\subsection{Vector Data}
To display vector data, an auxiliary set of points must be 
defined by a file with the \lit{.vpts} suffix.
It follows the same format as the vertex file.
A file with the same base name but having the extension \lit{.vec} defines the 
vector and scalar data. It has the following format:
\begin{verbatim}
data.x data.y data.z [scalar_datum]
data.x data.y data.z [scalar_datum]
.
.
.
data.x data.y data.z [scalar_datum]
\end{verbatim}
The scalar datum, as indicated, is optional.

Vector data can also be input as an IGB file using the types
\texttt{vec3f, vec4f, vec3d, vec4d} where 3 or 4 refers to the number of
elements in each datum,
and \texttt{d} and \texttt{f} refer to float or double.
The first 3 elements define the value of the vector field,
and the optional 4th element is the
scalar component as above. This file has the suffix \lit{.vec.igb}.

\subsection{Auxiliary Grid}
An auxiliary grid may be defined, optionally on which may be displayed
data. The grid may contain any of the elements forming the main grid
(vertex,line segments,surface elements,volume elements), and the
elements may change as a function of time.
If scalar data has already been read in, the number of time instances in
the auxiliary grid must either be one, or the same as the scalar data.
The points file may have only one time instance, which is then assumed constant over all time.

A vertex file is mandatory and has the extension \lit{.pts\_t}.
An element file is optional. If present, it has the same base name as the
vertex file but with the extension \lit{.elem\_t}.
Scalar data may also be optionally defined on the auxiliary grid. The file
has the same \texttt{basename} as the vertex file but with the extension
\lit{.dat\_t}.
The file formats follow:\\
\newcolumntype{A}{>{\ttfamily}l}
\begin{longtable}{|AAA|A|A|}\hline
    \multicolumn{3}{|l|}{base.pts\_t}& base.elem\_t & base.dat\_t \\
    \hline
    \multicolumn{3}{|l|}{\#times}& \#times & \#times \\ 
    \multicolumn{3}{|l|}{\#points\_time0} & \#elements\_time0 & \#data\_time0 \\
pt(0,0).x & pt(0,0).y & pt(0,0).z & element(0,0) & data(0,0) \\
pt(1,0).x & pt(1,0).y & pt(1,0).z & element(1,0) & data(1,0) \\
. & . & . & . & . \\
. & . & . & . & . \\
. & . & . & . & . \\
. & . & . & element(M,0) & . \\
. & . & . & \#elements\_time1 & . \\
. & . & . & element(0,1) & . \\
. & . & . & element(1,1) & . \\
. & . & . & . & . \\
pt(N,0).x & pt(N,0).y & pt(N,0).z & . & data(N,0) \\
  \multicolumn{3}{|l|}{\#points\_time1} & . & \#data\_time1 \\
pt(0,1).x & pt(0,1).y & pt(0,1).z & . & data(0,1) \\
pt(1,1).x & pt(1,1).y & pt(1,1).z & . & data(1,1) \\
. & . & . & . & . \\
. & . & . & element(M,1) & . \\
. & . & . & \#elements\_time2 & . \\
. & . & . & element(0,2) & . \\
. & . & . & . & . \\ \hline
\end{longtable}

Auxiliary grids have some limitations compared to the regular meshes.
They are constrained to a single surface, and a single region. 
Data opacity is not available. 
Only the vertex itself may be highlighted and not any connected components, and
no connectivity information is available via the highlight window.
Also, isosurfaces/isolines cannot be computed on them.

\subsection{Dynamic Points}
Points may also move in space as functions of time.
This is often associated with displacement during contraction, for
example.
The number of points must remain constant for all time instances,
as well as the elements defined by them.
Dynamic point files use the IGB format (see \S\ref{sec:IGB}) with data type
\texttt{vec3f}. The extension for the file in this case is \lit{.dynpt}.

\subsection{HDF5 Format}
All of the previous data types may now be packaged into one HDF5 file. Reading and
writing of the data is done through an API so the data format will not be
described. The HDF5 file should have the suffix \lit{.datH5} and may contain multiple
datasets of differing types.

\subsection{CG meta format}
Cool Graphics (CG) is a visualization program written chiefly by Jamey Eason
and its file format was pretty much copied for this program.
This format is kept for historical reasons and its use is deprecated.
There must be a vertex file (as previously described) and there
may a file for tetrahedra. These files must share a common basename.
\emph{Note that a major difference between CG format and the previously described
formats is that \textbf{CG vertex numbering starts at one instead of
zero}.}
This will not affect the vertex file but means that if the same grid is
described by the two formats, the tetrahedral indices for the CG file will
all be one greater than for the regular format.
In addition, there is a metafile listing the surfaces and
there may be a sequence of data files. 
The file formats for the metafile and data files follow.
\subsubsection{CG metafile}
This file must have the suffix \lit{.cg\_in} and adheres to
the following format:
\begin{verbatim}
number_surface_files
0
surface_file_1
surface_file_2
.
.
.
surface_file_n
\end{verbatim}
where \texttt{surface\_files}
are triangle files (see section~\ref{sec:tris}) for
format) with the \lit{.tri} extension. 
The extension is \emph{not} 
given in the CG metafile, eg, if the actual file name is \texttt{endo.tri},
only \texttt{endo} is given.
\subsubsection{Data files}
Data is given in a set of ASCII files with the extensions \lit{.t\#} where
\texttt{\#} is the time of the data, i.e., it is composed of digits.
For each file, the format is
\begin{verbatim}
t = #
a b c
a b c
.
.
.
a b c
\end{verbatim}
where the first line indicates the time (\# same as in file extension)
and each line contains three data.
Currently, the first 2 are ignored but must be present.

\subsection{Temporal Data Agreement}
When temporal data is present, i.e., multiple frames of data exist for any
grid, the number of instances must agree for all grids loaded.
Given that one grid has $T$ frames of data where $T\ge2$, any grid can only
have 0, 1, or $T$ frames of data.
If there is one frame of data, it is always displayed.
Thus, for example, if the scalar vertex data was loaded and contained 
1 frame of data, an
auxiliary grid with 100 frames could be read in, and subsequently a
vector data grid could only be read if it had 1 or 100 frames of data.

\section{Invocation}
The program is run by typing
\begin{verbatim}
meshalyzer [opts] [pts [vpts] [dat|tdat|igb] [mshz] [tri ...] [pts_t] [dynpt]]
\end{verbatim}
where the extensions of the required file types are given.
If no file is specified, a file input box will pop up.
Note that for the \lit{pts} file, the dot of the extension can be left in to facilitate
using tab completion. 
For example, if the vertices file was called \emph{model.pts},
one could specify \lit{model.pts}, \lit{model.}, or \lit{model} equally on the command line.
This only applies to the vertex file.

\subsection{OpenMP}
\label{sec:omp}
Certain computations in meshalyzer can take advantage of OpenMP parallelization. 
Computing isolines (\autoref{sec:iso}) is one such computation.
OpenMP is standard on all compilers except Apple's version of clang, but can be added.
Set the environment variable \texttt{OMP\_NUM\_THREADS} to a value that works for you.

\subsection{Options}

\label{sec:options}
\begin{description}
    \item[--help] Display the usage message
    \item[--iconifycontrols]  iconify the control window on startup
    \item[--groupID=GID] Be part of this semaphore group for \meshal linking. See \S\ref{sec:link}.
    \item[--noelem] Do not read in the element file. This will speed up reading in the model at the expense of
        not being able to put data on the cutting planes.
    \item[--thrdRdr] Force threaded data reading. Even if one has enough memory to read in all the data at
        once, it is probably just as fast to read it in on demand. Using this option will reduce start up time
        and stop \meshal from using all the RAM.
    \item[--PNGfile=\emph{file}] Output file name for PNG files or output directory name for PNG sequences
    \item[--frame=\emph{int}] first frame for PNG output (-1=do not set)
    \item[--numframe=\emph{int}] number of frames to output to PNG images (default=1,-1=all)
    \item[--size=\emph{int}] width and height of PNG in pixels (default=512)
    \item[--compSurf=\emph{[+][file]}] compute and write boundary surfaces to \lit{file}. If \lit{file} is not
        specified, use the model name. Specify \lit{+} to NOT exit immediately after writing file. 
        To not write a file, specify \lit{file} as \lit{/dev/null}.
\end{description}

Note that only enough characters to uniquely identify the option need be used.
See the Offscreen Rendering section\ref{sec:offscreen} for a complete description of how to use PNG related options.

\subsection{Environment variables}
\meshal reads the following environment variables:
\begin{description}
\item[MESHALYZER\_MODEL\_DIR] This is a colon separated list of directories
which will be searched for models. If a model is not found as
specified, the model will be searched relative to these directories.
Also, when \meshal is invoked with no model file, the chooser will open in
the first directory specified in the variable.
\end{description}

\subsection{Default settings}

Upon invoking  \meshal, your home directory will be
searched for a default state file called \texttt{.default.mshz}.
If found, it will be read in automatically.
With this file, any setting within \meshal can be altered.
The format of this file is explained in \S\ref{sec:statef}

\section{Graphical User Interface}

\begin{figure}[htbp]
\centerline{\includegraphics[width=6cm]{controls}}
\caption{The control widget.}
\end{figure}

\subsection{Volume Mesh}
To display the volume element mesh, click on the  \lit{Voxele Mesh} 
radio button in the
\emph{Display as:} box.
The colour of the volume elements can be changed with the \lit{Voxele colour}
button.
No other structure types will be displayed.

\subsection{Regions}
To not display the mesh as a set of volume elements,
click on the  \lit{Surfaces} 
radio button in the
\lit{Display as:} box.
This will display all structures except volume elements.

Display of each structure type can be toggled on and off on a
region-by-region basis or all-at-once.
The regions in which changes will take place are selected
by highlighting them in the list.
Any changes made to display structures will only occur to the regions selected.
The opacity value of a region
is changed by dragging in the opacity bar. It affects
all structures in a  region equally.
Sometimes rendering with opaque objects does not look quite
right because of drawing
order.
The order can be reversed by checking \lit{Reverse Draw order} under the \lit{Image}
menu.

For each structure, there is a button toggling its display, 
and a button to select its display properties.
Pressing the \lit{props} button will open a widget to specify 
colour when it is not displaying data, to specify the output stride, size 
and if a 3D effect is to be used. 
\textbf{Note that the 3D effect is memory intensive and may cause a segmenation violation
for a large number of objects}.

Different structures in different layers can be coloured differently.
Under \lit{Image/Randomly colour}, one can select which structure types gets randomly
coloured based on the region to which it belongs.
\lit{Image/Background colour} changes the colour of the background.

\subsection{Tab Widget}

\subsubsection{Highlighting}

Highlighting allows one to investigate the structure of the mesh.
One of each type of structure can be highlighted. 
A highlighted element is drawn in a special highlight colour.
The highlighted structure can be chosen by typing its number.
Values can also by dragging the mouse. 
See the FLTK manual for
a full explanation of the latter.
Pressing CTRL causes the arrow keys to increment by 10 while pressing
SHIFT causes them to increment by 100.
The mouse wheel can also be used with SHIFT and CTRL increasing the stride as well.
Hold both for a factor of 1000.
Volume elements can be selected to be drawn as a wireframe (\texttt{Vol Ele})
or a solid faced object (\texttt{Solid Vol Ele}).
Clicking on the \lit{current reg/surf} button highlights the first
structure of each
type for the currently selected shell (0 if \emph{All} is chosen).

\label{para:pickvertex}
The highlighted vertex can also be selected with the mouse.
\emph{Vertices must be displayed to activate this button.}
Clicking on the \lit{Pick Vertex} button will enter vertex picking mode
with the button turning red to indicate this.
A vertex can then be selected by clicking on it.
If you are having trouble selecting a vertex, zoom in and click on its center.
The clicking area for a vertex is that of a vertex drawn with a size of 10 (non-3D).
Three attempts are allowed to click on a vertex before picking mode is turned off.
Note that the highlighted node can be changed by using the mouse wheel (as explained above).
For the highlighted vertex, its associated scalar data value
is displayed in the gold widget.
You can choose to display the surface elements that the vertex is part of, or
the volume elements that it is part of.
The elements can be drawn as wireframe or with filled sides.
For detailed information about the highlighted objects, click on the \lit{?} button.
See the \texttt{Information Window} (\autoref{sec:infowin}).

\subsubsection{Time Plot}
\label{sec:timeplot}
The time series of the highlighted vertex can be displayed by clicking the 
\lit{plot time series} button.
The current time is indicated by a vertical green line.
A trace can be saved by clicking on the \lit{Hold} button.
Up to 8 traces can be saved this way.
To clear the held traces, click on mouse button 3 and select 
\lit{clear static curves.}
The plotted traces can be saved in ASCII format by clicking
the \lit{Save} button.
Normally, when a new point is clicked, the x and y range are recalculated
and the scale adjusted accordingly.
To prevent this behaviour, deselect the \lit{Autoscale} button.
Within the time plot, a zooming rectangle can be selected with mouse button 1.
Clicking the middle mouse button will pop up the coordinates of the mouse.
Clicking on mouse button 3 will pop up a menu which includes \lit{reset view} 
to rescale the graph and selections for setting the \emph{X} and \emph{Y}
range displayed.
\begin{figure}[htb]
\centerline{\includegraphics[width=10cm]{timeplot}}
\caption{Time series window.}
\end{figure}

\subsubsection{Information Window}
\label{sec:infowin}
Clicking on the gold \lit{?} button pops up a information window with details of the
selected objects.
For the highlighted node, all the objects, of which it is a part, are listed.
For each structure, the defining nodes are listed.
\textbf{Clicking on any line will cause the object in that line to become the highlighted object.}
For example, clicking on one of the nodes defining a terahedron will make that node the highlighted node.
\emph{Clicking on any line in the window also 
copies the text to the selection buffer}, so it can
be easily pasted into another application. 


\subsubsection{Lighting}
\label{sec:lighting}
Lighting is controlled in the light tab (\autoref{fig:lightDiag}).
The light is directional with its direction, $\hat{L}$, controlled by the orienter.
Clicking and dragging the mouse in the orienter changes $\hat{L}$.
If \lit{Eye} coordinates are used, the light remains fixed while the object rotates.
If \lit{World} coordinates, the light rotates in space with the object.
The direction of the light is graphically illustrated by the red arrow.
The \lit{flip} button will reverse the light direction, and an orientation along a major axis
can be selected from the \lit{set light dir} menu.
The incident light is white with the intensity of the different lighting components adjusted with
the sliders and expalined below:
\centerline{\begin{tabular}{|l|p{0.7\columnwidth}|}\hline\hline
    \textbf{Light Type} & \textbf{Description} \\ \hline\hline
    Amb  & Ambient light s constant for all points on the surface. \\\hline
    Diff & Diffusive light intensity is proportional to the cosine of the angle of incidence, $\propto \hat{L}\cdot\hat{n}$. it is the surface colour. \\\hline
    Spec & Like diffusive, but with an exponent,  $\propto (\hat{L}\cdot\hat{n})^N$, and the reflected light is white,
            not the colour of the object. \\ \hline
    Shiny & The exponent $N$ for specular light. Setting it higher keeps the reflection smaller. \\
           \hline\hline
\end{tabular}}
With \lit{facet shading} enabled, Gouraud shading is turned off and lines
are not antialiased. This may speed up rendering on slow platforms.
Note that surface material properties may also be set, which depend on lighting. See  \S\ref{sec:surface}.

\lit{Backface} controls lighting of back facing polygons, as defined by the sense of the point order:
\begin{description}
    \item[Cull] Do not draw any polygons facing the back. This is fine for closed surfaces,
        and will speed up rendering, as well as make transparency brighter.
    \item[Unlit] Back facing polygons will be unlit and dark. This saves lighting calculations on one side.
        This has traditionally been the default.
    \item [Lit] perform lighting calculation for both sides of the polygon. This is the slowest but the best. 
        The intensity of the light for the backward facing polygons can be adjusted on the Surface color widget.
\end{description}
\begin{figure}[htb]
\centerline{\includegraphics[width=10cm]{light}}
 \caption{Lighting tab.}
    \label{fig:lightDiag}
\end{figure}

As a general outline, the following table gives the lighting settings to achieve material effects (L=low, M=medium, H=high, V=very):
\begin{longtable}{|l|c|c|c|c|}
    \hline
    material & Ambient & Diffuse & Specular & Shiny \\ \hline
    Glass    & L      &  H     & H        & H  \\
    Stone    & L      &  VH    & L        & VL \\
    Metal    & L      &  M     & H        & H  \\
    Plastic  & VL     &  VL    & M        & L  \\
    Rubber   & VL     &  M     & M        & VL \\
    \hline
\end{longtable}

\subsubsection{Scalar Data}

\label{sec:scalardata}
Scalar data is read under the \lit{File} menu in the top bar.
It can be static or time-dependent.
If time-dependent, animation can be played by clicking the green double arrow button
in the bottom panel.
The delay between frames in $\mu$s is selectable.
\lit{\#frames} selects how many frames to increment at a time.

If data is present, each vertex has associated scalar data which is linearly
mapped to a colour.
Clicking \lit{optimal} maps the currently displayed minimum data value to 
level 0 and the currently displayed 
maximum data value to the maximum colour level.
The number of entries in the colour map is determined by the \lit{levels} widget.
When \lit{auto cs} is selected, the colour map is re-calibrated whenever the displayed
time changes.
It is equivalent to pressing \lit{optimal} every time that time is changed.
The values corresponding to the minimum and maximum colour values are 
available for editing.
Pressing mouse button 3 pops up a small menu to \lit{reverse} the colour scale, or make the colour scale symmetric about 0 based 
on either the maximum (\lit{symmetric max}) or minimum 
(\lit{symmetric min}) data value.

Different structures may be coloured according to the data.
The \lit{Data on:} choice widget selects which structure types are coloured according
to the data values associated with the vertices defining the structures.

\subsubsection{Vector Data}

Vector data is specified on the command line or by selecting \lit{Read Vector Data}
under the \lit{File} menu item.
Arrows are drawn at each vector grid point.
The size of all arrows can be scaled with the roller.
The relative length of the arrow can be based on the magnitude of the vector data,
by the optional scalar data value, or be fixed.
Colour can be based on vector magnitude, scalar data or be constant.
The constant value is selected by the \lit{colour} button.
Magnitude and scalar data are mapped to a selectable colour map as with
vertex scalar data.
To display a subset of the data, a stride may be chosen.
Sometimes, especially with a regular grid is used, a constant stride will lead to aliasing effects. In this case,
checking the \lit{stochastic} button will add a random perturbation to the stride so that the model is
irregularly sampled but on average, at the specified stride.
The initial starting point for the stride, \lit{start}, can also be set.
Drawing heads in the vectors is also optional. Not drawing them will improve
rendering speed and they may not be necessary for certain kinds of data, like
fibre direction.

\subsubsection{Auxiliary Grid}

Auxiliary grids are specified on the command line or by selecting
\lit{Read Aux Grid} under the \lit{File} menu.
The \lit{Display} button toggles drawing of the grid.
The colouring of the model components is controlled independently of the
main grid.
Widgets for selecting the colour scale and mapping of the scalar data to
colour are available. See \S\ref{sec:scalardata} for details.
Components are grouped into point, line, surface and volume elements.
Each group of grid components can be coloured with a fixed colour chosen
with the \lit{color} button.
If scalar data is present, the components can be coloured according to the
associated data value, that is, \lit{datafied}.
The size of the components can also be controlled. For surface and volume
elements, the size refers to the line width when the components are drawn
as wireframe.
How the components are drawn can also be specified.

A node can be selected by entering its number in the provided widget on the
tab. 
The highlighting option must first be turned on.
Furthermore, if an auxiliary grid has the same number of vertices at all
instances of time, the time series of the vertex data can be displayed by
clicking on the \lit{Plot} button.
See \S\ref{sec:timeplot} for a description of the widget.

\subsubsection{HDF5 data}

A file with the suffix \lit{.datH5} can be read in. This file may contain many data
sets. Upon successfully opening the file, a dialog will open which displays the
data sets from the file which may be viewed on the current grid.

\subsubsection{Surfaces}

\label{sec:surface}
Only surfaces checked in the list are affected by any changes effected.
The fill colour of the elements composing surfaces can be selected as well
as the independent outline colour. 
Outlining and filling the elements can also be controlled. 
The opacity value selected under the surface colour applies when data is present as well.
Lighting properties can also be set for individual surfaces.
\lit{Specular} and \lit{diffusive} are as explained in \S\ref{sec:lighting}.
\lit{shiny} controls the exponent of the specular light with a higher number making highlights sharper.
\lit{back light} controls intensity of backward facing polygons when backlighting is ``lit'' (\autoref{sec:lighting})
Surfaces can also be randomly coloured by Image/Randomly Color/Surfaces.
Surfaces are renamed with the \lit{Rename} button. You will be prompted if you
want to overwrite the surface file with the new label.
The normals of a surface can also be flipped by selecting \lit{flip/normals}.


\subsection{Image Menu}

\subsubsection{Reset Transform}
Restore the original default transformation.

\subsubsection{View}
Choose from standardized views. The first submenu indicates the axis which
is sticking out of the screen and the diagrams show the positive axes of
the other two dimensions.

\subsubsection{Randomly colour}

For each region, assign the same random colour to all of the element
types chosen.

\subsubsection{Background colour}

Select the background colour.


\subsubsection{Reverse draw order}

Draw the surfaces in the opposite order. This can be useful when surfaces
overlap and different perspectives are chosen.

\subsubsection{No rotation}

The trackball no longer performs rotations, only translation and scaling. This is automatically set for 1D and
2D data.

\subsection{Sync}
Syncing transfers setting to different running instances of meshalyzer.
See \S\ref{sec:link} for details.

\subsection{Data Menu}

\subsubsection{Data Opacity}
Data opacity is the ability to draw structures with an alpha value based on the
values of data associated with the structure.
For data below a minimum value, the data is draw with the \lit{minimum opacity}.
For data above a maximum value, it is drawn with the \lit{maximum opacity}.
In between the two data values, linear interpolation of the opacity values is used.
The opacity for each structure type is independent.
\begin{figure}[htb]
\centerline{\includegraphics[width=8cm]{opacity_dialog}}
\caption{Data opacity dialogue.}
\end{figure}

A common use is the draw surfaces as translucent and then draw excited regions as
fully opaque.

\subsubsection{Clipping Planes}

By selecting \lit{Clipping} from the \lit{Data} menu item,
the clipping widget is popped open (\autoref{fig:clipdiag}).
Six clipping planes are available.
They are defined by the normal to the clipping plane and the intercept of the
plane.
Only structures located on the side of the plane to which the normal points are drawn.
To flip the normal to point in the opposite direction, click on \lit{Flip}.
You can enter values manually, after which you should  \lit{Unitize} so that
the normal has unit magnitude.
This ensures that when changing the intercept with the slider, one can move the
plane through the whole object.
For each clipping plane, several different modes are available:
\begin{description}
	\item[Off] The clipping plane is inactive and not visible
	\item[On]  The clipping plane is active but not visible
	\item[Whole Plane] The plane is active and can be seen
	\item[Intersection] The plane is on and can be seen only where it
		 intersects the object
    \item[Datafied] The plane is on, can be seen only where it
		 intersects the object, and if data is present,
		 will have data interpolated on to it.
 \end{description}
\begin{figure}[htbp]
\centerline{\includegraphics[width=12cm]{clip}}
\caption{Clipping plane dialogue.}
    \label{fig:clipdiag}
\end{figure}
At the bottom of the widget is a graphical interface for reorienting the clipping plane. 
It reflects the orientation of the \emph{selected} clipping plane, the one displayed in yellow.
To select a plane, simply click anywhere within its box.
The selected clipping plane may be rotated by clicking and dragging the mouse in the orienter widget.

Clipping plane orientations may be copied and pasted between each other. The right mouse button will bring up the copy/paste menu. A settings for a plane can be copied as is (\lit{paste+}), or flipped 180 degrees (\lit{paste-}). The latter is helpful for displaying slices. 
The same menu also lets you orient a clipping plane in the plane of the screen (\lit{screen}).

To the bottom right is the colour selector for intercepted clipping planes when there is no data.
The opacity may also be selected, but this applies to all clipping planes, datified or not.
For colour or opacity to take effect, the \lit{Apply} button must be pushed.

\subsubsection{IsoSurfaces/IsoLines}
\label{sec:iso}
By selecting \lit{Isosurf} from the \lit{Data} menu item,
the isosurface/isolines widget is popped open.
This widget controls display of isovalue surfaces and lines.
Isosurfaces are only available if elements are defined. 
They are drawn with a specified colour and opacity.
Changes to the \lit{value} are reflected when enter is pressed or the focus
changes.

For isolines, surfaces must be defined. An initial isovalue, ending
isovalue and the number of isovalue lines are specified.
The \texttt{increment} box is an output showing the difference between successive isovalues.
By clicking \lit{match colors}, the isoline levels will match the colour scale of the
model data so that isolines correspond to the colur boundaries.
If \lit{datified} is selected, the lines are coloured according to 
the data colour scale, otherwise all lines are drawn with the same
specified \lit{colour}.
The thickness of the lines can also be controlled and whether the lines are drawn as 3D cylinders.
Isolines are composed of connections (\autoref{sec:cnnx}) and, as such, are arranged to form lines if possible
by checking if the end of one segment is the start of another.
The parameter \texttt{close} is used to filter the points of the connections.
If two points are less than this distance apart (as measured by the L1 norm), they are coalesced into one point.
Increasing \texttt{close} has the effects of smoothing the isolines, as well as
linking more connections to form fewer and longer lines, but portions of lines may disappear under convex surfaces.

\subsubsection{Dead range}

Often, one does not have data for all vertices in the mesh and one uses a bogus placeholder value. 
In this case, it is conventient to draw the nondatified objects in a different colour so that they stand out, or
not even draw them at all. We consider data outside of a specified range to be \lit{dead}. You can specifiy a \emph{minimum valid value} and any data below this
value will be considered dead. Likewise a \emph{maximum valid value} can be selected, or both. The colour and opacity of the dead vertices can be selected
arbitrarily.
The \lit{Apply} button must be pressed to enact the changes. \lit{Recalibrate} scales the colour scale for the nondead range.

\subsubsection{Branch cut}

Branch cuts represent discontinuities in the value of a function which are artificial. 
An example is the branch cut in
the imaginary plane which defines trigonometric functions to return values in the range $[-\pi,\pi)$.
This leads to spurious values when interpolating within elements through which a branch cut passes. 
Any modulo function will also display this property.
Continuing with the example of trigonometric functions, an element with nodal values near $\pi$ and $-\pi$
should not be interpolated to contain a zero value.
Choosing the appropriate branch cut range will ignore interpolation within such elements,
especially when calculating isolines and surfaces (\autoref{sec:iso}).
Four common ranges are available.
It is suggested that an appropriate colour scale is used which wraps around, 
i.e., has the same value at the two extremes.

\subsection{Output Menu}

\subsubsection{Single Images}
Images can be saved in PNG format under the \lit{Output} menu.
These images may be blown up to arbitrary size without pixelation effects.
\textbf{Note that the images have metadata added.}
The colour scale range is recorded in the \emph{Description} field 
of the metadata,
and a field called \emph{Data file} gives the absolute path of the data file used to produce the image.
Additonally, the paths of the mesh, and, if present, the vector data and the
auxiliary grid data are stored.

\subsubsection{Colour Bar}

The colour bar in use with the set number of discrete levels will be output as a PNG file.

\subsubsection{Animation Sequences}
For animation data, one can save a sequence of images in PNG format under the 
\lit{Output} menu.
For sequences, one selects a base name for the files and then 5 numbers for
the time frame number are appended, eg., image00012.png, image00013.png, etc.
These images are raster plots, based on the screen buffer, so larger 
windows will scale better.

\subsubsection{Recording Event Sequences}
It is possible to automatically write an image every time the contents of the window
change because of an event.
Thus, one can make a sequence of the model rotating or a sequence of the model as a
cutting plane is passed through it.
To begin recording, select \lit{Recording/start} under the \lit{Output} menu.
\lit{Output} will turn green to indicate that it is in recording mode.
As above, you will be prompted for a base file name which will have frame numbers
appended to it.
A blue \lit{Redraw} label will also appear on the main menu bar.
Use this to force the output of the image, even if nothing has changed.
Manipulate the model any way you wish and when finished, select \lit{stop}.
A dialogue will pop up indicating how many frames were written.

\subsubsection{Visible nodes}

A list of the visible nodes and clipping planes can be generated by
selecting
\lit{Output/Visible vertices}.
You will be prompted for a filename and a file with the following format
will be produced:
\begin{verbatim}
number_clip_planes_on
a1 b1 c1 d1
a2 b2 c2 d2
.
.
.
an bn cn dn
number_visible_vertices
visible_node1
visible_node2
.
.
.
visible_nodeN
\end{verbatim}
The coefficients (a,b,c,d) 
for the clipping plane are defined in the specified model coordinate system.

\subsection{Saving The Current View}

The current view can be saved by clicking on \lit{Save transform} under the \lit{File} menu.
You will be prompted for a file in which to save the current modelling transformation.
The current rotation, scaling and translation of the grid will be written to a file with
the extension \lit{.xfrm}.
Once saved, it can be restored later by choosing \lit{Read transform} and selecting the file.

Standard views are available under the \lit{Image} menu under \lit{View}.
The normal which points directly out of (+) or into (-) the screen is
first selected and then the positive direction of the other axes.

\subsection{Saving/Restoring the State}
\label{sec:statef}

The state is everything including the view transform. 
You can save the state under \lit{Save state} in the \lit{File} menu.
You will be prompted for a file which will have the extension \lit{.mshz}.
This file is text and can be edited by hand afterwards. 
Entries are generally of the form\\
\centerline{\texttt{widget\_name = value}}
but more complicated formats are also used. 
It is best to save a state file and study it.
You may delete any entries which you do not wish restored.
Unknown \texttt{widget\_names} are ignored with a message.
Names can change between versions so these messages are not fatal.
A state file can be specified on the command line and will supercede
any settings from the default state file.

\section{Grid window}

The grid is displayed in a window which has a virtual trackball.

\begin{longtable}{cll}\hline
    \textbf{Mouse} & \textbf{Modifier} & \textbf{Action} \\ 
    \textbf{Button}&                   &  \\ \hline\hline
    1   & - &  trackball rotate \\ \hline
    2   & - & \multirow{2}{*}{translate} \\
    1   & SHIFT & \\ \hline
    3   & - & \multirow{2}{*}{scale} \\
    1   & CTRL & \\ \hline
    2+3 & -          & vertical move -- rotate about screen $X$ \\
    1   & CTRL+SHIFT & horizontal move -- rotate about screen $Z$ \\
    \hline
\end{longtable}
\vspace{5pt}

\noindent
The axes showing the orientation of the window may be displayed by clicking on the
\lit{Axes} button.

\begin{longtable}{|c|l|}\hline
Key & Action \\ \hline
    $\leftarrow$ & decrement time \\
    $\rightarrow$ & increment time \\
    c & pop control window \\
    o & recalibrate the colour scale to the optimal for the displayed data \\
    p  & enter \hyperref[para:pickvertex]{vertex picking} mode\\
    r  & reread the current data file \\
    t & \hyperref[sec:link]{temporally sync} \\
    v & \hyperref[sec:link]{viewport sync} \\
    \hline
\end{longtable}

\section{Linking}

\label{sec:link}
Different \meshal instances can be linked together so that certain operations are applied to all
instances.
To link instances of \meshal, click on \lit{File/Link} which will open up a linking dialog.
At the top of the dialogue is the Process Identifer (PID)  of the current \meshal instance, below which is a list of the
currently running but unlinked processes which contain the word \meshal.
To link, select a process and press the \lit{link selected} button.
Successfully linked processes are shown in the bottom list.
Linking is bidirectional so that linking a new process includes it in the group of currently
linked processes. As such, operations performed in any of the linked processes will be sent to
all processes. 
Unlinking is also bidirectional, so unlinking it removes it entirely from the group.

Currently, linking supports the following operations:
\begin{description}
\item[Temporal changes] Increments or decrements in time will be transmitted to all instances. 
    This includes arrows and the animation button.
\item[Temporal syncing] Clicking on the \lit{sync} button (beside the animation pause button)
      will set all instances to the same time. This is also achieved by pressing \lit{t} in the
      model window.
\item[Viewport syncing] Clicking \lit{Image/Sync/Viewport} or pressing \lit{v} in the model window 
     will transmit the current scale, relative orientation, and relative translation to all other instances.
     If the meshes are not oriented along the same axes, a new reference direction can be defined and then the rotation 
     relative to this orientation will be applied. 
     The simplest way to use this is to 
     set the linked meshes 
     to their respective default views, orient one a mesh to match the others, 
     and then click \lit{Image/Sync/Set reference view}.
     Clicking \lit{Image/Sync/Reference view} will put the mesh in the reference view.
 \item[Colour Scale] Clicking \lit{Image/Sync/Colour Scale}, or pressing the sync button 
     beside the colour bar will transmit the current colour map to all other instances.
 \item[Clipping planes]  Clicking \lit{Image/Sync/Clip} or pressing the button on the clipping plane dialogue widget
     will send the clipping plane info to the linked instances. As with viewport suncing, the clipping is performed 
     relative to the reference view.
\end{description}

\noindent
As a side effect of temporal linking, \meshal responds to the following UNIX signals:
\begin{longtable}{|l|l|}\hline
Signal & Action \\ \hline
SIGUSR1 & advance forward by the frame increment \\
SIGUSR2 & go backwards by the frame increment \\ \hline
\end{longtable}

If you wish to have different masters controlling different groups of slaves, you need
to specify a groupID on the command line for each group. The default is \lit{0}. 

\textbf{NB}. Apple machines do not respond immediately when syncing is performed. The target windows will be updated 
when they gain focus, i.e., when the mouse is clicked within them.

\section{FlyBy's}
\label{sec:flyby}
FlyBy's are animated views of the model. They are defined as occurring between two different model states. As implemented in \meshal, the 
model is put into the start start and then the view is transformed in a sequence of steps,
using \emph{Slerp}, until it matches the view corresponding to the second state, at which point the second state is loaded.
FlyBy's are made with the dialogue \texttt{Options/Fly By}.

\begin{figure}[H]
       \centerline{ \includegraphics[width=5cm]{flyby.png}}
       \caption{FlyBy dialogue widget. The play and record buttons (bottom row of buttons)
       only activate when two or more states are in the list.}
\end{figure}

To make a FlyBy, at least two states need to be defined.
To define a state, adjust the model to get the desired view, data, lighting, etc. and then press the \texttt{+} button to add it to the list.
As many states as desired can be added.
States can be deleted from the list with the \lit{Delete} button and reordered with the Up/Down arrow buttons. 
To see a particular state, select it in the list, and press the load (circular arrow) button.
States can also be renamed to be more informative.

To view the FlyBy, press the play button. The time between frames is controlled by the \lit{delay} value in milliseconds.
If data is present, the \lit{adv time} button can be checked so that the time advances with every step.
To record the FlyBy, set the output base name and click on the record (red dot) button.
A series of PNG files will be produced with the base name and then the frame number (00000,00001, $\ldots$) appended.

Remember that the  \lit{\#steps} refers to the number of transitions to go from the selected state to the next one.

\section{Offscreen Rendering}
\label{sec:offscreen}
Output PNG files may be written noninteractively. To do so, the \texttt{PNGfile} option (\S\ref{sec:options}) must be specified. 
If one output frame is specified by setting \texttt{numframes} to 1, then \texttt{PNGfile}
is the output file name with \lit{.png} appended
automatically if it is not specified. For more than 1 frame, \texttt{PNGfile} is a directory name, which will be created if
necessary, and the output files will have the names \texttt{frameXXXXX.png} where XXXXX is the frame number padded on the
left with zeros, eg., frame 8 would be \lit{frame00008.png}. Directory names will have \lit{.png} stripped if detected on
the end. 
By default, the initial frame is not set, i.e., it will be that of a state file if one is read, or 0 if a state file is not
specified. 

The simplest way to use offscreen rendering is to interactively 
set up meshalyzer in a suitable state and then save it. The model,
data and state files are then specified normally on the command line
and the additional PNG related options added.
A simple example might be something like
\begin{verbatim}
meshalyzer --PNGfile=movie --numfr=10 --frame=5 myopurk.
        Vm.igb state.mshz
\end{verbatim}
which would produce 10 PNGs in the movie directory by putting the data in Vm.igb on the myopurk model and use the
settings in state.mshz. 

There are two version of \meshal for offscreen rendering. There are no differences in running the code but it is a
question of environment and speed.

\subsection{OSMesa}
OSMesa (http://www.mesa3d.org/osmesa.html) is an offscreen rendering library which performs all of its operations in
software. This has the advantage that it can be used even if a window server is not running. This library must be
available on the system. However, since it does not take advantage of the graphics hardware, rendering is considerably
slower but can be compensated for by specifying many processes (\texttt{--nprocs}).
This executable must be explicitly compiled by
\begin{verbatim}
make mesalyzer
\end{verbatim}
with the resultant executable called \texttt{mesalyzer}. It cannot be used to display a window on the screen. 
The executable still expects an available Xserver but does not actually use it. 
Thus, you need to forward X connections if 
remotely connecting using \texttt{ssh}.
If running remotely, you probably also need to set the following environment variable:
\begin{verbatim}
export LIBGL_ALWAYS_INDIRECT=y
\end{verbatim}
If you are running on a headless system
(or having display troubles), you can try running a virtual X server with the command \texttt{Xvfb}.
Below is an example with a bash shell.
\begin{verbatim}
Xvfb :1 &
export DISPLAY=:1
mesalyzer ....
\end{verbatim}

\subsection{GLUT rendering}
Under Linux, the GLUT library (http://www.opengl.org/resources/libraries/glut/) can be used to create an OpenGL context which then
allows offscreen rendering to use the graphics card. This is compiled into the default version of \meshal. It renders
very quickly but only if a windowing system is available. A small window with no content will be created that is a
byproduct of establishing a connection with the windowing system.
This is not needed on Macs.

\section{Known Issues}

\begin{enumerate}
    \item Under Linux, when a clipping plane is pasted, the plane will be properly pasted, 
        but then \meshal will act as if 
        clipping plane 1 was selected with a left mouse click.
    \item On Macs, linking updates are not performed until the target window is clicked.
    \item On Macs, when starting up with an auxiliary grid, the grid surface may not be
        properly illuminated. This is random and \meshal must be retried.
    \item With the update to version 2, mesalyzer no longer compiles. It never compiled on Macs.
\end{enumerate}

\end{document}