embodichain.toolkits

embodichain.toolkits#

The embodichain.toolkits package contains asset-preparation and manipulation utilities that can be used independently of the simulation loop.

Standalone asset-preparation and manipulation utilities usable independently of the simulation loop.

Includes parallel-gripper grasp sampling, URDF convex decomposition, and URDF assembly.

Submodules

`acd`	Approximate convex decomposition toolkit.
`graspkit`	Standalone grasp-pose generation contracts and implementations.
`urdf_assembly`	URDF builder utilities for assembling multi-component robot models (`URDFAssemblyManager`).

GraspKit — Parallel-Gripper Grasp Sampling#

The embodichain.toolkits.graspkit package owns the standalone grasp-pose service contracts. The toolkit does not import embodichain.lab, so the same generator instance can be called directly or installed in a higher-level planning runtime.

`GraspPoseGenerator`	Standalone service that generates grasp poses from target geometry.
`ParallelJawGraspPoseGenerator`	Base service shared by two-finger parallel-jaw grippers.
`ParallelJawGripperModelCfg`	Physical geometry shared by parallel-jaw grasp generators.
`get_parallel_jaw_gripper_model`	Return a fresh configuration for a named parallel-jaw gripper model.

class embodichain.toolkits.graspkit.GraspPoseGenerator[source]#

Standalone service that generates grasp poses from target geometry.

The contract has no dependency on Gym, simulation, atomic actions, or Task Program. Application code may call it directly or install the same service instance alongside a motion generator in a higher-level runtime.

Methods:

`get_best_grasp_poses`(*, mesh_vertices, ...)	Return success, best pose, and opening width for every object pose.
`get_valid_grasp_poses`(*, mesh_vertices, ...)	Return candidates, optionally restricted to one projected axis end.

abstract get_best_grasp_poses(*, mesh_vertices, mesh_triangles, obj_poses, approach_direction)[source]#

Return success, best pose, and opening width for every object pose.

Return type:: tuple[Tensor, Tensor, Tensor]

abstract get_valid_grasp_poses(*, mesh_vertices, mesh_triangles, obj_poses, approach_direction, obj_longest_axis=None, is_positive_part=True)[source]#

Return candidates, optionally restricted to one projected axis end.

Return type:: list[tuple[Tensor, Tensor]]

class embodichain.toolkits.graspkit.ParallelJawGraspPoseGenerator[source]#

Base service shared by two-finger parallel-jaw grippers.

Methods:

`__init__`(gripper_model)
`get_dual_arm_valid_grasp_poses`(*, ...[, ...])	Return coordinated candidate sets for two parallel-jaw grippers.

Attributes:

gripper_model

Return an owned snapshot of the physical gripper model.

__init__(gripper_model)[source]#

abstract get_dual_arm_valid_grasp_poses(*, mesh_vertices, mesh_triangles, obj_poses, left_to_right_arm_direction, approach_direction, middle_empty_ratio=0.4)[source]#

Return coordinated candidate sets for two parallel-jaw grippers.

Return type:: list[dict[str, dict[str, object]] | None]

property gripper_model: ParallelJawGripperModelCfg#: Return an owned snapshot of the physical gripper model.

class embodichain.toolkits.graspkit.ParallelJawGripperModelCfg[source]#

Bases: object

Physical geometry shared by parallel-jaw grasp generators.

model_id names one concrete end-effector model or calibration. Product names belong in that value (for example "dh_pgi_140_80"), not in the generator class hierarchy.

Attributes:

`finger_length`	Finger length along the grasp-frame approach axis in metres.
`finger_thickness`	Finger extent along the opening axis in metres.
`finger_width`	Finger extent perpendicular to its opening and approach axes.
`max_opening_width`	Maximum usable distance between the two fingers in metres.
`min_opening_width`	Minimum usable distance between the two fingers in metres.
`model_id`	Stable identifier for the concrete gripper geometry.
`palm_depth`	Palm/root extent along the grasp-frame approach axis in metres.

finger_length: float#: Finger length along the grasp-frame approach axis in metres.

finger_thickness: float#: Finger extent along the opening axis in metres.

finger_width: float#: Finger extent perpendicular to its opening and approach axes.

max_opening_width: float#: Maximum usable distance between the two fingers in metres.

min_opening_width: float#: Minimum usable distance between the two fingers in metres.

model_id: str#: Stable identifier for the concrete gripper geometry.

palm_depth: float#: Palm/root extent along the grasp-frame approach axis in metres.

embodichain.toolkits.graspkit.get_parallel_jaw_gripper_model(model_id)[source]#

Return a fresh configuration for a named parallel-jaw gripper model.

The built-in catalog contains grasp-planning geometry rather than URDF or downloadable asset metadata. Callers with an unregistered calibration can construct ParallelJawGripperModelCfg directly.

Parameters:: model_id (str) – Stable identifier of a built-in gripper geometry.
Return type:: ParallelJawGripperModelCfg
Returns:: An independently owned gripper-model configuration.
Raises:: ValueError – If model_id is malformed or is not built in.

`GraspPoseGenerator`	Standalone service that generates grasp poses from target geometry.
`ParallelJawGraspPoseGenerator`	Base service shared by two-finger parallel-jaw grippers.
`ParallelJawGripperModelCfg`	Physical geometry shared by parallel-jaw grasp generators.
`get_parallel_jaw_gripper_model`	Return a fresh configuration for a named parallel-jaw gripper model.

The embodichain.toolkits.graspkit.pg_grasp module provides a reusable antipodal implementation of these contracts. The pipeline consists of three stages:

Antipodal sampling — Surface points are uniformly sampled on the mesh and rays are cast to find antipodal point pairs on opposite sides.
Pose construction — For each antipodal pair, a 6-DoF grasp frame is built aligned with the approach direction.
Filtering & ranking — Grasp candidates that cause the gripper to collide with the object are discarded; survivors are scored by a weighted cost.

Public API

The application-facing entry point is AntipodalGraspPoseGenerator. Its configuration separates the physical gripper model, grasp algorithm, collision policy, and annotation/cache policy. Mesh-specific sampling and collision state remain private implementation details.

`GraspPoseGenerator`	Standalone service that generates grasp poses from target geometry.
`ParallelJawGraspPoseGenerator`	Base service shared by two-finger parallel-jaw grippers.
`ParallelJawGripperModelCfg`	Physical geometry shared by parallel-jaw grasp generators.
`AntipodalGraspPoseGenerator`	Reusable antipodal generator for any parallel-jaw gripper model.
`AntipodalGraspPoseGeneratorCfg`	Algorithm-only configuration for antipodal candidate generation.
`ParallelJawGraspCollisionCfg`	Collision-check policy independent of physical gripper dimensions.
`GraspAnnotationCfg`	Geometry annotation and cache-refresh policy.
`AntipodalSampler`	AntipodalSampler samples antipodal point pairs on a given mesh.
`AntipodalSamplerCfg`	Configuration for AntipodalSampler.
`GripperCollisionChecker`
`GripperCollisionCfg`	Configuration for the GripperCollisionChecker.
`ConvexCollisionChecker`	ConvexCollisionChecker performs efficient collision checking between a batch of query point clouds and a convex decomposition of a mesh.
`ConvexCollisionCheckerCfg`	Configuration for ConvexCollisionChecker.

AntipodalGraspPoseGenerator#

class embodichain.toolkits.graspkit.pg_grasp.AntipodalGraspPoseGenerator[source]#

Bases: ParallelJawGraspPoseGenerator

Reusable antipodal generator for any parallel-jaw gripper model.

Target meshes are supplied per call. The service lazily owns one private single-mesh backend per tensor-backed mesh, allowing callers to reuse sampled annotations without placing live generator state on a scene affordance or exposing a second generator API.

Methods:

`__init__`(gripper_model, *[, algorithm_cfg, ...])
`get_best_grasp_poses`(*, mesh_vertices, ...)	Return the lowest-cost antipodal grasp for every object pose.
`get_dual_arm_valid_grasp_poses`(*, ...[, ...])	Return antipodal candidate sets separated for a left/right pair.
`get_valid_grasp_poses`(*, mesh_vertices, ...)	Return ranked candidates, optionally from one projected axis end.
`prepare_mesh`(*, mesh_vertices, mesh_triangles)	Prepare and return antipodal pairs for one target mesh.

Attributes:

`algorithm_cfg`	Return an owned algorithm-configuration snapshot.
`annotation_cfg`	Return an owned annotation-policy snapshot.
`collision_cfg`	Return an owned collision-policy snapshot.

