Table of Contents
Example using the AMP Operator
Contents
The Ampersand Operator
For first time users of Visual3D's scripting language the use of the & operator may not be straightforward. The Expressions page contains some links and examples of how to use this operator including:
The ampersand (&) is used in pipeline commands to concatenate strings together, and is a separator for the parser to find pieces that need to be parsed separately. To get the most out of this tutorial, it is recommended that you run the commands in Visual3D alongside reading the text descriptions, as the Pipeline Processing Results dialog is a helpful tool for understanding and debugging in this interface.
Example 1: Jane Elizabeth Doe
Let there be a Visual3D workspace in which we have three parameters: FIRST_NAME, MIDDLE_NAME and LAST_NAME. Let us set each of these parameter values to be JANE, ELIZABETH and DOE, respectively:
Select_Active_File !/FILE_NAME=*.c3d ! /QUERY= ! /SUBJECT_TAGS=NO_SUBJECT ; Set_Pipeline_Parameter /PARAMETER_NAME=FIRST_NAME /PARAMETER_VALUE=JANE ; Set_Pipeline_Parameter /PARAMETER_NAME=MIDDLE_NAME /PARAMETER_VALUE=ELIZABETH ; Set_Pipeline_Parameter /PARAMETER_NAME=LAST_NAME /PARAMETER_VALUE=DOE ;
Say we want to create a new signal with the value JANE ELIZABETH DOE. We start by opening the pipeline command Evaluate_Expression:
Evaluate_Expression /EXPRESSION=::FIRST_NAME::MIDDLE_NAME::LAST_NAME /RESULT_TYPES=DERIVED /RESULT_FOLDERS=DEVELOPMENT /RESULT_NAME=RESULT ;
The output for running this command is “ERROR! Parameter EXPRESSION is not specified, and is a required parameter!”. If you run this, you will also notice that in the Pipeline Processing Results dialog the EXPRESSION field will be blank. When the expression field has been populated in the pipeline but appears blank in the results dialog, this typically indicates a syntax error.
Let's first clarify what the “::” does in this scripting language. Using the parameter FIRST_NAME, let us use Evaluate_Expression to see what FIRST_NAME evaluates to:
Evaluate_Expression /EXPRESSION=FIRST_NAME /RESULT_TYPES=DERIVED /RESULT_FOLDERS=DEVELOPMENT /RESULT_NAME=RESULT ;
The expression evaluates to FIRST_NAME, when what we wanted was JANE. Now if we add the “::” to our evaluate expression:
Evaluate_Expression /EXPRESSION=::FIRST_NAME /RESULT_TYPES=DERIVED /RESULT_FOLDERS=DEVELOPMENT /RESULT_NAME=RESULT ;
This evaluates to JANE. This tells us that the “::” allows us to access the information stored under the variable FIRST_NAME.
Recall earlier in this example, when the “ERROR! Parameter EXPRESSION is not specified, and is a required parameter!”. indicated a syntax error. We know that the “::” is correct because we want to access the data in the variables FIRST_NAME, MIDDLE_NAME, and LAST_NAME. This is where the & operator comes in.
The & operator acts as “glue” to stick multiple variables and strings together in the same expression. For example:
Evaluate_Expression /EXPRESSION=::FIRST_NAME&::MIDDLE_NAME&::LAST_NAME /RESULT_TYPES=DERIVED /RESULT_FOLDERS=DEVELOPMENT /RESULT_NAME=RESULT ;
Gives the result: JANEELIZABETHDOE. If you wanted to add spaces to this expression, you would use:
Evaluate_Expression /EXPRESSION=&::FIRST_NAME& &::MIDDLE_NAME& &::LAST_NAME /RESULT_TYPES=DERIVED /RESULT_FOLDERS=DEVELOPMENT /RESULT_NAME=RESULT ;
Which now evaluates to JANE ELIZABETH DOE.
Example 2: Jane and John Doe
Say we want to compare two string variables A and B:
Select_Active_File /FILE_NAME=*.c3d ! /QUERY= ! /SUBJECT_TAGS=NO_SUBJECT ; Set_Pipeline_Parameter /PARAMETER_NAME=A /PARAMETER_VALUE="jane" ; Set_Pipeline_Parameter /PARAMETER_NAME=B /PARAMETER_VALUE="john" ; Evaluate_Expression /EXPRESSION=(::A=::B) /RESULT_TYPES=DERIVED /RESULT_FOLDERS=DEVELOPMENT /RESULT_NAME=RESULT ;
This expression successfully evaluates (meaning it gives no errors), but does not produce the correct result. As you can see in the image below, the expression explicitly evaluates (::A=::B) to a value of 0. It does not actually read in the variables that we want to compare.
Let's add some “glue” and see what happens:
Evaluate_Expression /EXPRESSION=(::A&=&::B) /RESULT_TYPES=DERIVED /RESULT_FOLDERS=DEVELOPMENT /RESULT_NAME=RESULT ;
This evaluates the expression jane = john as 1 or True…hmmm. Practically speaking, we know this is not the case. This has occured because the Set_Pipeline_Parameter function does not read the “ ” we assigned to these variables earlier. So to evaluate if these strings match, we have to add them back in:
Evaluate_Expression
/EXPRESSION=("&::A&"="&::B&")
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=DEVELOPMENT
/RESULT_NAME=RESULT
;
This evaluates the statement jane = john to 0 or False. Let's test to see if jane = jane is true:
Evaluate_Expression
/EXPRESSION=("&::A&"="&::A&")
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=DEVELOPMENT
/RESULT_NAME=RESULT
;
And voila, there you have it.
Example 3: Jane and John go to the Market
Let’s say Jane and John have gone to a fruit stand at a local farmer’s market. Jane has purchased 33 apples and John has purchased 24 oranges. These values are stored in the DERIVED signal type under the folder MARKET as APPLES and ORANGES.
Let’s say you wanted to iterate through the market folder to find the total units of fruit that Jane and John purchased. You could in this instance, simply call an evaluate expression for both and sum the totals. But if you have 5 types of fruit, or 20, it would be easier to calculate this parameter in a for loop.
We start by setting all files to active and setting our total count to 0:
Select_Active_File /FILE_NAME=*.c3d ! /QUERY= ! /SUBJECT_TAGS=NO_SUBJECT ;
Evaluate_Expression /EXPRESSION=0 /RESULT_TYPES=DERIVED /RESULT_FOLDER= MARKET /RESULT_NAME=TOTAL ;
Because in this case the data we are dealing with is a variable within the workspace, not a pipeline parameter, we have to access it differently. To simply access the number of oranges we could use:
Evaluate_Expression /EXPRESSION=DERIVED::MARKET::ORANGES /RESULT_TYPES=DERIVED /RESULT_FOLDERS=MARKET /RESULT_NAME=ORANGES ;
However, if we wanted to loop through these files, we again need to use the & operator. In the example below, the iteration parameter name is FRUIT and there are two iteration parameter items, APPLES and ORANGES.
For_Each /ITERATION_PARAMETER_NAME=FRUIT ! /ITERATION_PARAMETER_COUNT_NAME= /ITEMS=APPLES + ORANGES ; Evaluate_Expression /EXPRESSION=DERIVED::MARKET::TOTAL + DERIVED::MARKET::FRUIT /RESULT_TYPES=DERIVED /RESULT_FOLDERS=MARKET /RESULT_NAME=TOTAL ; End_For_Each /ITERATION_PARAMETER_NAME=FRUIT ;
Executing this example will cause the “variable was not created because there were no Results” error. This is because of the way we accessed the FRUIT iteration parameter. Because FRUIT is an iteration parameter, we need to access it as ::FRUIT to get the values of APPLES and ORANGES. However, because ::FRUIT will evaluate to APPLES or ORANGES, we need to “glue” and extra “::” before the iteration parameter:
For_Each /ITERATION_PARAMETER_NAME=FRUIT !/ITERATION_PARAMETER_COUNT_NAME= /ITEMS= APPLES + ORANGES ; Evaluate_Expression /EXPRESSION=DERIVED::MARKET::TOTAL + DERIVED::MARKET&:&:&::FRUIT& /RESULT_TYPES=DERIVED /RESULT_FOLDERS=MARKET /RESULT_NAME=TOTAL ; End_For_Each /ITERATION_PARAMETER_NAME=FRUIT ;
This will correctly evaluate TOTAL to 57 fruits.