4. VTK FlowVR

4.1 Introduction

VTK FlowVR enables to:

• use FlowVR Render as the renderer for VTK applications (require minimal modifications of the original VTK application). It enables for instance to render VTK applications on a multi-projector environment. See the Publication "Shader-Based Parallel Rendering Framework" for the benefits of using such approach.
• use FlowVR for encapsulating VTK computations into FlowVR modules (still beta). It enables to use FlowVR for parallelizing VTK computations or for a distributed coupling of VTK with other applications.

4.2 Getting Started

4.2.1 Dependencies

To compile and run VTK FlowVR, the following tools should be properly installed:

• FlowVR and FlowVRrender (part of the FlowVR Suite)
• VTK 4.4 or higher (binaries available for some distributions). The examples provided are TCL based. So your VTK installation should at least support TCL binding.

4.2.2 Download, Compilation, Installation and Environment Variables

VTK FlowVR is part of the FlowVR Suite. So download FlowVR Suite, compile and install it: see the FlowVR Suite documentation.

4.2.3 Testing

To launch the test example:

bin/vtk-flowvr-demo.sh

4.2.4 Sample Datasets

Beside the test demo, VTK FlowVR comes with various examples (installed into share/vtk-flowvr/Examples/Tcl). Before to run these examples you need extra datasets not included into the FlowVR Suite package.

4.2.4.1 Prepare

Some datasets need to be installed in one particular directory: It is case for the 3D Fluid, XMasTree LO and Chapel Hill CT Head datasets. Use the VTK_FLOWVR_DATA_ROOT environment variable to give access to this directory. For instance put in your .bashrc:

export VTK_FLOWVR_DATA_ROOT=/where/is/the/directory

The same goes for the VTKData package: set the VTK_DATA_ROOT environment variable so it points to the directory containing the data. For instance put in your .bashrc:

export VTK_DATA_ROOT=/where/is/the/directory

See next section about where to find datasets.

4.2.4.2 Download

• TheVTKData package available at VTK software download page. Untar and set the VTK_DATA_ROOT environment variable to point to the directory containing this dataset. VTKData may be available for your distribution. For instance Debian has a package called vtkdata which can be installed by apt. Don't forget to set VTK_DATA_ROOT.

• The 3D Fluid dataset, available at http://flowvr.sourceforge.net/FlowVRDownload.php. Unpack and set the VTK_FLOWVR_DATA_ROOT directory to point to the directory containing this dataset.

