Command Line Arguments

Command-Line Arguments and Environment Variables

The following is a list of options available when running ParaView from the command line. When two options are listed, separated by a comma, either of them can be used to achieve the specified result. Unless otherwise specified, all command-line options are used on the client program. Following the list of command-line options is a set of environment variables ParaView recognizes.

General Options

- --data : Load the specified data file into ParaView (--data=data_file).

- --disable-registry, -dr : Launch ParaView in its default state; do not load any preferences saved in ParaView’s registry file.

- --help, /? : Display a list of the command-line arguments and their descriptions.

- --version, -V : Display ParaView’s version number, and then exit.

Client-Server Options

- --server, -s : Tell the client process where to connect to the server. The default is server =localhost. This command-line option is used on the client.

- --client-host, -ch : Tell the server process(es) where to connect to the client. The default is client-host=localhost. This command-line option is used on the server(s).

- --server-port, -sp : Specify the port to use in establishing a connection between the client and the server. The default is --server-port=11111. If used, this argument must be specified on both the client and the server command lines, and the port numbers must match.

- --data-server-port, -dsp : Specify the port to use in establishing a connection between the client and the data server. The default is --data-server-port=11111. If used, this argument must be specified on both the client and the data server command lines, and the port numbers must match.

- --render-server-port, -rsp : Specify the port to use in establishing a connection between the client and the render server. The default is --render-server-port=22221. If used, this argument must be specified on both the client and the render server command lines, and the port numbers must match.

- --reverse-connection, -rc : Cause the data and render servers to connect to the client. When using this option, the client, data server, and render server (if used) must be started with this command-line argument, and you should start the client before starting either server.

- --connect-id : Using a connect ID is a security feature in client-server mode. To use this feature, pass this command-line argument with the same ID number to the client and server(s). If you do not pass the same ID number, the server(s) will be shut down.

- --machines, -m : Use this command-line argument to pass in the network configuration file for the render server. See section Error: Reference source not found for a description of this file.

Rendering Options

- --stereo : Enable stereo rendering in ParaView.

- --tile-dimensions-x, -tdx : Specify the number of tiles in the horizontal direction of the tiled display ( tile dimensions-x=number_of_tiles). This value defaults to 0. To use this option, you must be running in client/server or client/data server/render server mode, and this option must be specified on the client command line. Setting this option to a value greater than 0 will enable the tiled display. If this argument is set to a value greater than 0 and -tdy (see below) is not set, then -tdy will default to 1.

- --tile-dimensions-y, -tdy : Specify the number of tiles in the vertical direction of the tiled display ( tile dimensions-y=number_of_tiles). This value defaults to 0. To use this option, you must be running in client/server or client/data server/render server mode, and this option must be specified on the client command line. Setting this option to a value greater than 0 will enable the tiled display. If this argument is set to a value greater than 0 and -tdx (see above) is not set, then -tdx will default to 1.

- --tile-mullion-x, -tmx : Specify the spacing (in pixels) between columns in tiled display images.

- --tile-mullion-y, -tmy : Specify the spacing (in pixels) between rows in tiled display images.

- --use-offscreen-rendering : Use offscreen rendering on the satellite processes. On unix platforms, software rendering or mangled Mesa must be used with this option.

- --disable-composite, -dc : Use this command-line option if the data server does not have rendering resources and you are not using a render server. All the rendering will then be done on the client.

Environment Variables

In addition to the command-line options previously listed, ParaView also recognizes the following environment variables.

- PV_DISABLE_COMPOSITE_INTERRUPTS If this variable is set to 1, it is not possible to interrupt the compositing of images in parallel rendering. Otherwise it is interruptible through mouse interaction.

- PV_ICET_WINDOW_BORDERS Setting this variable to 1 when running ParaView in tiled display mode using IceT causes the render window for each tile to be the same size as the display area in ParaView’s main application window. (Normally each render window fills the whole screen when tiled display mode is used.) This feature is sometimes useful when debugging ParaView.

- PV_PLUGIN_PATH If you have shared libraries containing plugins you wish to load in ParaView at startup, set this environment variable to the path for these libraries.

- PV_SOFTWARE_RENDERING This environment variable has the same effect as setting both the use software rendering and --use-satellite-software environment variables.

- VTK_CLIENT_SERVER_LOG If set to 1, a log file will be created for the ParaView client, server, and render server. The log files will contain any client-server streams sent to the corresponding client, server, or render server.

Executable help

paraview --help

--connect-id=opt Set the ID of the server and client to make sure they match. --cslog=opt ClientServerStream log file. --data=opt Load the specified data. To specify file series replace the numeral with a '.' eg. my0.vtk, my1.vtk...myN.vtk becomes my..vtk --data-directory=opt Set the data directory where test-case data are. --disable-light-kit When present, disables light kit by default. Useful for dashboard tests. --disable-registry -dr Do not use registry when running ParaView (for testing). --exit Exit application when testing is done. Use for testing. --help /? Displays available command line arguments. --machines=opt -m=opt Specify the network configurations file for the render server. --script=opt Set a python script to be evaluated on startup. --server=opt -s=opt Set the name of the server resource to connect with when the client starts. --state=opt Load the specified statefile (.pvsm). --stereo Tell the application to enable stereo rendering (only when running on a single process). --stereo-type=opt Specify the stereo type. This valid only when --stereo is specified. Possible values are "Crystal Eyes", "Red-Blue", "Interlaced", "Dresden", "Anaglyph", "Checkerboard" --test-baseline=opt Add test baseline. Can be used multiple times to specify multiple baselines for multiple tests, in order. --test-directory=opt Set the temporary directory where test-case output will be stored. --test-script=opt Add test script. Can be used multiple times to specify multiple tests. --test-threshold=opt Add test image threshold. Can be used multiple times to specify multiple image thresholds for multiple tests in order. --version -V Give the version number and exit. --vrpn Tell the application to use VRPN for head tracking --vrpn-address=opt Specify the VRPN tracker name. This valid only when --vrpn is specified. Examples: "Tracker0@localhost", "Head0@localhost"Please check VRPN configuration file --vrui Tell the application to use VRUI for head tracking --vrui-address=opt Specify the VRUI host name.

