<span class="cmss-12">paraFoam</span>

6.1 paraFoam

The main post-processing tool provided with OpenFOAM is a reader module to run with ParaView, an open-source, visualization application. The module is compiled into 2 libraries, PV3FoamReader and vtkPV3Foam using version 4.1.0 of ParaView supplied with the OpenFOAM release (PVFoamReader and vtkFoam in ParaView version 2.x). It is recommended that this version of ParaView is used, although it is possible that the latest binary release of the software will run adequately. Further details about ParaView can be found at http://www.paraview.org and further documentation is available at http://www.kitware.com/products/paraviewguide.html.

ParaView uses the Visualisation Toolkit (VTK) as its data processing and rendering engine and can therefore read any data in VTK format. OpenFOAM includes the foamToVTK utility to convert data from its native format to VTK format, which means that any VTK-based graphics tools can be used to post-process OpenFOAM cases. This provides an alternative means for using ParaView with OpenFOAM. For users who wish to experiment with advanced, parallel visualisation, there is also the free VisIt software, available at http://www.llnl.gov/visit.

In summary, we recommend the reader module for ParaView as the primary post-processing tool for OpenFOAM. Alternatively OpenFOAM data can be converted into VTK format to be read by ParaView or any other VTK -based graphics tools.

6.1.1 Overview of paraFoam

paraFoam is strictly a script that launches ParaView using the reader module supplied with OpenFOAM. It is executed like any of the OpenFOAM utilities either by the single command from within the case directory or with the -case option with the case path as an argument, e.g.:


    paraFoam -case <caseDir>

