grasping-direct-ik

grasping-direct-ik

Direct-IK grasp: rotate the gripper to grasp orientation at a safe height above the target, then descend straight down, then close. No trajectory planner — works on platforms where CuRobo is not deployed, or in uncluttered scenes where planning is overkill.

Nothing here is written for one hand. The grasp rotation is composed by the connector's robot.grasp_frame from the hand's measured approach and closing axes, the fingertip floor and the hover clearance come from robot.describe_gripper / robot.describe_workspace, so the same subgraph grasps the same way on a hand that closes along tool-local x and on one that closes along tool-local y.

When to use

• The curobo tool bundle is not deployed (no collision-aware planner available).
• The scene is uncluttered enough that a straight-line approach is safe.

When NOT to use

• Cluttered scenes where the arm must thread between obstacles. Prefer grasping-with-planner if available.

Recommended subgraph state flow

The subgraph state machine the agent generates should look like (7 states):

open → compute_grasp → refine_grasp → compute_align → rotate_align → descend → close → grasped

(grasped is the success-marker noop from sg.add_exit("grasped"), with an edge to END.)

State details:

1. open — type: tool, tool: "robot.open_gripper", inputs: { settle_steps: 40 }.
2. compute_grasp — type: tool, tool: "geometry.top_down_grasp_candidates", inputs: { obb: Ref("in.target_obb") }.
3. refine_grasp — type: script, file scripts/<sg>/refine_top_down_grasp.py (from this bundle's canonical_scripts). Inputs: grasp_pose = Ref("compute_grasp.candidates.poses.0"), target_obb = Ref("in.target_obb"). Returns grasp_pose: the candidate with its rotation rebuilt so this hand's closing axis lies across the OBB's short horizontal axis (robot.describe_gripper + robot.grasp_frame(approach=-z, close_heading_deg)), and its Z raised to the fingertip floor (support_z + finger.reach_m + finger.clearance_m) when the hand states its finger envelope. Keep this state: the candidate fan is world-aligned and a thin object's centred grasp jams the jaws on the table without the floor.
4. compute_align — type: script, file scripts/<sg>/compute_align_pose.py. Inputs: grasp_pose = Ref("refine_grasp.grasp_pose"), target_obb = Ref("in.target_obb"), optionally clearance (a literal in metres). Returns align_pose at the grasp XY and rotation, with z = max(obb_top, grasp_z) + clearance. Omit clearance (or pass 0) and the script asks robot.describe_workspace for align_clearance_m — the hand's own envelope above the fingertips. Pin it (e.g. 0.12) when the held object is what needs the room, such as a long tool that will hang below the fingertips on the way up.
5. rotate_align — type: tool, tool: "robot.go_to_pose", inputs: { pose: Ref("compute_align.align_pose") }.
6. descend — type: tool, tool: "robot.go_to_pose", inputs: { pose: Ref("refine_grasp.grasp_pose") } — the same pose compute_align was given, so hover and grasp share one rotation.
7. close — type: tool, tool: "robot.close_gripper", inputs: { settle_steps: 60 }. Edge directly from close to the grasped success marker; the subgraph's on_error: "failed" catches any raise from earlier steps. Whether the gripper actually closed on the object is checked by the target_held postcondition checkpoint (see ## Checkpoints), NOT by a re-check-and-raise node (none such exists).