Reference/API

Environments

Create an environment with build_env(cfg, robot_config, device); EnvConfig selects the backend.

class[source]
graspkit.envs.BaseEnv()
Bases: ABC

Unified grasp env: MsEnv (ManiSkill), MjEnv (MuJoCo), IsaacEnv (Isaac), RealEnv (hardware).

  • evaluate is the batched-rollout, reported-SR path shared by all eval call sites.
  • reset/get_qpos/step_qpos/get_rgb/get_pointcloud are the deploy primitives shared by sim and real.
  • get_object_pose/set_object_pose/observe drive simulated closed-loop policy evaluation.
Members
attribute[source]
BaseEnv.last_rollouts: list[Rollout]
method[source]
BaseEnv.reset(
scene: SceneDescription | list[SceneDescription] | None = None,
init_qpos: torch.Tensor | None = None,
root_pose: torch.Tensor | None = None,
camera_pose: torch.Tensor | None = None
)

Initialize the scene (simulators accept a list, one env each), robot, and calibrated camera pose.

Parameters
sceneSceneDescription | list[SceneDescription] | None= None
init_qpostorch.Tensor | None= None
root_posetorch.Tensor | None= None
camera_posetorch.Tensor | None= None
method[source]
BaseEnv.get_qpos() -> torch.Tensor

Current joint positions, ours order, shape (B, D).

Returns
torch.Tensor
method[source]
BaseEnv.step_qpos(
q: torch.Tensor
)

Command target q (ours order) and advance one control step.

Parameters
qtorch.Tensorrequired
method[source]
BaseEnv.get_info() -> dict[str, torch.Tensor]

Return backend metrics for the current state.

Returns
dict[str, torch.Tensor]
method[source]
BaseEnv.set_qpos_traj(
traj_qpos: torch.Tensor,
qpos_callback: Callable[[int, torch.Tensor], None] | None = None
) -> dict[str, torch.Tensor]

Stream one (T, D) qpos trajectory through the backend; the callback sees measured qpos.

Parameters
traj_qpostorch.Tensorrequired
qpos_callbackCallable[[int, torch.Tensor], None] | None= None
Returns
dict[str, torch.Tensor]
method[source]
BaseEnv.get_rgb() -> np.ndarray

Latest RGB camera image, shape (H, W, 3), uint8.

Returns
np.ndarray
method[source]
BaseEnv.get_pointcloud(
mask: np.ndarray
) -> torch.Tensor

Object cloud selected by an aligned image mask, in world frame, shape (B, N, 3).

Parameters
masknp.ndarrayrequired
Returns
torch.Tensor
method[source]
BaseEnv.get_object_pose() -> torch.Tensor

Target object world poses, shape (B, 7) [xyz, quat_wxyz]; simulators only.

Returns
torch.Tensor
method[source]
BaseEnv.set_object_pose(
pose: torch.Tensor
)

Teleport the target objects to world poses (B, 7); simulators only.

Parameters
posetorch.Tensorrequired
method[source]
BaseEnv.observe() -> dict[str, torch.Tensor]

Sim-only, robot-free: rgb (B, V, H, W, 3), world xyz/seg (B, N, 3/1), seg_id, camera_poses.

Returns
dict[str, torch.Tensor]
method[source]
BaseEnv.evaluate(
batch: GraspKitData,
record: bool = False
) -> dict[str, torch.Tensor]

Rollout of batch.full_traj_qpos; infos keyed by metric; record=True fills self.last_rollouts.

Parameters
batchGraspKitDatarequired
recordbool= False
Returns
dict[str, torch.Tensor]
method[source]
BaseEnv.close()

Release the backend (sim envs / worker pool / hardware).

class[source]
graspkit.configs.experiment_config.EnvConfig(
ms_env_config: MsEnvConfig = MsEnvConfig(),
mj_env_config: Optional[MjEvalConfig] = None,
isaac_env_config: Optional[IsaacEnvConfig] = None,
mj_native_env_config: Optional[MjNativeEnvConfig] = None,
load_scenes: bool = True,
control_freq: int = 50,
target_lift_dist: float = 0.2,
object_mass: float = 0.01,
floating_object: bool = False,
camera_width: int = 960,
camera_height: int = 540,
camera_intrinsic: Tuple[Tuple[float, float, float], ...] = (lambda: ((677, 0, 492), (0, 677, 268), (0, 0, 1)))(),
camera_near: float = 0.01,
cameras: Tuple[CameraSpec, ...] = (),
contact_offset: float = 0.001,
num_envs: int = 2048,
num_seeds: int = 1,
enable_perturbation: bool = True,
perturbation_step_range: Tuple[int, int] = (35, 80),
perturbation_magnitude: float = 150.0,
num_perturbations: int = 8,
perturbation_duration: int = 1
)

