manual.tex 57.2 KB
Newer Older
1
\documentclass[12pt,onecolumn,a4paper]{article} % document style report
Edward Vigmond's avatar
Edward Vigmond committed
2 3 4 5 6 7 8 9

%\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}
Edward Vigmond's avatar
Edward Vigmond committed
10
\usepackage{longtable}
11
\usepackage{array}
12
\usepackage{float}
Edward Vigmond's avatar
Edward Vigmond committed
13
\usepackage{overcite}                                 % superscript notation of references
14
\usepackage{xcolor}                                 % superscript notation of references
15
\usepackage{multirow}
16
\usepackage[pdftex]{graphicx}                  % Grafikpaket für Bilder laden
17
\usepackage[colorlinks=true]{hyperref}                  % Für Referenzerstellung
Edward Vigmond's avatar
Edward Vigmond committed
18 19 20 21 22 23
\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}
Edward Vigmond's avatar
Edward Vigmond committed
24
\renewcommand{\floatpagefraction}{0.7}
Edward Vigmond's avatar
Edward Vigmond committed
25 26 27 28 29

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

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

Edward Vigmond's avatar
Edward Vigmond committed
33 34 35 36 37 38 39 40 41 42 43
\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} 
44
\\ \vspace{1cm} Manual Version 2.0
Edward Vigmond's avatar
Edward Vigmond committed
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
\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
Edward Vigmond's avatar
Edward Vigmond committed
60
thought too loudly when he was beside me in the office.
Edward Vigmond's avatar
Edward Vigmond committed
61

62 63 64 65 66
\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.
67
      \texttt{clang} works on Mac but \texttt{OpenMP} should be installed.
68
  \item[FLTK 1.3] This is the widget set responsible for all the windows. It is recommended to 
69 70
    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.
71
  \item[libpng] Needed for producing PNG format files.
72
  \item[GLUT] This is needed for offscreen rendering on a graphics card on non-Macs.
73 74
  \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.
75 76
  \item[OpenMP] This is recommended but needs to be installed on Macs.
  \item[OSMesa] Optional but required for offscreen rendering in software.
77 78
\end{description}

Edward Vigmond's avatar
Edward Vigmond committed
79 80
\section{Input Files}

Edward Vigmond's avatar
Edward Vigmond committed
81 82
\meshal assumes that there is a model, defined by a set of vertices,
which is to be displayed.
Edward Vigmond's avatar
Edward Vigmond committed
83 84
Beyond that, everything is optional.
The vertices may be connected to form structures, specifically
85
triangular elements, quadrilaterals, tetrahedra,hexahedra, prisms, 
Edward Vigmond's avatar
Edward Vigmond committed
86
or simple line segments.
Edward Vigmond's avatar
Edward Vigmond committed
87 88
Scalar data may be associated with every point on the grid and 
may be used to colour
Edward Vigmond's avatar
Edward Vigmond committed
89 90 91 92 93 94
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.
Edward Vigmond's avatar
Edward Vigmond committed
95
Regions are delimited by tagged volume elements (see \autoref{sec:voleles}),
Edward Vigmond's avatar
Edward Vigmond committed
96
or may be specified by
Edward Vigmond's avatar
Edward Vigmond committed
97
a range of vertices (see~\autoref{sec:regfile}),
Edward Vigmond's avatar
Edward Vigmond committed
98 99 100 101
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.
Edward Vigmond's avatar
Edward Vigmond committed
102 103
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 
Edward Vigmond's avatar
Edward Vigmond committed
104 105 106 107
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.
108
Surfaces are defined by surface element files (see \S\ref{sec:surffile}).
Edward Vigmond's avatar
Edward Vigmond committed
109 110 111 112 113 114 115 116
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}}
Edward Vigmond's avatar
Edward Vigmond committed
117
\caption{Relationship between vertices (Points) and other structures.}
Edward Vigmond's avatar
Edward Vigmond committed
118 119
\label{fig:UML}
\end{figure}
Edward Vigmond's avatar
Edward Vigmond committed
120

