Anchors

Named frames on an object. Skills target anchors by name, so they work wherever the object sits.

An anchor is a named frame fixed to one link of an object: a grasp point on a plate, a slot on a shaker, the top of a stand. Anchors are defined once per object type, in objects/<type>/<type>.object_model.yaml, and every instance of the type has them.

A skill asks for an anchor by name on an object it was given, and gets back the anchor's pose in the world as the object stands now. Move the object, load another world or run on another bench, and the same skill still reaches the right place, because no coordinate was written into the skill.

What an anchor holds

FieldDescription
nameThe key under anchors:. Must not equal a URDF link name.
parent_linkThe link it is fixed to. An anchor on a lid moves when the lid opens.
link_T_anchorIts pose relative to that link: xyz in metres, wxyz scalar-first quaternion.
descriptionWhat it is, in words. A grasp anchor also states its grasp here.

The full format is in objects/<name>/<name>.object_model.yaml.

The object anchor

Every object model must have an anchor named object; loading fails without it. It is the frame a pose for the object means: a world places the object by this frame, and get_object_pose(obj) returns it. For objects that rest on a table, the editor puts its origin at the (+X, +Y, -Z) corner of the bounding box, on the surface the object stands on.

Grasp anchors and seat anchors

There are two kinds of anchor, and the kind decides how you use it.

KindHow it is recognisedIts pose meansStarter examples
GraspThe description states a grasp: ... | grasp: width 0.03 m, standoff 0.06 mWhere the tool centre point (TCP) is when the gripper holds the object there. Its +Z is the approach direction, pointing into the object.grasp_short on the plate, lid_grip on the shaker lid
SeatAny other anchorA face or point on the object. Holders use these as places where another object sits.top_center on a stand, slot_1 to slot_4 on the shaker, bottom_center on the plate

A grasp states:

  • width: the gripper opening at the grasp, in metres.
  • standoff: how far back along the anchor's -Z the pre-approach pose is. Default 0.05 m.
  • gripper_variant: the gripper the grasp was taught with. Omitted means the stock gripper.

Pre-approach

The pre-approach pose is the grasp anchor's pose moved back along its own -Z: grasp.preapproach() uses the anchor's standoff (or 0.05 m when it states none), grasp.preapproach(0.10) uses 10 cm. Because +Z points into the object, an anchor whose axes are wrong sends the gripper in from the wrong side. Check a new grasp anchor in the 3D view before you use it.

Seats

An object sits on a holder by putting its bottom_center anchor exactly on one of the holder's seat anchors (default top_center). The style aligned keeps the axes of the two anchors together; flipped_180 turns the object half a turn about the seat anchor's Z. A seated object follows its holder when the holder moves. See How anchor snapping works.

Using anchors in a skill

from protocol_schema import SkillObject

from .modules import anchor, move_arm, resolve, set_gripper

ARM = "right"


def touch_grasp(plate: SkillObject = {"object_ref": "wellplate"}):
    """Hover over the plate's grasp_short anchor, then open to its grasp width.

    Args:
        plate: The plate.
    """
    grasp = anchor(resolve(plate), "grasp_short")  # fails here if the anchor does not exist
    move_arm(ARM, grasp.preapproach(0.10))
    set_gripper(ARM, grasp.width)
    return {"success": True}

The calls that read anchors:

CallReturns
anchor(obj, name)An Anchor: .pose (world pose), .width, .standoff, .gripper_variant (None for a seat anchor), .kind ("tcp" or "seat"), .link, and .preapproach(standoff=None).
get_anchor_pose(obj, name)The world pose only.
list_anchors(obj)The anchor names of the object.
get_object_pose(obj)The pose of the object anchor.

obj is a skill input (SkillObject), an instance id or a display name. An unknown anchor raises an error that lists the anchors the object has.

For an articulated object, pass joints= to evaluate an anchor at other joint values without changing the world:

lid_open = anchor(shaker_id, "lid_grip", joints={"lid_joint": 1.666})

The starter skills move_plate and shaker_lid show a full pick, place and lid sequence built from anchors. The full verb list is in the skill runtime API.

Naming anchors

Name an anchor after the physical feature, not after the move you make there today: slot_1, top_center, grasp_short, lid_grip. Skill code then reads like the protocol, and a second skill can reuse the same anchor. Two genuinely different grasps on one object are two anchors (grasp_short, grasp_long).

Editing anchors

Anchors you get with an object from the mesh database are a starting point. You edit your project's copy in the Object Database editor or by hand in the YAML. Edits stay in your project; the catalog is not changed. After Save to Project, the next move in a running world uses the new anchor.

A file that loads cleanly is internally consistent; it says nothing about whether an anchor is in the right place. Check a moved or new anchor in the sim before you run it on hardware.


Did this page help you?