A MoveIt object subframe names a useful coordinate frame on a collision object, such as a screwdriver tip or bottle opening. Once the object is attached, a planning request can refer to that object-relative point instead of asking the robot’s original tool frame to reach the target. The frame’s pose, attachment state and lifetime must remain consistent through pickup and release.
This is a different problem from placing the wrist correctly. A long tool can put its tip far from the wrist, and a bottle’s opening has an orientation as well as a position. Naming those task points makes the intended geometric relationship explicit.
Check which pose the subframe is relative to
The current ROS 2 CollisionObject message at a pinned revision defines an object pose relative to the header frame. Its shapes and subframe poses are relative to that object pose. The subframe_names and subframe_poses arrays must have matching lengths.
Read that together with the MoveIt subframes tutorial, which still contains ROS 1 commands and describes subframes directly in the header coordinate system. For current ROS 2 message construction, follow the actual installed message definition. Do not copy an offset from that tutorial without checking the additional object-pose transform.
For a hypothetical bottle whose origin is at its base, the opening offset belongs in bottle coordinates. Moving the bottle changes the object’s pose; it should not require rewriting a world-coordinate opening into the local subframe field. Applying the object’s translation twice would place the planned opening incorrectly.
Use the object name and subframe name together
MoveIt identifies the frame using object_name/subframe_name. The message’s example is screwdriver/tip. Keeping the object identity in that name distinguishes several tools with a similarly named tip.
For an attached object, the tutorial sets the planning end-effector link to the desired subframe. A request can then express where that subframe should go relative to a target frame. Both sides matter: which carried point is moving, and which frame defines its destination?
| Request element | Example meaning | Mistake to catch |
|---|---|---|
| Attached object identity | The tool currently held by the robot | Referring to a previous tool instance |
| Moving subframe | The carried screwdriver tip | Planning for the wrist instead |
| Target frame | A task fixture or another object’s subframe | Mixing object-local and world coordinates |
| Target orientation | The required tip-axis alignment | Matching position while rotating the tool incorrectly |
These are conceptual examples, not a complete launch or motion command. The robot’s planning group, solver configuration and scene must support the request being constructed.
Attachment and detachment change what can be planned
After pickup, confirm that the scene represents the object as attached to the intended robot link. The carried collision geometry and its task subframe should describe the same object. A tip name without the corresponding attachment does not describe a tool moving with the hand.
When detaching, restore the planning end-effector reference to an appropriate robot link before issuing the next robot motion. The tutorial explicitly calls out this cleanup. Retaining an old tool-tip reference after release makes the next request depend on a frame that no longer belongs to the robot’s attached structure.
The PlanningScene ownership guide addresses which scene a consumer actually reads. For subframes, use that distinction to verify that the planning request sees the attachment and pose updates intended for it.
A planning-scene frame is not automatically a TF frame
The tutorial notes that subframes are available within MoveIt planning requests and are not automatically published into TF. Another ROS consumer therefore needs an explicit transform-publication arrangement if it must use the same task frame. Keep one authoritative pose definition and inspect how updates reach each consumer.
The tutorial and pinned message were checked October 16, 2026; no MoveIt request was executed. A useful local review follows one object through creation, attachment, tool-tip planning and detachment, verifying the frame composition and object identity at each transition.