Edward Vigmond's avatar
Edward Vigmond committed
121
All files (except IGB described below) are ASCII files.
Edward Vigmond's avatar
Edward Vigmond committed
122
They may be \emph{gzipped} 
123
in which case \lit{.gz} should be appended to the extensions given below.
Edward Vigmond's avatar
Edward Vigmond committed
124 125 126 127 128 129
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.
130
It must have the extension \lit{.pts} with the following format:
Edward Vigmond's avatar
Edward Vigmond committed
131 132 133 134 135 136 137 138 139 140 141 142 143 144
\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}
145
\label{sec:cnnx}
Edward Vigmond's avatar
Edward Vigmond committed
146 147
Connections are line segments between vertices.
The file defining the connections
148
has the extension \lit{.cnnx} with the following format:
Edward Vigmond's avatar
Edward Vigmond committed
149 150 151 152 153 154 155 156 157
\begin{verbatim}
number_connections
vertex#1 vertex#2
vertex#1 vertex#2
.
.
.
vertex#1 vertex#2
\end{verbatim}
158 159 160 161 162 163
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,
164 165 166
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.
167
A line is an entity which can be highlighted.
168

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

\subsection{Cables}
\label{sec:cabs}
178
\textcolor{red}{The use of cable files is deprecated. }
179 180 181
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
182
has the extension \lit{.cables} with the following format:
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
\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.

199 200 201
\subsection{Surface Elements}

\label{sec:surffile}
202
These files have the suffix \lit{.surf} and
Edward Vigmond's avatar
Edward Vigmond committed
203
may define several surfaces in one file.
204
Any 2-dimensional element can be specified.
Edward Vigmond's avatar
Edward Vigmond committed
205
Labels are any sequence of characters not including white space.
206 207
The file has the following format:
\begin{verbatim}
Edward Vigmond's avatar
Edward Vigmond committed
208
number_elements_in_surface0 label_for_surface0 [label]
209 210 211 212 213 214
Tr vertex0 vertex1 vertex2 float
Qd vertex0 vertex1 vertex2 vertex3 float
.
.
.
Qd vertex0 vertex1 vertex2 vertex3 float
Edward Vigmond's avatar
Edward Vigmond committed
215
number_eleemnts_in_surface1 label_for_surface1 [label]
216 217 218 219 220
Tr vertex0 vertex1 vertex2 float
Tr vertex0 vertex1 vertex2 float
.
.
.
Edward Vigmond's avatar
Edward Vigmond committed
221
number_elements_in_surfaceN label_for_surfaceN [label]
222 223 224 225 226 227 228
Qd vertex0 vertex1 vertex2 vertex3 float
Tr vertex0 vertex1 vertex2 float
.
.
.
Tr vertex0 vertex1 vertex2 float
\end{verbatim}
Edward Vigmond's avatar
Edward Vigmond committed
229
where label is string without spaces which will be used to identify the surface in the list of surfaces.
230 231

\subsubsection{Triangles}
Edward Vigmond's avatar
Edward Vigmond committed
232
\label{sec:tris}
233
\textcolor{red}{Triangle files are deprecated. }
234
They are defined in a file with the extension \lit{.tris} or \lit{.tri}
Edward Vigmond's avatar
Edward Vigmond committed
235 236
which has the following format:
\begin{verbatim}
237
number_triangles_in_surface0 label_for_surface0
Edward Vigmond's avatar
Edward Vigmond committed
238 239 240 241 242 243
vertex0 vertex1 vertex2 float
vertex0 vertex1 vertex2 float
.
.
.
vertex0 vertex1 vertex2 float
244
number_triangles_in_surface1 label_for_surface1
Edward Vigmond's avatar
Edward Vigmond committed
245 246 247 248 249
vertex0 vertex1 vertex2 float
vertex0 vertex1 vertex2 float
.
.
.
250
number_triangles_in_surfaceN label_for_surfaceN
Edward Vigmond's avatar
Edward Vigmond committed
251 252 253 254 255 256 257 258 259 260 261 262
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}
Edward Vigmond's avatar
Edward Vigmond committed
263
\label{sec:voleles}
Edward Vigmond's avatar
Edward Vigmond committed
264
There are two formats for defining volume elements, either the deprecated
Edward Vigmond's avatar
Edward Vigmond committed
265 266 267 268
tetrahedral file or the newer general element file. Details follow.

\subsubsection{Mixed element files}
\label{sec:elem}
269
Volume elements are specified by files with the \lit{.elem} extension.
Edward Vigmond's avatar
Edward Vigmond committed
270 271 272 273 274 275 276 277
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]
278
Tr n1 n2 n3 [region [region_label]]
279
Ln n1 n2 [region]
Edward Vigmond's avatar
Edward Vigmond committed
280
Qd n1 n2 n3 n4 [region [region_label]]
281
Ln n1 n2 [region]
Edward Vigmond's avatar
Edward Vigmond committed
282 283 284 285
.
.
.
\end{verbatim}
286
where \texttt{Hx, Py, Pr, Tt, Tr, Qd, Ln}
Edward Vigmond's avatar
Edward Vigmond committed
287
stand for Hexahedron, Pyramid, Prism,
288 289 290 291
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
292
once in the file per region.
Edward Vigmond's avatar
Edward Vigmond committed
293 294
\begin{figure}
\centerline{\includegraphics[width=10cm]{volelemdef}}
Edward Vigmond's avatar
 