pvbatch --help

--cslog=opt ClientServerStream log file. --help /? Displays available command line arguments. --machines=opt -m=opt Specify the network configurations file for the render server. --symmetric -sym When specified, the python script is processed symmetrically on all processes. --use-offscreen-rendering Render offscreen on the satellite processes. This option only works with software rendering or mangled mesa on Unix. --version -V Give the version number and exit.

pvdataserver --help

--client-host=opt -ch=opt Tell the data|render server the host name of the client, use with -rc. --connect-id=opt Set the ID of the server and client to make sure they match. --cslog=opt ClientServerStream log file. --data-server-port=opt -dsp=opt What port data server use to connect to the client. (default 11111). --help /? Displays available command line arguments. --machines=opt -m=opt Specify the network configurations file for the render server. --reverse-connection -rc Have the server connect to the client. --timeout=opt Time (in minutes) since connecting with a client after which the server may timeout. The client typically shows warning messages before the server times out. --version -V Give the version number and exit.

pvpython --help

--connect-id=opt Set the ID of the server and client to make sure they match. --cslog=opt ClientServerStream log file. --data=opt Load the specified data. To specify file series replace the numeral with a '.' eg. my0.vtk, my1.vtk...myN.vtk becomes my..vtk --help /? Displays available command line arguments. --machines=opt -m=opt Specify the network configurations file for the render server. --state=opt Load the specified statefile (.pvsm). --stereo Tell the application to enable stereo rendering (only when running on a single process). --stereo-type=opt Specify the stereo type. This valid only when --stereo is specified. Possible values are "Crystal Eyes", "Red-Blue", "Interlaced", "Dresden", "Anaglyph", "Checkerboard" --version -V Give the version number and exit.

pvrenderserver --help

--client-host=opt -ch=opt Tell the data|render server the host name of the client, use with -rc. --connect-id=opt Set the ID of the server and client to make sure they match. --cslog=opt ClientServerStream log file. --help /? Displays available command line arguments. --machines=opt -m=opt Specify the network configurations file for the render server. --render-server-port=opt -rsp=opt What port should the render server use to connect to the client. (default 22221). --reverse-connection -rc Have the server connect to the client. --tile-dimensions-x=opt -tdx=opt Size of tile display in the number of displays in each row of the display. --tile-dimensions-y=opt -tdy=opt Size of tile display in the number of displays in each column of the display. --tile-mullion-x=opt -tmx=opt Size of the gap between columns in the tile display, in Pixels. --tile-mullion-y=opt -tmy=opt Size of the gap between rows in the tile display, in Pixels. --use-offscreen-rendering Render offscreen on the satellite processes. This option only works with software rendering or mangled mesa on Unix. --version -V Give the version number and exit.

pvserver --help

--client-host=opt -ch=opt Tell the data|render server the host name of the client, use with -rc. --connect-id=opt Set the ID of the server and client to make sure they match. --cslog=opt ClientServerStream log file. --disable-composite -dc Use this option when rendering resources are not available on the server. --help /? Displays available command line arguments. --machines=opt -m=opt Specify the network configurations file for the render server. --reverse-connection -rc Have the server connect to the client. --server-port=opt -sp=opt What port should the combined server use to connect to the client. (default 11111). --tile-dimensions-x=opt -tdx=opt Size of tile display in the number of displays in each row of the display. --tile-dimensions-y=opt -tdy=opt Size of tile display in the number of displays in each column of the display. --tile-mullion-x=opt -tmx=opt Size of the gap between columns in the tile display, in Pixels. --tile-mullion-y=opt -tmy=opt Size of the gap between rows in the tile display, in Pixels. --timeout=opt Time (in minutes) since connecting with a client after which the server may timeout. The client typically shows warning messages before the server times out. --use-offscreen-rendering Render offscreen on the satellite processes. This option only works with software rendering or mangled mesa on Unix. --version

-V Give the version number and exit.

Application Settings

Application Settings

Application wide settings are saved in between sessions so that every time you start ParaView on the same machine you get the same behaviors. The settings are stored in an XML file that resides at %APPDATA%\ParaView\ParaViewVERSION.ini on Windows and ~/.config/ParaView/ParaViewVERSION.ini on all other platforms. If you need to restore ParaView's default settings you can either move this file or run with the --disable-registry argument.

These settings are managed via the settings dialog. On Macintosh this is reached from the Preferences entry in the ParaView menu. On Unix, Linux and Windows systems it is reached from the Settings entry on the Edit menu. These settings are program wide and are not to be confused with the View settings found under the Edit menu. Those settings are specific to each View window and are discussed in the Displaying Data chapter.

The following figures show the various pages within the settings dialog. Choose from among them by clicking on the page list toward the left. Click on the arrow to expose the three sub pages in the Render View settings category. Some plugins add their own pages to the dialog but we do not discuss them here and instead refer you to any documentation that comes along with the plugin. Do note though that most settings are documented within the application via tooltips.

General

Figure 1. General Preferences

- Default View : choose the View window type that ParaView initially shows when it starts up and connects to any server.