Extra volume rendering examples are based on datasets gathered by Roettger (http://www9.cs.fau.de/Persons/Roettger/library/):

• The XMasTree,
• Chapel Hill CT Head

You can use the Datasets/generate.sh script (only available in the source code) to download and install these datasets or you can just follow the steps bellow:

• Download these datasets and install them into the VTK_FLOWVR_DATA_ROOT directory.
• Install the library required to extract the raw data:
  • Download VIEWER-2.2.zip or a more recent version if available into VTK_FLOWVR_DATA_ROOT
  • Unzip and compile:
    unzip VIEWER-2.2.zip cd viewer ./build.sh
• Extract the raw data for each data set:
  cd $VTK_FLOWVR_DATA_ROOT ./viewer/tools/pvm2pvm CT-Head.pvm CT-Head-8.pvm ./viewer/tools/pvm2raw CT-Head-8.pvm CT-Head-8.pvm.raw ./viewer/tools/pvm2pvm XMasTree-LO.pvm XMasTree-LO-8.pvm ./viewer/tools/pvm2raw XMasTree-LO-8.pvm XMasTree-LO-8.pvm.raw

4.3 User Manual

4.3.1 Overview

We only describe how to render a VTK application using FlowVR Render. The other approaches are still very experimental.

4.3.2 VTK Viewer

We present in the following how to turn a VTK application into a FlowVR Render viewer module. We rely on a TCL example. Support for C++ is also provided (apply the same changes as the one proposed for TCL).

4.3.2.1 Limitations

The current VTK FlowVR version is an early release. It imposes a number of limitations on the VTK applications that can use VTK FlowVR for rendering:

• do not use vtkWindowRenderInteractor
• do not use any class related to rendering that does not render through vtkPolyDataMapper.

These limitations will be suppressed in future releases.

4.3.2.2 Context

The chosen example is based on theVTK quadric example. The goal is to visualize the following complicated equation for a quadric:

The value of this function is calculated over a regular 3D array of points (i.e., a volume or structured point dataset), and then an iso-contour of the quadric , where is a constant (i.e. the contour value), is computed and assigned a color for the rendering.

To render this VTK application using FlowVR Render is a 3 step process:

• Turn the code of the VTK application into a FlowVR Renderviewer
• Connect this viewer to a FlowVR Render renderer
• Compile and launch the application.

These steps are detailed in the following.

4.3.2.3 Code Modifications

Based on the VTK quadric sample, we show the necessary modifications required to turn a standard VTK program into a FlowVR Render viewer.

• We first need to enable FlowVR and FlowVR Render to be used in the script. To do so just add a package require statement the beginning:
  package require vtkflowvrrender
  Achieving the same thing with c++ is done by:
  #include "FlowVRRender/vtkFlowVRRenderFactory.h" /* add at the beginning of your main function */ vtkFlowVRRenderFactory *vfrf = vtkFlowVRRenderFactory::New(); vfrf->Register ();

• To be used as a FlowVR Render viewer, the application must be first declared as a FlowVR module^4.1.
  vtkFlowVRModule module

• Due to the current limitations vtkRenderWindowInteractor is replaced by:
  module Initialize module Start renWin # rendering loop
  Beware the order is important. The module Initialize sequence is used to end the FlowVR module registration.

See VTK documentation for more information about this example.

4.3.2.4 .desc File

As required by FlowVR, each module must be associated with a .desc file (metamodule description file). Because all VTK viewers only differ by their script name, we provide a generic .desc file

The script is defined by the template <template id=''script''>/path/to/script/</template> to be instantiated in the .mml file with the correct name. If a relative path is given, note that it is relative to the desc file location.

4.3.3 FlowVR Network

Following the FlowVR programming model, to set up an application we need to build a network. For that purpose we need:

• a .mml file listing the modules to launch,
• a perl script defining the way modules are connected.

In the following we detail how to set up an application launching one VTK viewer and one FlowVR Render renderer on the same machine. Starting from this configuration a user can build complex networks, for rendering on multiple displays for instance.

4.3.3.1 .mml File

The .mml file for the quadric example defines:

• a renderer moduleFlowVR Render manual
• a viewer module for the quadric tcl program using the generic .desc file share/vtk-flowvr/modules/desc/vtk.desc.xml with the template <template id=''script''> correctly instantiated.

4.3.3.2 Perl Script

Use the standard src/perl/render-swaplock.plï¿12and src/perl/render-fifo.pl perl scripts for connecting viewers and renderers that is provided with FlowVR Render.

This is simply done by setting the PERL variable in the Makefile of the application to:

PERL= render-swaplock.pl | render-fifo.pl.

The resulting makefile for the quadric example is share/vtk-flowvr/Examples/Tcl/quadric/Makefile.

4.3.3.3 The Resulting Application

The resulting application consists in a viewer (the VTK module) and a renderer (the Visu/render/0 module and its associated module for swaplock Visu/Swaplock/0.

Figure: The network of the vtk quadric example using FlowVR Render for rendering.

4.3.4 Compiling and Running the Application

From the share/vtk-flowvr/Examples/Tcl/quadric/ directory, compile the application with:

make

To launch the application (after starting a flowvr daemon - flowvrd):

make run

FlowVR-GUI
None of the Tcl examples are GUI compliant for the moment.

4.4 Other Examples

Other examples are provided. They are located in the source tree under Examples/Tcl.

Some of these examples require external datasets that must have been properly installed.

To compile and execute each of these examples, go into the target directory, compile with:

make

Execute (a FlowVR daemon must be running) with

make run

The different examples are:

• fluid2d. It requires no external dataset. It is the same as the testflowvr.sh program.
• fluid3d1render. It displays a 3D fluid simulation. It requires the external data "Fluid 3D''. This example also proposes a multi-windowed version. To compile and run:
  make -f Makefile.para.ml run
• quadric. The quadric example detailed before. No external dataset required.
• warpComb. A VTK example. See at the top of the source file Examples/Tcl/warpComb/modules/warpComb.tcl for a short explanation of this example.
• skull and xmas are two examples of volume rendering. They requires external datasets (respectively "CT Head'' and "XMasTree LO'').