Edward Vigmond committed
295
\caption{Volume elements\label{fg:voleledef}}
Edward Vigmond's avatar
Edward Vigmond committed
296 297 298 299
\end{figure}

\subsubsection{Tetrahedra}
\label{sec:tets}
300
Tetrahedra are defined in a file with a \lit{.tetras} extension and the following
Edward Vigmond's avatar
Edward Vigmond committed
301 302 303 304 305 306 307 308 309 310 311 312 313 314 315
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}
Edward Vigmond's avatar
Edward Vigmond committed
316
\label{sec:regfile}
317
Regions may be explicitly specified in a separate file with the extention 
318
\lit{.region}
Edward Vigmond's avatar
Edward Vigmond committed
319 320 321 322 323 324 325 326 327 328 329
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}

330 331 332 333
\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.
Edward Vigmond's avatar
Edward Vigmond committed
334

335
\subsubsection{ASCII format}
336
A data file typically has the extension \lit{.dat} or \lit{.out} but these extensions
Edward Vigmond's avatar
Edward Vigmond committed
337 338
are suggested and not required.
The file simply contains lines with one entry per line, the data value for the
339 340 341 342 343
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.
Edward Vigmond's avatar
Edward Vigmond committed
344 345

\subsubsection{IGB format}
Edward Vigmond's avatar
Edward Vigmond committed
346
\label{sec:IGB}
Edward Vigmond's avatar
Edward Vigmond committed
347 348 349 350
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.
351
For irregular grids, the individual dimensions are meaningless but xdim$\times$ ydim$\times$ zdim should be equal to the number of vertices/elements.
Edward Vigmond's avatar
Edward Vigmond committed
352 353
The header is composed of strings of the format below, separated by
white space.
Edward Vigmond's avatar
Edward Vigmond committed
354 355 356 357 358 359 360 361 362 363 364 365 366
\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,
367 368
	                   float, double, int, uint, vec3f, vec4f,
					   vec3d, vec4d\\ \hline
Edward Vigmond's avatar
Edward Vigmond committed
369
	unites  & string & units of data \\
Edward Vigmond's avatar
Edward Vigmond committed
370
	facteur & float & scaling factor for data \\
Edward Vigmond's avatar
Edward Vigmond committed
371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392
	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}
Edward Vigmond's avatar
Edward Vigmond committed
393 394
Note that for unstructured grids, $x$, $y$ and $z$ specific values 
are meaningless.
Edward Vigmond's avatar
Edward Vigmond committed
395 396

\subsection{Vector Data}
Edward Vigmond's avatar
Edward Vigmond committed
397
To display vector data, an auxiliary set of points must be 
398
defined by a file with the \lit{.vpts} suffix.
Edward Vigmond's avatar
Edward Vigmond committed
399
It follows the same format as the vertex file.
400
A file with the same base name but having the extension \lit{.vec} defines the 
Edward Vigmond's avatar
Edward Vigmond committed
401 402 403 404 405 406 407 408 409 410 411
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.

412 413 414 415 416 417
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
418
scalar component as above. This file has the suffix \lit{.vec.igb}.
419

420 421 422
\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
423
(vertex,line segments,surface elements,volume elements), and the
424 425 426
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.
427
The points file may have only one time instance, which is then assumed constant over all time.
428

429
A vertex file is mandatory and has the extension \lit{.pts\_t}.
Edward Vigmond's avatar
Edward Vigmond committed
430
An element file is optional. If present, it has the same base name as the
431
vertex file but with the extension \lit{.elem\_t}.
432
Scalar data may also be optionally defined on the auxiliary grid. The file
433
has the same \texttt{basename} as the vertex file but with the extension
434
\lit{.dat\_t}.
435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462
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}

463 464 465 466 467 468 469
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.

Edward Vigmond's avatar
Edward Vigmond committed
470 471 472 473 474 475 476
\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
477
\texttt{vec3f}. The extension for the file in this case is \lit{.dynpt}.
478

Edward Vigmond's avatar
Edward Vigmond committed
479 480 481
\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
482
described. The HDF5 file should have the suffix \lit{.datH5} and may contain multiple
Edward Vigmond's avatar
Edward Vigmond committed
483 484
datasets of differing types.

