Special Interest Area: Visualization

Visualizing Data With Paraview

—Steven Cutchin, SDSC

Paraview is an excellent tool for a variety of scientific visualization tasks. Paraview is an Open Source software project managed and promoted by Kitware, Inc. The same company that provides support for VTK. To quote from Kitware's web-site:

ParaView is an open-source, multi-platform, extensible application designed for visualizing large data sets. This scalable application runs on single-processor workstations as well as on large parallel supercomputers.

SDSC has installed Paraview on our HPC resources and is keeping it up to date with the latest stable versions. Paraview provides iso-surfacing, streamlines, ribbons, segmentation, mesh generation and a large collection of additional features. It is extensible and programmers can add their own file formats and visualization features to it.

In addition to Paraview SDSC has installed a collection of other software tools on Datastar. Many of these tools are installed in /usr/local/apps32 and /usr/local/apps. Please look under /usr/local/apps for mpirun which is used in the advanced part of this tutorial.

Paraview can be run in two different very useful ways. The first way is to run it as a standard X-Windows application. From an X-Windows machine with OpenGL extensions you can log on to Datastar run paraview and have it display on your desktop machine. To do this you should ssh to dsdirect.sdsc.edu with X11 forwarding enabled. Do this with ssh -Y dsdirect.sdsc.edu Then you can work with Paraview directly on your desktop.

Paraview Remote Display

From yourlocal Linux/MacOSX/Cygwin machine:

#login to datastar with X Forwarding enabled.
cmd>ssh -Y dsdirect.sdsc.edu

On Datastar

#make certain Paraview is in your path.
dsdirect>setenv PATH /usr/local/apps32/paraview-2.2.1/bin:$PATH

#now your ready to go: fire up paraview
dsdirect>paraview

#at this point wait and the paraview GUI should come up on your local machine.
#You must have GLX extensions on your X-Window system for this to work. GLX extensions support OpenGL 3D drawing in X.

This can be very handy and very quick if you have a fast Internet connection. However the direct mode has the problem that a lot of data and information is being streamed back and forth between datastar and your desktop with every mouse click. This can get very slow if you have a poor network connection. Also it won't work if your desktop system is a Windows machine. It will work in Cygwin for those of you who run X-Servers under Cygwin.

Paraview Client/Server Mode

To address the prior problem Paraview can be run in Client/Server mode where the client runs on your desktop machine, Linux or Windows, and a server that does all of the visualization work runs on Datastar. The server streams the geometry data to the client and the client handles all of the other interactions locally. This is much more efficient on slower network connections.

To use paraview in client server mode your first start a paraview server (pvserver) on datastar and then start a client (pvclient) on your local machine telling it to connect to the server on datastar.The steps for running Paraview in Client/Server mode are straightforward. Start the remote server on datastar and then start you local client telling it to connect to datastar. You can get help from pvclient with the -help command line option. The same for pvserver.

How to Start Paraview in Client/Server Mode

On Datastar (dslogin.sdsc.edu)

% setenv PATH /usr/local/apps32/paraview-2.2.1/bin:$PATH
% pvserver #starts up the server, server waits for client.

On a Desktop (Windows or Linux)
Bring up a command shell and cd to where paraview is installed.
If it is added to your path already you should not need the ./ before the comand.

% ./pvclient --server-host=dsdirect.sdsc.edu

The splash screen should should appear and then Paraview should start up. You can now browse the files on datastar through the client on your desktop. Make certain you turn off Composite on the main render options page in the paraview gui before loading data.

Loading Raw Data into Paraview

Paraview supports an extensive array of file formats. This is very useful, but what if the desired format is not on the list?

Search the Internet or the Kitware site and see if another developer has created a handler for the desired format. (This is the ideal method to resolve this issue.)
Select the closest existing format handler and modify it to support the desired format. (This is a realistic and good approach, but time consuming.)
Ask a Paraview expert to create a handler.
If the desired format is 2D or 3D raw binary volumes, simply use the 'Raw Files Reader' built into Paraview. (This is also preferred and quick if, of course, the data is volumetric and regular in nature. See example below for more details.)

Example: How to load raw binary 3D volume data into Paraview

Select the File -> Open Data menu item.
Select "Files of type: All Files (*.*)" and the raw volume.
You will get a message: "Could not find an appropriate reader for file"
Select the [OK] button.
Select the "Raw (binary) Files Reader".
In the "Parameters" tab, specify the following fields:
Data type
Data type: byte, short, int, float, etc.
Extent: [ 0 ][X-1][ 0 ][Y-1][ 0 ][Z-1]
For example, if the volume resolution is 750 x 375 x 100, then
Extent: [ 0 ][749][ 0 ][374][ 0 ][ 99]
Press the [Accept] button.

Paraview will tell you quite clearly if it loaded the data. You may have to modify the order of your grid size to get things to load properly. For example if your program outputs data with Y varying the fastest you may need to exchange Y and X values in the Extent options for your data to load properly. Paraview assumes that X varies the fastest and that Z varies slowest. So if you output the data with some other variable varying the fastest you will need to interchange the extent values.

One nice option is that you don't have to load the entire volume if you don't want to. You can load sub-sets by reducing the Z value. So if you only want to load in 10 fields from you volume you can set Z to 9 in the extents range.

The reader will happily work with both 2d and 3d volumes. So you can easily visualize 2d slices and just plain 2d output data

Example Paraview Visualization of SCEC Data

The following images show examples of datasets loaded and visualized in Paraview. (Clicking on the screenshot thumbnails will open a full-sized version.)

Surface Representation of the Volume

Dataset: vol_vy.03600
After loading the volume data, do the following:

Select the Display tab
Change the format representation to Surface (This will display the outside of the volume as a colored surface, revealing information about the data. Also, it is possible to adjust the color table by using the built in controls.)

Volume Render (only runs on a single node)

Paraview is capable of simple volume rendering (but only with one server or in stand-alone mode).
After loading volume data, do the following:

Select the Filter -> Tetrahedralize menu item

Once the new filter appears, do the following:

Select the Display tab
Change the Representation Type to Volume Render

Isosurfaces Generated in Parallel

When running in distributed mode iso-surfaces can be generated in parallel.
To do this simply:

Press the "Generate Isosurfaces" icon
Add "Contour Values"
Click on Apply

Isosurfaces Generated in Parallel, Colored by Processor

After having generated iso-surface in parallel, it is possible to see how they were split across processor boundaries by using the "Process Id Scalars" menu item.

Select the Filter -> Process Id Scalars menu item
Select the "Display" tab
Color by: "Point Piece"

A display similar to the following image should appear:

Advanced Options

The following section cover advanced parts of using paraview and if you want to try them out, which I encourage you to do, then you may need to do a little digging on datastar and other threads articles.

You will need to have ccmake installed in your path. ccmake is installed in /usr/local/apps32. For the distributed client/server option you will need to have mpirun installed in your path as well. This is also installed in /usr/local/apps32. If you have not used mpirun before, you should work through the mpi tutorials before you try it out with Paraview.

Compiling Paraview from Source

Building Paraview can be quite an undertaking and involves many steps. It generally works smoothly on a Linux or Windows system. However more esoteric systems, eg Datastar, can require a significant amount of debugging and compile tweaking to get things to work right. Below we have example instructions for compiling Paraview on a Linux system. If you are tyring to compile Paraview on an unusual architecture expect some challenges but feel free to approach us for help. We would be happy to share our knowledge.

How to build Paraview on Linux

Download the latest release from the Paraview website:
http://www.paraview.org/HTML/Download.html
paraview-2.2.1-x86-linux.tar.gz
Untar the file into some directory:

% tar zxvf paraview-2.2.1-x86-linux.tar.gz
Run ccmake to configure the Makefiles.

% ccmake ../paraview-2.2.1

Here are the ccmake options that need to be set:

CMAKE_INSTALL_PREFIX	/projects/vis/tools/paraview-2.2.1
CMAKE_VERBOSE_MAKEFILE	ON
MPI_INCLUDE_PATH	/usr/local/apps/mpich-1.2.5.2/include
MPI_LIBRARY	/usr/local/apps/mpich-1.2.5.2/lib/libpmpich.a
OPENGL_INCLUDE_DIR	/projects/vis/tools/mesa-6.4.1/include
OPENGL_gl_LIBRARY	/projects/vis/tools/mesa-6.4.1/lib/libmGL.a
OPENGL_glu_LIBRARY	/projects/vis/tools/mesa-6.4.1/lib/libmGLU.a
OSMESA_INCLUDE_DIR	/projects/vis/tools/mesa-6.4.1/include
OSMESA_LIBRARY	/projects/vis/tools/mesa-6.4.1/lib/libmOSMesa.a
VTK_MPIRUN_EXE	/usr/local/apps/mpich-1.2.5.2/bin/mpirun
VTK_OPENGL_HAS_OSMESA	ON
VTK_USE_MPI	ON

Use the appropriate Mesa and MPI libraries installed on the system.

Make the distribution:
% make
% make install

Advanced Distributed Client/Server Mode

There is a very advanced way to use the Paraview server and that is to run it in a distributed mode across multiple processors. When run in this mode the server will distribute visualization tasks across multiple nodes and collect the results back to the server and send them to the client. Using this mode you can work with extremely large datasets on the server and still browse the results from your desktop. This mode uses MPI to communicate amongst the distributed nodes.

You need to be familiar with working with and using MPI on datastar in order to make this work.

You need to create a simple flat file that lists the machines you want to run the distrubted server on. The format of the file is simply the list of hosts: machinefile.txt host1.sdsc.edu host2.sdsc.edu ...

This file can be generated from the node list handed to your code when you launch a job through llsubmit.

How to Run Paraview in Distributed Client/Server Mode

On Datastar dslogin.sdsc.edu

% setenv PATH /usr/local/apps32/paraview-2.2.1/bin:$PATH

Start the Server in Distributed Mode. -np specifies number of nodes to use.

% mpirun -v -machinefile machines.txt -np 4 pvserver --use-offscreen-rendering #machines.txt contains a list of server machines

On your Desktop either Windows Or Linux
Bring up a command shell and cd to where paraview is installed.
If it is added to your path already you should not need the ./ before the comand.

% ./pvclient --server-host=dsnode1.sdsc.edu

dsnode1 is the host name of the first node that was given to your job by llsubmit. Or you could use a few interactive nodes on datastar and not go through the llsubmit system.

The splash screen should should appear and then Paraview should start up. You can now browse the files on datastar through the client on your desktop.

When using Paraview in distributed mode you may want to consider turning composite back on. Normally composite requires an X-Server connection but since we have specified offscreen rendering it won't need one and should work fine.

Steven Cutchin is reachable via e-mail at cutchin@sdsc.edu