Parametric Presets

Note

Setting up a parametric preset requires familiarity with both the URDF structure and javascript, if you aren’t confident in either of these but would like to have parametric presets, contact Verbotics and we can provide consultancy services to create these for you.

In addition to regular presets created entirely within cell editor, parametric presets are a type of preset that can have several options and parameters available to select from when importing the preset into cell editor.

Currently, to create a parametric preset, you’ll first need to create a standard preset using cell editor. Then, once exported, you’ll need to directly edit the presets internal files using a code editor of your choice, such as Visual Studio Code.

Adding a Parametric Preset into a Cell

Internal Preset Files

Presets exported from Cell Editor are saved as a “.vbpreset” file. However, replacing this file name extension with “.zip” then extracting the files will allow direct access to the presets internal files. These files consist of:

model.urdf: Contains different elements making up the preset, represented in URDF form (Universal Robotic Description Format). Identifies the robots links, visual bodies and collision bodies.
model.srdf: Contains data representing information about the model not included in the urdf file, but essential for the model to function in cell editor and weld. Identifies the models joints, disabled collisions, groups and group states.
model.json: Contains the model configuration data of the preset.
preset.json: Contains metadata relating to the preset.
meshes: A folder of the meshes used by the presets visual and collision bodies.

How to Convert a Preset to a Parametric Preset

To start, the model.urdf and model.srdf files will need to have the .js file extension added to the end of their file name. (E.g. model.urdf.js). If the parametric preset is to also affect the model configuration, then this will also need to be done to the model.json file.

Once done, each file will need to have the following adjustments made to enable parametric features:

Changes to Preset.JSON

An example of the structure of a parametric presets preset.JSON file is shown below:

{
    "name" : "Generic Hollow Wrist",
    "author" : "Ethan",
    "description" : "",
    "version" : "1.0.0",
    "manufacturer" : "Verbotics",
    "jointNames" : {

    },
    "robotNames" : {

    },
    "type" : "tool",
    "tags" : [

    ],
    "parameters" : [
        {
            "id" : "tool_scale",
            "label" : "Radius of Tool Flange",
            "type" : "real",
            "default" : 48.5,
            "min" : 10,
            "max" : 100
        },
        {
            "id" : "base_length",
            "label" : "Length of Torch Base",
            "type" : "real",
            "default" : 0,
            "min" : 0,
            "max" : 200
        },
        {
            "id" : "nozzle_base_length",
            "label" : "Length of Nozzle Base",
            "type" : "real",
            "default" : 55,
            "min" : 0,
            "max" : 200
        }
    ]
}

This example is for a parametric torch preset. Parametric presets will require an additional “parameters” structure added at the end of the file.

Each parameter to be added to a preset will need to consist of the following:

“id”: The name of the parameter, this will be used to reference the parameter in the urdf and srdf files.
“label”: The label of the parameter to be shown in the dialog that opens when importing the parametric preset into cell editor.
“type”: The type of data the parameter represents. E.g. if entering a length for a torch nozzle, this would be “real”.
“default”: The default value for the parameter.

The following may be required depending on the selected type:

“min”: The minimum value allowed to be entered for the parameter.
“max”: The maximum value allowed to be entered for the parameter.

The following data types are able to be selected for parameters:

Integer: Whole number, requires default, min and max to be defined.
Real: Decimal number, requires default, min and max to be defined.
Boolean: TRUE or FALSE, requires default to be defined.

If a parameter is to be limited to a selection of choices, a “choices” value will need to be defined with a series of different selectable label and value pairs. An example of this structure is below:

"choices" : [
    {"label" : "1250","value" : 1250},
    {"label" : "1600","value" : 1600},
    {"label" : "2000","value" : 2000},
    {"label" : "2500","value" : 2500},
    {"label" : "3150","value" : 3150},
    {"label" : "4000","value" : 4000}
]

Changes to model.URDF.js, model.SRDF.js and model.JSON.js Files

Both the URDF and SRDF files will initially contain a list of URDF and SRDF elements respectively. However, as the files are now javascript files, they will each need to be converted into a function which returns their original contents as a string.

For both files, this process will consist of the following ():

Add (function(){ to the start of the file on its own new line.
Add return on the line before the start of the URDF structure. Then place the entire URDF structure inside backticks (`).
Add }) to the end of the file on its own line.

If done correctly, both files will now return their original structures entered after the return statement. Using javascript, create functions before the return statements to alter these structures as you need.

Parameter values properties of the “parameters” object. E.g. a parameter labelled “torch_length” can be access with parameters.torch_length.

The easiest way to make changes is to use string interpolation with ${variable} to replace geometry values, mesh locations, joints etc. where needed, and adjust these variables using functions defined prior to the return statement.

If also having parameters make changes to the model configuration of the preset, the model.json.js file will also need these changes to be made.

For an example parametric preset to reference, you can download the Verbotics generic track preset here. Use the instructions noted at the top of this page to unzip the preset and examine its internal files.