Edward Vigmond's avatar
Edward Vigmond committed
485 486 487
\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.
Edward Vigmond's avatar
Edward Vigmond committed
488
This format is kept for historical reasons and its use is deprecated.
Edward Vigmond's avatar
Edward Vigmond committed
489 490 491 492 493 494 495 496 497 498 499 500
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}
501
This file must have the suffix \lit{.cg\_in} and adheres to
Edward Vigmond's avatar
Edward Vigmond committed
502 503 504 505 506 507 508 509 510 511 512 513
the following format:
\begin{verbatim}
number_surface_files
0
surface_file_1
surface_file_2
.
.
.
surface_file_n
\end{verbatim}
where \texttt{surface\_files}
Edward Vigmond's avatar
 
Edward Vigmond committed
514
are triangle files (see section~\ref{sec:tris}) for
515
format) with the \lit{.tri} extension. 
Edward Vigmond's avatar
Edward Vigmond committed
516 517 518 519
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}
520
Data is given in a set of ASCII files with the extensions \lit{.t\#} where
Edward Vigmond's avatar
Edward Vigmond committed
521 522 523 524 525 526 527 528 529 530 531 532 533 534 535
\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.

536 537 538 539 540 541 542 543 544 545 546
\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.

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

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

Edward Vigmond's avatar
Edward Vigmond committed
567 568
\subsection{Options}

569
\label{sec:options}
Edward Vigmond's avatar
Edward Vigmond committed
570
\begin{description}
571 572 573 574
    \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
Edward Vigmond's avatar
Edward Vigmond committed
575
        not being able to put data on the cutting planes.
576
    \item[--thrdRdr] Force threaded data reading. Even if one has enough memory to read in all the data at
Edward Vigmond's avatar
Edward Vigmond committed
577
        once, it is probably just as fast to read it in on demand. Using this option will reduce start up time
578
        and stop \meshal from using all the RAM.
579 580 581 582
    \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)
583 584
    \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. 
585
        To not write a file, specify \lit{file} as \lit{/dev/null}.
Edward Vigmond's avatar
Edward Vigmond committed
586
\end{description}
Edward Vigmond's avatar
Edward Vigmond committed
587

588 589 590
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.

591 592 593 594 595 596 597 598 599 600
\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}

601 602 603 604 605 606 607 608
\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}

Edward Vigmond's avatar
Edward Vigmond committed
609
\section{Graphical User Interface}
Edward Vigmond's avatar
Edward Vigmond committed
610 611

\begin{figure}[htbp]
612
\centerline{\includegraphics[width=6cm]{controls}}
Edward Vigmond's avatar
Edward Vigmond committed
613 614 615
\caption{The control widget.}
\end{figure}

Edward Vigmond's avatar
Edward Vigmond committed
616
\subsection{Volume Mesh}
617
To display the volume element mesh, click on the  \lit{Voxele Mesh} 
Edward Vigmond's avatar
Edward Vigmond committed
618 619
radio button in the
\emph{Display as:} box.
620
The colour of the volume elements can be changed with the \lit{Voxele colour}
Edward Vigmond's avatar
Edward Vigmond committed
621
button.
Edward Vigmond's avatar
Edward Vigmond committed
622 623 624
No other structure types will be displayed.

\subsection{Regions}
Edward Vigmond's avatar
Edward Vigmond committed
625
To not display the mesh as a set of volume elements,
626
click on the  \lit{Surfaces} 
Edward Vigmond's avatar
Edward Vigmond committed
627
radio button in the
628
\lit{Display as:} box.
Edward Vigmond's avatar
Edward Vigmond committed
629
This will display all structures except volume elements.
Edward Vigmond's avatar
Edward Vigmond committed
630 631 632 633

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
Edward Vigmond's avatar
Edward Vigmond committed
634
by highlighting them in the list.
Edward Vigmond's avatar
Edward Vigmond committed
635 636 637 638 639 640 641
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.
642
The order can be reversed by checking \lit{Reverse Draw order} under the \lit{Image}
Edward Vigmond's avatar
Edward Vigmond committed
643 644
menu.

Edward Vigmond's avatar
Edward Vigmond committed
645
For each structure, there is a button toggling its display, 
Edward Vigmond's avatar
Edward Vigmond committed
646
and a button to select its display properties.
647
Pressing the \lit{props} button will open a widget to specify 
Edward Vigmond's avatar
Edward Vigmond committed
648 649
colour when it is not displaying data, to specify the output stride, size 
and if a 3D effect is to be used. 
Edward Vigmond's avatar
Edward Vigmond committed
650
\textbf{Note that the 3D effect is memory intensive and may cause a segmenation violation
651
for a large number of objects}.
Edward Vigmond's avatar
Edward Vigmond committed
652 653

