Using ParaView to Visualize MFIX Vector Variables

Table of Contents

1. Introduction

This guide describes how to use ParaView, a scientific visualization application, to examine vector variables produced by MFIX. Familarity with MFIX, its output variables, and with ParaView are assumed. Basic ParaView concepts, such as clicking Accept after adding a new module or making changes to its parameters, are omitted in this document.

The reader is also expected to be familar with the PSC guide, Using ParaView to Visualize MFIX Scalar Variables , www.psc.edu/general/software/packages/mfix/MFIXScalarsGuide.php, referenced in this guide as MSG (MFIX Scalar Guide). It lists many web sites that the reader may find useful; describes how to install the MFIX translator and ParaView; and explains the general operation of the application.

This document assumes that the MFIX translator and ParaView are installed, and that at least one MFIX data set has been translated to VTK format. For more information on these processes, see MSG.

It is strongly recommended that the reader obtain a copy of the book The ParaView Guide from www.paraview.org. This book is the only complete documentation for ParaView and is referenced in these notes as PVG.

In this guide, vectors will be visualized using glyphs, a small symbol such as an arrow or a cone. The glyph will be at the cell centers when possible. However, certain operations require that the cell data be converted to node data with the glyphs at the nodes.

In many cases, the vector information is better understood when limited to a subset of the data set. Methods will be described for limiting the vectors to a volume, a plane, an isosurface and by size (Figure 1).

These notes refer to ParaView 2.0.1.



Figure 1. Vectors on an isosurface.

Figure 1. Vectors on an isosurface.
Click on the image for a larger version.


2. Editing the Pipeline

Each section of this guide will introduce a new pipeline (that is, a string of connected modules) such as

reader -> Cell Centers -> Glyph

A subsequent section may describe new modules and suggest that you change the pipeline to something like

reader -> Cell Centers -> Calculator -> Threshold -> Glyph

There are several ways to edit the pipeline to accomplish this change.

You could erase the old pipeline by exiting and then restarting ParaView, or by using Edit -> Delete All Modules. However, there are less drastic approaches.

If the new pipeline you wish to construct is the same as the old up to a point, you could delete the modules in the old after that point and then add the new modules. However, you will need to start at the end of the pipeline when deleting modules -- ParaView will not let you delete a module whose output is being used by another module.

A new module can also be inserted in an existing pipeline:

  1. Select which module will provide the input for the new module and make it current.
  2. Add the new module.
  3. Go to the module that will use the new module's output and use the Input pulldown menu on the Parameters tab to change the input to the new module.

The downside of this insertion is that the order of the modules in the Selection Window does not correspond to the order in which the data flows.

3. Basic Vector Display

This section will describe a simple graphics pipeline using 3 modules:

reader -> Cell Centers -> Glyph

Use File -> Open Data to add the reader module.3.1 Cell Centers

Click Filter -> Cell Centers to add this module to the pipeline.

In its never-ending attempt to be helpful, ParaView will probably turn off the reader's graphic at this point. However, since Cell Centers does not produce a graphic by default, the display is now blank.

You may wish to turn the reader's graphic back on (click the eye icon) and change it to a simple Outline ( MSG, Modifying the Reader's Graphic). This outline will be helpful as a reference for later graphics.

The Cell Centers module creates a new node (vertex) at the center of each cell and then assigns to the new node all of the data from the orginal cell. The original node data is lost -- not a problem for MFIX users since there is no node data.

The result is that the original MFIX cell data now looks like node data. This is much better than using the CelltoPoint module since the latter uses averaging that changes the values of the variables.

Cell Centers, by default, produces no cells. To observe this, look at the list of variables in the Color by pulldown on the Display tab. All variables' names have the prefix "Point" to indicate that they are attached to the points (nodes). Also, note that the Number of cells on the Information tab is 0.

However, we shall be passing the ouput from Cell Centers to some other modules that require cells, even if the cells are trivial. On the Parameters tab, click Generate vertices and then Accept. In spite of the button's name, this change will generate cells of type "point" (the cell has only one point). If you again check the Color by and Number of cells information you will see that both point and cell data are produced along with one cell per point.

