objects/<name>/<name>.object_model.yaml
Field reference for the object model: profile, parts, articulations and anchors.
Every object type in a project is a folder objects/<name>/ with two files:
objects/wellplate_stand/
├── wellplate_stand.urdf # links, joints, mesh file names
└── wellplate_stand.object_model.yaml # profile, parts, articulations, anchors
The folder name is the object type. It must match ^[a-z_][a-z0-9_-]{0,63}$. The project copy carries no mesh files: the mesh file names in the URDF resolve against the type's entry in the mesh database when a world loads.
The folder can also hold motions.yaml (stored motions, see The Object Database) and tag files (tags.yaml, units/<handle>/tags.yaml) copied from the catalog. You do not write those by hand.
Example
The wellplate_stand object from the starter project:
urdf: wellplate_stand.urdf
profile: {template: null}
parts:
body:
links: [body]
description: Wellplate raised stand (CAD, with AprilTag mounts)
articulations:
default:
description: Static object, no actuated joints
joints: {}
anchors:
object:
parent_link: body
description: Object placement frame (to be refined)
link_T_anchor:
xyz: [-0.152799, 0.110799, 0.0]
wxyz: [0.707107, 0.0, 0.0, 0.707107]
top_center:
parent_link: body
description: top center of stand, at height of 7.5cm, where a plate will sit.
link_T_anchor:
xyz: [-0.064375, 0.0435, 0.075]
wxyz: [0.707107, 0.0, 0.0, 0.707107]Top-level keys
| Key | Required | Description |
|---|---|---|
urdf | yes | The companion URDF, relative to this file. Normally <name>.urdf. The file must exist. |
profile | yes | The object's kind. Write profile: {template: null} for labware, holders and instruments. |
parts | no | Named groups of URDF links. |
articulations | see below | Named joint presets. |
anchors | yes | Named frames on the object. Must contain object. |
spherization | no | Path, relative to this file, of a collision-sphere file. The file must exist when the key is set. |
The loader reads only these keys. Any other key, at any level, fails the load with an unknown key error that suggests putting app data under profile:; anything under profile is kept as written.
profile.template accepts null, arm, gripper or camera. The last three describe robot hardware. A file without profile fails with missing 'profile'.
parts
partsparts:
lid:
links: [lid]
description: plateshaker_v4 lid| Key | Description |
|---|---|
links | URDF link names. Every one must exist in the URDF. |
description | Required. Free text. |
articulations
articulationsarticulations:
default:
description: lid closed
joints: {lid_joint: 0.0}
open:
description: lid open (just past vertical, it stays up)
joints: {lid_joint: 1.666}| Key | Description |
|---|---|
joints | {joint_name: value}, radians for revolute joints. |
description | Required. Free text. |
Rules checked against the URDF:
- When the URDF has independently actuated joints (not
fixed, not<mimic>), adefaultpreset is required, and it must list exactly those joints: none missing, none extra. - An object without actuated joints needs no
default. An empty one (joints: {}) is allowed. - Every other preset may list a subset of the actuated joints, and only actuated joints.
anchors
anchorsanchors:
lid_grip:
parent_link: lid
description: "Pinch on the lid's front lip ... | grasp: width 0.03 m, standoff 0.06 m"
link_T_anchor:
xyz: [0.200386, -0.114337, 0.162826]
wxyz: [0.365919, 0.118174, -0.877364, -0.287001]An anchor has exactly three keys:
| Key | Description |
|---|---|
parent_link | The URDF link the anchor is fixed to. It must exist in the URDF. An anchor on a moving link moves with it. |
description | What the frame is and how it is used, in words. It also carries the grasp, see below. |
link_T_anchor | The anchor's pose relative to parent_link: xyz in metres, wxyz a quaternion with the scalar first. The quaternion is normalized on load. |
Load fails when:
- there is no anchor named
object(required anchor(s) missing: ['object']), parent_linkis not a link of the URDF (the message lists the links that exist),- an anchor has the same name as a URDF link,
- a quaternion has a norm near zero,
- an anchor is named like a tag (
tag_<digits>): tags belong in a unit'stags.yaml, not in the model, - an anchor carries a removed field:
grasp,viewpoint,samplingorprior_weights. Older files used these as nested blocks. Write that information into the description instead.
The grasp in the description
A grasp is one segment of the description, after |:
Pinch the rim | grasp: width 0.08 m, standoff 0.04 m, gripper_variant wellplate
| Item | Required | Description |
|---|---|---|
width <w> m | yes | Gripper opening at the grasp, metres. |
standoff <s> m | no | Distance back along the anchor's -Z for the pre-approach pose. Default 0.05. |
gripper_variant <name> | no | The gripper the grasp was taught with. Omitted means the stock gripper. |
Items are separated by , and keep this order. A description may state one grasp. A segment that starts with grasp: but does not match the format, or a second grasp segment, is an error rather than "no grasp". The Object Database editor writes this segment for you when you switch Grasp on.
An anchor whose description states a grasp is a grasp anchor (kind "tcp" in the skill API); any other anchor is a seat anchor (kind "seat"). See Anchors.
The object anchor
object anchorobject is the frame a pose for the object means. A world places the object by this frame, and get_object_pose() in a skill returns it. In the Object Database editor only its rotation is editable: the editor puts its origin at the (+X, +Y, -Z) corner of the rotated bounding box, so the geometry lies in the -X, -Y, +Z octant and rests on the Z = 0 plane.
See also
Updated 9 days ago