Reference/API

Motion Planning

GraspTrajBuilder filters grasps, optionally IK-converts them onto an arm, then plans with build_motion_planner: a WarpPlanner by default, or its base TorchPlanner when MotionPlannerConfig.backend is "torch".

class[source]
graspkit.stages.grasp_traj_build.GraspTrajBuilder(
cfg: GraspTrajBuilderConfig,
device: Device
)

Convert floating-base grasps into deployable trajectories: filter, optional IK-convert to fixed, then plan.

Parameters
cfgGraspTrajBuilderConfigrequired
deviceDevicerequired
Members
attribute[source]
GraspTrajBuilder.filters: List[Filter]
method[source]
GraspTrajBuilder.build(
batch: GraspKitData,
start_qpos: Optional[Float[torch.Tensor, ...]] = None,
skip_filter: bool = False,
target_xy: Optional[torch.Tensor] = None
) -> Tuple[GraspKitData, Bool[torch.Tensor, 'B K']]

target_xy (S, 2) overrides the ori-gate target when scenes lack a target mesh (e.g. deploy perception).

Parameters
batchGraspKitDatarequired
start_qposOptional[Float[torch.Tensor, ...]]= None
skip_filterbool= False
target_xyOptional[torch.Tensor]= None
Returns
Tuple[GraspKitData, Bool[torch.Tensor, 'B K']]
method[source]
GraspTrajBuilder.filter_grasps(
batch: GraspKitData,
success: Bool[torch.Tensor, 'B K']
) -> Tuple[Bool[torch.Tensor, 'B K'], List[str]]
Parameters
batchGraspKitDatarequired
successBool[torch.Tensor, 'B K']required
Returns
Tuple[Bool[torch.Tensor, 'B K'], List[str]]
class[source]
graspkit.configs.experiment_config.GraspTrajBuilderConfig(
fixed_base_robot_config: Optional[RobotConfig] = None,
floating_base_robot_config: Optional[RobotConfig] = None,
convert_to_fixed: bool = False,
motion_planner: MotionPlannerConfig = MotionPlannerConfig(),
hand_axis: Optional[HandAxis] = None,
hand_axis_target: Tuple[float, float, float] = (0.0, 0.0, 1.0),
filter_hand_axis_max_angle_deg: float = 30.0,
contact_avoid_filter: bool = False,
pen_filter: bool = False,
pen_filter_threshold: float = 0.005,
rest_pose_filter_max_dist: Optional[float] = None,
arm_range_fraction: float = 0.3,
ori_threshold_deg: float = 45.0,
plan_table_only: bool = False
)

Grasp traj builder: floating-base grasps -> deployable trajectories (stages/traj_builder).

Parameters
fixed_base_robot_configOptional[RobotConfig]= None
floating_base_robot_configOptional[RobotConfig]= None
convert_to_fixedbool= False
motion_plannerMotionPlannerConfig= MotionPlannerConfig()
hand_axisOptional[HandAxis]= None
hand_axis_targetTuple[float, float, float]= (0.0, 0.0, 1.0)
filter_hand_axis_max_angle_degfloat= 30.0
contact_avoid_filterbool= False
pen_filterbool= False
pen_filter_thresholdfloat= 0.005
rest_pose_filter_max_distOptional[float]= None
arm_range_fractionfloat= 0.3
ori_threshold_degfloat= 45.0
plan_table_onlybool= False
Members
attribute[source]
GraspTrajBuilderConfig.fixed_base_robot_config: Optional[RobotConfig] = None

Fixed-base arm+hand robot trajectories are planned for; also the camera-mount robot. None if floating-only.

attribute[source]
GraspTrajBuilderConfig.floating_base_robot_config: Optional[RobotConfig] = None

Floating-base hand-only robot the input grasps come from.

attribute[source]
GraspTrajBuilderConfig.convert_to_fixed: bool = False

True: filter + IK-convert floating grasps, build trajectories for the fixed robot. False: plan grasps as-is.

attribute[source]
GraspTrajBuilderConfig.motion_planner: MotionPlannerConfig = field(default_factory=MotionPlannerConfig)

Motion planner config for the trajectory from the init pose to the grasp pose.

attribute[source]
GraspTrajBuilderConfig.hand_axis: Optional[HandAxis] = None

Hand-axis cone filter on optimized grasps: which hand_coord_spec axis to check. None disables it.

attribute[source]
GraspTrajBuilderConfig.hand_axis_target: Tuple[float, float, float] = (0.0, 0.0, 1.0)

Direction hand_axis should point, in the robot base frame (world for floating hands).

attribute[source]
GraspTrajBuilderConfig.filter_hand_axis_max_angle_deg: float = 30.0