Different structures in different layers can be coloured differently.
654
Under \lit{Image/Randomly colour}, one can select which structure types gets randomly
Edward Vigmond's avatar
Edward Vigmond committed
655
coloured based on the region to which it belongs.
656
\lit{Image/Background colour} changes the colour of the background.
Edward Vigmond's avatar
Edward Vigmond committed
657 658 659 660 661 662 663 664

\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.
vigmond's avatar
vigmond committed
665 666 667
The highlighted structure can be chosen by typing its number.
Values can also by dragging the mouse. 
See the FLTK manual for
Edward Vigmond's avatar
Edward Vigmond committed
668 669 670
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.
671 672
The mouse wheel can also be used with SHIFT and CTRL increasing the stride as well.
Hold both for a factor of 1000.
Edward Vigmond's avatar
Edward Vigmond committed
673 674
Volume elements can be selected to be drawn as a wireframe (\texttt{Vol Ele})
or a solid faced object (\texttt{Solid Vol Ele}).
675
Clicking on the \lit{current reg/surf} button highlights the first
Edward Vigmond's avatar
Edward Vigmond committed
676 677 678
structure of each
type for the currently selected shell (0 if \emph{All} is chosen).

Edward Vigmond's avatar
Edward Vigmond committed
679
\label{para:pickvertex}
Edward Vigmond's avatar
Edward Vigmond committed
680
The highlighted vertex can also be selected with the mouse.
681
Clicking on the \lit{Pick Vertex} button will enter vertex picking mode
Edward Vigmond's avatar
Edward Vigmond committed
682 683
with the button turning red to indicate this.
A vertex can then be selected by clicking on it.
684
If you are having trouble making a selection, display vertices, zoom in and click on a vertex center.
685
The clicking area for a vertex is that of a vertex drawn with a size of 10 (non-3D).
686
Three attempts are allowed to click on a vertex before picking mode is turned off.
687
Note that the highlighted node can be changed by using the mouse wheel (as explained above).
688
For the highlighted vertex, its associated scalar data value
Edward Vigmond's avatar
Edward Vigmond committed
689
is displayed in the gold widget.
Edward Vigmond's avatar
Edward Vigmond committed
690
You can choose to display the surface elements that the vertex is part of, or
Edward Vigmond's avatar
Edward Vigmond committed
691
the volume elements that it is part of.
Edward Vigmond's avatar
Edward Vigmond committed
692
The elements can be drawn as wireframe or with filled sides.
693 694
For detailed information about the highlighted objects, click on the \lit{?} button.
See the \texttt{Information Window} (\autoref{sec:infowin}).
Edward Vigmond's avatar
Edward Vigmond committed
695 696

\subsubsection{Time Plot}
697
\label{sec:timeplot}
698
The time series of the highlighted vertex can be displayed by clicking the 
699
\lit{plot time series} button.
Edward Vigmond's avatar
Edward Vigmond committed
700
The current time is indicated by a vertical green line.
701
A trace can be saved by clicking on the \lit{Hold} button.
Edward Vigmond's avatar
Edward Vigmond committed
702 703
Up to 8 traces can be saved this way.
To clear the held traces, click on mouse button 3 and select 
704
\lit{clear static curves.}
Edward Vigmond's avatar
Edward Vigmond committed
705
The plotted traces can be saved in ASCII format by clicking
706
the \lit{Save} button.
Edward Vigmond's avatar
Edward Vigmond committed
707 708
Normally, when a new point is clicked, the x and y range are recalculated
and the scale adjusted accordingly.
709
To prevent this behaviour, deselect the \lit{Autoscale} button.
Edward Vigmond's avatar
Edward Vigmond committed
710 711
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.
712
Clicking on mouse button 3 will pop up a menu which includes \lit{reset view} 
Edward Vigmond's avatar
Edward Vigmond committed
713 714 715 716 717 718 719 720
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}
721 722 723 724
\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.
Edward Vigmond's avatar
Edward Vigmond committed
725
For each structure, the defining nodes are listed.
726 727 728 729 730 731
\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. 

Edward Vigmond's avatar
Edward Vigmond committed
732 733

