Difference between revisions of "ParaView/Users Guide/Calculator"

From KitwarePublic
Jump to: navigation, search
(Working with Point Coordinates)
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Image:ParaView_UG_Calculator.png|300px]]
+
[[Image:ParaView_UG_Calculator.png|thumb|300px|'''Figure 6.2''' ]]
  
 
== Basics ==  
 
== Basics ==  
  
The Calculator Filter can be use to calculate derived quantities from existing attributes. The main parameter of the Calculator is an expression that describes how to calculate the derived quantity. You can enter this expression as free-form text or using some of the shortcuts (buttons and menus provided). Here we describe various options available within the Calculator.
+
The Calculator Filter can be use to calculate derived quantities from existing attributes. The main parameter of the Calculator is an expression that describes how to calculate the derived quantity. You can enter this expression as free-form text or using some of the shortcuts (buttons and menus provided). There are some "hidden" expressions for which there are no buttons. Operands that are accessible only by typing in the function name include:
 +
*min(expr1, expr2) Returns the lesser of the two scalar expressions
 +
*max(expr1, expr2) Returns the greater of the two scalar expressions
 +
*cross(expr1, expr2) Returns the vector cross product of the two vector expressions
 +
* sign(expr) Returns -1, 0 or 1 depending if the scalar expression is less than, equal to or greater than zero respectively
 +
* if(condition,true_expression,false_expression) Evaluates the conditional expression and then evaluates and returns one of the two expressions
 +
* '''>'''  Numerical "greater than" conditional test
 +
* '''<''' Numerical "less than" conditional test
 +
* '''=''' Numerical "equal to" conditional test
 +
* '''&''' Boolean "and" test conjunction
 +
* '''|''' Boolean "or" test conjunction
  