Hand-axis cone half-angle in degrees.

attribute[source]
GraspTrajBuilderConfig.contact_avoid_filter: bool = False

Reject grasps where the contact-avoid point is closer to the target than the contact point on that link.

attribute[source]
GraspTrajBuilderConfig.pen_filter: bool = False

Reject grasps whose hand spheres overlap the target by more than pen_filter_threshold (m); fingertip ok.

attribute[source]
GraspTrajBuilderConfig.pen_filter_threshold: float = 0.005
attribute[source]
GraspTrajBuilderConfig.rest_pose_filter_max_dist: Optional[float] = None

Reject grasps whose arm qpos (L2 over arm joints) is further than this from robot rest pose; None disables.

attribute[source]
GraspTrajBuilderConfig.arm_range_fraction: float = 0.3

Half-width (fraction of each arm joint's range around its midpoint) the IK solution must lie in; 1.0 disables.

attribute[source]
GraspTrajBuilderConfig.ori_threshold_deg: float = 45.0

Ori-gate half-angle (deg) for the floating->fixed IK conversion; 45 = default, 90 effectively disables.

attribute[source]
GraspTrajBuilderConfig.plan_table_only: bool = False

Plan against a table-only scene (object removed), mirroring deployment. Pre/post qpos use the real scene.

class[source]
graspkit.stages.motion_plan.WarpPlanner(
cfg: MotionPlannerConfig,
robot_config: RobotConfig,
device: Device = 'cpu'
)
Bases: TorchPlanner

TorchPlanner on robokit's MotionPlanner: joint-goal plans, or one plan from start through the lift.

Parameters
cfgMotionPlannerConfigrequired
robot_configRobotConfigrequired
deviceDevice= 'cpu'
Members
methodinherited from TorchPlanner[source]
WarpPlanner.plan(
batch: GraspKitData,
start_qpos: Optional[Float[torch.Tensor, num_dofs]] = None,
return_pre_post_only: bool = False
) -> GraspKitData

Plan a padded batch: needs grasp_qpos, returns pre/post-grasp qpos + full_traj_qpos unless pre-post-only.

Parameters
batchGraspKitDatarequired
start_qposOptional[Float[torch.Tensor, num_dofs]]= None
return_pre_post_onlybool= False
Returns
GraspKitData
methodinherited from TorchPlanner[source]
WarpPlanner.get_pre_post_grasp_qpos(
scene_geom: SceneGeom,
grasp_qpos: Float[torch.Tensor, 'n_scenes n_grasps num_dofs']
) -> Tuple[Float[torch.Tensor, 'n_scenes n_grasps num_dofs'], Float[torch.Tensor, 'n_scenes n_grasps num_dofs']]
Parameters
scene_geomSceneGeomrequired
grasp_qposFloat[torch.Tensor, 'n_scenes n_grasps num_dofs']required
Returns
Tuple[Float[torch.Tensor, 'n_scenes n_grasps num_dofs'], Float[torch.Tensor, 'n_scenes n_grasps num_dofs']]
methodinherited from TorchPlanner[source]
WarpPlanner.interpolate_qpos(
init_qpos: Float[torch.Tensor, '... num_dofs'],
end_qpos: Float[torch.Tensor, '... num_dofs'],
num_steps: int
) -> Float[torch.Tensor, '... num_steps num_dofs']
Parameters
init_qposFloat[torch.Tensor, '... num_dofs']required
end_qposFloat[torch.Tensor, '... num_dofs']required
num_stepsintrequired
Returns
Float[torch.Tensor, '... num_steps num_dofs']
methodinherited from TorchPlanner[source]
WarpPlanner.compute_pose_penetration(
qpos: Float[torch.Tensor, '... num_dofs'],
scene_geom: SceneGeom
) -> Float[torch.Tensor, ...]
Parameters
qposFloat[torch.Tensor, '... num_dofs']required
scene_geomSceneGeomrequired
Returns
Float[torch.Tensor, ...]
methodinherited from TorchPlanner[source]
WarpPlanner.interpolate_trajs(
orig_trajs: Float[torch.Tensor, 'n_scenes n_trajs n_steps num_dofs'],
num_steps: int
) -> Float[torch.Tensor, 'n_scenes n_trajs num_steps num_dofs']
Parameters
orig_trajsFloat[torch.Tensor, 'n_scenes n_trajs n_steps num_dofs']required
num_stepsintrequired
Returns
Float[torch.Tensor, 'n_scenes n_trajs num_steps num_dofs']
methodinherited from TorchPlanner[source]
WarpPlanner.compute_energy(
full_traj_qpos: Float[torch.Tensor, 'n_scenes n_trajs n_steps num_dofs'],
scene_geom: SceneGeom
) -> dict[str, torch.Tensor]

Compute E_pen + E_smooth for a trajectory; mirrors optimize_trajs loss, a benchmark reference metric.

Parameters
full_traj_qposFloat[torch.Tensor, 'n_scenes n_trajs n_steps num_dofs']required
scene_geomSceneGeomrequired
Returns
dict[str, torch.Tensor]
methodinherited from TorchPlanner[source]
WarpPlanner.get_lifting_target_qpos(
post_grasp_qpos: Float[torch.Tensor, 'n_scenes n_grasps num_dofs']
) -> Float[torch.Tensor, 'n_scenes n_grasps num_dofs']
Parameters
post_grasp_qposFloat[torch.Tensor, 'n_scenes n_grasps num_dofs']required
Returns
Float[torch.Tensor, 'n_scenes n_grasps num_dofs']
method[source]
WarpPlanner.plan_full(
start_qpos: Float[torch.Tensor, 'n_scenes n_grasps num_dofs'],
pre_grasp_qpos: Float[torch.Tensor, 'n_scenes n_grasps num_dofs'],
grasp_qpos: Float[torch.Tensor, 'n_scenes n_grasps num_dofs'],
post_grasp_qpos: Float[torch.Tensor, 'n_scenes n_grasps num_dofs'],
lift_qpos: Optional[Float[torch.Tensor, 'n_scenes n_grasps num_dofs']],
scene_geom: SceneGeom
) -> Tuple[Float[torch.Tensor, 'n_scenes n_grasps num_steps num_dofs'], Float[torch.Tensor, 'n_scenes n_grasps']]

One robokit plan: start → pre-grasp against the scene, then grasp, the locked hold and the lift without it.

robokit times every segment but the hold, which keeps num_steps_holding; the plan is sampled every control_dt and padded with its last frame to num_steps when shorter. Returns it and the start → pre-grasp penetration.

Parameters
start_qposFloat[torch.Tensor, 'n_scenes n_grasps num_dofs']required
pre_grasp_qposFloat[torch.Tensor, 'n_scenes n_grasps num_dofs']required
grasp_qposFloat[torch.Tensor, 'n_scenes n_grasps num_dofs']required
post_grasp_qposFloat[torch.Tensor, 'n_scenes n_grasps num_dofs']required
lift_qposOptional[Float[torch.Tensor, 'n_scenes n_grasps num_dofs']]required
scene_geomSceneGeomrequired
Returns
Tuple[Float[torch.Tensor, 'n_scenes n_grasps num_steps num_dofs'], Float[torch.Tensor, 'n_scenes n_grasps']]
method[source]
WarpPlanner.optimize_trajs(
init_trajs: Float[torch.Tensor, '... num_steps num_dofs'],
scene_geom: SceneGeom
) -> Tuple[Float[torch.Tensor, '... num_steps num_dofs'], Float[torch.Tensor, ...]]
Parameters
init_trajsFloat[torch.Tensor, '... num_steps num_dofs']required
scene_geomSceneGeomrequired
Returns
Tuple[Float[torch.Tensor, '... num_steps num_dofs'], Float[torch.Tensor, ...]]
class[source]
graspkit.configs.experiment_config.MotionPlannerConfig(
backend: Literal['torch', 'warp'] = 'warp',
pre_grasp_arm_grad_move: float = 0.001,
pre_grasp_hand_grad_move: float = 0.0,
post_grasp_hand_grad_move: float = 1.0,
lifting_dist: float = 0.3,
padding_dist: float = 0.025,
opt_steps: int = 300,
pen_weight: float = 1.0,
arm_smooth_weight: float = 100.0,
hand_smooth_weight: float = 10.0,
vel_smooth_weight: float = 0.1,
num_steps_pre_grasp: int = 150,
num_steps_pre_to_grasp: int = 25,
num_steps_holding: int = 75,
close_during_holding: bool = False,
num_steps_post_grasp: int = 50,
control_dt: float = 0.02,
enable_joint_optimization: bool = False,
traj_opt_max_iter: int = 100,
traj_opt_smoothness_weight: float = 200.0,
traj_opt_accel_smoothness_weight: float = 30.0,
traj_opt_self_collision_weight: float = 0.0,
traj_opt_self_collision_margin: float = 0.02,
start_from_grasp_dof_indices: Optional[Tuple[int, ...]] = None,
num_samples_per_batch: int = 2048,
num_grasps_per_scene: int = 32
)

Trajectory optimization params — hand-independent defaults.

Parameters
backendLiteral['torch', 'warp']= 'warp'
pre_grasp_arm_grad_movefloat= 0.001
pre_grasp_hand_grad_movefloat= 0.0
post_grasp_hand_grad_movefloat= 1.0
lifting_distfloat= 0.3
padding_distfloat= 0.025
opt_stepsint= 300
pen_weightfloat= 1.0
arm_smooth_weightfloat= 100.0
hand_smooth_weightfloat= 10.0
vel_smooth_weightfloat= 0.1
num_steps_pre_graspint= 150
num_steps_pre_to_graspint= 25
num_steps_holdingint= 75
close_during_holdingbool= False
num_steps_post_graspint= 50
control_dtfloat= 0.02
enable_joint_optimizationbool= False
traj_opt_max_iterint= 100
traj_opt_smoothness_weightfloat= 200.0
traj_opt_accel_smoothness_weightfloat= 30.0
traj_opt_self_collision_weightfloat= 0.0
traj_opt_self_collision_marginfloat= 0.02
start_from_grasp_dof_indicesOptional[Tuple[int, ...]]= None
num_samples_per_batchint= 2048
num_grasps_per_sceneint= 32
Members
attribute[source]
MotionPlannerConfig.backend: Literal['torch', 'warp'] = 'warp'

Motion planner backend. 'warp' (default; robokit MotionPlanner, fixed-base only) is faster than 'torch'.

attribute[source]
MotionPlannerConfig.pre_grasp_arm_grad_move: float = 0.001

Pre-grasp arm gradient move

attribute[source]
MotionPlannerConfig.pre_grasp_hand_grad_move: float = 0.0

Pre-grasp hand gradient move

attribute[source]
MotionPlannerConfig.post_grasp_hand_grad_move: float = 1.0

Post-grasp hand gradient move

attribute[source]
MotionPlannerConfig.lifting_dist: float = 0.3

Lifting distance

attribute[source]
MotionPlannerConfig.padding_dist: float = 0.025

Padding distance

attribute[source]
MotionPlannerConfig.opt_steps: int = 300

Optimization steps

attribute[source]
MotionPlannerConfig.pen_weight: float = 1.0

Penetration weight

attribute[source]
MotionPlannerConfig.arm_smooth_weight: float = 100.0

Arm smooth weight

attribute[source]
MotionPlannerConfig.hand_smooth_weight: float = 10.0

Hand smooth weight

attribute[source]
MotionPlannerConfig.vel_smooth_weight: float = 0.1

Velocity smooth weight

attribute[source]
MotionPlannerConfig.num_steps_pre_grasp: int = 150

Number of steps in pre-grasp

attribute[source]
MotionPlannerConfig.num_steps_pre_to_grasp: int = 25

Number of steps in pre-to-grasp

attribute[source]
MotionPlannerConfig.num_steps_holding: int = 75

Number of steps in holding

attribute[source]
MotionPlannerConfig.close_during_holding: bool = False

Close gradually during holding instead of settling at the closed pose.

attribute[source]
MotionPlannerConfig.num_steps_post_grasp: int = 50

Number of steps in post-grasp

attribute[source]
MotionPlannerConfig.control_dt: float = 0.02

Seconds per trajectory step, the simulator's control period.

attribute[source]
MotionPlannerConfig.enable_joint_optimization: bool = False

Fixed base, warp: one robokit plan through start, pre-grasp, grasp, hold and lift, timed by robokit except the hold (num_steps_holding); at least num_steps long. False optimizes start → pre-grasp alone and fills the other phases at their step counts.

attribute[source]
MotionPlannerConfig.traj_opt_max_iter: int = 100
attribute[source]
MotionPlannerConfig.traj_opt_smoothness_weight: float = 200.0
attribute[source]
MotionPlannerConfig.traj_opt_accel_smoothness_weight: float = 30.0
attribute[source]
MotionPlannerConfig.traj_opt_self_collision_weight: float = 0.0

Self-collision weight (warp only). 0 disables the term; the robokit q_goal preset ships it off.

attribute[source]
MotionPlannerConfig.traj_opt_self_collision_margin: float = 0.02

Self-collision margin in metres; only read when the weight is > 0.

attribute[source]
MotionPlannerConfig.start_from_grasp_dof_indices: Optional[Tuple[int, ...]] = None

DOF indices whose start values come from grasp_qpos, not init pose; also locked during post-grasp lift IK.

attribute[source]
MotionPlannerConfig.num_samples_per_batch: int = 2048

Number of samples per batch

attribute[source]
MotionPlannerConfig.num_grasps_per_scene: int = 32

Number of grasps to plan per scene (pad/truncate to this)

property[source]
MotionPlannerConfig.num_steps: int