Models and objects

files says which models the widget loads and where it puts them. objects then finds objects in those models by name and links them to your application’s parameters. This page lists every option of both, with the 3D models page as the starting point.

Model files

Each entry in files loads one glTF file (.glb, or .gltf with its data embedded), in the order of the list. The path is relative to the JSON file.

With parent, the model keeps its place in the world when it is attached, unless you set position and rotationZYX: those place it relative to the parent. Use this to mount a gripper model on the flange of a robot model, for example.

Several copies of one model

A model that appears more than once, such as a row of identical axes or boxes on a conveyor, is downloaded and read once. There are three ways to add the copies:

"files": [
  { "file": "axis.glb", "name": ["AxisA", "AxisB"] },
  { "file": "box.glb", "instances": [
      { "name": "Box_left", "position": [0.5, -0.3, 0] },
      { "name": "Box_right", "position": [0.5, 0.3, 0], "rotationZYX": [1.57, 0, 0] }
  ] },
  { "file": "ball.glb", "instances": { "name": "ball", "count": 1000 } }
]

• A name list adds one copy per name, all with the entry’s parent, position, rotationZYX and scale.
• An instances list gives each copy its own name and place. A field an item leaves out is taken from the file entry.
• instances with count adds count copies named ball_1, ball_2 and so on (start sets the first number, default 1), all at the same place. Links then move them, see Numbered objects.

Copies share the geometry and textures, but each has its own materials, so a colour or opacity link on one copy does not change the others. Find a part inside a copy with a search pattern: Box_left*Lid.

GPU instancing draws all copies of a mesh in one go, which keeps the dashboard fast with hundreds or thousands of copies. It is on by default for { name, count }. The cost: the copies share one material. A colour link per copy still works, but opacity, glow and shadow settings apply to all copies together. Set "instancing": false on the file entry to give each copy its own material, or "instancing": "off" in renderSettings to switch it off for the whole file. Models with lights, cameras, lines, skinned or morphed meshes, or meshes with several materials are always added as separate copies.

Objects

Each entry in objects applies settings and links to one object in the loaded models.

Shadows need a spotLight with castShadow, see Camera, lights and rendering.

Find objects by name

A name finds the first object with that name, anywhere in the scene. A search pattern finds an object inside another one: "Robot2*Link1" first finds Robot2, then Link1 below it. Patterns work in objects, parent, camera and animations.

If two models contain objects with the same names, give each model its own name in files and use patterns: duplicates across files are not renamed.

Links

A link takes a value from a parameter, scales it, and applies it to an axis or a property of the object. The value is value × gain + offset.

For example, "gain": [1, 1, 1, 0, 0, 0] on a pose link keeps the position and drops the rotation.

Axes

visible and opacity work together, in any order: an object with opacity 0 is hidden, and it shows again when the opacity rises, unless a visible link hides it.

A fixed value without link sets something once, for example a see-through housing:

{ "name": "Housing", "links": [{ "axis": "opacity", "value": 0.4 }] }

Properties

property sets any property of the object directly: a name such as intensity for a light, or a path with dots such as material.emissive.r. The value is converted to the property’s type, and a property the object does not have is reported once. This example colours an LED strip from a four-element parameter, red, green, blue and brightness:

{
  "name": "LedStrip",
  "links": [
    { "property": "material.emissive.r", "link": "root/UserParameters/IO/LedColorEmissive", "channel": 0 },
    { "property": "material.emissive.g", "link": "root/UserParameters/IO/LedColorEmissive", "channel": 1 },
    { "property": "material.emissive.b", "link": "root/UserParameters/IO/LedColorEmissive", "channel": 2 },
    { "property": "material.emissiveIntensity", "link": "root/UserParameters/IO/LedColorEmissive", "channel": 3, "gain": 2 }
  ]
}

Vector lengths

magnitude uses the length of a vector instead of one element: true takes the whole array, { "start": 0, "length": 3 } a part of it. A twist [vx, vy, vz, wx, wy, wz] gives the linear speed with start 0 and the angular speed with start 3. gain and offset apply to the length, and channel is not used.

magnitude works for every axis or property that takes one number. On pose, position, rotationZYX, color and scaleChildren it is ignored, with a warning.

Numbered objects

When many objects are linked the same way, such as the axes of a gantry or a thousand balls, one entry with count stands for all of them. %d in name becomes the number (%02d pads it to two digits). The numbers start at start, default 1.

A link of such an entry reads its value in one of two ways:

• One parameter per object. %d in the link path becomes the number of the parameter. The link’s own start sets the first one (default: the entry’s start), and stride the step (default 1):

  {
    "name": "Slider_%d", "count": 6,
    "links": [{
      "link": "root/AxesControl/actuatorControlLoops/actuatorControlLoop%02d/actuatorPositionActual",
      "axis": "x", "start": 0
    }]
  }
  

  Slider_1 to Slider_6 follow actuatorControlLoop00 to actuatorControlLoop05.

• One array parameter for all objects. Without %d in the path, object number i reads from element channel + i × stride. Use stride 1 for one value per object, or 6 for one pose per object. Without stride, all objects read the same element:

  { "name": "ball_%d", "count": 1000, "links": [{ "link": "root/Balls/poses", "axis": "pose", "stride": 6 }] }
  

  ball_1 reads elements 0 to 5, ball_2 elements 6 to 11, and so on.

Older keys

Files made for earlier versions keep working. The widget still reads these keys, and the editor marks them with what to use instead: