====== Expressions Overview ======

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.

===== Evaluate_Expression Command =====

The Evaluate_Expression command allows the users to include expressions for defining the processing of the signals.
<code>
Evaluate_Expression
/Expression=
!/Signal_Type=
!/Signal_Folder=
!/Signal_Name=
/Result_Type=
/Result_Folder=
/Result_Name=
!/Apply_as_suffix_to_signal_name=FALSE
;
</code>

===== Expression Syntax =====

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:
  -[[visual3d:documentation:pipeline:expressions:expression_syntax#data_tree_syntax|Data Tree Signals]]
  -[[visual3d:documentation:pipeline:expressions:expression_syntax#model_builder_syntax|In Model Builder mode]]
  -[[visual3d:documentation:pipeline:expressions:expression_syntax#Model_Metric_Syntax|Model Metrics]]
  -[[visual3d:documentation:pipeline:expressions:expression_syntax#pipeline_parameter_syntax|Pipeline Parameters]]
  -[[visual3d:documentation:pipeline:expressions:expression_syntax#tag_syntax|File Tags]]
  -[[visual3d:documentation:pipeline:expressions:expression_syntax#C3D_Parameter_Syntax|C3D Parameters]]
  -[[Visual3D:Documentation:Pipeline:General_Information:String_Data|String Data]]

===== Visual3D Reserved Characters =====

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.

^Reserved Characters                                                            ^Character Names ^
|[[Visual3D:Documentation:Pipeline:Expressions:Reserved_Characters#Amp|&]]      |Ampersand       |
|[[Visual3D:Documentation:Pipeline:Expressions:Reserved_Characters#Colon|:]]    |Colon           |
|[[Visual3D:Documentation:Pipeline:Expressions:Reserved_Characters#Semicolon|;]]|Semicolon       |
|[[Visual3D:Documentation:Pipeline:Expressions:Reserved_Characters#Plus|+]]     |Plus            |
|[[Visual3D:Documentation:Pipeline:Expressions:Reserved_Characters#FSlash|/]]   |Forward Slash   |

===== Visual3D Reserved Names =====

We have introduced reserved names for a few common ideas that are useful to reference in constructing expressions.

^Reserved Names                                                                              ^Usage                      ^
|[[Visual3D:Documentation:Pipeline:Expressions:Reserved_Names#CURRENT_SIGNAL|CURRENT_SIGNAL]]|short hand for signal names|
|[[Visual3D:Documentation:Pipeline:Expressions:Reserved_Names#NAN|NAN]]                      |Not a Number               |
|[[Visual3D:Documentation:Pipeline:Expressions:Reserved_Names#isNAN|isNAN]]                  |Is Not a Number?           |

===== Numbers =====

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)|
|[[Visual3D:Documentation:Pipeline:Expressions:Expression_Numbers#random|rand()]]|Generate a random number                                                                            |

===== Mathematical Operators =====

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                                         ^
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Plus|+]]                         |Plus or Add                                 |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Minus|-]]                        |Minus or Subtract                           |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Multiply|*]]                     |Multiply                                    |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Divide|/]]                       |Divide                                      |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Power|^]]                        |Power or Exponent                           |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Logical_Or||]]                   |logical OR -> the operator NOT is allowed   |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Logical_And|&]]                  |logical AND -> the operator NOT is allowed  |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Equals|== OR =]]                 |Equals                                      |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Not_Equals|<> OR ><]]            |Not Equals                                  |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Less_Than|<]]                    |Less Than                                   |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Less_Than_Or_Equals|<= OR =<]]   |Less Than or Equals To                      |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Greater_Than|>]]                 |Greater Than                                |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#Greater_Than_Or_Equals|>= OR =>]]|Greater Than or Equals To                   |
|[[Visual3D:Documentation:Pipeline:Expressions:Mathematical_Operators_#NOT|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 ugly truth of the logical AND====

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.

<code>
! 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
;
</code>

===== Brackets =====

^Brackets                                                                    ^Usage                               ^
|[[Visual3D:Documentation:Pipeline:Expressions:Brackets#Parentheses|( )]]    |contain the parameters in a function|
|[[Visual3D:Documentation:Pipeline:Expressions:Brackets#Square_Brackets|[ ]]]|specify frame numbers and components|

===== Functions =====

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.

====  Metric Functions ====

  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_Minimum|Metric_Minimum]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_Maximum|Metric_Maximum]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_Range|Metric_Range]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_Mean|Metric_Mean]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_Median|Metric_Median]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_StdDev|Metric_StdDev]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_RMS|Metric_RMS]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_Sum|Metric_Sum]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_Integrate|Metric_Integrate]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Metric_InterQuartile|Metric_InterQuartile]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Metric_Functions#Cross_Correlation|Cross_Correlation]]

====  Signal Functions ====

  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Data_Exists|Data Exists]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Frame_Count|Frame_Count]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Add|Add]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Sort|Sort]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Transpose|Transpose]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Interpolate|Interpolate]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#First_Derivative|First Derivative]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Second_Derivative|Second Derivative]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Resolve_Discontinuity|Resolve_Discontinuity]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Indefinite_Integral|Indefinite_Integral]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Cumulative_Sum|Cumulative_Sum]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Point_Relative_To_3_Points|Point_Relative_To_3Points]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Point_Tracked_By_3_Points|Point_Tracked_By_3Points]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Snip|Snip]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Spline|Spline]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Signal_Functions#Append_As...|Append_As]]

