embodichain.lab.sim.shapes

embodichain.lab.sim.shapes#

Overview#

Geometry configuration objects used to build collision, visual, and deformable simulation shapes. ShapeCfg is the common base; MeshCfg, CubeCfg, and SphereCfg describe triangle-mesh, box, and sphere primitives respectively. MeshCollisionCfg explicitly selects the collision representation and its cooking settings, while LoadOption controls mesh loading.

MeshCfg accepts either a file path or explicit vertex/triangle arrays; for surface deformables, the array-backed form preserves node order for particle flags and kinematic trajectories. Volume deformables generate a separate tetrahedral simulation mesh during voxelization.

Type aliases

MeshCollisionApproximation

Supported collision representations for a triangle mesh.

Classes

`CubeCfg`	Configuration parameters for a cube shape.
`LoadOption`	LoadOption(rebuild_normals: 'bool' = <factory>, rebuild_tangent: 'bool' = <factory>, rebuild_3rdnormal: 'bool' = <factory>, rebuild_3rdtangent: 'bool' = <factory>, smooth: 'float' = <factory>, gltfloader: 'bool' = <factory>)
`MeshCollisionCfg`	Collision-geometry construction for `MeshCfg`.
`MeshCfg`	Configuration parameters for a triangle mesh shape.
`ShapeCfg`	ShapeCfg(shape_type: 'str' = <factory>, visual_material: 'VisualMaterialCfg \| None' = <factory>)
`SphereCfg`	Configuration parameters for a sphere shape.

class embodichain.lab.sim.shapes.ShapeCfg[source]#

Bases: object

ShapeCfg(shape_type: ‘str’ = <factory>, visual_material: ‘VisualMaterialCfg | None’ = <factory>)

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

Attributes:

`shape_type`	Type of the shape.
`visual_material`	Configuration parameters for the visual material of the shape.

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: ShapeCfg

shape_type: str#: Type of the shape. Must be specified in subclasses.

visual_material: VisualMaterialCfg | None#: Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.MeshCfg[source]#

Bases: ShapeCfg

Configuration parameters for a triangle mesh shape.

Attributes:

`collision`	Optional collision representation and cooking parameters.
`compute_uv`	Whether to compute UV coordinates for the shape.
`fpath`	File path to the shape mesh file.
`load_option`	Options for loading and processing the shape.
`normals`	Optional per-vertex normals with shape `(N, 3)`.
`project_direction`	Direction to project the UV coordinates.
`shape_type`	Type of the shape.
`triangles`	Optional array-backed triangle indices with shape `(M, 3)`.
`uv_coords`	Optional per-vertex texture coordinates with shape `(N, 2)`.
`vertices`	Optional array-backed mesh vertices with shape `(N, 3)`.
`visual_material`	Configuration parameters for the visual material of the shape.

collision: MeshCollisionCfg | None#

Optional collision representation and cooking parameters.

None uses a single convex hull. Mesh collision construction belongs to the geometry because it cannot be applied meaningfully to primitive shapes or to articulation links without a named source-shape overlay.

compute_uv: bool#

Whether to compute UV coordinates for the shape. Defaults to False.

If the shape already has UV coordinates, setting this to True will recompute and overwrite them.

fpath: str | None#

File path to the shape mesh file.

Provide either this path or both vertices and triangles.

load_option: LoadOption#: Options for loading and processing the shape.

normals: Union[Sequence[Sequence[float]], ndarray, None]#: Optional per-vertex normals with shape (N, 3).

project_direction: List[float]#: Direction to project the UV coordinates. Defaults to [1.0, 1.0, 1.0].

shape_type: str#: Type of the shape. Must be specified in subclasses.

triangles: Union[Sequence[Sequence[int]], ndarray, None]#: Optional array-backed triangle indices with shape (M, 3).

uv_coords: Union[Sequence[Sequence[float]], ndarray, None]#: Optional per-vertex texture coordinates with shape (N, 2).

vertices: Union[Sequence[Sequence[float]], ndarray, None]#

Optional array-backed mesh vertices with shape (N, 3).

Array-backed meshes preserve vertex order, which is useful when per-node deformable flags or kinematic trajectories refer to stable node indices.

visual_material: VisualMaterialCfg | None#: Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.MeshCollisionCfg[source]#

Bases: object

Collision-geometry construction for MeshCfg.

The approximation is explicit. Strategy-specific fields are rejected when they do not apply, so changing a numerical cooking value cannot silently select a different collision representation.

Attributes:

