Add a 3D model

The last step gives your dashboard a digital twin: a 3D model of your robot or machine in the Grid 3D widget, with its parts moved by parameters from your application. The guide below is the 3D models page of the Grid documentation, shown here so you can finish the walkthrough without leaving it.

The Grid 3D widget shows a 3D model, a digital twin, of your robot or machine, and moves its parts with live parameters from your application: a joint turns when the real joint turns. You build the model in Blender or a CAD tool, export it as a glTF file, and write a small JSON file that links each moving part to a parameter.

The video shows the whole workflow, from creating a model to linking it to an application:

Prepare the model

The widget moves an object by setting its position, rotation or scale relative to its parent. So how you build the model decides how it moves:

1. Build with z up. The camera treats z as up. In Blender’s glTF exporter, switch +Y Up off under Transform.
2. Put each moving part’s origin at its pivot. In Blender, place the 3D cursor on the joint and use Object > Set Origin > Origin to 3D Cursor.
3. Parent the parts in a chain, base to tool, so each part moves with the one before it.
4. Apply rotation and scale to every moving part (Object > Apply > Rotation & Scale), so its local axes line up with the joint.
5. Give moving parts simple names, without spaces, dots or other special characters. See the name rules below.
6. Export as .glb, the binary format. Tick Apply Modifiers under Geometry if you use modifiers. Animations you made in Blender are exported with the model and can be played in the dashboard.

Keep the file small, so the dashboard loads quickly on a tablet: the stock robot models are 4 to 8 MB. There is no hard limit. Draco and Meshopt compression make files smaller and are supported. A .gltf text file also works, as long as its buffers and textures are embedded in it.

How object names change on import

The importer changes some characters in object names. Use the changed name in the JSON file:

To see the final names, type grid3d.tree() in the browser console. See Inspect the scene in the browser console.

Write the model JSON

The JSON file tells the widget which model files to load and which parameter moves which object. The paths of model files are relative to the JSON file. Name the file <name>.3d.json, for example robot.3d.json: the file editor in the portal then checks it against the schema and suggests the keys as you type.

This minimal file loads one model and turns the object Link1 with the first joint position:

{
  "files": [
    { "file": "robot.glb" }
  ],
  "objects": [
    {
      "name": "Link1",
      "links": [
        { "link": "root/ManipulatorControl/jointPositionsActual", "channel": 0, "axis": "rz" }
      ]
    }
  ]
}

Each entry in links takes one value from a parameter and applies it to the object. These are the fields you need most:

The widget does not convert units: positions are in metres and rotations in radians, relative to the object’s parent. For a parameter in degrees, use gain 0.0174533; for millimetres, 0.001. Colours, glow, any other property of an object, vector lengths and numbered objects are on Models and objects.

"objects": [
  {
    "name": "Link1",
    "castShadow": true,
    "links": [{ "axis": "rz", "link": "root/ManipulatorControl/jointPositionsActual", "channel": 0 }]
  },
  {
    "name": "Link2",
    "castShadow": true,
    "links": [{ "axis": "ry", "link": "root/ManipulatorControl/jointPositionsActual", "channel": 1 }]
  },
  {
    "name": "ToolPose",
    "links": [{ "axis": "pose", "link": "root/ManipulatorControl/manipulatorToolPoseActual" }]
  }
]

To find an object inside another one, separate the names with *: "Robot2*Link1" finds Link1 under Robot2. Use this when you load two models with the same object names. Give each one its own name in files, because duplicates across files are not renamed.

All options at a glance

The same file can do much more than move parts. Each topic has its own page:

Two rules apply to the whole file:

• A key that ends in _ is ignored. JSON has no comments, so use this to keep an alternative setting: "spotLight_": { ... } switches the spot light off and keeps its settings, and a files entry with "file_" instead of "file" is not loaded.
• Old keys keep working. Settings the schema marks as deprecated are still read, so files made for earlier versions show the same scene. The editor marks them, with what to use instead.

The schema

The schema describes every key, its type and its default: v-3d schema. The portal’s file editor uses it for files named *.3d.json. Other editors, such as Visual Studio Code, can use it through their JSON schema settings.

Add it to the dashboard

1. Upload the model files and the JSON file to your Grid project, in the same folder or with matching relative paths.
2. Add a 3D widget to your canvas.
3. In its model property, select the JSON file.

The widget has two more settings: frequency divider, how often the parameters update (default 100), and disable view navigation, which locks the camera.

When something is wrong

While the widget loads the file, it checks it: files that are missing or are not a glTF model, objects that are not found, keys with a value it does not know. Errors and warnings show in a pop-up on the dashboard, and all of them, with the details, in the browser console (press F12). Each message names the place in the file, such as objects[3] or animations[0], and most say how to fix it. For an object that is not found, the message lists the names that come close.

Inspect the scene in the browser console

Open the browser console (F12) on the dashboard and type one of these:

The console also shows the Grid version the dashboard runs, in the line that starts with grid version:.

Things to know

• Materials are shared. opacity changes the object’s material, and every other object in the same file that uses that material changes with it. Give an object its own material before you make it transparent. Copies of a model from a name list or an instances list each get their own materials.
• Shadows cost computing power. Objects cast no shadows unless you set castShadow or receiveShadow on them. Keep these to a few objects on slower devices.
• Only changed values are applied, so a parameter that does not change does not cost anything. The scene is only drawn again when something changed, or while an animation plays.