Open Parameters
The process commonly described by the term "configuring a 3d model" typically contains the following three steps:
- a user changes one or more parameters of a 3d model
- the model is changed with respect to the new parameters
- the user gets a visual feedback
The trCAD system has a build-in mechanism for defining, setting and (re-)evaluating of user-configurable parameters inside a 3d model. In combination with its extension, the trCAD JavaScript API, it can auto-generate a full web-based graphical user interface (GUI) from these parameter definitions.
Such parameters that can be read and set by external users are called open parameters. This section explains their definition and usage. A related concept of parameters that can only be read externally, public parameters, are discusses in the public parameters section.
Open parameters
An open parameter is a variable that is explicitly defined to be readable and writeable from the outside. "From the outside" means here a general external scope that lies out of sight of the model creator when building his object. In many times this might be the auto-generated user interface but it could also be another script including the model or a different so-far unknown system.
The model creator should consider which parameters are best suited for model configuration and how these are designed. Certainly, the way the parameter influences the model should be easy to understand by somebody not involved in the construction. Reducing cross-correlations between different open parameters to a minimum may be another good idea. Defining open parameters in common units creates a more tangible user experience. The amount of open parameters should certainly not be too overwhelming for a common user. These are just a few ideas for parameter design and there may be many more.
To create an open parameter, the keyword open needs to be added to its variable declaration. In addition, an attribute section needs to be added following the declaration. This contains all mandatory and eventually some optional attributes. In code this looks like that:
Example
open int myopenparameter
{
name = "My Open Parameter"
descr = "This integer value will be usable from within the script"
value = 5
}
echo( myopenparameter )
Output
5
The example defines a variable myopenparameter as an open parameter and sets its three attributes name, descr and value that are mandatory for an integer open parameter. If the trCAD JavaScript API is used, the parameter is automatically created in the control section of the GUI:
An open parameter as it is displayed in the auto-generated web GUI.
The value of the open parameter after its declaration in the example is '5' unless the parameter is changed to another value by the user.
Note
By default, an open parameter is only requested from the user when it is actually used during runtime of the 3d model script. This means for the above example that the parameter won't turn up in the auto-generated GUI if the last line including the echo is deleted. The idea behind this is, to avoid cluttering the control panel with open parameters that have no influence onto the 3d model.
Open parameters can be generated from certain data types only. The respective references of the data types show, whether open parameters can be constructed from them.
Although open parameters can be defined and used in non-global scopes, i.e. inside higher statement blocks, its identifier must be unique within all open parameters of the package.
Mandatory attributes
The following three attributes are mandatory for all open parameters:
| Attribute | Data Type | Meaning |
| name | string | The name of the open parameter that will be visible from the outside. It should describe the parameter briefly. |
| descr | string | A more detailed description of the parameter. It should explain the usage and effect of the open parameter. In case of the default control, this is shown when the user clicks on the "information" icon. |
| value | data type of the parameter | The default value of the open parameter that will used when no other user-specified value is set. |
Note that more mandatory attributes may be required by certain data types and additional optional attributes may be available. Lists of all additionally available attributes are given in the reference sections of the respective data types.
Interdependent open parameters
Simple dependencies
Some features of an open parameter may depend on the values of other open parameters. This can simply be modeled by defining the attributes of the open parameter in dependence of the values of other open parameters that were declared earlier. The following example makes the default value and the optional attribute min of open parameter myopenint2 depending on open parameter myopenint1:
Example
open int myopenint1
{
name = "My First Open Integer"
descr = "The first integer value."
value = 5
}
open int myopenint2
{
name = "My Second Integer"
descr = "The second integer value. It must be larger than " + myopenint1 + "."
value = myopenint1 + 2
min = myopenint1 + 1
}
echo( myopenint2 )
The GUI as it results from the example.
Mutual interdependencies
Often two or more open parameters are mutually interdependendent. An example would be one value that shall be specified in two different units. In this case, the dependency can be modeled explicitly into the script. The changed attribute is used to check whether an open parameter was changed recently. From this, the other open parameters can be adjusted accordingly as shown in the following example:
Example
open float tempC
{
name = "Temperature [°C]"
descr = "The temperature in degree Celsius."
value = 0.0
}
open float tempF
{
name = "Temperature [°F]"
descr = "The temperature in degree Fahrenheit."
value = 32.0
}
if( tempC.changed )
tempF = tempC * 9.0/5.0 + 32.0
if( tempF.changed )
tempC = ( tempF - 32.0 ) * 5.0 / 9.0
echo( tempC + "°C = " + tempF + "°F" )
Two mutually dependent open parameters.
Remark
The changed attribute is implicitly available on all open parameters. It has a boolean data type.
Open arrays
The open keyword can also be used for defining open arrays. The size of the array is left blank in the open parameter declaration since it may vary during use.
Example
int fibonacci[] = [0, 1, 1, 2, 3]
open int sequence[]
{
name = "User sequence"
descr = "Insert a sequence of numbers here"
value = fibonacci
}
echo( sequence )
Using the default value results in the output
Output
<int>[0,1,1,2,3]
Arrays with higher dimensions can be handled in the same way. The dimensions number must equal the number of [] pairs.
Example
int fibonacci[][] = [[0,1],[1,2],[3,5]]
open int sequence[][]
{
name = "User sequence"
descr = "Insert a sequence of numbers here"
value = fibonacci
}
echo( sequence )
Output
<int>[[0,1],[1,2],[3,5]]
The get and set functions
In some occasions, it is desired to request an open parameter without directly using it. This may be the case when a parameter is not used in the default setup of a configurator but it should already appear in the GUI. This can be achieved by the get function that takes the open parameter as argument:
Example
open int i
{
name = "My Open Parameter"
descr = "An open parameter integer."
value = 3
}
get( i )
There is also a set function that allows to set an open parameter value. It takes the open parameter and the value is should be set to:
Example
open int i
{
name = "My Open Parameter"
descr = "An open parameter integer."
value = 3
}
set( i, 6 )
echo( i )
Output
6
Using the set command is identical to assigning the open parameter directly, i.e. the line stating set( i, 6 ) can be replaced by a line i = 6.
Remark
The set command can also be used to address open parameters of lower lying packages. This is explained in more details here.