__init__(gripper_model, *, algorithm_cfg=None, collision_cfg=None, annotation_cfg=None)[source]#

property algorithm_cfg: AntipodalGraspPoseGeneratorCfg#: Return an owned algorithm-configuration snapshot.

property annotation_cfg: GraspAnnotationCfg#: Return an owned annotation-policy snapshot.

property collision_cfg: ParallelJawGraspCollisionCfg#: Return an owned collision-policy snapshot.

get_best_grasp_poses(*, mesh_vertices, mesh_triangles, obj_poses, approach_direction)[source]#

Return the lowest-cost antipodal grasp for every object pose.

Return type:: tuple[Tensor, Tensor, Tensor]

get_dual_arm_valid_grasp_poses(*, mesh_vertices, mesh_triangles, obj_poses, left_to_right_arm_direction, approach_direction, middle_empty_ratio=0.4)[source]#

Return antipodal candidate sets separated for a left/right pair.

Return type:: list[dict[str, dict[str, object]] | None]

get_valid_grasp_poses(*, mesh_vertices, mesh_triangles, obj_poses, approach_direction, obj_longest_axis=None, is_positive_part=True)[source]#

Return ranked candidates, optionally from one projected axis end.

Return type:: list[tuple[Tensor, Tensor]]

prepare_mesh(*, mesh_vertices, mesh_triangles)[source]#

Prepare and return antipodal pairs for one target mesh.

The configured annotation mode determines whether the whole mesh is sampled automatically or a region is selected through Viser. Prepared pairs are cached by the private mesh backend and returned as an owned tensor snapshot.

Parameters:

mesh_vertices (Tensor) – Target-local vertex positions with shape (N, 3).
mesh_triangles (Tensor) – Triangle indices with shape (M, 3).

Return type:

Tensor

Returns:

Antipodal contact pairs with shape (K, 2, 3).

AntipodalGraspPoseGeneratorCfg#

class embodichain.toolkits.graspkit.pg_grasp.AntipodalGraspPoseGeneratorCfg[source]#

Bases: object

Algorithm-only configuration for antipodal candidate generation.

Attributes:

`approach_deviation_angle`	Maximum candidate deviation from the requested approach direction.
`approach_direction_samples`	Number of approach-direction variants evaluated per antipodal pair.
`max_candidates`	Maximum number of ranked candidates returned per object pose.
`ray_deviation_angle`	Maximum random ray deviation from a sampled surface normal.
`sample_count`	Number of surface rays sampled while finding antipodal pairs.

approach_deviation_angle: float#: Maximum candidate deviation from the requested approach direction.

approach_direction_samples: int#: Number of approach-direction variants evaluated per antipodal pair.

max_candidates: int#: Maximum number of ranked candidates returned per object pose.

ray_deviation_angle: float#: Maximum random ray deviation from a sampled surface normal.

sample_count: int#: Number of surface rays sampled while finding antipodal pairs.

ParallelJawGraspCollisionCfg#

class embodichain.toolkits.graspkit.pg_grasp.ParallelJawGraspCollisionCfg[source]#

Bases: object

Collision-check policy independent of physical gripper dimensions.

Attributes:

`filter_ground_collision`	Whether candidates intersecting the inferred support plane are removed.
`max_decomposition_hulls`	Maximum convex hull count used for target-mesh decomposition.
`opening_margin`	Additional opening used while checking finger collisions in metres.
`point_sample_density`	Sampling density passed to the parallel-jaw collision model.

filter_ground_collision: bool#: Whether candidates intersecting the inferred support plane are removed.

max_decomposition_hulls: int#: Maximum convex hull count used for target-mesh decomposition.

opening_margin: float#: Additional opening used while checking finger collisions in metres.

point_sample_density: float#: Sampling density passed to the parallel-jaw collision model.

GraspAnnotationCfg#

class embodichain.toolkits.graspkit.pg_grasp.GraspAnnotationCfg[source]#

Bases: object

Geometry annotation and cache-refresh policy.

Attributes:

`force_refresh`	Whether the service recomputes annotations when first seeing a mesh.
`selection_mode`	Use the full mesh or select a region through the Viser frontend.
`use_largest_connected_component`	Whether an interactive selection keeps only its largest component.
`viser_port`	Port used only by interactive region selection.

force_refresh: bool#: Whether the service recomputes annotations when first seeing a mesh.