- On File Open : Control the timestep shown by default when ParaView opens a file with multiple time steps.

- Rescale Data Range Mode : Controls how color lookup tables are adjusted when data ranges change

- Heart-Beat Interval : Sets the length of time between keepalive messages that the client sends to the remote server which prevents the TCP connection between the two machines from shutting down.

- Auto Accept : Makes every change take effect immediately rather than requiring you to click the Apply button.

- Auto Convert Properties : Tells ParaView to do some data conversions automatically so that more filters are immediately applicable to the data you have at hand.

- Crash Recovery : Tells ParaView to save a record of each action you take so that you can easily recover your work if ParaView crashes mid-session.

- Use Multi-Core : Tells ParaView to spawn an MPI parallel server on the same machine that is running the GUI so as to better take advantage of multi-core machines on processing bound problems.

Colors

Figure 2. Color Preferences

When setting up visualizations, most datasets in the visualization are typically colored using scalar colors. However, there may be items in the setup that are simply colored using a solid color including text and other annotations. Also by default ParaView uses a grey background, so the default colors chosen for objects tends to be setup so that it looks appropriate on the gray background. However, when saving a screenshot for printing, one would prefer to white background, for example. In that case, it can be tedious to go to every object and change its color to work with the new background color.

To make it easier to change colors on the fly, ParaView defines color categories. Users can choose to assign a color category to any object when specifying a color using the category menu on most color-chooser buttons, as shown below.

Color Category Menu on the Display Tab

Following associations are setup by default:

- Foreground color: outlines and wireframes

- Background color: background color in render views

- Surface color: solid color to surfaces

- Text color: color to 2D text

- Selection color: color used to show highlighted/selected elements in render view.

- Egde color: used for edges in Surface With Edges mode.

Animation

Figure 3. Animation Preferences

- Cache Geometry : When checked this allows ParaView to save and later reuse rather than regenerate visible geometry during animation play back to speed up replay.

- Cache Limit : This is the maximum size of the animation playback geometry cache (on each node when in parallel).

Charts

Figure 4. Chart Preferences

- Hidden Series : Allows you to specify a set of regular expressions that are compared against array names so that various bookkeeping arrays are not drawn in 2D charts and thus distract from the meaningful ones.

Render View General

Figure 5. General Render View Preferences

- Use Immediate Mode Rendering : Controls whether OpenGL display lists are used or not which are generally faster only when rendering relatively small amounts of geometry.

The LOD Parameters settings control if, when and to what extent ParaView will down sample the data it draws while you move the mouse so as to maintain interactivity. The algorithm by which ParaView down samples the data is known as quadric clustering.

- LOD Threshold : Rendered data that is smaller than the specified size is not down sampled.

- LOD Resolution : When data is downsampled, this controls how coarsely.

- Outline threshold : Data that is larger than this threshold is drawn only as a bounding box while you move the camera.

- Lock Interactive Render : Controls how long ParaView waits after you have released the mouse and finished moving the camera before it returns to a full resolution render.

- Allow Rendering Interrupts : makes the drawing process interuptable so that you can move the camera immediately, without having to wait for a potentially slow full resolution render to complete.

The Depth Peeling settings control the algorithm that ParaView uses (given a sufficiently capable GPU) to draw translucent geometry correctly.

- Enable Depth Peeling : Controls whether ParaView will try to use the (potentially slow) depth peeling algorithm at all.

- Number of Peels : Controls the number of passes in the rendering algorithm. Higher produces quality images but increases rendering time.

The Coincident Topology Resolution settings control the method that ParaView uses to draw co-planar polygons in a non conflicting way (to avoid z-tearing in graphics terminology). Changes to these parameters do not take effect until ParaView is restarted.

The pull down menu allows you to choose between various algorithms that deal with z-tearing.

1. Do Nothing : does not attempt to resolve overlapping geometry

2. Use Z-Buffer Shift : adjusts OpenGL's Z direction scaling to draw one object slightly in front of the other. The Z Shift property controls the amount of offset.

3. Use Polygon Offset : adjusts polygon locations (by calling glPolygonOffset()) for the same purpose. For an explanation of the Factor and Units parameters, see http://www.opengl.org/resources/faq/technical/polygonoffset.htm. The Offset Faces parameters controls whether filled polygons are moved rather than the points and edges.

- Use Offscreen Rendering for Screenshots : This checkbox is enabled only when offscreen rendering is available. It tells ParaView to generate images that are being captured as screenshots in offscreen contexts. On some platforms this is necessary to avoid accidentally capturing overlapping pixels (such as a mouse pointer) from the operating system.

Render View Camera

Figure 6. Camera Preferences

These settings allow you to assign particular key/mouse press combinations to various camera moving controls. There are two sets of settings. Control for 3D Movements pertain to the 3D View. Control for 2D Movements pertain to the 2D View.

In the 3D View controls you can assign the following motions to any combination of left, middle or right mouse button press and no, shift or control key press.

- Pan

- Roll

- Rotate

- Multi-Rotate

- Zoom

Rotation is not possible in the 2D View, which lacks a down direction to move about. So in this area you can only choose from Pan and Zoom.

Clicking Reset Defaults restores the button assignments to the factory settings.

Render View Server

Figure 7. Server Preferences

These settings control how and where rendering happens when you are connected to a remote server.

The Remote Rendering Parameters are controls that generally affect the breakup of rendering work between the remote server and the local client machine.

- Remote Render Theshold : geometry that is smaller than the set value will be delivered to the client for local rendering. Data that is larger than the set value will be rendered remotely and pixels will be sent instead.

