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 and can now decide whether he likes his changes or not.
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.
This section explains how user-configurable parameters can be definied in the trCAD script language. These parameters are called "open parameters" and are explained in this section. A related concept, public parameters, are discusses in the next section.
Open parameters
An open parameter is a variable that is explicitly defined to be readable and writeable from outside. "From 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 software system.
The model creator should consider which parameters are most suitable for model configuration and how they are designed. Certainly, the way the parameter influences the model should be easy to understand by someone who is not involved in the construction. Reducing cross-correlation between different open parameters to a minimum may be a good idea. Let open parameters appear in common standard physical units may be achieved by adding some scaling factors. The amount of open parameters should certainly not overwhelm a standard user. These are just a few ideas for parameter design guidelines and there many be many more but we do not want to discuss this here in further details.
To create an open parameter, the keyword open needs to be added to the variable declaration of the parameter. In addition, an attribute section has to be added to the back of the declaration that contains all mandatory and eventual 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 variable myopenparameter to be an open parameter and sets the 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:
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
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 on 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 the group of all open parameters of the package.
Attributes
The three mandatory attributes define the appearance of the open parameter control:
| Attribute | Data Type | Meaning |
| name | string | This is the name of the open parameter as it is presented to the outside world. It should describe the parameter briefly. |
| descr | string | This is a more detailed description of the parameter that may be visible to the user. In case of the default control, this is shown when the user clicks on the "information" icon. It should make clear what effect the parameter really has. |
| value | data type of the parameter | This is the default value for this open parameter that is always used by the trCAD CAD kernel when no other user-specific value is set. |
These three are mandatory for all data type. Beside these, other data types may have more mandatory attributes and there are also a number of optional ones. All available attributes are all listed in the references of the 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 dependencies
Often two or more open parameters are mutually dependendent like in the case of one value that gets represented in two 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 it is 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 available on all open parameters automatically. It has a boolean data type.
Open arrays
Like for other data types, the open keyword can be used to define an open array. The size of the array is left blank in the open parameter declaration since it is not defined yet.
Example
int fibonacci[5]
fibonacci[0] = 0
fibonacci[1] = 1
fibonacci[2] = 1
fibonacci[3] = 2
fibonacci[4] = 3
open int sequence[]
{
name = "User sequence"
descr = "Insert a sequence of numbers here"
value = fibonacci
}
echo( sequence )
Using the default value gives the output
Output
{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[3][2]
fibonacci[0][0] = 0
fibonacci[0][1] = 1
fibonacci[1][0] = 1
fibonacci[1][1] = 2
fibonacci[2][0] = 3
fibonacci[2][1] = 5
open int sequence[][]
{
name = "User sequence"
descr = "Insert a sequence of numbers here"
value = fibonacci
}
echo( sequence )
Output
{{0,1},{1,2},{3,5}}
The output of the examples shows the format of an array input string as comma separated list in curly brackets.
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. The task 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.
