Reference/API

Policy

Create a policy with build_grasp_policy(cfg, robot_config, device).

graspkit.models.grasp_policy.GraspPolicy(
cfg: GraspPolicyConfig,
action_dim: int,
robot_config: RobotConfig
)
Bases: nn.Module

Predicts pre-grasp, grasp and post-grasp configurations from an observation; see build_grasp_policy.

Parameters
cfgGraspPolicyConfigrequired
action_dimintrequired
robot_configRobotConfigrequired
Members
attribute[source]
GraspPolicy.robot_helper: GraspRobot | None
property[source]
GraspPolicy.generator: CVAE | FlowMatching
method[source]
GraspPolicy.forward(
obs: dict,
actions: Float[torch.Tensor, 'b n t d']
) -> dict[str, torch.Tensor]
Parameters
obsdictrequired
actionsFloat[torch.Tensor, 'b n t d']required
Returns
dict[str, torch.Tensor]
method[source]
GraspPolicy.preprocess(
initial: dict,
current: dict,
calibrated: bool
) -> dict[str, torch.Tensor]

One scene's input from env.observe() slices plus "qpos" (1, 1, D); calibrated views skip the initial.

Parameters
initialdictrequired
currentdictrequired
calibratedboolrequired
Returns
dict[str, torch.Tensor]
method[source]
GraspPolicy.get_action(
obs: dict,
num_samples_per_scene: int = 1,
noise: torch.Tensor | None = None
) -> Float[torch.Tensor, 'b n t d']

Sample actions; guided sampling accepts raw noise shaped (batch * samples, latent_dim).

Parameters
obsdictrequired
num_samples_per_sceneint= 1
noisetorch.Tensor | None= None
Returns
Float[torch.Tensor, 'b n t d']
method[source]
GraspPolicy.select(
obs: dict,
actions: Float[torch.Tensor, 'b n t d']
) -> torch.Tensor

Each scene's best proposal index by the grasp evaluator, on the features get_action left in obs.

Parameters
obsdictrequired
actionsFloat[torch.Tensor, 'b n t d']required
Returns
torch.Tensor
graspkit.configs.grasp_policy_config.GraspPolicyConfig(
num_queries: int = 3,
convert_rxyz_to_rot6d: bool = False,
analytic_euler: bool = False,
coupled_floating_base: bool = False,
rot_begin_idx: int = 3,
enable_kinematic_loss: bool = False,
vision_encoder: Literal['pointnet', 'pointnet_state', 'spconv', 'rgb', 'rgb_resnet', 'rgb_resnet_views'] = 'spconv',
vision_encoder_feature_dim: int = 512,
vision_encoder_normalization: Literal['layernorm', 'groupnorm'] | None = None,
vision_encoder_global_feature: bool = True,
center_pointcloud: bool = False,
pointcloud_scale: float = 1.0,
train_yaw_augmentation: bool = False,
canonical_yaw: bool = False,
enable_objectness_prediction: bool = True,
num_points: int = 2048,
object_points_only: bool = True,
generative_model: Literal['cvae', 'flow', 'flow_transformer'] = 'cvae',
cvae_latent_dim: int = 256,
cvae_hidden_dim: int = 256,
cvae_learned_prior: bool = False,
normalize_cvae_actions: bool = False,
reconstruction_loss: Literal['native', 'phase_std_mse'] = 'native',
qpos_weight: float = 1.0,
rot_weight: float = 1.0,
tl_weight: float = 1.0,
kinematic_weight: float = 100.0,
kl_weight: float = 0.01,
objectness_weight: float = 0.02,
graspness_weight: float = 0.02,
enable_penetration_loss: bool = False,
penetration_weight: float = 0.1,
penetration_threshold: float = 0.005,
penetration_every: int = 1,
penetration_warmup_iters: int = 0,
prior_fingertip_weight: float = 0.0,
use_mean: bool = True,
cvae_temperature: float = 1.0,
grasp_evaluator_guidance_steps: int = 0,
grasp_evaluator_guidance_radius: float = 2.0,
grasp_evaluator_local_features: bool = False,
grasp_evaluator_anchor_state: bool = False,
grasp_evaluator_hand_joint_features: bool = False,
grasp_evaluator_mask_constant_features: bool = True
)

Grasp policy architecture, losses and sampling.

Reusable presets live in graspkit/configs/grasp_policy.py.