- Client Outline Threshold : while the camera is being manipulated and when geometry is being rendered locally, or in tiled display mode when it is being rendered both locally and remotely, data that is larger than this threshold will be rendered as a bounding box to maintain interactivity

- Suppress Ordered Compositing : This setting turns of the relatively slow transfer of data that must happen in parallel in order to render translucent geometry (as in volume rendering for instance) correctly.

The Client/Server Parameters section has controls that affect how pixels are transfered between the render server and the client while the data is being rendered remotely and images rather than geometry are being delivered to the client. The Apply presets for ... menu allows you to choose from a set of default settings which are generally well suited to particular network connection bandwidths.

- Interactive Subsample Rate : This setting controls how coarsely the image is downsampled to maintain interactivity while the camera is being manipulated.

- Image Compression : Enables compression of images during interaction. You can choose from either of the two image compression algorithms:

1. Squirt : Chooses IceT's native squirt image compression algorithm. The slider to the right controls the colorspace fidelity of the compression and conversely the interactive responsiveness.

1. Zlib : Chooses the ZLib library's compression algorithm instead. The spin box to the right specifies a compression level (1 through 9). The slider controls the colorspace fidelity. The Strip Alpha checkbox removed the Opacity channel (if any) from the shipped images.

The Tile Display Parameters section contains controls that take effect when doing tiled display wall rendering.

- Still Subsample Rate : This puts a screen space coarseness limit on the normally full resolution rendering that happens once you release the mouse after moving the camera. Image compositing time can prevent interactivity when working with large displays. This limit allows you to preview your results quickly and then choose to render truly full resolution results only once when you are satisfied with the preview.

- Compositing Threshold : This threshold allows you to get faster rendering times in the circumstance that you are visualizing relatively small data sets on large tiled displays. When the geometry size is below the threshold, the geometry is broadcast to all nodes in the render server. After this broadcast the relatively slow tiled image compositing algorithm is entirely omitted.

building/compile/install

Introduction

This page describes how to build and install ParaView. It covers both the release and the development versions. It covers both Unix-type systems (Linux, HP-UX, Solaris, Mac) as well as Windows.

Prerequisites

- The ParaView build process requires CMake version 2.8.2 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (8 or later).

- Building ParaView's user interface requires TrollTech's Qt, version 4.6.* (4.6.2 recommended) Qt is dual licensed. To compile ParaView, either the open or commercial version may be used. If you intend to make changes the ParaView's GUI and distribute the results, you must obtain a commercial license. The open source version of Qt can be found here [8]. Commercial licenses can be purchased directly from TrollTech [9]. For more information on what can be done with the open source version, read this [10].

- In order to run ParaView in parallel, MPI [11], [12] is also required.

- In order to use scripting, python is required [13].

Download And Install CMake

CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.

Using Binaries

There are several precompiled binaries available at the CMake download page.

On Unix-like operating systems Let's say on Linux, download the appropriate version and follow these instructions: Download http://www.cmake.org/files/v2.8/cmake-2.8.2-Linux-i386.tar.gz cd $HOMEwget http://www.cmake.org/files/v2.8/cmake-2.8.2-Linux-i386.tar.gzmkdir softwarecd softwaretar xvfz ../cmake-2.8.2-Linux-i386.tar.gz Now you have the directory $HOME/software/cmake-2.8.2-Linux-i386/bin, and inside there are executables cmake and ccmake. You can also install CMake in the /usr/local or /opt by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your $PATH. | On Windows Download the installer http://www.cmake.org/files/v2.8/cmake-2.8.2-win32-x86.exe Follow the installation instructions On Windows, if you are not administrator Download http://www.cmake.org/files/v2.8/cmake-2.8.2-win32-x86.zip Uncompress into some directory Optional: create a shortcut on the desktop.

Build Your Own CMake

On Unix-like operating systems Download the source code http://www.cmake.org/files/v2.8/cmake-2.8.2.tar.gz cd $HOMEwget http://www.cmake.org/files/v2.8/cmake-2.8.2.tar.gztar xvfz cmake-2.8.2.tar.gzcd cmake-2.8.2./configure --prefix=$HOME/softwaremakemake install Again, you can install it in /usr/local or /opt by changing the prefix. | On Windows To build CMake on windows, a previous version of CMake is required. This can be downloaded from the CMake download page.

Download And Install Qt

ParaView uses Trolltech's Qt as its GUI library. Qt is required whenever the ParaView client is built. See this page for Qt licensing information: [14].

- As stated above, The open source version of Qt can be found at [15].

  1. For sourcecode, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.6.2 is known to work.

  2. For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.6.2 is known to work.

- Commercial licenses can be purchased directly from TrollTech [16].

Download And Install ffmpeg (.avi) movie libraries

When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [17]

Download And Install MESA 3D libraries

ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [18].

There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.

- Build as follows:

- make realclean

- make TARGET (for instance, make linux-x86-64)

Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.

Download ParaView Source Code

If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.

Download The Release

Don't forget that you can always just download the binaries from the ParaView download page. This page contains binaries for several platforms and the source code for the releases.

Note: debian build

List of packages to build ParaView on Debian:

libphonon-dev libphonon4 libqt4-assistant qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev

With MPI (using openmpi, you can use any other flavour):

openmpi-common openmpi-bin libopenmpi-dev

With Python:

python2.5-dev

Checkout Development Version from git

Note that you may need to download and install a git client, here: [19]

On Unix-like operating systems mkdir $HOME/projectscd $HOME/projectscd 3.10.0 git clone git://paraview.org/ParaView.git ParaView cd ParaView git checkout -b trunk origin/master git submodule init git submodule updateUpdate git fetch origin git rebase origin/master git submodule update | On Windows We recommend [msysgit| ]. Msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.