\subsubsection{Lighting}
Edward Vigmond's avatar
Edward Vigmond committed
734
\label{sec:lighting}
735
Lighting is controlled in the light tab (\autoref{fig:lightDiag}).
Edward Vigmond's avatar
Edward Vigmond committed
736 737
The light is directional with its direction, $\hat{L}$, controlled by the orienter.
Clicking and dragging the mouse in the orienter changes $\hat{L}$.
738 739
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.
740
The direction of the light is graphically illustrated by the red arrow.
741 742
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.
Edward Vigmond's avatar
Edward Vigmond committed
743 744 745 746 747
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
Edward Vigmond's avatar
Edward Vigmond committed
748
    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
Edward Vigmond's avatar
Edward Vigmond committed
749
    Spec & Like diffusive, but with an exponent,  $\propto (\hat{L}\cdot\hat{n})^N$, and the reflected light is white,
Edward Vigmond's avatar
Edward Vigmond committed
750 751
            not the colour of the object. \\ \hline
    Shiny & The exponent $N$ for specular light. Setting it higher keeps the reflection smaller. \\
Edward Vigmond's avatar
Edward Vigmond committed
752 753
           \hline\hline
\end{tabular}}
754
With \lit{facet shading} enabled, Gouraud shading is turned off and lines
Edward Vigmond's avatar
Edward Vigmond committed
755
are not antialiased. This may speed up rendering on slow platforms.
756
Note that surface material properties may also be set, which depend on lighting. See  \S\ref{sec:surface}.
Edward Vigmond's avatar
Edward Vigmond committed
757

758
\lit{Backface} controls lighting of back facing polygons, as defined by the sense of the point order:
Edward Vigmond's avatar
Edward Vigmond committed
759 760 761 762 763 764 765 766
\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}
767 768 769 770 771 772
\begin{figure}[htb]
\centerline{\includegraphics[width=10cm]{light}}
 \caption{Lighting tab.}
    \label{fig:lightDiag}
\end{figure}

773 774 775 776 777 778 779 780 781 782 783
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}
Edward Vigmond's avatar
Edward Vigmond committed
784 785 786

\subsubsection{Scalar Data}

787
\label{sec:scalardata}
788
Scalar data is read under the \lit{File} menu in the top bar.
Edward Vigmond's avatar
Edward Vigmond committed
789 790 791 792
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.
793
\lit{\#frames} selects how many frames to increment at a time.
Edward Vigmond's avatar
Edward Vigmond committed
794 795 796

If data is present, each vertex has associated scalar data which is linearly
mapped to a colour.
797
Clicking \lit{optimal} maps the currently displayed minimum data value to 
Edward Vigmond's avatar
Edward Vigmond committed
798 799
level 0 and the currently displayed 
maximum data value to the maximum colour level.
800 801
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
Edward Vigmond's avatar
Edward Vigmond committed
802
time changes.
803
It is equivalent to pressing \lit{optimal} every time that time is changed.
Edward Vigmond's avatar
Edward Vigmond committed
804 805
The values corresponding to the minimum and maximum colour values are 
available for editing.
806 807 808
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.
Edward Vigmond's avatar
Edward Vigmond committed
809 810

Different structures may be coloured according to the data.
811
The \lit{Data on:} choice widget selects which structure types are coloured according
Edward Vigmond's avatar
Edward Vigmond committed
812 813 814 815
to the data values associated with the vertices defining the structures.

\subsubsection{Vector Data}

816 817
Vector data is specified on the command line or by selecting \lit{Read Vector Data}
under the \lit{File} menu item.
Edward Vigmond's avatar
Edward Vigmond committed
818 819 820 821 822
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.
823
The constant value is selected by the \lit{colour} button.
Edward Vigmond's avatar
Edward Vigmond committed
824 825
Magnitude and scalar data are mapped to a selectable colour map as with
vertex scalar data.
Edward Vigmond's avatar
Edward Vigmond committed
826 827
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,
828
checking the \lit{stochastic} button will add a random perturbation to the stride so that the model is
Edward Vigmond's avatar
Edward Vigmond committed
829
irregularly sampled but on average, at the specified stride.
830
The initial starting point for the stride, \lit{start}, can also be set.
vigmond's avatar
vigmond committed
831 832 833
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.
Edward Vigmond's avatar
Edward Vigmond committed
834

835 836 837
\subsubsection{Auxiliary Grid}

Auxiliary grids are specified on the command line or by selecting
838 839
\lit{Read Aux Grid} under the \lit{File} menu.
The \lit{Display} button toggles drawing of the grid.
840 841 842 843
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.
844
Components are grouped into point, line, surface and volume elements.
845
Each group of grid components can be coloured with a fixed colour chosen
846
with the \lit{color} button.
847
If scalar data is present, the components can be coloured according to the
848
associated data value, that is, \lit{datafied}.
849 850 851 852 853
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.

854 855 856 857 858
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
859
clicking on the \lit{Plot} button.
860 861
See \S\ref{sec:timeplot} for a description of the widget.

Edward Vigmond's avatar
Edward Vigmond committed
862 863
\subsubsection{HDF5 data}

864
A file with the suffix \lit{.datH5} can be read in. This file may contain many data
Edward Vigmond's avatar
Edward Vigmond committed
865 866 867
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.

Edward Vigmond's avatar
Edward Vigmond committed
868 869
\subsubsection{Surfaces}

870
\label{sec:surface}
Edward Vigmond's avatar
Edward Vigmond committed
871
Only surfaces checked in the list are affected by any changes effected.
Edward Vigmond's avatar
Edward Vigmond committed
872
The fill colour of the elements composing surfaces can be selected as well
Edward Vigmond's avatar
Edward Vigmond committed
873 874
as the independent outline colour. 
Outlining and filling the elements can also be controlled. 
875 876
The opacity value selected under the surface colour applies when data is present as well.
Lighting properties can also be set for individual surfaces.
877 878
\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.
879
\lit{back light} controls intensity of backward facing polygons when backlighting is ``lit'' (\autoref{sec:lighting})
Edward Vigmond's avatar
Edward Vigmond committed
880
Surfaces can also be randomly coloured by Image/Randomly Color/Surfaces.
881
Surfaces are renamed with the \lit{Rename} button. You will be prompted if you
vigmond's avatar
vigmond committed
882
want to overwrite the surface file with the new label.
883 884
The normals of a surface can also be flipped by selecting \lit{flip/normals}.

Edward Vigmond's avatar
Edward Vigmond committed
885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909

\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.

vigmond's avatar
vigmond committed
910 911
\subsubsection{No rotation}

912
The trackball no longer performs rotations, only translation and scaling. This is automatically set for 1D and
vigmond's avatar
vigmond committed
913 914
2D data.

Edward Vigmond's avatar
Edward Vigmond committed
915 916 917 918
\subsection{Sync}
Syncing transfers setting to different running instances of meshalyzer.
See \S\ref{sec:link} for details.

Edward Vigmond's avatar
Edward Vigmond committed
919 920 921 922 923
\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.
924 925
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}.
Edward Vigmond's avatar
Edward Vigmond committed
926 927 928 929 930 931 932 933 934 935 936 937
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}