Turning on Generate vertices will also create a graphic: one pixel at each cell. Use the options under the Display tab to select how the pixels are colored and the size of the pixels.

Because each cell is only one point, the output from Cell Centers cannot be used by any method, such as an isosurface, that requires an area or volume for each cell. But the output is perfect for the next module.

3.2 Glyph

Click the button in the Tool Bar with the popup help saying Generate a glyph (10th from left) or Filter -> Glyph. Turn off the graphic from Cell Centers to better see the glyphs. By default, the first vector variable from the MFIX file (for example, gas_velocity) will be used to orient and set the size of the arrow glyph.

Change the Scale Factor, if needed, to adjust the size of the glyphs. ParaView often makes a poor choice for the scale.

Additional glyph options will be discussed in the final section of this guide.

Warning: A bug in this module can result in a failure to update when parameters or upstream modules change. For example, when showing glyphs on a cut, the glyphs may stay the same even when the cut is moved. This tends to happen when Glyph's Mask Points checkbox is off. The workaround is to turn Glyph's masking on, at least temporarily.

4. Simple Methods for Limiting Vectors

At the completion of the previous section ParaView is trying to put a glyph (an arrow) at every data point, i.e., at every cell in the MFIX data set. Usually, this produces a slow and useless display.

This section will describe two simple and fast methods for limiting the number of vectors. However, neither is based on the value of the data or an area of interest (such as a cut plane or isosurface). As a result, vectors of interest (say, the ones with the largest magnitude) might be eliminated. Use with caution.

4.1 Masking

A masked cell is not drawn.

The Glyph module includes a simplified set of masking options at the bottom of the Paramters tab. By default, the number of glyphs is limited to 5000 by random masking. See the PVG for details. Setting the Maximum Number of Glyphs to a low value (say, 100) helps reveal how this process works.

You can gain a little more control over masking by adding the Mask Points module so that your pipeline looks like this:

reader -> Cell Centers -> Mask Points -> Glyph

See the PVG for details. The rest of this guide will not use Mask Points but you can insert it in the pipeline if you wish.

Be sure to turn off masking in Glyph if you are using Mask Points to avoid confusion.

4.2 Level-of-Detail (LOD)

In ParaView, the LOD feature is used to temporarily substitute a simplified drawing for the original when moving the drawing (e.g., rotation with the mouse).

You may have already seen this in action - displays of a large number of vectors can easily trigger this feature. See the PVG's Section 6.1 for details.

5. Limiting Vectors to A Volume

The MSG's section "Clipping" describes how the Clip module, using the Box clip function, can limit the data to a selected volume. Clipping affects both scalar and vector data.

Although clipping could be added anywhere along the graphics pipeline, it's probably easiest to understand the results if done before other operations. Add it to a vector display as follows:

reader -> Clip -> Cell Centers -> Glyph

6. Limiting Vectors to A Cut Plane

A cut plane works for vectors as well as scalars (see the MSG section "Adding a Cut Plane"). Your pipeline could look like

reader -> Cut -> Cell Centers -> Glyph

or, if you wish to also clip the volume, like

reader -> Clip -> Cut -> Cell Centers -> Glyph

7. Limiting Vectors by Magnitude

The Threshold module can delete cells using any scalar variable associated with the cell or its vertices. Unfortunately, MFIX data does not include, as a scalar variable, the magnitude of its vectors. We can easily create this variable with a pipeline such as

reader -> Cell Centers -> Calculator -> Threshold -> Glyph

or

reader -> Clip -> Cut -> Cell Centers -> Calculator -> Threshold -> Glyph

7.1 Add A Calculator

With the Cell Centers module current, add the Calculator module by clicking on the button with the popup help saying Create new arrays ... (4th from the left) or Filter -> Calculator.