Parameters
num_queriesint= 3
convert_rxyz_to_rot6dbool= False
analytic_eulerbool= False
coupled_floating_basebool= False
rot_begin_idxint= 3
enable_kinematic_lossbool= False
vision_encoderLiteral['pointnet', 'pointnet_state', 'spconv', 'rgb', 'rgb_resnet', 'rgb_resnet_views']= 'spconv'
vision_encoder_feature_dimint= 512
vision_encoder_normalizationLiteral['layernorm', 'groupnorm'] | None= None
vision_encoder_global_featurebool= True
center_pointcloudbool= False
pointcloud_scalefloat= 1.0
train_yaw_augmentationbool= False
canonical_yawbool= False
enable_objectness_predictionbool= True
num_pointsint= 2048
object_points_onlybool= True
generative_modelLiteral['cvae', 'flow', 'flow_transformer']= 'cvae'
cvae_latent_dimint= 256
cvae_hidden_dimint= 256
cvae_learned_priorbool= False
normalize_cvae_actionsbool= False
reconstruction_lossLiteral['native', 'phase_std_mse']= 'native'
qpos_weightfloat= 1.0
rot_weightfloat= 1.0
tl_weightfloat= 1.0
kinematic_weightfloat= 100.0
kl_weightfloat= 0.01
objectness_weightfloat= 0.02
graspness_weightfloat= 0.02
enable_penetration_lossbool= False
penetration_weightfloat= 0.1
penetration_thresholdfloat= 0.005
penetration_everyint= 1
penetration_warmup_itersint= 0
prior_fingertip_weightfloat= 0.0
use_meanbool= True
cvae_temperaturefloat= 1.0
grasp_evaluator_guidance_stepsint= 0
grasp_evaluator_guidance_radiusfloat= 2.0
grasp_evaluator_local_featuresbool= False
grasp_evaluator_anchor_statebool= False
grasp_evaluator_hand_joint_featuresbool= False
grasp_evaluator_mask_constant_featuresbool= True
Members
attribute[source]
GraspPolicyConfig.num_queries: int = 3

Configurations decoded per trajectory; the trainer and evaluator assume three: pre-grasp, grasp and post-grasp.

attribute[source]
GraspPolicyConfig.convert_rxyz_to_rot6d: bool = False

Floating base: predict a continuous 6D rotation instead of Euler rxyz, converted back on output.

attribute[source]
GraspPolicyConfig.analytic_euler: bool = False

Use exact, non-iterative Euler conversion after decoding rotations.

attribute[source]
GraspPolicyConfig.coupled_floating_base: bool = False

Share wrist rotation across all three poses and wrist translation during closing.

attribute[source]
GraspPolicyConfig.rot_begin_idx: int = 3

Start index of the floating-base rotation in each action.

attribute[source]
GraspPolicyConfig.enable_kinematic_loss: bool = False

Add the MSE between predicted and target link positions from forward kinematics.

attribute[source]
GraspPolicyConfig.vision_encoder: Literal['pointnet', 'pointnet_state', 'spconv', 'rgb', 'rgb_resnet', 'rgb_resnet_views'] = 'spconv'

Observation backbone.

attribute[source]
GraspPolicyConfig.vision_encoder_feature_dim: int = 512

Condition feature size passed to the generator.

attribute[source]
GraspPolicyConfig.vision_encoder_normalization: Literal['layernorm', 'groupnorm'] | None = None

Normalization for the SpConv encoder.

attribute[source]
GraspPolicyConfig.vision_encoder_global_feature: bool = True

Return one scene feature; False keeps per-point features for local grasp-point conditioning.

attribute[source]
GraspPolicyConfig.center_pointcloud: bool = False

Predict floating-base translations relative to the observed point-cloud centroid.

attribute[source]
GraspPolicyConfig.pointcloud_scale: float = 1.0

Fixed coordinate scale applied only to vision-encoder inputs.

attribute[source]
GraspPolicyConfig.train_yaw_augmentation: bool = False

Rotate training observations and target poses together around the vertical axis.

attribute[source]
GraspPolicyConfig.canonical_yaw: bool = False

Use a deterministic observed-point-cloud yaw frame for training and inference.

attribute[source]
GraspPolicyConfig.enable_objectness_prediction: bool = True

With local features, train a target-segmentation head and mask graspness at inference.