938
By selecting \lit{Clipping} from the \lit{Data} menu item,
939
the clipping widget is popped open (\autoref{fig:clipdiag}).
Edward Vigmond's avatar
Edward Vigmond committed
940 941 942 943
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.
944
To flip the normal to point in the opposite direction, click on \lit{Flip}.
945
You can enter values manually, after which you should  \lit{Unitize} so that
Edward Vigmond's avatar
Edward Vigmond committed
946 947 948 949 950 951 952 953 954 955 956
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
957 958
		 intersects the object, and if data is present,
		 will have data interpolated on to it.
Edward Vigmond's avatar
Edward Vigmond committed
959
 \end{description}
Edward Vigmond's avatar
Edward Vigmond committed
960
\begin{figure}[htbp]
Edward Vigmond's avatar
Edward Vigmond committed
961 962
\centerline{\includegraphics[width=12cm]{clip}}
\caption{Clipping plane dialogue.}
963
    \label{fig:clipdiag}
Edward Vigmond's avatar
Edward Vigmond committed
964
\end{figure}
Edward Vigmond's avatar
Edward Vigmond committed
965
At the bottom of the widget is a graphical interface for reorienting the clipping plane. 
966
It reflects the orientation of the \emph{selected} clipping plane, the one displayed in yellow.
967 968 969
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.

970 971 972 973
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.
974
The opacity may also be selected, but this applies to all clipping planes, datified or not.
975
For colour or opacity to take effect, the \lit{Apply} button must be pushed.
Edward Vigmond's avatar
Edward Vigmond committed
976

Edward Vigmond's avatar
Edward Vigmond committed
977
\subsubsection{IsoSurfaces/IsoLines}
978
\label{sec:iso}
979
By selecting \lit{Isosurf} from the \lit{Data} menu item,
Edward Vigmond's avatar
Edward Vigmond committed
980 981 982 983
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.
984
Changes to the \lit{value} are reflected when enter is pressed or the focus
Edward Vigmond's avatar
Edward Vigmond committed
985 986 987 988
changes.

