====== Pipeline Parameters ======

An important feature of the pipeline is the ability to create and use Pipeline Parameters, which allows users to store a text string for use in later Pipeline commands. In one sense it is similar to specifying a global variable, such as body weight, that could be used in computations. In practice, however, Pipeline Parameters are actually much more flexible than that: since pipeline commands permit multiple entries on a single line for a given parameter, and since the entire line can be represented as a string, a single Pipeline Parameter can represent multiple entries.

===== Using a Pipeline Parameter =====

Pipeline parameters are designated for Visual3D's parser by two colons before the parameter name. For example, Visual3D recognizes the pipeline parameter named TEST as ::TEST

As an example of using a Pipeline Parameter, we could assign a number of C3D file names to a Pipeline Parameter called C3D_FILE and then reference it when assigning a TAG called TEST_TAG to a group of files:

<code>
Assign_Tags_To_File
/MOTION_FILE_NAMES=::C3D_FILE
! /QUERY=
/TAGS=TEST_TAG
;
</code>

Things can get a little more complicated when pipeline parameters are [[visual3d:documentation:pipeline:expressions:expression_syntax#pipeline_parameter_syntax|used in expressions]].

An example pipeline using pipeline parameters can be found in the sample files for the [[visual3d:tutorials:knowledge_discovery:typical_processing_session|Typical Processing Session]] tutorial.

===== Automatic Creation of Pipeline Parameters =====

Several of the pipeline commands are capable of prompting the user for input. The value of the variable is automatically saved as a pipeline parameter so that it can be used elsewhere in the pipeline. For example,

<code>
File_Open
! FILE_NAME= 
;
</code>

If the variable FILE_NAME is empty (as shown above), then a browse dialog will appear allowing the user to select the file(s). This file(s) can be set to a pipeline parameter named C3D_FILE as follows:

<code>
Set_Pipeline_Parameter 
/PARAMETER_NAME=C3D_FILE 
/PARAMETER_VALUE=::FILE_NAME 
;
</code>

The PARAMETER_VALUE is assigned the variable name (e.g. FILE_NAME) from the previous command. For subsequent commands the user can use ::C3D_FILE to refer to the files that were selected by the user. This pipeline parameter will not be modified unless the user explicitly overwrites it.

===== Pipeline Parameters Syntax =====

Concatenating pipeline parameters is tricky because of the rules used for parsing the parameters in Visual3D. For example, given a pipeline parameter representing a signal name ::NAME, to use this parameter in the following command is straightforward.

<code>
Multiply_Signals_By_Constant
/Signal_Types= TARGET 
/Signal_Names=::NAME 
/Signal_Folder= ORIGINAL 
/Signal_Components= X 
/Result_Name=::NAME 
/Result_Folder= PROCESSED 
/Result_Suffix=  
/Constant= 1 
:;
</code>

The equivalent result can be accomplished using [[visual3d:documentation:pipeline:expressions:expressions_overview|Evaluate_Expression]], but now the syntax for including the parameter ::NAME in the definition of the signal name is much uglier due to the rules for parsing parameters.

<code>
Evaluate_Expression
/EXPRESSION=TARGET::ORIGINAL&:&:&::NAME&-VECTOR(1,0,0)
/RESULT_NAME=::NAME
/RESULT_TYPE=DERIVED
/RESULT_FOLDER=PROCESSED
;
</code>

==== Pipeline Parameters in Expressions ====
As another example, the following command is a valid expression:

<code>
Evaluate_Expression
/EXPRESSION=MODEL::SEGMENT::RFT::MASS
/RESULT_NAME=SEG_MASS
/RESULT_TYPE=METRIC
/RESULT_FOLDER=PROCESSED
;
</code>

But given a pipeline parameter SEG_NAME the following expression is invalid:

<code>
Evaluate_Expression
/EXPRESSION=MODEL::SEGMENT::&::SEG_NAME&::MASS
/RESULT_NAME=SEG_MASS
/RESULT_TYPE=METRIC
/RESULT_FOLDER=PROCESSED
;
</code>

One possible solution is as follows:

<code>
Evaluate_Expression
/EXPRESSION=MODEL::SEGMENT&:&:&::SEG_NAME&:&:MASS 
/RESULT_NAME=SEG_MASS 
/RESULT_TYPE=METRIC 
/RESULT_FOLDER=PROCESSED 
;
</code>

==== Syntax Specification ====

Visual3D's command pre-processor replaces all global pipeline parameters before parsing the command.

  - This first looks for a pipeline command at the start of the parameter. For example =::something
  - Then it looks for all ampersand colon colons. For example &::something&
  - It then replaces what is between the ampersands (or to end of line) assuming it is a pipeline parameter.
  - When using a signal name, the natural thing to follow the second ampersand is the colon colon for the next signal name item. For example &::something&::MASS
    - But, the preprocessor looks at the &::MASS and assumes this is another global pipeline parameter because it is an ampersand colon colon &::something
    - To work around this, you need to write the line in a way that &::MASS is not treated as a global pipeline parameter. To do this, you can add another ampersand to concatenate the colons. &:&:MASS This fools the preprocessor so it doesn't find an &::
    - It's kind of a kludge, but it makes sense when you understand it first looks for all &:: to do a replacement. In the case of the expression &::something&::MASS the term ::MASS becomes a null string because it doesn't exist as a global pipeline parameter.

===== Default Pipeline Parameters =====

Visual3D pipeline commands automatically creates pipeline parameters whenever a command is executed. The general syntax of a Visual3D command is:

<code>
Command_Name 
/Parameter1= something 
/Parameter2= this_value+another_value 
/Parameter3= 3.14 
!/Parameter4= default_value_for_Parameter4
;
</code>

When the command is executed, each of the parameters is stored as a pipeline parameter, and can be referred to in other commands. For example, the dummy command above, in the context only of the pipeline parameters, would be equivalent to the following commands:

<code>
Set_Pipeline_Parameter
/PARAMETER_NAME=Parameter1 
/PARAMETER_VALUE=something
;

Set_Pipeline_Parameter 
/PARAMETER_NAME=Parameter2 
/PARAMETER_VALUE=this_value+another_value 
;

Set_Pipeline_Parameter 
/PARAMETER_NAME=Parameter3 
/PARAMETER_VALUE=3.14
;

Set_Pipeline_Parameter 
/PARAMETER_NAME=Parameter4
/PARAMETER_VALUE=default_value_for_Parameter4
;
</code>

The consequence is that users must be very conscious of the pipeline parameters that they create explicitly. If common names like FOLDER are defined by the user, they may actually change their value over a series of commands that include a parameter named FOLDER.

===== Example =====

An [[visual3d:documentation:pipeline:pipeline_commands:pipeline_parameters_example|example]] is given that adds a TAG to an individual file based on a C3D parameter. In this case, the file will be tagged from the motion system manufacturer according to the information found in the [[visual3d:documentation:c3d_signal_types:c3d_format|C3D file]]'s corresponding parameter.