Skip to content

Robot libraries

Jump to bottom
visose edited this page Jun 28, 2026 · 44 revisions

Robot libraries define the robot cells, tools, frames, meshes, and IO names that appear in the Load Robot System, Load Tool, and Load Frame components.

A library is a pair of files with the same base name:

  • LibraryName.xml: robot systems, tools, frames, IO names, controller metadata, and kinematic data.
  • LibraryName.3dm: display meshes and optional collision meshes.

The XML should describe controller and mechanism facts. Do not invent shop-layout coordinates or project-specific placement in the library. Place the loaded robot system in a Rhino model with the Base input on Load Robot System.

If you only want to install a robot and start programming, read the install sections below. If you are creating or contributing a library, read the XML, 3DM, mesh hygiene, and validation sections.

Install an online library

  1. Place a Load Robot System component in Grasshopper.
  2. Click Libraries.
  3. Select a library.
  4. Click Install.

Downloaded libraries are cached in the plugin data folder, not in the local documents library folder.

Install a local library

  1. Download or create a matching XML and 3DM pair.
  2. Place both files in the local Robots library folder.

Typical local paths:

  • Windows: C:\Users\userName\Documents\Robots
  • macOS: /Users/userName/Robots

Local libraries take priority over downloaded online libraries with the same file name. If the library window shows Local override, the local files are the ones being used.

If a library does not appear or meshes are missing, see Troubleshooting.

Edit or publish a library

To edit a downloaded library, install it, copy the XML and 3DM pair into the local library folder, and edit the local copy.

Public library updates usually go through a pull request to the libraries branch. Include both the XML and the 3DM file. For new robot models, use real vendor or public mesh sources when possible rather than placeholder geometry.

XML structure

The XML file can contain robot systems, tools, and frames. Names are what the Grasshopper value lists display.

Robot system

<RobotSystem name="ExampleCell" manufacturer="ABB" controller="IRC5">
  <Mechanisms group="0">
    <RobotArm manufacturer="ABB" model="IRB120" payload="3">
      <Base x="0" y="0" z="0" q1="1" q2="0" q3="0" q4="0" />
      <Joints>
        <Revolute number="1" a="0" d="290" minrange="-165" maxrange="165" maxspeed="250" />
        <!-- More joints -->
      </Joints>
    </RobotArm>
  </Mechanisms>
</RobotSystem>

Supported mechanism elements are RobotArm, Positioner, Track, and Custom.

Important fields:

  • name: user-facing robot system name.
  • manufacturer: one of ABB, KUKA, UR, Staubli, FrankaEmika, Doosan, Fanuc, Igus, or Jaka.
  • controller: optional controller description.
  • group: mechanical group index. Most cells use 0.
  • model: model name. It must match the 3DM layer naming convention.
  • payload: maximum payload in kilograms.
  • movesRobot: optional for external mechanisms. Use it when a track or positioner moves the robot base.
  • Base: origin and orientation as millimeters plus quaternion values.

Joint fields:

  • number: controller joint number, starting at 1.
  • a, d: DH distances in millimeters.
  • α, θ: optional DH angles in degrees. These can also be omitted when the built-in robot class supplies defaults.
  • sign: optional joint direction override.
  • minrange, maxrange: revolute ranges in degrees, prismatic ranges in millimeters.
  • maxspeed: revolute speed in degrees per second, prismatic speed in millimeters per second.

IO names

IO names are optional. They let command components use named IO declarations in generated code.

<IO useControllerNumbering="false">
  <DO names="GripperOpen,GripperClose" />
  <DI names="PartPresent" />
  <AO names="ExtrusionSpeed" />
  <AI names="Pressure" />
</IO>

Tools

<Tool name="Gripper" useController="true" number="1">
  <Tcp x="0" y="0" z="120" q1="1" q2="0" q3="0" q4="0" />
  <Mass weight="3.5" x="0" y="0" z="60" />
</Tool>
  • useController is optional and defaults to false.
  • When useController is true, the TCP in XML is used for simulation, while generated code refers to tool data that already exists on the controller.
  • number is an optional controller tool index used by manufacturers that support numbered controller-managed tool data. See Manufacturer support.
  • The mass centroid x, y, and z attributes are optional.

Frames

<Frame name="Fixture" useController="true" number="1">
  <Base x="0" y="0" z="0" q1="1" q2="0" q3="0" q4="0" />
  <Coupling group="0" mechanism="0" />
</Frame>
  • Static frames do not need a Coupling element.
  • Coupled frames move with an external mechanism or coordinated robot.
  • number is the optional controller frame index when useController is true. See Manufacturer support.

3DM mesh layers

The 3DM file stores display meshes and optional collision meshes.

Mechanism display meshes

Mechanism display meshes are read from a parent layer named:

Mechanism.Manufacturer.Model

Example:

RobotArm.ABB.IRB120

Under that parent layer, use child layers named 0, 1, 2, and so on:

  • 0: mechanism base mesh.
  • 1: first joint mesh.
  • 2: second joint mesh.
  • Continue through all joints.

The model portion must match the XML model value. Keep layer names exact and avoid extra geometry on unrelated layers.

Mechanism collision meshes

Optional collision meshes use a sibling parent layer with .Collision appended:

RobotArm.ABB.IRB120.Collision

Use matching child layers named 0, 1, 2, and so on. You only need to add child layers for parts with different collision geometry. Missing or empty collision layers fall back to the matching display mesh.

Tool meshes

Tool display meshes use:

Tool.ToolName

Optional tool collision meshes use:

Tool.ToolName.Collision

If the collision layer is missing or empty, the display mesh is used for collision checking.

Mesh hygiene

Before publishing or sharing a 3DM library:

  • Keep only mesh geometry used by the library.
  • Remove blocks, materials, construction geometry, and unrelated layers.
  • Keep display meshes detailed enough to identify the robot, but not heavier than needed.
  • Use simpler collision meshes when display meshes are dense.
  • Keep collision meshes aligned with the display meshes.
  • Check both the XML and 3DM together before submitting a pull request.

Validation checklist

  • XML and 3DM file names match.
  • Robot system, tool, and frame names are clear and stable.
  • Manufacturer and model names match the supported values and layer names.
  • Joint numbers, ranges, speeds, and payload come from reliable controller or vendor data.
  • The first robot pose is reasonable when loaded in Grasshopper.
  • Display mesh layer count matches base plus joint count.
  • Optional collision meshes are conservative and correctly indexed.
  • No project-specific base placement is baked into the library XML.

Clone this wiki locally