\relax \special {t4ht=


Figure 6.1: The paraFoam window


ParaView is launched and opens the window shown in Figure 6.1. The case is controlled from the left panel, which contains the following:

Pipeline Browser
lists the modules opened in ParaView, where the selected modules are highlighted in blue and the graphics for the given module can be enabled/disabled by clicking the eye button alongside;
Properties panel
contains the input selections for the case, such as times, regions and fields;
Display panel
controls the visual representation of the selected module, e.g. colours;
Information panel
gives case statistics such as mesh geometry and size.

ParaView operates a tree-based structure in which data can be filtered from the top-level case module to create sets of sub-modules. For example, a contour plot of, say, pressure could be a sub-module of the case module which contains all the pressure data. The strength of ParaView is that the user can create a number of sub-modules and display whichever ones they feel to create the desired image or animation. For example, they may add some solid geometry, mesh and velocity vectors, to a contour plot of pressure, switching any of the items on and off as necessary.

The general operation of the system is based on the user making a selection and then clicking the green Apply button in the Properties panel. The additional buttons are: the Reset button which can be used to reset the GUI if necessary; and, the Delete button that will delete the active module.

6.1.2 The Properties panel

The Properties panel for the case module contains the settings for time step, regions and fields.


\relax \special {t4ht=


Figure 6.2: The Properties panel for the case module


The controls are described in Figure 6.2. It is particularly worth noting that in the current reader module, data in all time directories are loaded into ParaView (in the reader module for ParaView 2.x, a set of check boxes controlled the time that were displayed). In the current reader module, the buttons in the Current Time Controls and VCR Controls toolbars select the time data to be displayed, as shown is section 6.1.4.

As with any operation in paraFoam, the user must click Apply after making any changes to any selections. The Apply button is highlighted in green to alert the user if changes have been made but not accepted. This method of operation has the advantage of allowing the user to make a number of selections before accepting them, which is particularly useful in large cases where data processing is best kept to a minimum.

There are occasions when the case data changes on file and ParaView needs to load the changes, e.g. when field data is written into new time directories. To load the changes, the user should check the Update GUI button at the top of the Properties panel and then apply the changes.

6.1.3 The Display panel

The Display panel contains the settings for visualising the data for a given case module.


\relax \special {t4ht=


Figure 6.3: The Display panel


The following points are particularly important:

6.1.4 The button toolbars

ParaView duplicates functionality from pull-down menus at the top of the main window and the major panels, within the toolbars below the main pull-down menus. The displayed toolbars can be selected from Toolbars in the main View menu. The default layout with all toolbars is shown in Figure 6.4 with each toolbar labelled. The function of many of the buttons is clear from their icon and, with tooltips enabled in the Help menu, the user is given a concise description of the function of any button.


\relax \special {t4ht=


Figure 6.4: Toolbars in ParaView


6.1.5 Manipulating the view

This section describes operations for setting and manipulating the view of objects in paraFoam.

6.1.5.1 View settings

The View Settings are selected from the Edit menu, which opens a View Settings (Render View) window with a table of 3 items: General, Lights and Annotation. The General panel includes the following items which are often worth setting at startup:

The Lights panel contains detailed lighting controls within the Light Kit panel. A separate Headlight panel controls the direct lighting of the image. Checking the Headlight button with white light colour of strength 1 seems to help produce images with strong bright colours, e.g. with an isosurface.

The Annotation panel includes options for including annotations in the image. The Orientation Axes feature controls an axes icon in the image window, e.g. to set the colour of the axes labels x  \relax \special {t4ht=, y  \relax \special {t4ht= and z  \relax \special {t4ht=.

6.1.5.2 General settings

The general Settings are selected from the Edit menu, which opens a general Options window with General, Colors, Animations, Charts and Render View menu items.

The General panel controls some default behaviour of ParaView. In particular, there is an Auto Accept button that enables ParaView to accept changes automatically without clicking the green Apply button in the Properties window. For larger cases, this option is generally not recommended: the user does not generally want the image to be re-rendered between each of a number of changes he/she selects, but be able to apply a number of changes to be re-rendered in their entirety once.

The Render View panel contains 3 sub-items: General, Camera and Server. The General panel includes the level of detail (LOD) which controls the rendering of the image while it is being manipulated, e.g. translated, resized, rotated; lowering the levels set by the sliders, allows cases with large numbers of cells to be re-rendered quickly during manipulation.

The Camera panel includes control settings for 3D and 2D movements. This presents the user with a map of rotation, translate and zoom controls using the mouse in combination with Shift- and Control-keys. The map can be edited to suit by the user.

6.1.6 Contour plots

A contour plot is created by selecting Contour from the Filter menu at the top menu bar. The filter acts on a given module so that, if the module is the 3D case module itself, the contours will be a set of 2D surfaces that represent a constant value, i.e. isosurfaces. The Properties panel for contours contains an Isosurfaces list that the user can edit, most conveniently by the New Range window. The chosen scalar field is selected from a pull down menu.

6.1.6.1 Introducing a cutting plane

Very often a user will wish to create a contour plot across a plane rather than producing isosurfaces. To do so, the user must first use the Slice filter to create the cutting plane, on which the contours can be plotted. The Slice filter allows the user to specify a cutting Plane, Box or Sphere in the Slice Type menu by a center and normal/radius respectively. The user can manipulate the cutting plane like any other using the mouse.

The user can then run the Contour filter on the cut plane to generate contour lines.

6.1.7 Vector plots

Vector plots are created using the Glyph filter. The filter reads the field selected in Vectors and offers a range of Glyph Types for which the Arrow provides a clear vector plot images. Each glyph has a selection of graphical controls in a panel which the user can manipulate to best effect.

The remainder of the Properties panel contains mainly the Scale Mode menu for the glyphs. The most common options are Scale Mode are: Vector, where the glyph length is proportional to the vector magnitude; and, Off where each glyph is the same length. The Set Scale Factor parameter controls the base length of the glyphs.

6.1.7.1 Plotting at cell centres

Vectors are by default plotted on cell vertices but, very often, we wish to plot data at cell centres. This is done by first applying the Cell Centers filter to the case module, and then applying the Glyph filter to the resulting cell centre data.

6.1.8 Streamlines

Streamlines are created by first creating tracer lines using the Stream Tracer filter. The tracer Seed panel specifies a distribution of tracer points over a Line Source or Point Cloud. The user can view the tracer source, e.g. the line, but it is displayed in white, so they may need to change the background colour in order to see it.

The distance the tracer travels and the length of steps the tracer takes are specified in the text boxes in the main Stream Tracer panel. The process of achieving desired tracer lines is largely one of trial and error in which the tracer lines obviously appear smoother as the step length is reduced but with the penalty of a longer calculation time.

Once the tracer lines have been created, the Tubes filter can be applied to the Tracer module to produce high quality images. The tubes follow each tracer line and are not strictly cylindrical but have a fixed number of sides and given radius. When the number of sides is set above, say, 10, the tubes do however appear cylindrical, but again this adds a computational cost.

6.1.9 Image output

The simplest way to output an image to file from ParaView is to select Save Screenshot from the File menu. On selection, a window appears in which the user can select the resolution for the image to save. There is a button that, when clicked, locks the aspect ratio, so if the user changes the resolution in one direction, the resolution is adjusted in the other direction automatically. After selecting the pixel resolution, the image can be saved. To achieve high quality output, the user might try setting the pixel resolution to 1000 or more in the x  \relax \special {t4ht=-direction so that when the image is scaled to a typical size of a figure in an A4 or US letter document, perhaps in a PDF document, the resolution is sharp.

6.1.10 Animation output

To create an animation, the user should first select Save Animation from the File menu. A dialogue window appears in which the user can specify a number of things including the image resolution. The user should specify the resolution as required. The other noteworthy setting is number of frames per timestep. While this would intuitively be set to 1, it can be set to a larger number in order to introduce more frames into the animation artificially. This technique can be particularly useful to produce a slower animation because some movie players have limited speed control, particularly over mpeg movies.

On clicking the Save Animation button, another window appears in which the user specifies a file name root and file format for a set of images. On clicking OK, the set of files will be saved according to the naming convention “<fileRoot>_<imageNo>.<fileExt>”, e.g. the third image of a series with the file root “animation”, saved in jpg format would be named “animation_0002.jpg” (<imageNo> starts at 0000).

Once the set of images are saved the user can convert them into a movie using their software of choice. The convert utility in the ImageMagick package can do this from the command line, e.g. by


    convert animation*jpg movie.mpg
When creating an mpg movie it can be worth increasing the default quality setting, e.g. with -quality 90%, to reduce the graininess that can occur with the default setting.
Creative Commons License
This User Guide is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License .