Differences

This shows you the differences between two versions of the page.

--- visual3d:documentation:pipeline:expressions:reserved_names [2024/06/19 12:50] – sgranger
+++ visual3d:documentation:pipeline:expressions:reserved_names [2025/06/20 18:45] (current) – Cleaned up page and added section headers. wikisysop
@@ Line 1: / Line 1: @@
-visual3d reserved names
+====== Reserved Names ======
-===== contents =====
+Certain names are reserved within the Visual3D pipeline/expression syntax in order to simplify common tasks.
+===== CURRENT_SIGNAL =====
-  * [[#current_signal|1 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.
-    * [[#used_to_allow_multiple_signals_to_be_specified_in_an_expression|1.1 used to allow multiple signals to be specified in an expression]]
-    * [[#used_to_specifying_all_signals_of_a_given_type|1.2 used to specifying all signals of a given type]]
-    * [[#apply_as_suffix_to_signal_name|1.3 apply_as_suffix_to_signal_name]]
-  * [[#nan|2 nan]]
-  * [[#isnan|3 isnan]]
+==== Example: Compute the length of one signal ====
-===== current_signal =====
+The legacy syntax is:
-used to refer to a specific signal with a simple syntax
+<code>
-compute the length of one signal.
+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 is:
+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.
-**evaluate_expression**
+<code>
-/expression=length(target::original::rft1)
+! Create a pipeline parameter containing the marker name
-/result_types=derived
+Set_Pipeline_Parameter
-/result_folders=processed
+/PARAMETER_NAME=MARKER
-/result_name=_length
+/PARAMETER_VALUE=RFT1
-/apply_as_suffix_to_signal_name=true
+;
-**;**
-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.
-! create a pipeline parameter containing the marker name
+Evaluate_Expression
-**set_pipeline_parameter**
+/EXPRESSION=LENGTH(TARGET::ORIGINAL&:&:&::MARKER&)
-/parameter_name=marker
+/RESULT_TYPES=DERIVED
-/parameter_value=rft1
+/RESULT_FOLDERS=PROCESSED
-**;**
+/RESULT_NAME=_LENGTH
-**evaluate_expression**
+;
-/expression=length(target::original&:&:&::marker&)
+</code>
-/result_types=derived
-/result_folders=processed
-/result_name=_length
-**;**
-this gets even more complicate if the folder is also a pipeline parameter.
-an alternative is the following
+This gets even more complicate if the folder is also a pipeline parameter. An alternative is the following:
-**evaluate_expression**
+<code>
-/expression=length(current_signal)
+Evaluate_Expression
-/signal_types=target
+/EXPRESSION=LENGTH(CURRENT_SIGNAL)
-/signal_folder=original
+/SIGNAL_TYPES=TARGET
-/signal_names=::marker
+/SIGNAL_FOLDER=ORIGINAL
-/result_types=derived
+/SIGNAL_NAMES=::MARKER
-/result_folders=processed
+/RESULT_TYPES=DERIVED
-/result_name=_length
+/RESULT_FOLDERS=PROCESSED
-/apply_as_suffix_to_signal_name=true
+/RESULT_NAME=_LENGTH
-**;**
+/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
-\\
+;
+</code>
-=== used to allow multiple signals to be specified in an expression ===
+==== Example: Specify multiple signals in an expression ====
-compute the length of targets rft1, rft2, and rft3 in the original folder
+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:
-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
+;
-[[visual3d:documentation:pipeline:pipeline_commands:for_each_and_end_for_each|for_each]]
+Evaluate_Expression
-/iteration_parameter_name= markers
+/EXPRESSION=LENGTH(TARGET::ORIGINAL&:&:&::MARKERS&)
-/items= rft1+rft2+rft3
+/SIGNAL_TYPES=TARGET
-**;**
+/SIGNAL_FOLDER=ORIGINAL
-**evaluate_expression**
+/SIGNAL_NAMES=
-/expression=length(target::original&:&:&::markers&)
+/RESULT_TYPES=DERIVED
-/signal_types=target
+/RESULT_FOLDERS=PROCESSED
-/signal_folder=original
+/RESULT_NAME=::MARKERS
-/signal_names=
+/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
-/result_types=derived
+;
-/result_folders=processed
-/result_name=::markers
-/apply_as_suffix_to_signal_name=true
-**;**
-end_for_each
-/iteration_parameter_name=markers
-**;**
-using current_signal
-**evaluate_expression**
+End_For_Each
-/expression=length(current_signal)
+/Iteration_Parameter_Name=MARKERS
-/signal_types=target
+;
-/signal_folder=original
+</code>
-/signal_names=rft1+rft2+rft3
-/result_types=derived
-/result_folders=processed
-/result_name=_length
-/apply_as_suffix_to_signal_name=true
-**;**
-\\
+Instead, using the CURRENT_SIGNAL reserved name:
-=== used to specifying all signals of a given type ===
+<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>
-compute the length of all targets in the original folder
+==== Example: Specify all signals of a given type ====
-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
+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:
-[[visual3d:documentation:pipeline:pipeline_commands:set_pipeline_parameter_to_list_of_signal_names|set_pipeline_parameter_to_list_of_signal_names]]
+<code>
-/parameter_name=all_targets
+Set_Pipeline_Parameter_To_List_Of_Signal_Names
-/signal_type=target
+/PARAMETER_NAME=ALL_TARGETS
-/signal_folder=original
+/SIGNAL_TYPE=TARGET
-**;**
+/SIGNAL_FOLDER=ORIGINAL
-[[visual3d:documentation:pipeline:pipeline_commands:for_each_and_end_for_each|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
-**;**
-using current_signal
-**evaluate_expression**
+For_Each
-/expression=length(current_signal)
+/Iteration_Parameter_Name= MARKERS
-/signal_types=target
+/Items= ::ALL_TARGETS
-/signal_folder=original
+;
-/signal_names=
-/result_types=derived
-/result_folders=processed
-/result_name=_length
-/apply_as_suffix_to_signal_name=true
-**;**
-\\
+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
+;
-=== apply_as_suffix_to_signal_name ===
+End_For_Each
+/Iteration_Parameter_Name=MARKERS
+;
+</code>
-if **apply_as_suffix_to_signal_name** is **true**, or result_names.size() == signal_names.size()
+Instead, using the CURRENT_SIGNAL reserved name:
-compute 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>
-**evaluate_expression**
+==== Example: Apply suffix to signal name ====
-/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
-**;**
-compute the length of two targets (rft1 and rft2) in the original folder
-**evaluate_expression**
+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.
-/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
-**;**
-compute a best_plane_fit for multiple signals at each frame of data
-**evaluate_expression**
+For example, when computing the length of all TARGETS in the ORIGINAL folder.
-/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
-**;**
-\\
-if **apply_as_suffix_to_signal_name** is **false**, and result_names.size() == 1
-compute the length of one target (target::original::rft1)
+<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>
-**evaluate_expression**
+Or when computing the length of two TARGETS (RFT1 and RFT2) in the ORIGINAL folder
-/expression=length(target::original::rft1)
-/result_types=derived
-/result_folders=processed
-/result_name=rft1_length
-**;**
-===== nan =====
-nan is a reserved string used to designate "not a number".
+<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>
-visual3d commands refer to [[visual3d:documentation:c3d_signal_types:data_not_found|no_data or data_not_found]] as nan
+Also when calculating a Best_Plane_Fit for multiple signals at each frame of data.
-for example, the expression 1/0 results in nan
+<code>
-===== isnan =====
+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>
-isnan(expression) tests values against nan - if the number is nan the result is 1, otherwise the result is 0
+===== NAN =====
-[set_pipeline_parameter_from_expression]
+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.
-/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]
+For example, the expression 1/0 results in NAN.
-/parameter_name= nan_test
-/expression=isnan(15)
-/as_integer=true
-**;**
-::nan_test = 0
-example: set negative values to no_data
-if the z-component of the lelb signal is below 0 set the frame to no_data
+==== isNAN function ====
-**evaluate_expression**
+The function isNAN(expression) tests values against NAN - If the number is NAN the result is 1, otherwise the result is 0.
-/expression=(target::original::lelb::z>0)/(target::original::lelb::z>0)*target::original::lelb
-/result_name=lelb
-/result_type=target
-/result_folder=processed
-**;**
+<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.