Many (but not all) edit boxes and pipeline command parameters allow the use of expressions instead of numerical values. Visual3D uses a common expression parser, so the following syntax is common across all command parameters that allow expressions.
The Evaluate_Expression command allows the users to include expressions for defining the processing of the signals.
Evaluate_Expression /Expression= !/Signal_Type= !/Signal_Folder= !/Signal_Name= /Result_Type= /Result_Folder= /Result_Name= !/Apply_as_suffix_to_signal_name=FALSE ;
Expressions are incredibly flexible and capable of ingesting most data types in Visual3D. The key to using expressions is to understand the syntax used for each data type:
There are five characters that cause the expression parser considerable trouble. We have introduced reserved pipeline commands that can be used in the place of these characters.
We have introduced reserved names for a few common ideas that are useful to reference in constructing expressions.
| Reserved Names | Usage |
|---|---|
| CURRENT_SIGNAL | short hand for signal names |
| NAN | Not a Number |
| isNAN | Is Not a Number? |
We have introduced three number-related functions to aid in the construction of expressions.
| Numerical Functions | Result |
|---|---|
| pi() | 3.14159265358979323846 |
| gravity_vector() | gravity vector in the laboratory coordinate system. For a z-up coordinate system returns (0,0,-9.81) |
| rand() | Generate a random number |
In its simplest use, the Evaluate_Expression command can be used to evaluate arbitrary mathematical expressions. Use the following characters for your mathematical operators.
| Mathematical Operators | Use |
|---|---|
| + | Plus or Add |
| - | Minus or Subtract |
| * | Multiply |
| / | Divide |
| ^ | Power or Exponent |
| | | logical OR → the operator NOT is allowed |
| & | logical AND → the operator NOT is allowed |
| == OR = | Equals |
| <> OR >< | Not Equals |
| < | Less Than |
| <= OR =< | Less Than or Equals To |
| > | Greater Than |
| >= OR => | Greater Than or Equals To |
| NOT() | NOT() |
Note: Visual3D parses the mathematical operators before it parses the signal names. If you have a signal name that contains a mathematical operator (e.g. R-Foot1), Visual3D will probably not be able to parse the equation expression properly.
Also Note the potential conflict between some of the operators and the reserved characters. If the string is obviously an expression, there is no conflict.
The & character is used by Visual3D for concatenating strings. This works quite well, but there is one circumstance where this choice of delimiter is a nuisance. That is when you want & to actually be a logical AND and the parser throws it away.
As of v2024.04.1 you can use the reserved string AMP for these cases.
Example given a file that has TAGS labelled TEST1 and TEST2.
! To select files containing the tags TEST1 and TEST2 Select_Active_File /FILE_NAME=ALL_FILES /QUERY=TEST1 & TEST2 ! /SUBJECT_TAGS=NO_SUBJECT ; ! But what if you want to generalize and use another pipeline parameter for TEST2 Set_Pipeline_Parameter /PARAMETER_NAME=SCOTT2 /PARAMETER_VALUE=TEST1 &::AMP &::SCOTT ; Select_Active_File /FILE_NAME=ALL_FILES /QUERY=TEST1 &::AMP &::SCOTT ! /SUBJECT_TAGS=NO_SUBJECT ;
Visual3D has pre-defined functions embedded in the pipeline to help you construct your expressions. These functions are commonly used or have been added based on customer use.
Examples of using Evaluate_Expressions can be found here: Expressions Examples