Objects, anchors, and the world model

The world model is the platform's picture of where every object sits and how its graspable features are oriented. This page is the call reference for reading that picture from a skill: resolving an object's pose, resolving a named anchor into a world-frame grasp pose, computing a safe pre-approach point, and keeping the model in sync after you move something. For the concepts behind anchors and snapping, read Anchors and Anchor snapping first.

Conventions used throughout this page:

• Positions are in metres, as [x, y, z].
• Orientations are given two ways: rpy is roll, pitch, yaw in radians, and wxyz is a scalar-first quaternion [w, x, y, z].
• Many calls select an object by its display name plus an optional index. The name is the object's display name in the world (for example "tube_50_station"). When several objects share a name, index picks one of them. A few calls also accept a world UUID directly in place of the name; those are noted below.

The object you receive: SkillObject

When your skill declares an object-typed parameter, the platform passes in a SkillObject. It bundles the two things a skill needs for a world object into one value.

Fields:

• id: the object's world UUID (a string). This is what you pass to functions that address an object by UUID, and what identifies the specific instance in the world.
• pose: a 12-element list: [centroid_x, centroid_y, centroid_z, roll, pitch, yaw, extent_x, extent_y, extent_z, origin_x, origin_y, origin_z]. Positions and extents are in metres, angles in radians.

Use object.id to address the world instance in the calls below.

def robotic_code(source_plate):
    pose = get_object_pose("my_plate")
    tcp_transform = get_object_tcp_transform(source_plate.id)

Reading poses

get_object_pose

get_object_pose(object_name: str, index: int | None = None) -> dict

Returns the world-frame pose of an object, selected by display name and optional index.

Parameters:

• object_name: the object's display name in the world.
• index: optional. Selects one instance when several share the name. None matches the first object with that name.

Returns a dict:

• xyz: [x, y, z] position in metres.
• rpy: [roll, pitch, yaw] in radians.
• wxyz: [w, x, y, z] orientation quaternion, scalar-first.
• object_id: the resolved world UUID (string).

Raises ValueError if no object matches the name and index.

load_object_anchor

load_object_anchor(
    object_name: str,
    anchor_name: str,
    index: int | None = None,
    joint_config: dict | None = None,
) -> dict

Resolves a named anchor on an object into a world-frame pose, together with its grasp parameters. Works for both static and articulated objects.

Parameters:

• object_name: the object's display name, or its world UUID directly.
• anchor_name: the anchor's name from the object model (for example "grasp_vertical", "lid_grasp").
• index: optional. Disambiguates multiple objects with the same name.
• joint_config: optional. A map of joint name to angle in radians, used to resolve the anchor on an articulated object. When None, the object's current joint configuration is used (an articulated object) or an empty configuration (a static object).

Returns a dict:

• xyz: [x, y, z] anchor position in metres.
• rpy: [roll, pitch, yaw] in radians.
• wxyz: [w, x, y, z] orientation quaternion, scalar-first.
• standoff: the anchor's grasp standoff distance in metres, or 0.0 if the anchor defines no grasp.
• width: the grasp opening width in metres, or 0.0 if the anchor defines no grasp.
• gripper_variant: the gripper variant string for this grasp (defaults to "stock").
• object_id: the resolved world UUID (string).

Raises ValueError if the object is not found, and FileNotFoundError if the object has no resolvable object model or the anchor's model cannot be located.

anchor = load_object_anchor("my_plate", "grasp_vertical")
move_arm("left_arm", anchor["xyz"], anchor["rpy"])
set_gripper("left_arm", anchor["width"])

anchor_preapproach

anchor_preapproach(anchor: dict, default_standoff: float = 0.0) -> list

Computes a pre-approach position that sits a standoff distance back from an anchor, along the direction the arm approaches from. The anchor's Z axis points toward the target, so the pre-approach point backs off along the anchor frame's -Z.

Parameters:

• anchor: a dict as returned by load_object_anchor.
• default_standoff: the standoff distance in metres to use when the anchor itself defines no positive standoff. Defaults to 0.0.

The standoff used is the anchor's own standoff when it is greater than 0.0, otherwise default_standoff. If the resulting standoff is 0.0, the anchor position is returned unchanged.

Returns [x, y, z], the world-frame pre-approach position in metres. It carries position only; reuse the anchor's rpy or wxyz for orientation.

anchor = load_object_anchor("my_plate", "grasp_vertical")
pre = anchor_preapproach(anchor, default_standoff=0.05)
move_arm("left_arm", pre, anchor["rpy"])   # approach point
move_arm("left_arm", anchor["xyz"], anchor["rpy"])  # grasp point

get_object_tcp_transform

get_object_tcp_transform(object_id: str) -> Pose

Returns the transform from an arm's tool centre point to an object that is currently attached to that arm.

Parameters:

• object_id: the world UUID of an object currently attached to an arm.

Returns a Pose (the TCP-to-object transform). Read .xyz for position in metres and .wxyz for the scalar-first orientation quaternion.

Raises ValueError if the object is not found, or if it is not currently attached to an arm.

Snapping an object into place

Snapping asserts where an object is. It pins the object to a fixed world pose, so from that moment the object no longer follows whatever was holding it. If the holder later moves (for example a rotor rotates, or the arm that carried the object moves on), the snapped object stays put in the model and must be re-snapped to match reality. See Anchor snapping for when and why to do this. Neither call below moves the arm; they only update the world model.

snap_object_to_world_pose

snap_object_to_world_pose(object_id: str, xyz: list, wxyz: list) -> None

Pins an object to an explicit world-frame pose. Any current mount is dropped and the object is re-attached as a fixed world object at the given pose.

Parameters:

• object_id: the world UUID of the object to snap.
• xyz: target world-frame position [x, y, z] in metres.
• wxyz: target world-frame orientation [w, x, y, z], scalar-first.

