====== Reserved Names ======

Certain names are reserved within the Visual3D pipeline/expression syntax in order to simplify common tasks.


===== CURRENT_SIGNAL =====

The CURRENT_SIGNAL reserved named is used to refer to a specific signal within the input to [[visual3d:documentation:pipeline:expressions:expressions_overview|Evaluate_Expression]] with a simple syntax.

==== Example: Compute the length of one signal ====

The legacy syntax is:

<code>
Evaluate_Expression
/EXPRESSION=LENGTH(TARGET::ORIGINAL::RFT1)
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=_LENGTH
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;
</code>

The legacy syntax can get complicated if [[Visual3D:Documentation:Pipeline:General_Information:Pipeline_Parameters|Pipeline Parameters]] are used in the signal name because of the order in which equations are parsed.

<code>
! Create a pipeline parameter containing the marker name
Set_Pipeline_Parameter
/PARAMETER_NAME=MARKER
/PARAMETER_VALUE=RFT1
;

Evaluate_Expression
/EXPRESSION=LENGTH(TARGET::ORIGINAL&:&:&::MARKER&)
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=_LENGTH
;
</code>

This gets even more complicate if the folder is also a pipeline parameter. An alternative is the following:

<code>
Evaluate_Expression
/EXPRESSION=LENGTH(CURRENT_SIGNAL)
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=::MARKER
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=_LENGTH
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;
</code>


==== Example: Specify multiple signals in an expression ====

This example computes the length of TARGETS RFT1, RFT2, and RFT3 in the ORIGINAL folder. The legacy implementation requires a [[Visual3D:Documentation:Pipeline:Pipeline_Commands:For_Each_and_End_For_Each|For_Each]] statement:

<code>
For_Each
/Iteration_Parameter_Name= MARKERS
/Items= RFT1+RFT2+RFT3
;

Evaluate_Expression
/EXPRESSION=LENGTH(TARGET::ORIGINAL&:&:&::MARKERS&)
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=::MARKERS
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;

End_For_Each
/Iteration_Parameter_Name=MARKERS
;
</code>

Instead, using the CURRENT_SIGNAL reserved name:

<code>
Evaluate_Expression
/EXPRESSION=LENGTH(CURRENT_SIGNAL)
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=RFT1+RFT2+RFT3
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=_LENGTH
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;
</code>

==== Example: Specify all signals of a given type ====

This example computes the length of all TARGETS in the ORIGINAL folder. The legacy implementation requires a [[Visual3D:Documentation:Pipeline:Pipeline_Commands:For_Each_and_End_For_Each|For_Each]] command and a command to get the names of all of the TARGETS:

<code>
Set_Pipeline_Parameter_To_List_Of_Signal_Names
/PARAMETER_NAME=ALL_TARGETS
/SIGNAL_TYPE=TARGET
/SIGNAL_FOLDER=ORIGINAL
;

For_Each
/Iteration_Parameter_Name= MARKERS
/Items= ::ALL_TARGETS
;

Evaluate_Expression
/EXPRESSION=LENGTH(TARGET::ORIGINAL&:&:&::MARKERS&)
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=::MARKERS
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;

End_For_Each
/Iteration_Parameter_Name=MARKERS
;
</code>

Instead, using the CURRENT_SIGNAL reserved name:

<code>
Evaluate_Expression
/EXPRESSION=LENGTH(CURRENT_SIGNAL)
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=_LENGTH
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;
</code>

==== Example: Apply suffix to signal name ====

If the /APPLY_AS_SUFFIX_TO_SIGNAL_NAME parameter is true or if the number of result signals is the same as the number of input signals, then a suffix can be easily added for the result signal's name.

For example, when computing the length of all TARGETS in the ORIGINAL folder.

<code>
Evaluate_Expression
/EXPRESSION=LENGTH(CURRENT_SIGNAL)
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=_LENGTH
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;
</code>

Or when computing the length of two TARGETS (RFT1 and RFT2) in the ORIGINAL folder

<code>
Evaluate_Expression
/EXPRESSION=LENGTH(CURRENT_SIGNAL)
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=RFT1+RFT2
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=_LENGTH
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;
</code>

Also when calculating a Best_Plane_Fit for multiple signals at each frame of data.

<code>
Evaluate_Expression
/EXPRESSION=Best_Fit_Plane(CURRENT_SIGNAL)
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=LSK_1+LSK_2+LSK_3
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=PROCESSED
/RESULT_NAME=LSK_PLANE
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;
</code>

===== NAN =====

NAN is a reserved string used to designate "Not a Number". Visual3D commands refer to [[Visual3D:Documentation:C3D_Signal_Types:DATA_NOT_FOUND|NO_DATA or DATA_NOT_FOUND]] as NAN.

For example, the expression 1/0 results in NAN.

==== isNAN function ====

The function isNAN(expression) tests values against NAN - If the number is NAN the result is 1, otherwise the result is 0.

<code>
Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME= NAN_TEST
/EXPRESSION=ISNAN(1/0)
/AS_INTEGER=TRUE
;

::NAN_TEST = 1

Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME= NAN_TEST
/EXPRESSION=ISNAN(-999999.000000)
/AS_INTEGER=TRUE
;

::NAN_TEST = 1 ! Returns "1" because -999999 is equal to Data Not Found in Visual3D.

Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME= NAN_TEST
/EXPRESSION=ISNAN(15)
/AS_INTEGER=TRUE
;

::NAN_TEST = 0
</code>

==== Example: Set negative values to NO_DATA ====

In this example, if the z-component of the LELB signal is below 0 then we will set the frame to NO_DATA.

<code>
Evaluate_Expression
/EXPRESSION=(TARGET::ORIGINAL::LELB::Z>0)/(TARGET::ORIGINAL::LELB::Z>0)*TARGET::ORIGINAL::LELB
/RESULT_NAME=LELB
/RESULT_TYPE=TARGET
/RESULT_FOLDER=PROCESSED
;
</code>

===== ORIGIN =====

Internally Visual3D specifies the location ORIGIN. To avoid confusion, this string cannot be used to name either a TARGET or a LANDMARK.