'''Note:''' We recommend that you use the Python Calculator instead of Calculator if possible. The Python Calculator is more flexible, has more functions and is more efficient. However, it requires that ParaView is compiled with Python support and that NumPy is installed.
 
  
Let's start with a simple example. Create a Wavelet source and then apply the Calculator using "1" as the expression. '''Note:''' You can enter an expression by clicking in the expression entry box and typing. This should create an point array called "Result" in the output. A few things to note:
+
'''Note:''' It is recommended that you use the Python Calculator instead of Calculator if possible. The Python Calculator is more flexible, has more functions and is more efficient. However, it requires that ParaView is compiled with Python support and that NumPy is installed.
  
* The Calculator copies the input mesh to the output. It is possible to have the calculator to change the point coordinates. We will discuss this later.
+
Create a Wavelet source and then apply the Calculator using "1" as the expression. '''Note:''' You can enter an expression by clicking in the expression entry box and typing. This should create a point array called "Result" in the output. A few things to note:
 +
 
 +
* The Calculator copies the input mesh to the output. It is possible to have the calculator change the point coordinates, which is discussed.
 
* The expression is calculated for each element in the output point or cell data (depending on the Attribute Mode).
 
* The expression is calculated for each element in the output point or cell data (depending on the Attribute Mode).
  
 
Next, change the expression to be "5 * RTData" and the Result Array Name to be "5 times rtdata" (without the quotes). If you change to surface representation and color by the new array,  you will notice that the filter calculated "5 * RTData" at each point.  
 
Next, change the expression to be "5 * RTData" and the Result Array Name to be "5 times rtdata" (without the quotes). If you change to surface representation and color by the new array,  you will notice that the filter calculated "5 * RTData" at each point.  
  
The main use case for the Calculator is to utilize one or more input arrays to calculate derived quantities. The Calculator can either work on point centered attributes or cell centered attributes (but not both). In order to help enter the names of the input arrays, the Calculator provides two menus accessible through the "Scalars" and "Vectors" buttons. If you select an array name from either menus, it will be inserted to the expression entry box at the cursor location. You can also use the other buttons to enter any of the functions available to the Calculator. Most of these functions are obvious. We will cover the ones that are not below.
+
The main use case for the Calculator is to utilize one or more input arrays to calculate derived quantities. The Calculator can either work on point centered attributes or cell centered attributes (but not both). In order to help enter the names of the input arrays, the Calculator provides two menus accessible through the "Scalars" and "Vectors" buttons. If you select an array name from either menus, it will be inserted to the expression entry box at the cursor location. You can also use the other buttons to enter any of the functions available to the Calculator.  
  
 
== Working with Vectors ==
 
== Working with Vectors ==
  
Let's start with an example. Create a Wavelet source then apply the Random Vectors filter. Next, apply the Calculator. Now look at the Scalars and Vectors menus on the Object Inspector panel. You will notice that BrownianVectors shows up under Vectors, whereas BrownianVectors_X, _Y and _Z show up under scalars. The Calculator allows access to individual components of vectors using this naming convention. So if we use BrownianVectors_X as the expression, the Calculator will extract the first component of the BrownianVectors attribute. All of the Calculator's functions are applicable to vectors. Most of these functions treat the vector attributes same as scalars, mainly apply the same functions to all components of all elements. However, the following functions work only on vectors:
+
To start with an example, create a Wavelet source then apply the Random Vectors filter. Next, apply the Calculator. Now look at the Scalars and Vectors menus on the Object Inspector panel. You will notice that BrownianVectors shows up under Vectors, whereas BrownianVectors_X, _Y and _Z show up under scalars. The Calculator allows access to individual components of vectors using this naming convention. So if you use BrownianVectors_X as the expression, the Calculator will extract the first component of the BrownianVectors attribute. All of the Calculator's functions are applicable to vectors. Most of these functions treat the vector attributes the same as scalars, mainly applying the same functions to all components of all elements. However, the following functions work only on vectors:
  
 
* '''v1 . v2''' : Dot product of two vectors. Returns a scalar.
 
* '''v1 . v2''' : Dot product of two vectors. Returns a scalar.
* '''norm''' : Creates a new array which contains normalized versions of the input vectors.
+
* '''norm''' : Creates a new array that contains normalized versions of the input vectors.
 
* '''mag''' : Returns the magnitude of input vectors.
 
* '''mag''' : Returns the magnitude of input vectors.
  
You may have noticed that 4 calculator buttons on the Object Inspector are not actually functions. Clear is straightforward. It cleans the expression entry box. iHat, jHat and kHat on the other hand are not as clear. These represent unit vectors in X, Y and Z directions. They can be used to construct vectors from scalars. Let's consider a simple but common use case. We want to set the Z component of BrownianVectors from the previous example to 0. The expression to do that is "BrownianVectors_X *iHat+BrownianVectors_Y*jHat+0*kHat". This expression multiplies the X unit vector with the X component of the input vector, the Y unit vector with the Y component, and the Z unit vector with 0 and add them together. You can use this sort of expression to create vectors from individual components of a vector if the reader loaded them separately, for example. '''Note:''' We didn't really need the 0*kHat bit. It was for demonstration.
+
You may have noticed that four calculator buttons on the Object Inspector are not actually functions. Clear is straightforward. It cleans the expression entry box. iHat, jHat and kHat on the other hand are not as clear. These represent unit vectors in X, Y and Z directions. They can be used to construct vectors from scalars. Take for example the case where you want to set the Z component of BrownianVectors from the previous example to 0. The expression to do that is "BrownianVectors_X *iHat+BrownianVectors_Y*jHat+0*kHat". This expression multiplies the X unit vector with the X component of the input vector, the Y unit vector with the Y component, and the Z unit vector with 0 and add them together. You can use this sort of expression to create vectors from individual components of a vector if the reader loaded them separately, for example. '''Note:''' You did not really need the 0*kHat bit, which was for demonstration.
  
 
== Working with Point Coordinates ==
 
== Working with Point Coordinates ==
  
You may have noticed that one point-centered vector and its 3 components are always available in the Calculator. This vector is called "coords" and represents the point coordinates. You can use this array in your expression like any other array. For example, in our example above, we could use "mag(coords)*RTData" to scale RTData with the distance of the point to the origin.
+
You may have noticed that one point-centered vector and its three components are always available in the Calculator. This vector is called "coords" and represents the point coordinates. You can use this array in your expression like any other array. For instance, in the previous example you could use "mag(coords)*RTData" to scale RTData with the distance of the point to the origin.
 +
 
 +
It is also possible to change the coordinates of the mesh by checking the "Coordinate Results" box. Note that this does not work for rectilinear grids (uniform and non-uniform) since their point coordinates cannot be adjusted one-by-one. Since the previous examples used a uniform rectilinear grid, you cannot use them. Instead, start with the Sphere source, then use this expression: "coords+2*iHat". Make sure to check he "Coordinate Results" box. The output of the Calculator should be a shifted version of the input sphere.
 +
 
 +
== Dealing with Invalid Results ==
 +
 
 +
Certain functions are not applicable to certain arguments. For example, sqrt() works only on positive numbers since the calculator does not support complex numbers. Unless the "Replace invalid results" option is turned on, an expression that tries to evaluate the square root of a negative number will return an error such as this:
 +
 
 +
ERROR: In /Users/berk/Work/ParaView/git/VTK/Common/vtkFunctionParser.cxx, line 697
 +
vtkFunctionParser (0x128d97730): Trying to take a square root of a negative value
  
It is also possible to change the coordinates of the mesh by checking the "Coordinate Results" box. Note that this does not work for rectilinear grids (uniform and non-uniform) since their point coordinates cannot be adjusted one-by-one. Since our previous examples used a uniform rectilinear grid, we cannot use them. Instead, start with the Sphere source, then use this expression: "coords+2*iHat". Make sure to check he "Coordinate Results" box. The output of the Calculator should be a shifted version of the input sphere.
+
However, if you turn on the "Replace invalid results" option, the calculator will silently replace the result of the invalid expression with the value specified in "Replacement value". Note that this will happen only when the expression result is an invalid result so some of the output points (or cells) may have the Replacement Value whereas others may have valid results.

Revision as of 09:01, 10 June 2011

Figure 6.2

Basics

The Calculator Filter can be use to calculate derived quantities from existing attributes. The main parameter of the Calculator is an expression that describes how to calculate the derived quantity. You can enter this expression as free-form text or using some of the shortcuts (buttons and menus provided). There are some "hidden" expressions for which there are no buttons. Operands that are accessible only by typing in the function name include:

  • min(expr1, expr2) Returns the lesser of the two scalar expressions
  • max(expr1, expr2) Returns the greater of the two scalar expressions
  • cross(expr1, expr2) Returns the vector cross product of the two vector expressions
  • sign(expr) Returns -1, 0 or 1 depending if the scalar expression is less than, equal to or greater than zero respectively
  • if(condition,true_expression,false_expression) Evaluates the conditional expression and then evaluates and returns one of the two expressions
  • > Numerical "greater than" conditional test
  • < Numerical "less than" conditional test
  • = Numerical "equal to" conditional test
  • & Boolean "and" test conjunction
  • | Boolean "or" test conjunction


Note: It is recommended that you use the Python Calculator instead of Calculator if possible. The Python Calculator is more flexible, has more functions and is more efficient. However, it requires that ParaView is compiled with Python support and that NumPy is installed.

Create a Wavelet source and then apply the Calculator using "1" as the expression. Note: You can enter an expression by clicking in the expression entry box and typing. This should create a point array called "Result" in the output. A few things to note:

  • The Calculator copies the input mesh to the output. It is possible to have the calculator change the point coordinates, which is discussed.
  • The expression is calculated for each element in the output point or cell data (depending on the Attribute Mode).

Next, change the expression to be "5 * RTData" and the Result Array Name to be "5 times rtdata" (without the quotes). If you change to surface representation and color by the new array, you will notice that the filter calculated "5 * RTData" at each point.

The main use case for the Calculator is to utilize one or more input arrays to calculate derived quantities. The Calculator can either work on point centered attributes or cell centered attributes (but not both). In order to help enter the names of the input arrays, the Calculator provides two menus accessible through the "Scalars" and "Vectors" buttons. If you select an array name from either menus, it will be inserted to the expression entry box at the cursor location. You can also use the other buttons to enter any of the functions available to the Calculator.

Working with Vectors

To start with an example, create a Wavelet source then apply the Random Vectors filter. Next, apply the Calculator. Now look at the Scalars and Vectors menus on the Object Inspector panel. You will notice that BrownianVectors shows up under Vectors, whereas BrownianVectors_X, _Y and _Z show up under scalars. The Calculator allows access to individual components of vectors using this naming convention. So if you use BrownianVectors_X as the expression, the Calculator will extract the first component of the BrownianVectors attribute. All of the Calculator's functions are applicable to vectors. Most of these functions treat the vector attributes the same as scalars, mainly applying the same functions to all components of all elements. However, the following functions work only on vectors:

  • v1 . v2 : Dot product of two vectors. Returns a scalar.
  • norm : Creates a new array that contains normalized versions of the input vectors.
  • mag : Returns the magnitude of input vectors.

You may have noticed that four calculator buttons on the Object Inspector are not actually functions. Clear is straightforward. It cleans the expression entry box. iHat, jHat and kHat on the other hand are not as clear. These represent unit vectors in X, Y and Z directions. They can be used to construct vectors from scalars. Take for example the case where you want to set the Z component of BrownianVectors from the previous example to 0. The expression to do that is "BrownianVectors_X *iHat+BrownianVectors_Y*jHat+0*kHat". This expression multiplies the X unit vector with the X component of the input vector, the Y unit vector with the Y component, and the Z unit vector with 0 and add them together. You can use this sort of expression to create vectors from individual components of a vector if the reader loaded them separately, for example. Note: You did not really need the 0*kHat bit, which was for demonstration.

Working with Point Coordinates

You may have noticed that one point-centered vector and its three components are always available in the Calculator. This vector is called "coords" and represents the point coordinates. You can use this array in your expression like any other array. For instance, in the previous example you could use "mag(coords)*RTData" to scale RTData with the distance of the point to the origin.

It is also possible to change the coordinates of the mesh by checking the "Coordinate Results" box. Note that this does not work for rectilinear grids (uniform and non-uniform) since their point coordinates cannot be adjusted one-by-one. Since the previous examples used a uniform rectilinear grid, you cannot use them. Instead, start with the Sphere source, then use this expression: "coords+2*iHat". Make sure to check he "Coordinate Results" box. The output of the Calculator should be a shifted version of the input sphere.

Dealing with Invalid Results

Certain functions are not applicable to certain arguments. For example, sqrt() works only on positive numbers since the calculator does not support complex numbers. Unless the "Replace invalid results" option is turned on, an expression that tries to evaluate the square root of a negative number will return an error such as this:

ERROR: In /Users/berk/Work/ParaView/git/VTK/Common/vtkFunctionParser.cxx, line 697
vtkFunctionParser (0x128d97730): Trying to take a square root of a negative value

However, if you turn on the "Replace invalid results" option, the calculator will silently replace the result of the invalid expression with the value specified in "Replacement value". Note that this will happen only when the expression result is an invalid result so some of the output points (or cells) may have the Replacement Value whereas others may have valid results.