HAS-Motion Software Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== 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

<code>
SIGNAL_TYPE::SIGNAL_FOLDER::SIGNAL_NAME
</code>

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:

<code>
SIGNAL_TYPE::SIGNAL_FOLDER::SIGNAL_NAME::X
</code>

To specify a specific frame from a signal, e.g. Frame 2, use the square bracket notation as follows:

<code>
SIGNAL_TYPE::SIGNAL_FOLDER::SIGNAL_NAME[2]
</code>

Signals, metrics, and other data stored in the GLOBAL Workspace can be specified by prepending the GLOBAL namespace:

<code>
GLOBAL::SIGNAL_TYPE::SIGNAL_FOLDER::SIGNAL_NAME
</code>

**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:

<code>
METRIC_NAME
</code>

=== 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:

<code>
Name = BALL
Expression = Best_Fit_Sphere(List(BALL1, BALL2, BALL3, BALL4, BALL5, BALL6))
</code>

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:

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

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:

<code>
MODEL::METRIC::NAME
MODEL::TARGET::MARKER_NAME
MODEL::LANDMARK::LANDMARK_NAM
</code>

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:

<code>
MODEL::TARGET::MARKER_NAME::X
</code>

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).:

<code>
MODEL::FORCE::FP1
</code>

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.

<code>
Evaluate_Expression
/EXPRESSION=MODEL::FORCE::FP1
/RESULT_NAME=GLOBAL::SCOTT
/RESULT_TYPE=DERIVED
! /RESULT_FOLDER=PROCESSED
;
</code>

==== 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:

<code>
/EXPRESSION=2*pi()*&::LP_FREQ
</code>

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

<code>
&::LP_FREQ&*&::MULTIPLIER&-&::CONSTANT
</code>

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.

<code>
Evaluate_Expression
/EXPRESSION=ANALOG::FILTERED&:&:&::INDEX&:&:&X&-METRIC::PROCESSED&:&:&::INDEX&_zero
/RESULT_NAME=::INDEX
/RESULT_TYPE=ANALOG
/RESULT_FOLDER=OFFSET
;
</code>

==== 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::

<code>
TAG::TAG_NAME
</code>

==== 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:

<code>
PARAMETER::GROUP::PARAMETER_NAME
</code>