selection_mode: Literal['whole_mesh', 'interactive']#: Use the full mesh or select a region through the Viser frontend.

use_largest_connected_component: bool#: Whether an interactive selection keeps only its largest component.

viser_port: int#: Port used only by interactive region selection.

AntipodalSampler#

class embodichain.toolkits.graspkit.pg_grasp.AntipodalSampler[source]#

Bases: object

AntipodalSampler samples antipodal point pairs on a given mesh. It uses Open3D’s raycasting functionality to find points on the mesh that are visible along the negative normal direction from uniformly sampled points on the mesh surface. The sampler can also apply a random disturbance to the ray direction to increase the diversity of sampled antipodal points. The resulting antipodal point pairs can be used for grasp generation and annotation tasks.

Methods:

`__init__`([cfg])
`__new__`(**kwargs)
`sample`(vertices, faces)	Get sample Antipodal point pair

__init__(cfg=AntipodalSamplerCfg(n_sample=20000, max_angle=0.2617993877991494, max_length=0.1, min_length=0.001))[source]#

__new__(**kwargs)#

sample(vertices, faces)[source]#

Get sample Antipodal point pair

Parameters:

vertices (Tensor) – [V, 3] vertex positions of the mesh
faces (Tensor) – [F, 3] triangle indices of the mesh

Returns:

[N, 2, 3] tensor of N antipodal point pairs. Each pair consists of a hit point and its corresponding surface point.

Return type:

hit_point_pairs

AntipodalSamplerCfg#

class embodichain.toolkits.graspkit.pg_grasp.AntipodalSamplerCfg[source]#

Bases: object

Configuration for AntipodalSampler.

Methods:

`__init__`([n_sample, max_angle, max_length, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

Attributes:

`max_angle`	maximum angle (in radians) to randomly disturb the ray direction for antipodal point sampling, used to increase the diversity of sampled antipodal points.
`max_length`	maximum gripper open width, used to filter out antipodal points that are too far apart to be grasped
`min_length`	minimum gripper open width, used to filter out antipodal points that are too close to be grasped
`n_sample`	surface point sample number

__init__(n_sample=<factory>, max_angle=<factory>, max_length=<factory>, min_length=<factory>)#

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

max_angle: float#: maximum angle (in radians) to randomly disturb the ray direction for antipodal point sampling, used to increase the diversity of sampled antipodal points. Note that setting max_angle to 0 will disable the random disturbance and sample antipodal points strictly along the surface normals, which may result in less diverse antipodal points and may not be ideal for all objects or grasping scenarios.

max_length: float#: maximum gripper open width, used to filter out antipodal points that are too far apart to be grasped

min_length: float#: minimum gripper open width, used to filter out antipodal points that are too close to be grasped

n_sample: int#: surface point sample number

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

GripperCollisionChecker#

class embodichain.toolkits.graspkit.pg_grasp.GripperCollisionChecker[source]#

Bases: object

Methods:

`__init__`(object_mesh_verts, object_mesh_faces)
`__new__`(**kwargs)
`query`(obj_pose, grasp_poses, open_lengths[, ...])	query the collision status of the gripper with the object.

__init__(object_mesh_verts, object_mesh_faces, cfg=GripperCollisionCfg(max_open_length=0.1, finger_length=0.08, y_thickness=0.03, x_thickness=0.01, root_z_width=0.08, point_sample_dense=0.01, max_decomposition_hulls=16, open_check_margin=0.01))[source]#

__new__(**kwargs)#

query(obj_pose, grasp_poses, open_lengths, collision_threshold=0.0, is_filter_ground_collision=True, is_visual=False)[source]#

query the collision status of the gripper with the object. The gripper is represented as a point cloud generated from the grasp poses and open lengths, and the collision status is determined by checking the distance between the gripper points and the object mesh.

Parameters:

obj_pose (torch.Tensor) – [4, 4] of float. The homogeneous transformation matrix of the object pose in the world frame.
grasp_poses (torch.Tensor) – [B, 4, 4] of float. The homogeneous transformation matrices of the gripper root frame for B grasp poses.
open_lengths (torch.Tensor) – [B, ] of float. The opening lengths of the gripper fingers for B grasp poses.
collision_threshold (float, optional) – Collision distance threshold. Defaults to 0.0.
is_visual (bool, optional) – whether to visualize collision result. Defaults to False.

Returns:

[B, ] boolean tensor indicating whether a grasp pose is collided.

Return type:

torch.Tensor

GripperCollisionCfg#

class embodichain.toolkits.graspkit.pg_grasp.GripperCollisionCfg[source]#

Bases: object

Configuration for the GripperCollisionChecker. This class defines various parameters related to the gripper geometry, point cloud generation, and collision checking process. Users can customize these parameters based on the specific gripper being modeled and the requirements of the application.

Methods:

`__init__`([max_open_length, finger_length, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

Attributes:

`finger_length`	Length of the gripper fingers from the root to the tip, in z axis.
`max_decomposition_hulls`	Maximum number of convex hulls to decompose the object mesh into for collision checking.
`max_open_length`	Maximum opening length of the gripper fingers.
`open_check_margin`	Additional margin added to the gripper open length when checking for collisions.
`point_sample_dense`	Approximate number of points per unit length for the gripper point cloud.
`root_z_width`	Width of the gripper root along the Z-axis (the axis along the finger length direction).
`x_thickness`	Thickness of the gripper along the X-axis (the axis parallel to the finger opening direction).
`y_thickness`	Thickness of the gripper along the Y-axis (the axis perpendicular to the finger opening direction).

__init__(max_open_length=<factory>, finger_length=<factory>, y_thickness=<factory>, x_thickness=<factory>, root_z_width=<factory>, point_sample_dense=<factory>, max_decomposition_hulls=<factory>, open_check_margin=<factory>)#

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

finger_length: float#: Length of the gripper fingers from the root to the tip, in z axis. This should be set according to the specific gripper being modeled, and it defines how far the fingers extend from the gripper root frame.

max_decomposition_hulls: int#: Maximum number of convex hulls to decompose the object mesh into for collision checking. This should be set based on the complexity of the object geometry and the desired accuracy of collision checking. More hulls can provide a tighter approximation of the object shape but will increase computational cost.

max_open_length: float#: Maximum opening length of the gripper fingers. This should be set according to the specific gripper being modeled, and it defines the maximum distance between the two fingers when fully open.

open_check_margin: float#: Additional margin added to the gripper open length when checking for collisions. This can help account for uncertainties in the gripper pose or object geometry, and can be set based on the specific requirements of the application.

point_sample_dense: float#: Approximate number of points per unit length for the gripper point cloud. Higher values will yield denser point clouds, which can improve collision checking accuracy but also increase computational cost. This should be set based on the desired balance between accuracy and efficiency for the specific application.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

root_z_width: float#: Width of the gripper root along the Z-axis (the axis along the finger length direction). This should be set according to the specific gripper being modeled, and it defines how far the root extends along the Z direction.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

x_thickness: float#: Thickness of the gripper along the X-axis (the axis parallel to the finger opening direction). This should be set according to the specific gripper being modeled, and it defines the thickness of the fingers and the root in the X direction.

y_thickness: float#: Thickness of the gripper along the Y-axis (the axis perpendicular to the finger opening direction). This should be set according to the specific gripper being modeled, and it defines the width of the gripper’s main body and fingers in the Y direction.

ConvexCollisionChecker#

class embodichain.toolkits.graspkit.pg_grasp.ConvexCollisionChecker[source]#

Bases: object

ConvexCollisionChecker performs efficient collision checking between a batch of query point clouds and a convex decomposition of a mesh. The convex decomposition is represented by plane equations of the convex hulls, which are precomputed and cached for efficiency. The collision checking is done by computing the signed distance from each query point to the convex hulls using the plane equations, and determining if any points are colliding based on a specified collision threshold. This class can be used

Methods:

`__init__`(base_mesh_verts, base_mesh_faces[, ...])	Initialize the ConvexCollisionChecker by performing convex decomposition on the input mesh and extracting plane equations for the convex hulls.
`__new__`(**kwargs)
`query_batch_points`(batch_points[, ...])	Query collision status for a batch of point clouds.

__init__(base_mesh_verts, base_mesh_faces, max_decomposition_hulls=32)[source]#

Initialize the ConvexCollisionChecker by performing convex decomposition on the input mesh and extracting plane equations for the convex hulls. The plane equations are cached to disk to avoid redundant computation in future runs.

Parameters:

base_mesh_verts (Tensor) – [N, 3] vertex positions of the input mesh.
base_mesh_faces (Tensor) – [M, 3] triangle indices of the input mesh.
max_decomposition_hulls (int) – maximum number of convex hulls to decompose into. A higher number allows for a more accurate approximation of the original mesh but increases computation time and memory usage. The optimal number may depend on the complexity of the mesh and the required precision of collision checking.

__new__(**kwargs)#

query_batch_points(batch_points, collision_threshold=0.0, is_visual=False)[source]#

Query collision status for a batch of point clouds.

A point collides when its signed distance to any convex hull is less than or equal to collision_threshold.

Parameters:

batch_points (Tensor) – Point clouds with shape (B, n_point, 3).
collision_threshold (float) – Collision threshold in meters. Positive values also classify points near the surface as colliding; negative values allow slight penetration.
is_visual (bool) – Whether to visualize collision results for debugging.

Return type:

tuple[Tensor, Tensor]

Returns:

A tuple containing the (B, n_point) collision mask and signed distances. Negative distances are inside the object; positive distances are outside it.

ConvexCollisionCheckerCfg#

class embodichain.toolkits.graspkit.pg_grasp.ConvexCollisionCheckerCfg[source]#

Bases: object

Configuration for ConvexCollisionChecker.

Methods:

`__init__`([collision_threshold, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

Attributes:

`collision_threshold`	Collision threshold in meters.
`debug`	Whether to visualize the collision checking results for debugging purposes.
`n_query_mesh_samples`	Number of points to sample from the query mesh surface for collision checking.

__init__(collision_threshold=<factory>, n_query_mesh_samples=<factory>, debug=<factory>)#

collision_threshold: float#: Collision threshold in meters. A point is considered colliding if its signed distance to the hull interior is <= this threshold. This allows for a margin of error in collision checking, where a small positive threshold can be used to consider points near the surface as colliding, and a small negative threshold can be used to allow for slight penetration without considering it a collision.

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

debug: bool#: Whether to visualize the collision checking results for debugging purposes. If set to True, the code will generate visualizations of the query points colored by their collision status (e.g., red for colliding points and green for non-colliding points) along with the original mesh. This can help in understanding and verifying the collision checking process, especially during development and testing.

n_query_mesh_samples: int#: Number of points to sample from the query mesh surface for collision checking. A higher number of samples can provide a more accurate collision check at the cost of increased computation time. The optimal number may depend on the complexity of the mesh and the required precision of collision detection.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

Implementation Module#

`AntipodalGraspPoseGenerator`	Reusable antipodal generator for any parallel-jaw gripper model.
`AntipodalGraspPoseGeneratorCfg`	Algorithm-only configuration for antipodal candidate generation.
`ParallelJawGraspCollisionCfg`	Collision-check policy independent of physical gripper dimensions.
`GraspAnnotationCfg`	Geometry annotation and cache-refresh policy.

URDF Convex Decomposition#

The embodichain.toolkits.acd.urdf_modifider module converts concave URDF collision meshes into CoACD-generated convex hulls. The high-level function can also scale the model and recompute inertial properties.

embodichain.toolkits.acd.urdf_modifider.generate_urdf_collision_convexes(urdf_path, output_urdf_name, max_convex_hull_num=16, recompute_inertia=False, scale=None)[source]#

URDF Assembly#

URDF builder utilities for assembling multi-component robot models (URDFAssemblyManager).

Classes:

URDFAssemblyManager

A class to manage the assembly of URDF files and their components.

class embodichain.toolkits.urdf_assembly.URDFAssemblyManager[source]#

Bases: object

A class to manage the assembly of URDF files and their components.

Attributes:

`SUPPORTED_COMPONENTS`
`SUPPORTED_MESH_TYPES`
`SUPPORTED_SENSORS`
`SUPPORTED_WHEEL_TYPES`
`component_order_and_prefix`	Get the internal component order with their name prefixes.
`component_prefix`	Configure name prefixes per component type.
`name_case`	Get the current name case policy for joints and links.

Methods:

`__init__`([component_registry, ...])
`add_component`(component_type, urdf_path[, ...])	Add a URDF component to the component registry.
`attach_sensor`(sensor_name, sensor_source, ...)	Attach a sensor to a specific component and link, and register it in the sensor registry.
`get_attached_sensors`()	Get all attached sensors from the sensor registry.
`get_component`(component_type)	Retrieve a component from the registry by its type/name.
`merge_urdfs`([output_path, use_signature_check])	Merge URDF files according to single base link, connection point naming, and type compatibility matrix rules.

SUPPORTED_COMPONENTS = ['chassis', 'legs', 'torso', 'head', 'left_arm', 'right_arm', 'left_hand', 'right_hand', 'arm', 'hand']#

SUPPORTED_MESH_TYPES = ['stl', 'obj', 'ply', 'dae', 'glb']#

SUPPORTED_SENSORS = ['camera', 'lidar', 'imu', 'gps', 'force']#

SUPPORTED_WHEEL_TYPES = ['omni', 'differential', 'tracked']#

__init__(component_registry=None, sensor_registry=None, mesh_manager=None, component_manager=None, sensor_manager=None)[source]#

add_component(component_type, urdf_path, transform=None, **params)[source]#

Add a URDF component to the component registry.

This method creates a URDFComponent object and registers it in the component registry.

Parameters:

component_type (str) – The type/name of the component (e.g., ‘chassis’, ‘head’).
urdf_path (str or Path) – Path to the URDF file for this component.
transform (np.ndarray, optional) – 4x4 transformation matrix for positioning the component.
**params – Additional component-specific parameters (e.g., wheel_type for chassis).

Returns:

True if component added successfully, False otherwise.

Return type:

bool

attach_sensor(sensor_name, sensor_source, parent_component, parent_link, transform=None, **kwargs)[source]#

Attach a sensor to a specific component and link, and register it in the sensor registry.

This method creates a SensorAttachment object and registers it in the sensor registry.

Parameters:

sensor_name (str) – Unique name for the sensor (e.g., ‘camera’).
sensor_source (str or ET.Element) – Path to the sensor’s URDF file or an XML element.
parent_component (str) – Name of the component to which the sensor is attached.
parent_link (str) – Name of the link within the parent component for attachment.
**kwargs – Additional keyword arguments (e.g., transform, sensor_type).

Returns:

True if sensor attached successfully, False otherwise.

Return type:

bool

property component_order_and_prefix#

Get the internal component order with their name prefixes.

Note

This exposes the internal list of (component_name, prefix) pairs used when assembling URDFs. In most user code it is recommended to use component_prefix instead, which focuses on configuring prefixes rather than ordering.

Returns:: A list of tuples specifying component names and their prefixes.
Return type:: list[tuple[str, str | None]]

property component_prefix#

Configure name prefixes per component type.

This is a user-facing alias over component_order_and_prefix.

Semantics:: This setter is patch-only: it updates prefixes for components that already exist in the current internal order and does not allow introducing new component names.

Returns:: The internal list of (component_name, prefix) pairs.
Return type:: list[tuple[str, str | None]]

get_attached_sensors()[source]#

Get all attached sensors from the sensor registry.

Returns:: A dictionary mapping sensor names to SensorAttachment objects.
Return type:: dict

get_component(component_type)[source]#

Retrieve a component from the registry by its type/name.

Parameters:: component_type (str) – The type/name of the component to retrieve.
Returns:: The registered component object, or None if not found.
Return type:: URDFComponent or None

merge_urdfs(output_path='./assembly_robot.urdf', use_signature_check=True)[source]#

Merge URDF files according to single base link, connection point naming, and type compatibility matrix rules.

Parameters:

output_path (str) – Path where the merged URDF file will be saved.
use_signature_check (bool) – Whether to check signatures to avoid redundant processing.

Returns:

The root element of the merged URDF.

Return type:

ET.Element

property name_case#

Get the current name case policy for joints and links.

Returns:: A dictionary mapping ‘joint’ and ‘link’ to their respective case modes.
Return type:: dict[str, str]

embodichain.toolkits

Contents

embodichain.toolkits#

GraspKit — Parallel-Gripper Grasp Sampling#

AntipodalGraspPoseGenerator#

AntipodalGraspPoseGeneratorCfg#

ParallelJawGraspCollisionCfg#

GraspAnnotationCfg#

AntipodalSampler#

AntipodalSamplerCfg#

GripperCollisionChecker#

GripperCollisionCfg#

ConvexCollisionChecker#

ConvexCollisionCheckerCfg#

Implementation Module#

URDF Convex Decomposition#

URDF Assembly#