source: inundation/parallel/documentation/visualisation.tex @ 2920

\chapter{Visualisation}
The real-time visualisation component of the ANUGA system originally
used VPython (\url{http://www.vpython.org}). This implementation is being
superceded by a VTK-based (\url{http://www.vtk.org/}) visualiser which is
faster, capable of handling larger data sets and more configurable. At
the time of writing, the Domain class that uses the VTK visualiser
resides in ga/inundation/pyvolution/shallow\_water\_vtk.py. It has been
tested to work under Linux and Windows.

The visualiser class itself resides in
ga/inundation/pyvolution/vtk\_realtime\_visualiser.py.

Customisation options for the visualiser are members of the visualiser
class and their functions are as follows:
\begin{itemize}
\item setup: Dictionary mapping quantity name $\rightarrow$ boolean.
  if setup[q] is true, draw the quantity when the visualiser starts.
\item updating: Dictionary mapping quantity name $\rightarrow$
  boolean.  if updating[q] is true, update the rendering of this
  quantity each timestep.
\item qcolor: Dictionary mapping quantity name $\rightarrow$ (float,
  float, float). If the name of a quantity is found in qcolor, the
  colour specified (in (r, g, b) from 0.0 to 1.0) is used for display
  of that quantity instead of (0.5, 0.5, 0.5) (the default)
\item scale\_z: Dictionary mapping quantity name $\rightarrow$ float.
  Override the $z$ scaling of this quantity with the float specified.
\item default\_scale\_z: float. Multiply all $z$ coordinates by this
  amount unless an overriding value exists in scale\_z.
\end{itemize}
Screenshot:\\
\includegraphics{figures/vis-screenshot.eps}\\

Unlike the old VPython visualiser, the behaviour of the VTK
interaction classes completely tie up the thread that they are running
in. The solution was to use the TK interactor, and build a TKinter gui
around the render window.

Even using TK around the VTK interactor, this still ties up the thread
for TK's main loop. This was worked around by making the visualiser
use its own thread for rendering. This worked fine under Linux, but
under Windows the visualiser is `starved' by the CPU-bound thread that
contains the call to evolve(). To rectify this, the visualiser and the
main thread are explicitly synchronised: The visualiser waits on a
condition variable to signify that the evolve thread has finished
computation for its yieldstep. The visualiser then updates the VTK
data structures, while the evolving thread waits on another condition
variable for the visualiser to finish.  The visualiser then informs
the evolve thread that it is finished and returns to waiting. While
this does reduce the potential for concurrency, it still maintains an
acceptable level of interactivity.

Currently, the rendering method is only suitable for quantities for
which the concept of height makes sense (e.g. stage and elevation in the
Shallow Water domain). Adding support for alternate rendering methods
would be a welcome enhancement to this visualiser.