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

KeyRequiredDescription
urdfyesThe companion URDF, relative to this file. Normally <name>.urdf. The file must exist.
profileyesThe object's kind. Write profile: {template: null} for labware, holders and instruments.
partsnoNamed groups of URDF links.
articulationssee belowNamed joint presets.
anchorsyesNamed frames on the object. Must contain object.
spherizationnoPath, 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

parts:
  lid:
    links: [lid]
    description: plateshaker_v4 lid
KeyDescription
linksURDF link names. Every one must exist in the URDF.
descriptionRequired. Free text.

articulations

articulations:
  default:
    description: lid closed
    joints: {lid_joint: 0.0}
  open:
    description: lid open (just past vertical, it stays up)
    joints: {lid_joint: 1.666}
KeyDescription
joints{joint_name: value}, radians for revolute joints.
descriptionRequired. Free text.

Rules checked against the URDF:

  • When the URDF has independently actuated joints (not fixed, not <mimic>), a default preset 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

anchors:
  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:

KeyDescription
parent_linkThe URDF link the anchor is fixed to. It must exist in the URDF. An anchor on a moving link moves with it.
descriptionWhat the frame is and how it is used, in words. It also carries the grasp, see below.
link_T_anchorThe 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_link is 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's tags.yaml, not in the model,
  • an anchor carries a removed field: grasp, viewpoint, sampling or prior_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
ItemRequiredDescription
width <w> myesGripper opening at the grasp, metres.
standoff <s> mnoDistance back along the anchor's -Z for the pre-approach pose. Default 0.05.
gripper_variant <name>noThe 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 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


Did this page help you?