===== Expression Syntax =====
This page provides an overview of the syntax required to use [[visual3d:documentation:pipeline:expressions:expressions_overview|expressions]] to their full potential.
==== Data Tree Syntax ====
Signals from the [[visual3d:documentation:visual3d_signal_types:data_tree|data tree]] can be referenced in expressions by using the complete
SIGNAL_TYPE::SIGNAL_FOLDER::SIGNAL_NAME
syntax. To specify a particular element of a signal, e.g. the X Component, simply concatenate the element's name to the end of this:
SIGNAL_TYPE::SIGNAL_FOLDER::SIGNAL_NAME::X
To specify a specific frame from a signal, e.g. Frame 2, use the square bracket notation as follows:
SIGNAL_TYPE::SIGNAL_FOLDER::SIGNAL_NAME[2]
Signals, metrics, and other data stored in the GLOBAL Workspace can be specified by prepending the GLOBAL namespace:
GLOBAL::SIGNAL_TYPE::SIGNAL_FOLDER::SIGNAL_NAME
**NOTE**: Global data can always be accessed in an Expression regardless of the [[visual3d:documentation:definitions:active_files|Active Files]].
=== Examples for Specifying a Data Tree Signal ===
TARGET::ORIGINAL::RFT1 = Signal RFT1 in the TARGET type and ORIGINAL folder\\
ANALOG::PROCESSED::FX1 = Signal FX1 in the ANALOG type and PROCESSED folder\\
PARAMETER::ANALOG::RATE= Parameter RATE in the ANALOG group of the C3D PARAMETERS\\
==== Model Builder Syntax ====
Expressions in the Model builder have a simpler syntax because only one version of the metric can exist. In this case, the Type and Folder need not be specified and only the Metric Name is required:
METRIC_NAME
=== Example for Using a Model Metric ===
Given 6 markers placed on the surface of a round ball (BALL1, BALL2, BALL3, BALL4, BALL5, BALL6), this example demonstrates how to create a model metric at the centre of a best fit sphere to the ball.
Fill in the the following values in the dialog or pipeline command to create the model metric:
Name = BALL
Expression = Best_Fit_Sphere(List(BALL1, BALL2, BALL3, BALL4, BALL5, BALL6))
The resulting metric will have 3 values separated by a comma, e.g. the 3 components of the center's coordinates. You can create a landmark based on this model metric by using the following syntax:
{{:BallCenterLandmark.jpg}}
The syntax may seem a little strange, but [1,1] refers to the first element of the first frame
==== Model Metric Syntax ====
Model metrics can also be referenced more broadly throughout Visual3D. The following Model data is available to be used in expressions:
MODEL::SEGMENT::segname::LENGTH
MODEL::SEGMENT::segname::DEPTH
MODEL::SEGMENT::segname::CENTER_OF_MASS
MODEL::SEGMENT::segname::IXX
MODEL::SEGMENT::segname::IYY
MODEL::SEGMENT::segname::IZZ
MODEL::SEGMENT::segname::MASS
MODEL::SEGMENT::segname::PROXIMAL_RADIUS
MODEL::SEGMENT::segname::DISTAL_RADIUS
MODEL::SEGMENT::segname::ORIGIN
where "segname" is the name of the [[visual3d:documentation:modeling:segments:segment_overview|segment]]. Visual3D uses [[visual3d:documentation:modeling:segments:segment_default_names|default, 3-letter acronyms for segment names]], though these can be modified by the user.
A model's metrics, targets, and landmarks can all be referenced by using the appropriate namespace:
MODEL::METRIC::NAME
MODEL::TARGET::MARKER_NAME
MODEL::LANDMARK::LANDMARK_NAM
As previously, if you want to refer to a specific component of a signal then the component's name can be added to the end of the signal name:
MODEL::TARGET::MARKER_NAME::X
Forces can be referenced using the "FORCE" namespace and will create a global signal containing the average value of the specified FORCE signal over the range of frames specified for the model (e.g. if a range is not specified, all frames will be used).:
MODEL::FORCE::FP1
The command is executed once for each active file, so the resulting signal will continually be overwritten and current results will correspond to the last file processed.
Evaluate_Expression
/EXPRESSION=MODEL::FORCE::FP1
/RESULT_NAME=GLOBAL::SCOTT
/RESULT_TYPE=DERIVED
! /RESULT_FOLDER=PROCESSED
;
==== Pipeline Parameter Syntax ====
The syntax for using a pipeline parameter as part of an expression is a bit unusual and requires an understanding of how Visual3D parses parameters and pre-processes commands.
The ampersand **&** is used in pipeline commands to concatenate strings together and is therefore a separator for the parser to find the pieces that need to be parsed separately. For example, to use a pipeline parameter LP_FREQ:
/EXPRESSION=2*pi()*&::LP_FREQ
The ampersand tells the parser to take the string "2*pi()*" and the parameter name "::LP_FREQ" separately through the pre-parser. The first part is just taken as is since it is a standard string. The second part is prefixed with "::", indicating that this is the name of a pipeline parameter.
If you have more complex expressions, you might need to surround each pipeline parameter with an ampersand
&::LP_FREQ&*&::MULTIPLIER&-&::CONSTANT
which may evaluate to something like: 60*1.4-90.0 once all the pipeline parameters are substituted. The general rule to follow is to surround the pipeline parameter with ampersands.
=== Using a pipeline parameter as part of a signal definition ===
Pipeline parameters and signal definition both use "::" for different purposes. Because of this, and because of the parsing order for expressions, the required syntax for using a pipeline parameter as part of a signal definition is to prefix the pipeline parameter's name with "&:&:&::".
The following Evaluate_Expression incorporates a pipeline parameter to specify which signals should be subtracted.
Evaluate_Expression
/EXPRESSION=ANALOG::FILTERED&:&:&::INDEX&:&:&X&-METRIC::PROCESSED&:&:&::INDEX&_zero
/RESULT_NAME=::INDEX
/RESULT_TYPE=ANALOG
/RESULT_FOLDER=OFFSET
;
==== Tag Syntax ====
[[visual3d:documentation:pipeline:file_commands:assign_tags_to_file|File tags]] can be included in an expression by prefixing the tag name with the namespace TAG::
TAG::TAG_NAME
==== C3D Parameter Syntax ====
[[visual3d:documentation:c3d_signal_types:c3d_format#c3d_parameter_format|C3D parameters]] can be referenced from the PARAMETER:: namespace and providing both the GROUP and NAME:
PARAMETER::GROUP::PARAMETER_NAME