Configure ParaView With CMake

- Always use a separate build directory. Do not build in the source directory.

On Unix-like systems Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory. mkdir $HOME/projects/ParaView-bincd $HOME/projects/ParaView-binccmake $HOME/projects/ParaView3 About CCMake (Curses CMake GUI) Iterative process Select values, run configure (c key) Set the settings, run configure, set the settings, run configure, etc. Repeat until all values are set and the generate option is available (g key) Some variables (advanced variables) are not visible right away To see advanced varables, toggle to advanced mode (t key) To set a variable, move the cursor to the variable and press enter If it is a boolean (ON/OFF) it will flip the value If it is string or file, it will allow editing of the string For file and directories, the <tab> key can be used to complete To search for a variable press '/' key, and to repeat the search, press the 'n' key. | On Windows Use CMakeSetup from the CMake install location. Make sure to select the appropriate source and the build directory Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the Visual Studio 6 generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog. About CMakeSetup (Windows CMake GUI) Iterative process Select values, press the Configure button Set the settings, run configure, set the settings, run configure, etc. Repeat until all values are set and the OK button becomes available. Some variables (advanced variables) are not visible right away To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle). To set the value of a variable, click on that value. If it is boolean (ON/OFF), a drop-down menu will appear for changing the value. If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog. If it is a string, it will become an editable string.

ParaView Settings