Returns None.

snap_object_anchor_to_world_pose

snap_object_anchor_to_world_pose(
    object_id: str,
    anchor_name: str,
    xyz: list,
    wxyz: list,
) -> None

Pins an object so that one of its named anchors lands on an explicit world-frame target pose. The body pose needed to place the anchor there is computed for you, then the object is snapped. Works for any object and anchor combination.

Parameters:

• object_id: the world UUID of the object to snap.
• anchor_name: the anchor (from the object's object model) to align to the target.
• xyz: target world-frame position [x, y, z] in metres for the anchor.
• wxyz: target world-frame orientation [w, x, y, z] for the anchor, scalar-first.

Returns None. Raises ValueError if the object is not found.

Articulated objects and the joint arc

update_object_joint_config

update_object_joint_config(object_name: str, joint_config_update: dict) -> None

Updates the world model's joint configuration for an articulated object. Call this after you physically move an articulated part (a lid, a lever, a rotor) so the model stays in sync for collision checking and later anchor computation.

Parameters:

• object_name: the object's display name or world UUID.
• joint_config_update: a map of joint name to angle in radians. This is a partial update: only the joints you name are changed.

Returns None. Raises ValueError if the object is not found.

interpolate_anchor_joint_path

interpolate_anchor_joint_path(
    arm: str,
    object_name: str,
    anchor_name: str,
    joint_path: dict[str, tuple[float, float]],
    *,
    fixed_joints: dict[str, float] | None = None,
    steps: int = 5,
    speed: float = 20,
    wait: bool = True,
    index: int | None = None,
    sync_joint_config: bool = True,
) -> list[dict]

Sweeps an articulated object's joints and moves the arm along the arc the grasp anchor traces as it articulates. This commands real arm motion. Use it when the anchor you are holding travels with the articulation, for example closing or opening a lid while gripping its handle. Your skill is responsible for the entry sequence (loading the start anchor, pre-approach, closing the gripper) before you call this.

Parameters:

• arm: "left_arm" or "right_arm".
• object_name: the articulated object's display name or UUID.
• anchor_name: the anchor recomputed at each step.
• joint_path: a map of joint name to (start, end) angle in radians. Each joint is linearly interpolated from start to end across the sweep.
• fixed_joints: optional. A map of joint name to a constant angle in radians, held for every step.
• steps: number of waypoints. The final step lands on the end values. Defaults to 5.
• speed: the move speed passed through to each arm move. Defaults to 20.
• wait: block until each move completes. Defaults to True.
• index: optional. Disambiguates same-named objects.
• sync_joint_config: when True (the default), the object's joint configuration is updated to the end values after the sweep so the model matches reality.

Returns a list of anchor dicts (each shaped like load_object_anchor's return) for the poses traversed.

Raises ValueError if joint_path is empty.

interpolate_anchor_to_anchor

interpolate_anchor_to_anchor(
    arm: str,
    object_name: str,
    start_anchor: str,
    end_anchor: str,
    *,
    start_joint_config: dict | None = None,
    end_joint_config: dict | None = None,
    interpolate: bool = False,
    steps: int = 5,
    speed: float = 20,
    wait: bool = True,
    index: int | None = None,
) -> list[dict]

Moves the arm between two resolved anchor poses. This commands real arm motion. Use it when the path runs between two distinct anchors rather than tracking a single articulating anchor. Your skill is responsible for the entry sequence and any joint-config sync before or after.

Parameters:

• arm: "left_arm" or "right_arm".
• object_name: the object's display name or UUID.
• start_anchor: the anchor moved to first, resolved at start_joint_config.
• end_anchor: the anchor moved to second, resolved at end_joint_config.
• start_joint_config: optional joint configuration for resolving start_anchor.
• end_joint_config: optional joint configuration for resolving end_anchor.
• interpolate: when False (the default), the arm makes exactly two moves: to start_anchor, then to end_anchor, with no intermediate poses. When True, it follows a Cartesian path of steps poses from start to end (linear position, quaternion slerp for orientation).
• steps: number of waypoints when interpolate=True. The final step lands on end_anchor. Ignored when interpolate=False. Defaults to 5.
• speed: the move speed passed through to each arm move. Defaults to 20.
• wait: block until each move completes. Defaults to True.
• index: optional. Disambiguates same-named objects.

Returns a list:

• with interpolate=False: [start_anchor_dict, end_anchor_dict], each shaped like load_object_anchor's return.
• with interpolate=True: a list of {"xyz", "rpy", "wxyz"} poses traversed.

Per-object live state

Live state is a small, mutable bag of values the platform keeps for an object, separate from its geometry. It is where a skill records things like which tip a tip box should hand out next, or per-well calibration offsets.

get_world_state

get_world_state(object_id: str) -> dict

Returns the live-state dict for one object, addressed by its world UUID. Returns {} when the object has no live-state entry.

The keys present depend on the object. Common ones:

• type: the object's type string.
• tip_index: for tip boxes, the pointer to the next tip to use.
• calibration: a map of key to a [dx, dy] offset array. The source does not state the unit.

cal = get_world_state(object_id).get("calibration", {})
dx, dy = cal.get(str(key), [0.0, 0.0])

set_world_state

set_world_state(object_id: str, updates: dict) -> None

Merges updates into an object's live-state entry and persists it. Top-level keys are shallow-merged, so keys you do not mention are left alone. A nested map you do supply (for example the whole calibration) replaces the existing one wholesale rather than merging into it.

Parameters:

• object_id: the world UUID of the object.
• updates: the keys to merge in.

Returns None.

# Advance a tip box's next-tip pointer
set_world_state(tipbox_id, {"tip_index": (tip_index + 1) % 96})

Related