GRID Package

A GRID package contains user interface files and all related resources.

6 minute read

A GRID package contains a graphical user interface. It is deployed to the controller and served from there over HTTP, so you reach the interface from a browser without installing anything.

A GRID package holds one or more .grid files alongside the resources they use — images, 3D models, motion programs, error definitions and configuration:

├── gui_operator.grid         # gui for the operator
├── gui_maintenance.grid      # gui for maintenance crew
├── 3d
│   ├── 3dfile.glb            # 3d model in a GLTF file
│   └── model.json            # configuration of the 3d model and linking
├── config
├── errors
├── img
│   └── mylogo.svg            # some image
├── programs
└── safety

.grid files are created and edited with Motorcortex Grid.

3D models

Upload your GLTF file(s) to the package, into the 3d directory. You can place them in a subfolder if that is preferred.

model.json

Alongside them goes a JSON file that sets additional properties of the objects in the model and links object properties to Motorcortex parameters. In a shipped package this file is named after the model rather than model.json — 3d/MCX-Anthropomorphic-Robot-R00.json, for instance.

The tabs below show a minimal configuration, a full one, and the properties the file accepts. You can also download the schema itself: v-3d-schema.json.

Minimal configuration

The smallest configuration that does something: load one model file and rotate one object in it around its Z axis from a controller parameter.

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

name matches the object name inside cube.glb; only the first object with a matching name is used. channel picks an element of an array parameter and defaults to 0, so it can be left out when the parameter is a scalar.

Full configuration

Two model files, a camera, lighting, shadows, a trace line following the tool, and several objects driven from the parameter tree.

{
  "files": [
    {
      "file": "scenery.glb",
      "name": "scenery"
    },
    {
      "file": "robot.glb",
      "name": "robot"
    }
  ],
  "camera": "Camera",
  "cameraLookAt": {
    "x": 0.0,
    "y": 0.0,
    "z": 0.5
  },
  "hemisphereLight": {
    "intensity": 0.8
  },
  "spotLight": {
    "x": 1,
    "y": 1,
    "z": 5.8,
    "castShadow": true,
    "angle": 0.5,
    "intensity": 0.2,
    "penumbra": 1.5
  },
  "traceLine": {
    "color": "#ff0000",
    "lineWidth": 2,
    "tolerance": 0.001,
    "numPoints": 500,
    "links": [
      {
        "link": "root/ManipulatorControl/manipulatorToolPoseActual",
        "channel": 0,
        "axis": "x"
      },
      {
        "link": "root/ManipulatorControl/manipulatorToolPoseActual",
        "channel": 1,
        "axis": "y"
      },
      {
        "link": "root/ManipulatorControl/manipulatorToolPoseActual",
        "channel": 2,
        "axis": "z"
      }
    ]
  },
  "objects": [
    {
      "name": "Floor",
      "receiveShadow": true,
      "castShadow": false
    },
    {
      "name": "Base",
      "receiveShadow": false,
      "castShadow": true
    },
    {
      "name": "Link1",
      "castShadow": true,
      "links": [
        {
          "link": "root/ManipulatorControl/jointPositionsActual",
          "channel": 0,
          "axis": "rz"
        },
        {
          "link": "root/ManipulatorControl/manipulabilityDetector/isEnabled",
          "axis": "visible"
        }
      ]
    },
    {
      "name": "Link2",
      "castShadow": true,
      "links": [
        {
          "link": "root/ManipulatorControl/jointPositionsActual",
          "channel": 1,
          "axis": "rz"
        }
      ]
    }
  ]
}

The trace line draws in 3D from three links that supply x, y and z — here the first three channels of the tool pose. tolerance is how far a point must move before it is added, and numPoints caps the line, dropping the oldest points first.

Note

A flat array — "traceLine": [ {…}, {…} ] — is the older form of the same setting and is still accepted, but it cannot carry color, lineWidth, tolerance or numPoints.

Scene

Top-level properties of the configuration file.

Property	Type	Purpose
`files`	array	The 3D files to load
`objects`	array	Per-object settings and parameter links
`camera`	string	Name of the object to use as the camera
`cameraPosition`	`{x, y, z}`	Position of the camera, applied even to a camera loaded from a file
`cameraLookAt`	`{x, y, z}`	Point the camera initially points at
`hemisphereLight`	`{intensity}`	Ambient light
`spotLight`	`{x, y, z, intensity, angle, penumbra, castShadow}`	Spotlight
`environmentmap`	`{nx, ny, nz, px, py, pz}`	The six cube-map images; all six are required
`renderSettings`	`{fps, bloom}`	Frame-rate cap and the bloom post effect
`traceLine`	object	A line drawn through a linked x/y/z position

Files

Property	Type	Purpose
`file`	string	Path and filename of the model to load. Required
`name`	string	Name the model gets in the 3D scene
`parent`	string	Name of an object this one becomes a child of
`position`	`[x, y, z]`	Position of the object
`rotationZYX`	`[rz, ry, rx]`	Rotation as Euler angles, in ZYX order

Motorcortex is Z-up: z is the vertical axis, and rotations are applied in ZYX order.

Objects

Property	Type	Purpose
`name`	string	Name of the object or scene these settings apply to. Only the first match is used
`castShadow`	boolean	The object and its children cast shadows
`receiveShadow`	boolean	The object and its children receive shadows
`addEnvironmentMap`	boolean	The object’s materials use the environment map
`environmentMapIntensity`	number	Environment-map intensity, default `1`
`links`	array	Parameter links to apply to this object

Links

A link subscribes to one parameter and applies its value to one axis or property.

Property	Type	Purpose
`link`	string	Parameter path to subscribe to
`channel`	number	Index into an array parameter, default `0`
`axis`	string	The axis or property the value drives
`property`	string	Path to a property in the object’s scenegraph, relative to the object
`gain`	number	Multiplier applied before the value reaches the axis
`offset`	number	Added to the gained value
`value`	boolean, number or array	Initial value, overwritten once a valid link delivers one

axis accepts:

Value	Drives
`x`, `y`, `z`	Translation along one axis
`rx`, `ry`, `rz`	Rotation about one axis
`position`	Translation, all three axes from one array
`rotationZYX`	Rotation, all three angles from one array
`pose`	Position and orientation together
`s`	Uniform scale
`sx`, `sy`, `sz`	Scale along one axis
`scaleChildren`	Scale applied to the object’s children
`visible`	Whether the object is drawn
`opacity`	Material opacity
`emissiveIntensity`	Material emissive intensity

Trace line

Property	Type	Purpose
`links`	array	Links supplying the x, y and z of each point
`color`	string	CSS colour string, for example `#ff0000`, `rgb(255, 0, 0)`, `red`
`lineWidth`	number	Width of the line
`tolerance`	number	How far a point must be from the previous one before it is added
`numPoints`	number	Maximum points in the line; the oldest are dropped first