Binding Expressions
Expressions allow you to connect ARDI properties to the effects you apply in ARDI-VE.
You can substitute a property where you'd normally have any string or numeric value in your effects.
For example, you could have the following….
<spin speed="10"/>
…which can be used to spin an asset around at ten degrees per second.
But to make our scene look better, we can use our properties to drive our effects. For example, if we already have a property called 'Rotation Speed' on our asset, we can do the following…
<spin speed="[Rotation Speed]"/>
…which links our Rotation Speed property to the speed that the asset spins.
Format Options
Not every value maps directly to the values expected by the effects. For example, the rotation speed above is expected to be in degrees-per-second, but your real-world values would usually be different - often revolutions-per-minute.
Because of this, there are several options available when binding properties to effects.
Basic Copy
[ <property name/number> ]
This simply copies the property value directly into the effect.
Converting to Boolean
[ <property name/number>|value1|value2|value3 ]
This expression results in a boolean (yes/no) value. When the property (for example, 'Mode') matches any one of the given values, the boolean is 'true'. Otherwise, it's 'false'.
Using Measurement Scales
[ <property name/number>:%:<minimum>:<maximum>]
This uses the minimum and maximum scale of the measurement to rescale the value. It's most often used to convert properties from a raw value (for instance, tank level measured in meters) to a height (tank level measured in %).
Let's take a look at the following example…
Tank Level - Analogue value, 0.5 - 2.5m
If you used this expression…
[ Tank Level:%:0:100 ]
Then you would get the following values….
| Input | Output |
|---|---|
| 0.5 | 0 (0%) |
| 1 | 25 (25%) |
| 1.5 | 50 (50%) |
| 2 | 75 (75%) |
| 2.5 | 100 (100%) |
Mathematical Transform
[ <property name/number>:*:<offset>:<multiplier>]
This option allows you to add an offset and multiplier to your values.
Lets take a look at the last example, where we again want to convert a tank level in meters to a percentage.
Tank Level - Analogue value, 0.5 - 2.5m
To convert a 0.5-2.5 value to a 0-1 value, we need to first subtract 0.5, then multiply by 0.5. This gives us the following expression
[ Tank Level:*:-0.5:0.5 ]
NOTE - Where possible, please use the measurement-scale version of this function. This allows users to adjust your visual scales globally from the web interface, without needing to edit individual effect files.
Mapping Specific Values
[ ?<property name/number>:<value_in>=<value_out>|<value_in>=<value_out>]
Only Available in ARDI-2023+
This transform is used when you want to map specific input values to specific output values, which usually occurs when converting discrete properties (such as the state of a motor) into an analgue value (such as an animation speed).
Examples
| Example | Description |
|---|---|
[ Level ] | A simple copy of the property into the effect. |
[ Level|1 ] | Is '1' when the property equals one, otherwise it's 0. |
[ Level|3|5|12 ] | Is '1' when the property equals three, five or twelve, otherwise it's 0 |
[ Level:%:0:100] | Use the percentage of the property range. If the property has a range between 0 and 500, 500 results in an effect value of 100, 250 results in an effect of 50, 0 results in an effect of 0. |
[ Level:*:20:2 ] | The first option is an offset (an amount added to the base) and the second option is a multiplier. In this example, 20 is added to the amount before it is multiplied by 2, so that 0=40, 50 = 140 etc. |
[ ?State - Valve:0=50:1=0:2=100 ] | In this example, we are trying to animate a valve based on a discrete value, where 0 indicates the state is unknown, 1 indicates closed and 2 indicates open. The animation is completely open at 100% and closed at 0%. |
Relative Paths
You can also use relative paths in your expressions.
In some cases, the property you want to use might be in another object. In this case, you can use paths containing '/' slashes (like those of a Linux file-system) to navigate to other objects in the scene.
Let's take a look at a 3D scene with the following objects in it. We're placing an effect on the object called Pump.
If the Temperature property we want to use has already been assigned to the pump, the path would simply be Temperature.
If we want to use a property from a child element, such as the Motor, we could use a path like Motor/Temperature or (to be clearer), ./Motor/Temperature.
The path ../Outlet/Temperature would request the Temperature property of a sibling object (one that shares the same parent as the asset you're applying the effect to), since the double-period means 'go back one level'.
The @ symbol tells the system to start its search from the whole scene, so @Supply/Temperature would search for an object called Supply, and use its Temperature property.