==== String Data ====

  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#Syntax|Specifying String Data]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#Modify|Modifying String Data]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#Parsing|Parsing String Data]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#String_Left|String_Left]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#String_Right|String_Right]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#String_Mid|String_Mid]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#String_Find|String_Find]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#String_Reverse_Find|String_Reverse_Find]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#String_To_Lower|String_To_Lower]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#String_To_Upper|String_To_Upper]]
  *[[Visual3D:Documentation:Pipeline:General_Information:String_Data#To_String|To_String]]

==== Least Squares Fitting of Data ====

  *[[Visual3D:Documentation:Pipeline:Expressions:Least_Squares_Fitting_of_Data#Best_Fit_Plane|Best_Fit_Plane]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Least_Squares_Fitting_of_Data#Best_Fit_Circle|Best_Fit_Circle]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Least_Squares_Fitting_of_Data#Best_Fit_Sphere|Best_Fit_Sphere]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Least_Squares_Fitting_of_Data#Simple_Linear_Regression|Simple_Linear_Regression]]

====  Intersection Functions ====

  *[[Visual3D:Documentation:Pipeline:Expressions:Intersection_Functions#Line_Line_Intersect|Line_Line_Intersect]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Intersection_Functions#Line_Plane_Intersect|Line_Plane_Intersect]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Intersection_Functions#Project_Point_On_Plane|Project_Point_On_Plane]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Intersection_Functions#Point_Distance_To_Plane|Point_Distance_To_Plane]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Intersection_Functions#Point_Distance_To_Line|Point_Distance_To_Line]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Intersection_Functions#Is_Point_Inside_Polygon|Is_Point_Inside_Polygon]]

==== Assigned Force Functions ====

  *[[Visual3D:Documentation:Pipeline:Expressions:Assigned_Force_Functions#Forces|Force]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Assigned_Force_Functions#Center_Of_Pressure|Center Of Pressure]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Assigned_Force_Functions#Free_Moment|Free Moment]]

==== Trigonometric Functions ====

  *[[Visual3D:Documentation:Pipeline:Expressions:Trigonometric_Functions#Cosine|Cosine]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Trigonometric_Functions#Sine|Sine]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Trigonometric_Functions#Tangent|Tangent]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Trigonometric_Functions#Cotangent|Cotangent]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Trigonometric_Functions#Arctangent|Arctangent]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Trigonometric_Functions#Cosine|Cosine]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Trigonometric_Functions#Arcsine|Arcsine]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Trigonometric_Functions#ArcCos|ArcCos]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Trigonometric_Functions#Arctan2|Arctan2]]

====  Array and Matrix Functions ====

  *[[Visual3D:Documentation:Pipeline:Expressions:Array_and_Matrix_Functions#Vector|Vector]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Array_and_Matrix_Functions#Unit_Vector|Unit_Vector]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Array_and_Matrix_Functions#List|List]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Array_and_Matrix_Functions#Rotation_Multiply|Rotation_Multiply]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Array_and_Matrix_Functions#Rotation_Inverse|Rotation_Inverse]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Array_and_Matrix_Functions#Rotation_Transpose|Rotation_Transpose]]
  *[[Visual3D:Documentation:Pipeline:Expressions:Array_and_Matrix_Functions#Pose_Euler2Rotation4x4|Pose_4x4]]

==== Common Math Expressions ====

  * **int(a**) - truncate each component to the nearest integer
  * **round(a)** - round each component to the nearest integer
  * **fmod(y,x)** - Returns the floating-point remainder of y/x (Note: y and x must be one dimensional signals; returns a one dimensional signal)
  * **abs(a)** - absolute value
  * **sign(a)**= sign of the signal ((a<0)=-1, (a>0)=1, (a==0) = 0
  * **sqrt(a)** - square root
  * **exp(a)** - exponent
  * **log(a)** - natural log
  * **log10(a)** - log base 10
  * **length(x)** -- creates the length (magnitude) of a vector
  * **distance(a,b)** -- distance between two signals.
  * **dot (a, b)** -- creates the dot product of a and b
  * **cross (a, b)** -- creates the cross product of a and b

===== Expression Examples =====

Examples of using Evaluate_Expressions can be found here: **[[Visual3D:Documentation:Pipeline:Expressions:Examples|Expressions Examples]]**