ParaView/Users Guide/Python Calculator

Introduction

The Python Calculator is a ParaView filter that processes one or more input arrays based on an expression provided by the user to produce a new output array. The parameters of the filter include the expression, the association of the output array (Point or Cell Data), the name of output array and a toggle that controls whether the input arrays are copied to the output. In this document, we introduce the use of the Python Calculator and provide a list of functions available to the user.

Note that the Python Calculator depends on Python and NumPy. All ParaView binaries distributed by Kitware are built with these to enable the calculator. If you have built ParaView yourself, you have to make sure that NumPy is installed and that PARAVIEW_ENABLE_PYTHON is turned on when configuring the ParaView build.

Basic Tutorial

Start by creating a Sphere source and applying the Python Calculator to it. As the first expression, use the following and apply:

<source lang="python"> 5 </source>

This should create an array name "result" in the output point data. Note that this is an array that has a value of 5 for each point. When the expression results in a single value, the calculator will automatically make an constant array. Next, try the following:

<source lang="python"> Normals </source>

Now the "result" array should be the same as the input array Normals. As described in detail later, various functions are available through the calculator. For example, the following is a valid expression.

<source lang="python"> sin(Normals) + 5 </source>

It is very important to note that the Python Calculator has to produce one value per point or cell depending on the Array Association parameter. Most of the functions described here apply individually to all point or cell values and produce an array as the same dimensions as the input. However, some of them (such as min() and max()) produce single values.

Accessing Data

There are several ways of accessing input arrays within expressions. The simplest way is to access it by name:

<source lang="python"> sin(Normals) + 5 </source>

This is equivalent to:

<source lang="python"> sin(inputs[0].PointData['Normals']) + 5 </source>

The example above requires some explanation. Here inputs[0] refer to the first input (dataset) to the filter. Python Calculator can accept multiple inputs. Each input can be accessed as inputs[0], inputs[1], ... You can access the point or cell data of an input using the .PointData or .CellData qualifiers. You can then access individual arrays within the point or cell data containers using the [] operator. Make sure to use quotes or double-quotes around the array name. NOTE: Arrays that have names with certain characters (such as space, +, -, *, /) in their name can only be accessed using this method.

Certain functions apply directly on the input mesh. These filters expect an input dataset as argument. For example,

<source lang="python"> area(inputs[0]) </source>

Comparing Multiple Datasets

As described above, the Python Calculator can accept multiple inputs. Using this functionality, you can compare multiple datasets. There are a few things to note:

• Python Calculator will always copy the mesh from the first input to its output,
• All operations are applied point by point. In most cases, this requires that the input meshes (topology and geometry) are the same. At the least, it requires the the inputs have the same number of points or cells
• In parallel execution mode, the inputs have to be distributed exactly the same way across processes

For example, to compare the temperature of 2 datasets, you can select both inputs, apply the Python Calculator and then use the following expression.

<source lang="python"> inputs[0].PointData['temperature'] - inputs[1].PointData['temperature'] </source>

Basic Operations

The Python calculator supports all of the basic arithmetic operations using the +, -, * and / operators. These are always applied element-by-element to point and cell data including scalars, vectors and tensors. These operations also work with single values. For example, the following adds 5 to all components of all Normals.

<source lang="python"> Normals + 5 </source>

The following adds 1 to the first component, 2 to the second component and 3 to the third component:

<source lang="python"> Normals + [1,2,3] </source>

This is specially useful when mixing functions that return single values. For example, the following normalizes the Normals array:

<source lang="python"> (Normals - min(Normals))/(max(Normals) - min(Normals)) </source>

A common use case in a calculator is to work on one component of an array. This can be accomplished with the following:

<source lang="python"> Normals[:, 0] </source>

The expression above extracts the first component of the Normals vector. Here, : is a placeholder for "all elements". One element can be extracted by replacing : with an index. For example, the following creates an constant array from the first component of the normal of the first point:

<source lang="python"> Normals[0, 0] </source>

Whereas the following, assigns the normal of the first point to all points:

<source lang="python"> Normals[0, :] </source>

It is also possible to merge multiple scalars into on array. For this, we can use the hstack() function:

<source lang="python"> hstack([velocity_x, velocity_y, velocity_z]) </source>

Note the use of square brackets ([]).

Under the cover, the Python Calculator uses NumPy. All arrays in the expression are compatible with NumPy arrays and can be used where NumPy arrays can be used. For more information on what you can do with these arrays, consult with the NumPy book, which can be downloaded here.

Functions

- point the numpy documentation