Set the Attribute Mode to Cell Data. The other option, Point Data, may work just as well. Selecting Cell Data makes it easier to remember that the original data was cell data.

Set Result Array Name to mag gas_velocity or any other name you wish for the new variable. The following will assume the suggested name.

Use the calculator keypad to form the equation mag(gas_velocity) then click Accept.

7.2 Cut by Value

With the Calculator module current, add the Threshold module by clicking on the Tool Bar button with the popup help saying Extract cells that satisfy a threshold ... (8th from left) or Filter -> Threshold. Set:

  • Attribute Mode to Cell Data
  • Scalars to mag gas_velocity>
  • Lower Threshold to its center position (a good first guess)
  • All Scalars off

The Threshold module actually produces an interesting graphic that is faster than glyphs. If using the Glyph module, turn off its graphic so you can better see Threshold graphic. Then, on the Threshold Display tab, set:

  • Color by to Cell mag gas_velocity
  • Representation to Surface
  • Point size to 3 or larger

8. Limiting Vectors to An Isosurface

Isosurfaces, generated by the Contour module, require node data. Therefore, MFIX's cell data must first be converted to node data using the CellToPoint module. This, unfortunately, introduces changes to the variables because of the averaging used in the conversion. The minimum pipeline for this is:

reader -> CellToPoint -> Contour -> Glyph

Figure 1 shows the output from such a pipeline.

If you wish to also limit the isosurface and vectors to a specific volume, and to show only large vectors, use a pipeline like:

reader -> Clip -> CellToPoint -> Contour -> Calculator -> Threshold -> Glyph

The Contour module, if given a 2D input, will create lines instead of surfaces. For example, use Cut to create a 2D surface; Contour to draw 2D lines on the surface; and Glyph to draw vectors:

reader -> CellToPoint -> Cut -> Contour -> Glyph

Figure 2 shows the output from such a pipeline. Note that such a pipeline performs one average and two interpolations to compute the vector values at the vertices of the contour lines.

Gas velocity (arrows) along void fraction contour (purple lines).

Figure 2. Gas velocity (arrows) along void fraction contour (purple lines).
Click on the image for a larger version.


9. Glyphs Redux

The glyphs used by the Glyph module are controlled from several property sheets and tabs.

9.1 Orientation, Scale and Color

Up to 3 different variables can be used to control a glyph drawing.

On the Glyph -> Parameters tab, the Orient Mode can be:

Off - the glyph is shown unrotated
Vector - the glyph is rotated by a vector variable selected with the Vectors pulldown menu

The same tab's Scale Mode can be:

Off - the glyph is shown unscaled
Vector Magnitude - the glyph is scaled by the magnitude of the Vectors variable
Scalar - the glyph is scaled by a scalar variable selected with the Scalars pulldown menu
Vector Components - the glyph is scaled along each of the 3 coordinate axes by the corresponding component of the Vectors variable

The Scale Factor is combined with whatever scaling method is selected.

On the module's Display tab, the Color by pulldown menu selects the variable used to set the color.

9.2 Changing the Shape of A Glyph

The Glyph module's Parameters tab includes a pulldown menu, Glyph, that selects from among 5 basic shapes. The two simplest, Line and Glyph2D, use lines whose width can be controled on the Display tab.

Each glyph (e.g., the arrow glyph) also has its own property sheet which is somewhat hidden. The Selection Window, at the top of most property sheets, lists all the active modules. Clicking on one will show that module's property sheet. However, a glyph's property sheet is usually not listed.

To show a glyph property sheet, you must click Select -> Glyphs -> "style" where "style" is one of the 5 glyph styles. The observant reader will note that the selected glyph style is now listed in the Selection Window. It will be removed as soon as you switch to another property sheet.

For example, the property sheet for the arrow glyph was used to alter the arrows used for Figure 2 with the following settings:

   tip and shaft resolution: 20    tip radius: 0.15    tip length: 0.45    shaft radius: 0.05

Thicker, higher-resolution glyphs make for better final images but may slow the display update more than you wish for everyday work.