Variable | Description
BUILD_SHARED_LIBS | If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster.
PARAVIEW_USE_MPI | Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.
MPI_LIBRARY | Path to the MPI library (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. (see the note below)
MPI_EXTRA_LIBRARY | Path to extra MPI library (such as /usr/lib/libmpi++.so). If the MPI distribution is MPICH, this may not be found; in this case, it is ok for this variable to be set to MPI_EXTRA_LIBRARY-NOTFOUND.
MPI_INCLUDE_PATH | Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.
PARAVIEW_ENABLE_PYTHON | Makes python client scripting and the python programmable filter available.
PARAVIEW_BUILD_QT_GUI | Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building paraview on server nodes or when we are only interested in the python client, as it avoids building of the Qt client thus does not require Qt. ON by Default.
QT_QMAKE_EXECUTABLE | Path to Qt's qmake executable (such as /usr/local/Trolltech/Qt-4.2.2/bin/qmake). Cmake uses this to locate the rest of the required Qt executables, headers and libraries.
VTK_USE_CARBON | For Mac, this is the default. Neither X11 nor COCOA frameworks are supported.
VTK_OPENGL_HAS_OSMESA | Turn this to ON to enable MESA (i.e., software rendering). All mesa directory and file settings below depend on this flag.
OSMESA_INCLUDE_DIR | Set this to the include directory for MESA.
OPENGL_INCLUDE_DIR | Set this to the include directory for MESA.
OPENGL_gl_LIBRARY | Set this to the libGL.a or libGL.so file.
OPENGL_glu_LIBRARY | Set this to the libGLU.a or libGLU.so file.
OSMESA_LIBRARY | Set this to the libOSMesa.a or libOSMesa.so file.

Note for MPI settings: If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually.

Finish Configuring ParaView

Using CCMake Once all configuration options are set, you should be able to just run <generate> (g key). | Using CMakeSetup Once all configuration options are set, you should be able to just run <generate>, by clicking the "OK" button.

Build ParaView

You can now build ParaView using the appropriate build system.

Using Make CMake will now generate Make files. These makefiles have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system. Once you have makefiles you should be able to just type: make If you are on multi-processor system (let's say 4 processor), you can type: make -j 4 To create online documentation, type the following. (Note that ParaVeiw build does not create this documentation by default). make HTMLDocumentation | Using Visual Studio CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path. You should now be able to open the ParaView project (or workspace) file. Make sure to select the appropriate build type (Debug, Release, ...). To build ParaView, simply build the ALL_BUILD target. The ParaView build does not create the online documentation by default. Select the HTMLDocumentation target, right click, and select Build.

Install ParaView

ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location. For that purpose simply follow the instructions for "Distributing ParaView" and the unpack the generated archive at the appropriate install location.

Distributing ParaView

It is possible to create distribution binaries for ParaView using CPack which is included in CMake. The packaged binary can be in any of the variable supported generator formats eg. DEB (debian packages), RPM (RPM Packages), NSIS (Null Soft Installer) etc. Please refer to [[20]] for a complete list.

CMake Variables

When building ParaView so that it can be distributed, in most typical cases, ensure that the values for the following CMake variables are set correctly.

Variable | Value | Description
BUILD_SHARED_LIBS | ON | Enables shared libraries (unless you are sure you want to do static builds)
CMAKE_BUILD_TYPE | Release | Unless you want to end up with debug install, set this to Release
PARAVIEW_USE_MPI | OFF | Unless you are taking extra steps to ensure that the clients have the required MPI libraries, set this to OFF, since ParaView does not include rules to package MPI.
PARAVIEW_ENABLE_PYTHON | OFF | Unless you are taking extra steps to ensure that clients have the rquired python libraries/modules.
PARAVIEW_GENERATE_PROXY_DOCUMENTATION | ON | To ensure that the html documentation for the sources/filters/readers/writes is generated and packed into the application, turn the following flag ON.
PARAVIEW_INSTALL_DEVELOPMENT | OFF/ON | To package development files so that people can build plugins/custom-apps using the installation.
PARAVIEW_BUILD_QT_GUI | ON/OFF | To enable building the Qt client

PARAVIEW_EXTRA_INSTALL_RULES_FILE: Adding custom install rules

You can add additional install rules by writing a custom cmake file with install rules and then set PARAVIEW_EXTRA_INSTALL_RULES_FILE cmake variable to point to that file. ParaView process all install rules that have the COMPONENT set to either "Runtime" (for executables), or "RuntimeLibraries" (for shared libraries), or "BrandedRuntime" (for custom-application specific libraries/executables) only (and "Development" when PARAVIEW_INSTALL_DEVELOPMENT is TRUE). So you want to add your install rules with appropriate COMPONENT values in this custom cmake file.

e.g. you want to include mpilibs in the installation, in that case the custom install rules file could look something as follows:

INSTALL (FILES ${MPI_LIBRARY} ${MPI_EXTRA_LIBRARY}
DESTINATION ${PV_INSTALL_LIB_DIR}
COMPONENT RuntimeLibraries)

Generate Package

Following the configuration, simply run 'make' to compile and build.

On Unix-like operating systems To generate a tar ball, in the binary directory, simply run cpack -G TGZ --config {ParaViewBuild}/Applications/ParaView/CPackParaViewConfig.cmake If PARAVIEW_BUILD_QT_GUI was OFF, then to generate a package consisting of the server executables alone, use the following command: cpack -G TGZ --config {ParaViewBuild}/Applications/ParaView/CPackParaViewServersConfig.cmake | On Windows To generate a null-soft installer (requires [21]), in the binary directory, simply run cpack -G NSIS -C Release --config {ParaViewBuild}/Applications/ParaView/CPackParaViewConfig.cmake If PARAVIEW_BUILD_QT_GUI was OFF, then to generate a package consisting of the server executables alone, use the following command: cpack -G NSIS -C Release --config {ParaViewBuild}/Applications/ParaView/CPackParaViewServersConfig.cmake
On Mac To generate an app bundle that can be distributed, use cpack -G DragNDrop --config {ParaViewBuild}/Applications/ParaView/CPackParaViewConfig.cmake If PARAVIEW_BUILD_QT_GUI was OFF, then to generate a tarball consisting of the server executables alone, use the following command: cpack -G TGZ --config {ParaViewBuild}/Applications/ParaView/CPackParaViewServersConfig.cmake |

Miscellaneous Comments

- Don't untar the packaged tar ball over the build directory itself. You can always remove the build directory and untar the tar ball in its place.

- Don't use make install as it may install more files than required.

- CMAKE_INSTALL_PREFIX is not applicable when using cpack and will have no effect.

- Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree. By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly setup the environment to launch the equivalent executable in the lib/paraview-x.y directory.

- If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.

Notes

Compiling on the Mac

To compile on the Mac, follow the instructions for Unix. The recommended configuration settings are: BUILD_SHARED_LIBS=ON.

Environment Variables

If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run paraview. On windows one way to do so is to open up the environment variables dialog by clicking through Start->Control Panel->System->Advanced->Environment Variables. From that dialog add a new user variable called PATH with a value of C:\Qt\4.6.3\bin. For other operating systems, add Qt/4.6.3/lib to your LD_LIBRARY_PATH environment variable.

ParaView: [Welcome | Site Map]

How to write parallel VTK readers

Writing ParaView Readers

If the format of your data files is not one supported by default in ParaView (see section Error: Reference source not found), you will either need to convert your files to a format ParaView can read, or you must write your own data file reader for ParaView. The reader must operate within a standard VTK pipeline. In this chapter, we will discuss integrating the new reader class into VTK, including outlining which C++ methods should be implemented for the reader to work properly. The necessary user interface and server manager XML will be described. Creating parallel readers and readers that output multiple parts will also be covered. For VTK information beyond the scope of the chapter, see The VTK User's Guide by Kitware, Inc.

Integrating with VTK

VTK is written in C++, and new readers should also be written in this language. A reader plays the role of a source in a VTK pipeline, and must be implemented as a class deriving from vtkAlgorithm or one of its subclasses. The best choice for the immediate superclass of a new reader depends on the reader's output type. For example, a reader producing an instance of vtkPolyData may derive from vtkPolyDataAlgorithm to simplify its implementation. In order for a reader to function properly within VTK's pipeline mechanism, it must be able to respond to standard requests. This is implemented by overriding one or more of the following methods from the chosen superclass.

The interface to these methods utilizes vtkInformation objects which are heterogeneous maps storing key/value pairs. Many of these methods have the same three arguments. The first argument is of type vtkInformation* and contains at least one key specifying the request itself. The second argument is of type vtkInformationVector** and stores information about the input connections to the algorithm. This can be ignored by readers because they have no input connections. The third argument is of type vtkInformationVector* and contains one vtkInformation object for each output port of the algorithm. Most readers will have only one output port, but some may have multiple output ports (see the next section). All output information and data from the reader will be stored in one of these information objects.

ProcessRequest: This method is the entry point into a vtkAlgorithm through which the pipeline makes requests. A reader may override this method and implement responses to all requests. The method should be placed in the public section of the reader class. It should return 1 for success and 0 for failure. Full documentation of this method is beyond the scope of this chapter. Most readers should derive from one of the output-type-specific classes and implement the request-specific methods described below.

RequestInformation: This method is invoked by the superclass's ProcessRequest implementation when it receives a REQUEST_INFORMATION request. In the output port, it should store information about the data in the input file. For example, if the reader produces structured data, then the whole extent should be set here (shown below).

int vtkExampleReader::RequestInformation(
vtkInformation*, vtkInformationVector**,
vtkInformationVector* outVec)
{
vtkInformation* outInfo = outVec->GetInformationObject(0);
int extent[6];
// ... read file to find available extent ...
//store that in the pipeline
outInfo->Set
(vtkStreamingDemandDrivenPipeline::WHOLE_EXTENT(), extent, 6);
// ... store other information ...
return 1;
}

This method is necessary when configuring a reader to operate in parallel. (This will be further discussed later in this chapter.) It should be placed in the protected section of the reader class. The method should return 1 for success and 0 for failure.

RequestData: This method is invoked by the superclass's ProcessRequest implementation when it receives a REQUEST_DATA request. It should read data from the file and store it in the corresponding data object in the output port. The output data object will have already been created by the pipeline before this request is made. The amount of data to read may be specified by keys in the output port information. For example, if the reader produces vtkImageData, this method might look like this.

int vtkExampleReader::RequestData(
vtkInformation*, vtkInformationVector**,
vtkInformationVector* outVec)
{
vtkInformation* outInfo = outVec->GetInformationObject(0);
vtkImageData* outData = vtkImageData::SafeDownCast
(outInfo->Get(vtkDataObject::DATA_OBJECT()));
int extent[6] = {0,-1,0,-1,0,-1};
outInfo->Get
(vtkStreamingDemandDrivenPipeline::UPDATE_EXTENT(), extent);
outData->SetExtent(extent);
// ... read data for this extent from the file ...
return 1;
}

The method should be placed in the protected section of the reader class. It should return 1 for success and 0 for failure.

CanReadFile: The purpose of this method is to determine whether this reader can read a specified data file. Its input parameter is a const char* specifying the name of a data file. In this method you should not actually read the data but determine whether it is the correct format to be read by this reader. This method should return an integer value: 1 indicates that the specified file is of the correct type; 0 indicates it is not. It is not absolutely required that this method be implemented, but ParaView will make use of it if it exists.

SetFileName: This method allows you to specify the name of the data file to be loaded by your reader. The method is not required to have this exact name, but a method with this functionality must be implemented. The easiest way to implement SetFileName is with a vtkSetStringMacro in the header file for this class. (There is also an associated vtkGetStringMacro for implementing GetFileName.) This method handles allocating an array to contain the file name and lets the reader know that the pipeline should be updated when the name is changed.

vtkSetStringMacro(FileName);

When using this macro, you must also add a FileName instance variable of type char* in the protected section of this class. In the constructor for your reader, assign FileName the value NULL before you use SetFileName for the first time. In the destructor for your reader, call SetFileName(0)to free the file name storage.

Multi-Group (Multi-Block and AMR) Readers

As of VTK 5.0 and ParaView 2.4, multi-block and AMR datasets are supported. Multi-group readers follow the same guidelines as described in the previous sections. For convenience, you can subclass multi-block readers from vtkMultiBlockDataSetAlgorithm and AMR readers from vtkHierarchicalDataSetAlgorithm. If you do not sub-class from one of these classes, make sure to implement the CreateDefaultExecutive(), FillOutputPortInformation(), and FillInputPortInformation() methods appropriately. (You can use vtkMultiBlockDataSetAlgorithm as a starting point.) Two good examples of multi-group dataset readers are vtkMultiBlockPLOT3DReader and vtkXMLHierarchicalDataReader.

Parallel Readers

Unless otherwise specified, a VTK reader used in ParaView will cause the entire data set to be read on the first process. ParaView will then redistribute the data to the other processes. It is more desirable to have ParaView do the reading in parallel as well so that the data set is already appropriately divided across the processors. Changes should be made in two methods for ParaView readers to operate in parallel: RequestInformation and RequestData. Exactly which changes should be made depends on whether structured or unstructured data set types are to be read.

Structured

In RequestInformation for readers of structured data (vtkStructuredGrid, vtkRectilinearGrid, or vtkImageData), the WHOLE_EXTENT key should be set on the output information object, so that downstream filters can take into account the overall dimensions of the data. The WHOLE_EXTENT is specified using six parameters: the minimum and maximum index along each of the three coordinate axes (imin, imax, jmin, jmax, kmin, kmax or a single int array of length 6) for the entire data set. Example C++ code demonstrating this is shown below.

int vtkDEMReader::RequestInformation (
vtkInformation * vtkNotUsed(request),
vtkInformationVector ** vtkNotUsed( inputVector ),
vtkInformationVector *outputVector)
{
vtkInformation* outInfo =
outputVector->GetInformationObject(0);
int extent[6];
//Read entire extent from file.
...
outInfo->Set
(vtkStreamingDemandDrivenPipeline::WHOLE_EXTENT(), extent,6);
return 1;
}

Before doing any processing in the RequestData method, first get the UPDATE_EXTENT from the output information object. This key contains the sub-extent of the WHOLE_EXTENT for which the current process is responsible. The current process is responsible for filling in the data values for the update extent that is returned. An example of doing this is shown below.

int vtkDEMReader::RequestData(
vtkInformation* vtkNotUsed( request ),
vtkInformationVector** vtkNotUsed( inputVector ),
vtkInformationVector* outputVector)
{
// get the data object and find out what part we need to
// read now
vtkInformation *outInfo = outputVector->GetInformationObject(0);
int subext[6];
outInfo->Get
(vtkStreamingDemandDrivenPipeline::UPDATE_EXTENT(),
subext);
//read that part of the data in from the file
//and put it in the output data
...
return 1;
}

Unstructured

In the unstructured case (vtkPolyData or vtkUnstructuredGrid), the MAXIMUM_NUMBER_OF_PIECES key should be set on the output information object in RequestInformation. This specifies the maximum number of pieces that can be generated from the file. If this reader can only read the entire data set, then the maximum number of pieces should be set to 1. If the input file can be read into as many pieces as needed (i.e., one per processor), the maximum number of pieces should be set to -1, as shown below.

outInfo->Set(vtkStreamingDemandDrivenPipeline::MAXIMUM_NUMBER_OF_PIECES(), -1);

In the RequestData method, the reader should first get the UPDATE_NUMBER_OF_PIECES and UPDATE_PIECE_NUMBER from the output information object. The value returned from getting the UPDATE_NUMBER_OF_PIECES specifies the number of pieces into which the output data set will be broken. Getting UPDATE_PIECE_NUMBER returns the piece number (0 to UPDATE_NUMBER_OF_PIECES-1) for which the current process is responsible. The reader should use this information to determine which part of the data set the current process should read. Example code that demonstrates this is shown below.

int vtkUnstructuredGridReader::RequestData(
vtkInformation *,
vtkInformationVector **,
vtkInformationVector *outputVector)
{
vtkInformation *outInfo = outputVector->GetInformationObject(0);
int piece, numPieces;
piece = outInfo->Get
(vtkStreamingDemandDrivenPipeline::UPDATE_PIECE_NUMBER());
numPieces = outInfo->Get
(vtkStreamingDemandDrivenPipeline::UPDATE_NUMBER_OF_PIECES());
//skip to proper offset in the file and read piece
...
return 1;
}

It is possible that your data file can only be broken into a specified number of pieces, and that this number is different than the number of processors being used (i.e., the result of getting UPDATE_NUMBER_OF_PIECES). If the number of processors is larger than the possible number of pieces, then each processor beyond the number of available pieces should produce an empty output by calling Initialize() on the output. If the number of processors is smaller than the number of pieces, you should internally redistribute the extra data across the processors. For example, if your data set can produce ten pieces, and you are using five processors for reading, then process 0 could read pieces 0 and 5; process 1 could read pieces 1 and 6; etc.

Required XML

To use your new reader within ParaView, you must write XML code for the server manager and for the client. The server-side XML for ParaView's readers is located in the file Servers/ServerManager/Resources/readers.xml. When ParaView is compiled, the server manager XML code for a reader is used to create a proxy object for it. The ParaView client accesses the VTK class for the reader on the server through the proxy. Below is an excerpt from the server manager XML code for vtkXMLPolyDataReader. A few parts of this XML code segment are particularly worth noting, and more extensive information about server manager XML code can be found in section Error: Reference source not found.

First, notice the StringVectorProperty element named "FileName". It has a command attribute called "SetFileName". ParaView uses this property to tell the reader what file it should examine. This is done very early in the lifetime of a reader. Typically, ParaView code will give the reader a filename and then call the reader's CanReadFile method. If CanReadFile succeeds, ParaView will first call RequestInformation to get general information about the data within the file, and then call RequestData to read the actual data and produce a vtkDataObject.

The second notable portion of the XML code below is two properties that let the user choose particular arrays to load from the data file. When ParaView sees them, it creates a section on the Properties tab for the reader that lets the user select from the available cell-centered data arrays. In the following discussion, one can simply replace 'cell' with 'point' in order to let the user choose from the available point-centered arrays.

The StringVectorProperty named "CellArrayStatus" lets the ParaView client call the SetCellArrayStatus method on the server. The SetCellArrayStatus method is how the reader is told what it should do with each of the arrays the data file contains. It takes two parameters; the first is the name of the array, and the second is an integer indicating whether to read the array (1) or not (0).

The StringVectorProperty named 'CellArrayInfo' is an information property; that is, one through which the ParaView client gathers information from the server. The ParaView client uses it to gather the names of the cell-centered arrays from the reader. (See the nested Property sub-element in CellArrayStatus's ArraySelectionDomain element.) In order for this collection to work, two methods be implemented in the reader. GetNumberOfCellArrays returns the number (an int) of cell-centered arrays in the data file. This method does not accept any parameters. GetCellArrayName takes a single parameter the array's index (starting from 0). This method returns the name of the array (a const char*) with this index or NULL if the array has no name or if the index is larger than the number of arrays.

<SourceProxy name="XMLPolyDataReader"
class="vtkXMLPolyDataReader"
label="XML Polydata reader">
<StringVectorProperty name="FileName"
command="SetFileName"
animateable="0"
number_of_elements="1">
<FileListDomain name="files"/>
</StringVectorProperty>
<StringVectorProperty name="CellArrayInfo"
information_only="1">
<ArraySelectionInformationHelper attribute_name="Cell"/>
</StringVectorProperty>
<StringVectorProperty name="CellArrayStatus"
command="SetCellArrayStatus"
number_of_elements="0"
repeat_command="1" number_of_elements_per_command="2"
element_types="2 0"
information_property="CellArrayInfo"
label="Cell Arrays">
<ArraySelectionDomain name="array_list">
<RequiredProperties>
<Property name="CellArrayInfo"
function="ArrayList"/>
</RequiredProperties>
</ArraySelectionDomain>
</StringVectorProperty>
</SourceProxy>

The client-side XML is extremely simple. The purpose of the client-side XML is to enable readers from the server-side XML and to associate file extensions with them. In the case where multiple readers can read files that have the same file extensions, the CanReadFile method is called on each one in order to choose the correct one for each data file. The client-side XML file for readers is located in Qt/Components/Resources/XML/ParaViewReaders.xml. The portion of that file related to XMLPolyDataReader follows.

<Reader name="XMLPolyDataReader"
extensions="vtp"
file_description="VTK PolyData Files">
</Reader>

An alternative to modifying the ParaView source code directly is to use ParaView's plugin architecture. With a plugin, the same C++ source code and XML content must be written, but it is kept outside of the ParaView source code proper and is compiled separately from ParaView. Plugins are discussed in chapter Error: Reference source not found.