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
| Field | Description |
|---|---|
| name | The key under anchors:. Must not equal a URDF link name. |
parent_link | The link it is fixed to. An anchor on a lid moves when the lid opens. |
link_T_anchor | Its pose relative to that link: xyz in metres, wxyz scalar-first quaternion. |
description | What 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
object anchorEvery 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.
| Kind | How it is recognised | Its pose means | Starter examples |
|---|---|---|---|
| Grasp | The description states a grasp: ... | grasp: width 0.03 m, standoff 0.06 m | Where 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 |
| Seat | Any other anchor | A 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. Default0.05m.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:
| Call | Returns |
|---|---|
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.
Updated 9 days ago