`acd_method`	Approximate-convex-decomposition implementation.
`approximation`	Collision representation built from the source triangle mesh.
`is_hydroelastic`	Whether Newton uses the generated SDF for hydroelastic contact.
`max_convex_hull_num`	Deprecated compatibility view of `max_hulls`.
`max_hulls`	Maximum hull count for `convex_decomposition`; must be at least two.
`sdf_narrow_band_range`	Inner and outer signed-distance limits of the Newton SDF band [m].
`sdf_padding`	Extra padding used while Newton builds the mesh SDF [m].
`sdf_resolution`	Maximum SDF grid resolution; valid only for the `sdf` strategy.
`sdf_target_voxel_size`	Target Newton sparse-SDF voxel size [m], alternative to resolution.
`sdf_texture_format`	Newton SDF voxel storage format.

Methods:

from_dict(init_dict)

Parse a mesh-collision mapping, including deprecated field names.

acd_method: Optional[Literal['visacd', 'coacd', 'vhacd']]#

Approximate-convex-decomposition implementation.

None selects visacd when compiling mesh collision geometry. VisACD requires a DexSim build with CUDA/OptiX support.

approximation: Literal['convex_hull', 'convex_decomposition', 'triangle_mesh', 'sdf']#: Collision representation built from the source triangle mesh.

classmethod from_dict(init_dict)[source]#

Parse a mesh-collision mapping, including deprecated field names.

Return type:: MeshCollisionCfg

is_hydroelastic: bool | None#: Whether Newton uses the generated SDF for hydroelastic contact.

property max_convex_hull_num: int#: Deprecated compatibility view of max_hulls.

max_hulls: int | None#: Maximum hull count for convex_decomposition; must be at least two.

sdf_narrow_band_range: tuple[float, float] | None#: Inner and outer signed-distance limits of the Newton SDF band [m].

sdf_padding: float | None#: Extra padding used while Newton builds the mesh SDF [m].

sdf_resolution: int | None#: Maximum SDF grid resolution; valid only for the sdf strategy.

sdf_target_voxel_size: float | None#: Target Newton sparse-SDF voxel size [m], alternative to resolution.

sdf_texture_format: Optional[Literal['uint16', 'float32', 'uint8']]#: Newton SDF voxel storage format.

class embodichain.lab.sim.shapes.CubeCfg[source]#

Bases: ShapeCfg

Configuration parameters for a cube shape.

Attributes:

`shape_type`	Type of the shape.
`size`	Size of the cube (in m) as [length, width, height].
`visual_material`	Configuration parameters for the visual material of the shape.

shape_type: str#: Type of the shape. Must be specified in subclasses.

size: List[float]#: Size of the cube (in m) as [length, width, height].

visual_material: VisualMaterialCfg | None#: Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.SphereCfg[source]#

Bases: ShapeCfg

Configuration parameters for a sphere shape.

Attributes:

`radius`	Radius of the sphere (in m).
`resolution`	Resolution of the sphere mesh.
`shape_type`	Type of the shape.
`visual_material`	Configuration parameters for the visual material of the shape.

radius: float#: Radius of the sphere (in m).

resolution: int#: Resolution of the sphere mesh. Defaults to 20.

shape_type: str#: Type of the shape. Must be specified in subclasses.

visual_material: VisualMaterialCfg | None#: Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.LoadOption[source]#

Bases: object

LoadOption(rebuild_normals: ‘bool’ = <factory>, rebuild_tangent: ‘bool’ = <factory>, rebuild_3rdnormal: ‘bool’ = <factory>, rebuild_3rdtangent: ‘bool’ = <factory>, smooth: ‘float’ = <factory>, gltfloader: ‘bool’ = <factory>)

Methods:

`__init__`([rebuild_normals, rebuild_tangent, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`from_dict`(init_dict)	Initialize the configuration from a dictionary.
`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:

`gltfloader`	Whether to force DexSim's glTF loader.
`rebuild_3rdnormal`	Whether to rebuild the normal for the shape using 3rd party library.
`rebuild_3rdtangent`	Whether to rebuild the tangent for the shape using 3rd party library.
`rebuild_normals`	Whether to rebuild normals for the shape.
`rebuild_tangent`	Whether to rebuild tangents for the shape.
`smooth`	Angle threshold (in degrees) for smoothing normals.

__init__(rebuild_normals=<factory>, rebuild_tangent=<factory>, rebuild_3rdnormal=<factory>, rebuild_3rdtangent=<factory>, smooth=<factory>, gltfloader=<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.

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: LoadOption

gltfloader: bool#: Whether to force DexSim’s glTF loader. Defaults to False.

rebuild_3rdnormal: bool#: Whether to rebuild the normal for the shape using 3rd party library. Defaults to False.

rebuild_3rdtangent: bool#: Whether to rebuild the tangent for the shape using 3rd party library. Defaults to False.

rebuild_normals: bool#: Whether to rebuild normals for the shape. Defaults to False.

rebuild_tangent: bool#: Whether to rebuild tangents for the shape. Defaults to False.

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.

smooth: float#: Angle threshold (in degrees) for smoothing normals. Defaults to -1.0 (no smoothing).

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.

embodichain.lab.sim.shapes

Contents

embodichain.lab.sim.shapes#

Overview#