Objects, anchors, and the world

Find objects, read their anchors and poses, record where objects sit, drive articulations, and add or remove objects during a run.

A skill acts on the world model of the loaded world: its objects, where each one sits, and the state of their joints. The functions on this page read and record that model. None of them moves an arm.

Finding objects

FunctionReturns
resolve(obj)The instance id of obj, given an id, a display name, a SkillObject or an {"object_ref": ...} dict. Raises ObjectNotFound (with the closest ids) or AmbiguousObject (two objects share that display name).
name_of(obj)The object's display name.
list_objects(type=None)The sorted instance ids in the world, or only those of one object type.

Call resolve() on every object parameter at the top of a skill: a wrong name then fails before the arm moves.

Anchors

An anchor is a named pose on an object, defined in its object model. See Anchors.

grasp = anchor(plate, "grasp_short")
grasp.pose          # world Pose
grasp.width         # the grasp width it states (m), or None
grasp.preapproach() # the pose backed off along the approach axis

anchor(obj, name, *, joints=None) returns an Anchor evaluated where the object is now. Pass joints={"lid_joint": 1.2} to evaluate it with the object's joints at other values, without changing the world: an anchor on a lid moves with the lid. An unknown anchor raises AnchorNotFound, which lists the anchors the object has.

Anchor fieldMeaning
poseThe anchor's world pose.
object, nameThe instance id and the anchor name.
widthThe grasp width the anchor states (m), or None.
standoffThe approach distance the anchor states (m), or None.
kind"tcp" for an anchor that states a grasp (where the tool goes), "seat" for one that does not (a place an object's bottom_center lands).
linkThe part of the object it is attached to.
Anchor methodReturns
preapproach(standoff=None)The pose standoff metres back along the anchor's negative z axis (the tool approaches along +z). Default: the anchor's own standoff, else 0.05 m.
offset((dx, dy, dz), frame="local")The anchor pose moved along its own axes, or the world's with frame="world".

Other anchor functions:

FunctionReturns
get_anchor_pose(obj, name, *, joints=None)anchor(...).pose.
list_anchors(obj)The object's anchor names.
get_object_pose(obj)The pose of the object's placement frame (its object anchor).

Recording where objects are

These record a change without moving anything: an operator loaded a plate, a measurement corrected a pose. Each refuses an object an arm is holding (HeldByArm).

FunctionWhat it records
set_object_pose(obj, pose, *, anchor="object")The object's anchor is at pose (world). The object is then free-standing in the world, no longer seated on a holder.
seat(obj, holder, anchor="top_center", *, style="aligned")obj's bottom_center sits on holder's anchor. style is "aligned" or "flipped_180".
seat_of(obj)Where obj sits: a Seat with holder, anchor and style, or None.

Picking up and putting down with an arm are recorded with attach and release; see Arm motion and the gripper.

Articulated objects

FunctionEffect
get_articulation(obj)The object's joint values, {joint: value}.
set_articulation(obj, "open")Sets the joints to a preset of the object model.
set_articulation(obj, {"lid_joint": 1.2})Sets the named joints.

set_articulation changes the world model only; moving the physical part is the skill's job. A lid or door moved by the arm with move_path and sweep_anchor_steps updates the joint by itself; see Paths, lids, and two arms.

Adding and removing objects during a run

FunctionEffect
spawn(object_type, *, name=None, pose=None, on=None, style="aligned", joints=None, id=None)Adds an object of object_type at pose (world), or seated with on=(holder, anchor). The type is looked up in the project's objects/ first, then the mesh database. Returns the new instance id, <type>_<n> unless you pass id.
despawn(obj)Removes the object (consumed, discarded). Refused while an arm holds it (HeldByArm) or while other objects sit on it (HolderHasOccupants).
replace(obj, object_type, *, pose=None)Keeps the id and changes the type (an uncapped tube is the same tube). A seated object stays seated. Returns the id.

These change the world of the run in memory and are written to the run log. The world's files on disk are not changed, so reloading the world brings back its saved state. Each waits until the arm is between moves.

Per-object live state

Some objects carry state that outlives a run, such as the next tip of a tip box. It is stored per world in worlds/<world>/live_state.yaml, keyed by instance id.

FunctionEffect
get_world_state(object_id)The object's live-state entry as a dict, {} when it has none.
set_world_state(object_id, updates)Merges updates into the entry and saves the file. Top-level keys are merged; a nested value is replaced as a whole.
state = get_world_state(tipbox_id)
set_world_state(tipbox_id, {"tip_index": state.get("tip_index", 0) + 1})

Unlike the functions above, set_world_state writes a file in the world folder.


Did this page help you?