Reference/API

Scene

class[source]
graspkit.scene.scene_description.SceneDescription(
scene_id: str = '',
target_actor_id: str = '',
boxes: Dict[str, BoxDescription] = dict(),
meshes: Dict[str, MeshDescription] = dict(),
floating_scene_id: Optional[str] = None,
canonical_tabletop_scene_id: Optional[str] = None
)

Per-scene geometry with a scene id and a manipulation-target actor id.

Parameters
scene_idstr= ''
target_actor_idstr= ''
boxesDict[str, BoxDescription]= dict()
meshesDict[str, MeshDescription]= dict()
floating_scene_idOptional[str]= None
canonical_tabletop_scene_idOptional[str]= None
Members
attribute[source]
SceneDescription.scene_id: str = ''
attribute[source]
SceneDescription.target_actor_id: str = ''
attribute[source]
SceneDescription.boxes: Dict[str, BoxDescription] = field(default_factory=dict)
attribute[source]
SceneDescription.meshes: Dict[str, MeshDescription] = field(default_factory=dict)
attribute[source]
SceneDescription.floating_scene_id: Optional[str] = None
attribute[source]
SceneDescription.canonical_tabletop_scene_id: Optional[str] = None
method[source]
SceneDescription.load_scene_descriptions_msgpack(
msgpack_path: str,
return_splits: bool = False
) -> Union[Dict[str, SceneDescription], Dict[Literal['train', 'test'], Dict[str, SceneDescription]]]
Parameters
msgpack_pathstrrequired
return_splitsbool= False
Returns
Union[Dict[str, SceneDescription], Dict[Literal['train', 'test'], Dict[str, SceneDescription]]]
method[source]
SceneDescription.save_scene_descriptions_msgpack(
scene_descriptions: Union[Dict[str, SceneDescription], Dict[Literal['train', 'test'], Dict[str, SceneDescription]]],
msgpack_path: str
) -> None
Parameters
scene_descriptionsUnion[Dict[str, SceneDescription], Dict[Literal['train', 'test'], Dict[str, SceneDescription]]]required
msgpack_pathstrrequired
Returns
None
class[source]
graspkit.scene.scene_description.MeshDescription(
actor_id: str,
collision_mesh_path: str,
scales: Tuple[float, float, float],
position: Tuple[float, float, float] = (0.0, 0.0, 0.0),
quaternion: Tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.0),
visual_mesh_path: Optional[str] = None,
bounds: Optional[Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]] = None
)

Triangle mesh with actor id, optional visual-mesh path, and cached bounds.

Parameters
actor_idstrrequired
collision_mesh_pathstrrequired
scalesTuple[float, float, float]required
positionTuple[float, float, float]= (0.0, 0.0, 0.0)
quaternionTuple[float, float, float, float]= (1.0, 0.0, 0.0, 0.0)
visual_mesh_pathOptional[str]= None
boundsOptional[Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]]= None
Members
attribute[source]
MeshDescription.actor_id: str
attribute[source]
MeshDescription.collision_mesh_path: str
attribute[source]
MeshDescription.scales: Tuple[float, float, float]
attribute[source]
MeshDescription.position: Tuple[float, float, float] = (0.0, 0.0, 0.0)
attribute[source]
MeshDescription.quaternion: Tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.0)
attribute[source]
MeshDescription.visual_mesh_path: Optional[str] = None
attribute[source]
MeshDescription.bounds: Optional[Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]] = None
method[source]
MeshDescription.get_visual_mesh_path() -> str

Return the visual mesh path, falling back to the collision mesh.

python
>>> MeshDescription("o", "c.obj", (1.0, 1.0, 1.0)).get_visual_mesh_path()
'c.obj'
>>> MeshDescription("o", "c.obj", (1.0, 1.0, 1.0), visual_mesh_path="v.obj").get_visual_mesh_path()
'v.obj'
Returns
str
method[source]
MeshDescription.get_bounds() -> Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]
Returns
Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]
class[source]
graspkit.scene.scene_description.BoxDescription(
actor_id: str,
size: Tuple[float, float, float],
position: Tuple[float, float, float] = (0.0, 0.0, 0.0),
quaternion: Tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.0)
)

Box primitive, usually for static elements like tables.

Parameters
actor_idstrrequired
sizeTuple[float, float, float]required
positionTuple[float, float, float]= (0.0, 0.0, 0.0)
quaternionTuple[float, float, float, float]= (1.0, 0.0, 0.0, 0.0)
Members
attribute[source]
BoxDescription.actor_id: str
attribute[source]
BoxDescription.size: Tuple[float, float, float]
attribute[source]
BoxDescription.position: Tuple[float, float, float] = (0.0, 0.0, 0.0)
attribute[source]
BoxDescription.quaternion: Tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.0)
class[source]
graspkit.scene.scene_geom.SceneGeom(
scene_descriptions: List[SceneDescription],
device: Device = 'cpu'
)

Per-scene mesh-backed WarpScenes for grasp / motion optimizers.

Parameters
scene_descriptionsList[SceneDescription]required
deviceDevice= 'cpu'
Members
property[source]
SceneGeom.target_scene: WarpScene

The target mesh of each scene (none for a table-only scene); built lazily on first access.

method[source]
SceneGeom.update(
scene_descriptions: List[SceneDescription]
) -> None

Update geometry in place for a scene batch with the same layout; captured pointers stay valid.

Parameters
scene_descriptionsList[SceneDescription]required
Returns
None
method[source]
SceneGeom.build_collision_scene_in_base(
T_world_robot: np.ndarray
) -> WarpScene

One `WarpScene (mesh+box) for MotionPlanner.plan()`, in robot base frame (FK is base-relative).

Parameters
T_world_robotnp.ndarrayrequired
Returns
WarpScene
method[source]
SceneGeom.query_target_object_signed_distances(
query_points: torch.Tensor
) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]

Differentiable per-scene target-object SDF (single mesh -> diff path).

Parameters
query_pointstorch.Tensorrequired
Returns
Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
method[source]
SceneGeom.query_scene_signed_distances(
query_points: torch.Tensor
) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]

Full-scene SDF (meshes+primitives), differentiable; drives penetration gradient in motion/grasp-GD.

Parameters
query_pointstorch.Tensorrequired
Returns
Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
method[source]
SceneGeom.solver_scenes(
backend: Literal['mesh', 'sdf_volume'],
sdf_bake_padding: float = 0.25,
sdf_resolution: int = 64,
sdf_voxel_size: Optional[float] = None
) -> Tuple[WarpScene, WarpScene]

(target_scene, collision_scene); sdf_volume swaps the target mesh for an SDF (params in mesh units).

Parameters
backendLiteral['mesh', 'sdf_volume']required
sdf_bake_paddingfloat= 0.25
sdf_resolutionint= 64
sdf_voxel_sizeOptional[float]= None
Returns
Tuple[WarpScene, WarpScene]