The tabletop grasp task; select Isaac or MuJoCo with their optional configuration, otherwise ManiSkill.

Parameters
ms_env_configMsEnvConfig= MsEnvConfig()
mj_env_configOptional[MjEvalConfig]= None
isaac_env_configOptional[IsaacEnvConfig]= None
mj_native_env_configOptional[MjNativeEnvConfig]= None
load_scenesbool= True
control_freqint= 50
target_lift_distfloat= 0.2
object_massfloat= 0.01
floating_objectbool= False
camera_widthint= 960
camera_heightint= 540
camera_intrinsicTuple[Tuple[float, float, float], ...]= (lambda: ((677, 0, 492), (0, 677, 268), (0, 0, 1)))()
camera_nearfloat= 0.01
camerasTuple[CameraSpec, ...]= ()
contact_offsetfloat= 0.001
num_envsint= 2048
num_seedsint= 1
enable_perturbationbool= True
perturbation_step_rangeTuple[int, int]= (35, 80)
perturbation_magnitudefloat= 150.0
num_perturbationsint= 8
perturbation_durationint= 1
Members
attribute[source]
EnvConfig.ms_env_config: MsEnvConfig = field(default_factory=MsEnvConfig)

ManiSkill-only settings

attribute[source]
EnvConfig.mj_env_config: Optional[MjEvalConfig] = None

MuJoCo evaluator config; set this to select the MuJoCo backend.

attribute[source]
EnvConfig.isaac_env_config: Optional[IsaacEnvConfig] = None

Isaac backend config; mutually exclusive with mj_env_config.

attribute[source]
EnvConfig.mj_native_env_config: Optional[MjNativeEnvConfig] = None

Closed-loop MuJoCo backend config; at most one of the backend configs may be set.

attribute[source]
EnvConfig.load_scenes: bool = True

Whether to load scenes (actors and tables).

attribute[source]
EnvConfig.control_freq: int = 50

Control frequency.

attribute[source]
EnvConfig.target_lift_dist: float = 0.2

Target lift distance.

attribute[source]
EnvConfig.object_mass: float = 0.01

Mass of the object.

attribute[source]
EnvConfig.floating_object: bool = False

Whether to use a floating object.

attribute[source]
EnvConfig.camera_width: int = 960

Width of the camera.

attribute[source]
EnvConfig.camera_height: int = 540

Height of the camera.

attribute[source]
EnvConfig.camera_intrinsic: Tuple[Tuple[float, float, float], ...] = field(default_factory=lambda: ((677, 0, 492), (0, 677, 268), (0, 0, 1)))

Intrinsic matrix of the camera.

attribute[source]
EnvConfig.camera_near: float = 0.01

Near clipping plane of the camera.

attribute[source]
EnvConfig.cameras: Tuple[CameraSpec, ...] = ()

Cameras rendered instead of ManiSkill's base_camera (with ms_env_config.robot_uid None); Isaac and MuJoCo render only these.

attribute[source]
EnvConfig.contact_offset: float = 0.001

PhysX contact_offset (m). Larger = compliant/sticky-feeling fingertip pads.

attribute[source]
EnvConfig.num_envs: int = 2048

Number of environments to evaluate on

attribute[source]
EnvConfig.num_seeds: int = 1

Number of seeds

attribute[source]
EnvConfig.enable_perturbation: bool = True

Whether to enable perturbation

attribute[source]
EnvConfig.perturbation_step_range: Tuple[int, int] = (35, 80)

Perturbation step range

attribute[source]
EnvConfig.perturbation_magnitude: float = 150.0

Perturbation magnitude

attribute[source]
EnvConfig.num_perturbations: int = 8

Number of perturbations

attribute[source]
EnvConfig.perturbation_duration: int = 1

Number of consecutive steps to apply each perturbation force (1 = single impulse)