attribute[source]
GraspPolicyConfig.num_points: int = 2048

Points GraspPolicy.preprocess samples from an observed point cloud.

attribute[source]
GraspPolicyConfig.object_points_only: bool = True

GraspPolicy.preprocess keeps only the target's points, initial and current frames together (hands occlude).

attribute[source]
GraspPolicyConfig.generative_model: Literal['cvae', 'flow', 'flow_transformer'] = 'cvae'

cvae (models/cvae.py) or flow matching (models/flow_matching.py).

attribute[source]
GraspPolicyConfig.cvae_latent_dim: int = 256

Latent dimension of the CVAE.

attribute[source]
GraspPolicyConfig.cvae_hidden_dim: int = 256

Width of the generator networks and optional CVAE learned prior.

attribute[source]
GraspPolicyConfig.cvae_learned_prior: bool = False

Jointly learn a diagonal-Gaussian latent prior conditioned on the observation.

attribute[source]
GraspPolicyConfig.normalize_cvae_actions: bool = False

Encode standardized actions and decode physical actions using saved mean/std buffers.

attribute[source]
GraspPolicyConfig.reconstruction_loss: Literal['native', 'phase_std_mse'] = 'native'

Native reconstruction loss or MSE scaled by each phase's training action standard deviation.

attribute[source]
GraspPolicyConfig.qpos_weight: float = 1.0

Joint-position reconstruction weight: L1 for CVAE, MSE for flow.

attribute[source]
GraspPolicyConfig.rot_weight: float = 1.0

Floating-base rotation L1 weight.

attribute[source]
GraspPolicyConfig.tl_weight: float = 1.0

Floating-base translation L1 weight.

attribute[source]
GraspPolicyConfig.kinematic_weight: float = 100.0

Weight of the kinematic loss.

attribute[source]
GraspPolicyConfig.kl_weight: float = 0.01

Weight of the KL term to the unit Gaussian.

attribute[source]
GraspPolicyConfig.objectness_weight: float = 0.02

Weight of the local-feature objectness BCE.

attribute[source]
GraspPolicyConfig.graspness_weight: float = 0.02

Weight of the local-feature per-point graspness KL.

attribute[source]
GraspPolicyConfig.enable_penetration_loss: bool = False

if True, penalize hand collision-sphere penetration into the target object (needs scene geom at train time)

attribute[source]
GraspPolicyConfig.penetration_weight: float = 0.1

the weight of the penetration loss

attribute[source]
GraspPolicyConfig.penetration_threshold: float = 0.005

only penetration deeper than this (meters) is penalized (avoids punishing legitimate contact)

attribute[source]
GraspPolicyConfig.penetration_every: int = 1

compute the (expensive) penetration loss every N steps to amortize per-batch scene-geometry build

attribute[source]
GraspPolicyConfig.penetration_warmup_iters: int = 0

delay the penetration loss until this iteration so the policy learns to grasp first (replaces fine-tuning)

attribute[source]
GraspPolicyConfig.prior_fingertip_weight: float = 0.0

Attract prior-sampled fingertip collision spheres to the target surface during training.

attribute[source]
GraspPolicyConfig.use_mean: bool = True

Decode the prior mean for CVAE or integrate from zero noise for flow.

attribute[source]
GraspPolicyConfig.cvae_temperature: float = 1.0

Scale of the sampled generator noise; ignored when use_mean is True.

attribute[source]
GraspPolicyConfig.grasp_evaluator_guidance_steps: int = 0

Latent refinement steps using a trained grasp evaluator; zero disables guidance.

attribute[source]
GraspPolicyConfig.grasp_evaluator_guidance_radius: float = 2.0

Maximum L2 displacement from each initial latent draw.

attribute[source]
GraspPolicyConfig.grasp_evaluator_local_features: bool = False

Let the grasp evaluator attend to frozen local visual tokens; the actor stays unchanged.

attribute[source]
GraspPolicyConfig.grasp_evaluator_anchor_state: bool = False

Condition the local success critic on the current fixed-base robot configuration.

attribute[source]
GraspPolicyConfig.grasp_evaluator_hand_joint_features: bool = False

Encode hand joints instead of all actuated joints in the grasp evaluator.

attribute[source]
GraspPolicyConfig.grasp_evaluator_mask_constant_features: bool = True

Zero constant replay features after scorer normalization.