For isolines, surfaces must be defined. An initial isovalue, ending
isovalue and the number of isovalue lines are specified.
989
The \texttt{increment} box is an output showing the difference between successive isovalues.
990 991
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.
992
If \lit{datified} is selected, the lines are coloured according to 
Edward Vigmond's avatar
Edward Vigmond committed
993
the data colour scale, otherwise all lines are drawn with the same
994
specified \lit{colour}.
995 996 997 998 999 1000
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
1001
linking more connections to form fewer and longer lines, but portions of lines may disappear under convex surfaces.
Edward Vigmond's avatar
Edward Vigmond committed
1002

1003 1004 1005 1006
\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
1007
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
1008 1009
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.
1010
The \lit{Apply} button must be pressed to enact the changes. \lit{Recalibrate} scales the colour scale for the nondead range.
1011 1012

\subsubsection{Branch cut}
Edward Vigmond's avatar
Edward Vigmond committed
1013 1014 1015 1016 1017 1018 1019 1020

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.
1021
Choosing the appropriate branch cut range will ignore interpolation within such elements,
1022
especially when calculating isolines and surfaces (\autoref{sec:iso}).
Edward Vigmond's avatar
Edward Vigmond committed
1023
Four common ranges are available.
1024 1025
It is suggested that an appropriate colour scale is used which wraps around, 
i.e., has the same value at the two extremes.
Edward Vigmond's avatar
Edward Vigmond committed
1026

Edward Vigmond's avatar
Edward Vigmond committed
1027 1028 1029
\subsection{Output Menu}

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

1039 1040 1041 1042
\subsubsection{Colour Bar}

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

Edward Vigmond's avatar
Edward Vigmond committed
1043 1044
\subsubsection{Animation Sequences}
For animation data, one can save a sequence of images in PNG format under the 
1045
\lit{Output} menu.
Edward Vigmond's avatar
Edward Vigmond committed
1046 1047 1048 1049 1050 1051 1052 1053 1054 1055
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.
1056 1057
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.
Edward Vigmond's avatar
Edward Vigmond committed
1058 1059
As above, you will be prompted for a base file name which will have frame numbers
appended to it.
1060
A blue \lit{Redraw} label will also appear on the main menu bar.
Edward Vigmond's avatar
Edward Vigmond committed
1061
Use this to force the output of the image, even if nothing has changed.
1062
Manipulate the model any way you wish and when finished, select \lit{stop}.
Edward Vigmond's avatar
Edward Vigmond committed
1063 1064 1065 1066 1067 1068
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
1069
\lit{Output/Visible vertices}.
Edward Vigmond's avatar
Edward Vigmond committed
1070
You will be prompted for a filename and a file with the following format
Edward Vigmond's avatar
Edward Vigmond committed
1071 1072
will be produced:
\begin{verbatim}
1073
number_clip_planes_on
Edward Vigmond's avatar
Edward Vigmond committed
1074 1075 1076 1077 1078 1079
a1 b1 c1 d1
a2 b2 c2 d2
.
.
.
an bn cn dn
1080
number_visible_vertices
Edward Vigmond's avatar
Edward Vigmond committed
1081 1082 1083 1084 1085 1086 1087 1088
visible_node1
visible_node2
.
.
.
visible_nodeN
\end{verbatim}
The coefficients (a,b,c,d) 
1089
for the clipping plane are defined in the specified model coordinate system.
Edward Vigmond's avatar
Edward Vigmond committed
1090 1091 1092

\subsection{Saving The Current View}

1093
The current view can be saved by clicking on \lit{Save transform} under the \lit{File} menu.
Edward Vigmond's avatar
Edward Vigmond committed
1094 1095
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
1096
the extension \lit{.xfrm}.
1097
Once saved, it can be restored later by choosing \lit{Read transform} and selecting the file.
Edward Vigmond's avatar
Edward Vigmond committed
1098

1099
Standard views are available under the \lit{Image} menu under \lit{View}.
Edward Vigmond's avatar
Edward Vigmond committed
1100 1101 1102
The normal which points directly out of (+) or into (-) the screen is
first selected and then the positive direction of the other axes.

Edward Vigmond's avatar
Edward Vigmond committed
1103
\subsection{Saving/Restoring the State}
1104
\label{sec:statef}
Edward Vigmond's avatar
Edward Vigmond committed
1105 1106

The state is everything including the view transform. 
1107
You can save the state under \lit{Save state} in the \lit{File} menu.
1108
You will be prompted for a file which will have the extension \lit{.mshz}.
Edward Vigmond's avatar
Edward Vigmond committed
1109
This file is text and can be edited by hand afterwards. 
1110 1111 1112 1113
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.