class[source]
graspkit.configs.env_config.MsEnvConfig(
robot_uid: Optional[str] = None,
reconfiguration_freq: Optional[int] = 1
)

ManiSkill-only settings; the task itself is EnvConfig's.

Parameters
robot_uidOptional[str]= None
reconfiguration_freqOptional[int]= 1
Members
attribute[source]
MsEnvConfig.robot_uid: Optional[str] = None

ManiSkill agent uid; None registers one from the robot config. A hand-only uid on a floating-base robot means a static base.

attribute[source]
MsEnvConfig.reconfiguration_freq: Optional[int] = 1

Reconfiguration frequency.

class[source]
graspkit.configs.env_config.MjEvalConfig(
num_workers: int = 48,
obj_mass: float = 0.1,
miu_coef: tuple = (0.6, 0.02),
setting: str = 'fc',
max_pene: float = 0.01,
trans_thre: float = 0.05,
lift_slip_thre: float = 0.02,
min_lift_dist: float = 0.0,
grasp_interp_steps: int = 25,
lift_interp_steps: int = 50,
angle_thre: float = 15.0,
contact_margin: float = 0.01,
contact_threshold: float = 0.002,
fc_force_scale: float = 10.0,
timestep: float = 0.004,
solref_timeconst: float = 0.005,
obj_root: str = str(MUJOCO_EVAL_ROOT / 'example_object'),
hand: HandSpec = None
)

MuJoCo grasp-evaluation settings.

Parameters
num_workersint= 48
obj_massfloat= 0.1
miu_coeftuple= (0.6, 0.02)
settingstr= 'fc'
max_penefloat= 0.01
trans_threfloat= 0.05
lift_slip_threfloat= 0.02
min_lift_distfloat= 0.0
grasp_interp_stepsint= 25
lift_interp_stepsint= 50
angle_threfloat= 15.0
contact_marginfloat= 0.01
contact_thresholdfloat= 0.002
fc_force_scalefloat= 10.0
timestepfloat= 0.004
solref_timeconstfloat= 0.005
obj_rootstr= str(MUJOCO_EVAL_ROOT / 'example_object')
handHandSpec= None
Members
attribute[source]
MjEvalConfig.num_workers: int = 48
attribute[source]
MjEvalConfig.obj_mass: float = 0.1

Object mass (kg).

attribute[source]
MjEvalConfig.miu_coef: tuple = (0.6, 0.02)

[tangential, torsional] friction.

attribute[source]
MjEvalConfig.setting: str = 'fc'

Evaluation setting; only "fc" is ported.

attribute[source]
MjEvalConfig.max_pene: float = 0.01
attribute[source]
MjEvalConfig.trans_thre: float = 0.05
attribute[source]
MjEvalConfig.lift_slip_thre: float = 0.02

Tabletop: max object-vs-palm slip during the lift (tight; trans_thre is too loose).

attribute[source]
MjEvalConfig.min_lift_dist: float = 0.0

Tabletop: minimum actual object rise; zero preserves existing evaluator behavior.

attribute[source]
MjEvalConfig.grasp_interp_steps: int = 25

Interp frames for pregrasp->grasp and grasp->squeeze.

attribute[source]
MjEvalConfig.lift_interp_steps: int = 50

Interp frames for the squeeze->lift raise.

attribute[source]
MjEvalConfig.angle_thre: float = 15.0
attribute[source]
MjEvalConfig.contact_margin: float = 0.01
attribute[source]
MjEvalConfig.contact_threshold: float = 0.002
attribute[source]
MjEvalConfig.fc_force_scale: float = 10.0

Multiplies obj_mass for the fc/tabletop external force (lower = gentler test).

attribute[source]
MjEvalConfig.timestep: float = 0.004

MuJoCo step; lower (e.g. 0.001) stabilizes an actuated arm+hand grip.

attribute[source]
MjEvalConfig.solref_timeconst: float = 0.005

Rigid-contact solref[0]; smaller = more rigid (less penetration).

attribute[source]
MjEvalConfig.obj_root: str = str(MUJOCO_EVAL_ROOT / 'example_object')
attribute[source]
MjEvalConfig.hand: HandSpec = None

None -> build_env picks the default (floating SHADOW_HAND, or fixed-base VEGA_SHARPA).