omni.isaac.lab.sim.converters#
Sub-module containing converters for converting various file types to USD.
In order to support direct loading of various file types into Omniverse, we provide a set of
converters that can convert the file into a USD file. The converters are implemented as
sub-classes of the AssetConverterBase class.
The following converters are currently supported:
UrdfConverter: Converts a URDF file into a USD file.MeshConverter: Converts a mesh file into a USD file. This supports OBJ, STL and FBX files.
Classes
Base class for converting an asset file from different formats into USD format. |
|
The base configuration class for asset converters. |
|
Converter for a mesh file in OBJ / STL / FBX format to a USD file. |
|
The configuration class for MeshConverter. |
|
Converter for a URDF description file to a USD file. |
|
The configuration class for UrdfConverter. |
Asset Converter Base#
- class omni.isaac.lab.sim.converters.AssetConverterBase[source]#
Base class for converting an asset file from different formats into USD format.
This class provides a common interface for converting an asset file into USD. It does not provide any implementation for the conversion. The derived classes must implement the
_convert_asset()method to provide the actual conversion.The file conversion is lazy if the output directory (
AssetConverterBaseCfg.usd_dir) is provided. In the lazy conversion, the USD file is re-generated only if:The asset file is modified.
The configuration parameters are modified.
The USD file does not exist.
To override this behavior to force conversion, the flag
AssetConverterBaseCfg.force_usd_conversioncan be set to True.When no output directory is defined, lazy conversion is deactivated and the generated USD file is stored in folder
/tmp/IsaacLab/usd_{date}_{time}_{random}, where the parameters in braces are generated at runtime. The random identifiers help avoid a race condition where two simultaneously triggered conversions try to use the same directory for reading/writing the generated files.Note
Changes to the parameters
AssetConverterBaseCfg.asset_path,AssetConverterBaseCfg.usd_dir, andAssetConverterBaseCfg.usd_file_nameare not considered as modifications in the configuration instance that trigger USD file re-generation.Methods:
__init__(cfg)Initializes the class.
Attributes:
The absolute path to the directory where the generated USD files are stored.
The file name of the generated USD file.
The absolute path to the generated USD file.
The relative path to the USD file with meshes.
- __init__(cfg: AssetConverterBaseCfg)[source]#
Initializes the class.
- Parameters:
cfg – The configuration instance for converting an asset file to USD format.
- Raises:
ValueError – When provided asset file does not exist.
- property usd_instanceable_meshes_path: str#
The relative path to the USD file with meshes.
The path is with respect to the USD directory
usd_dir. This is to ensure that the mesh references in the generated USD file are resolved relatively. Otherwise, it becomes difficult to move the USD asset to a different location.
- class omni.isaac.lab.sim.converters.AssetConverterBaseCfg[source]#
The base configuration class for asset converters.
Attributes:
The absolute path to the asset file to convert into USD.
The output directory path to store the generated USD file.
The name of the generated usd file.
Force the conversion of the asset file to usd.
Make the generated USD file instanceable.
- usd_dir: str | None#
The output directory path to store the generated USD file. Defaults to None.
If None, it is resolved as
/tmp/IsaacLab/usd_{date}_{time}_{random}, where the parameters in braces are runtime generated.
- usd_file_name: str | None#
The name of the generated usd file. Defaults to None.
If None, it is resolved from the asset file name. For example, if the asset file name is
"my_asset.urdf", then the generated USD file name is"my_asset.usd".If the providing file name does not end with “.usd” or “.usda”, then the extension “.usd” is appended to the file name.
- force_usd_conversion: bool#
Force the conversion of the asset file to usd. Defaults to False.
If True, then the USD file is always generated. It will overwrite the existing USD file if it exists.
- make_instanceable: bool#
Make the generated USD file instanceable. Defaults to True.
Note
Instancing helps reduce the memory footprint of the asset when multiple copies of the asset are used in the scene. For more information, please check the USD documentation on scene-graph instancing.
Mesh Converter#
- class omni.isaac.lab.sim.converters.MeshConverter[source]#
Bases:
AssetConverterBaseConverter for a mesh file in OBJ / STL / FBX format to a USD file.
This class wraps around the omni.kit.asset_converter extension to provide a lazy implementation for mesh to USD conversion. It stores the output USD file in an instanceable format since that is what is typically used in all learning related applications.
To make the asset instanceable, we must follow a certain structure dictated by how USD scene-graph instancing and physics work. The rigid body component must be added to each instance and not the referenced asset (i.e. the prototype prim itself). This is because the rigid body component defines properties that are specific to each instance and cannot be shared under the referenced asset. For more information, please check the documentation.
Due to the above, we follow the following structure:
{prim_path}- The root prim that is an Xform with the rigid body and mass APIs if configured.{prim_path}/geometry- The prim that contains the mesh and optionally the materials if configured. If instancing is enabled, this prim will be an instanceable reference to the prototype prim.
Caution
When converting STL files, Z-up convention is assumed, even though this is not the default for many CAD export programs. Asset orientation convention can either be modified directly in the CAD program’s export process or an offset can be added within the config in Isaac Lab.
Attributes:
The configuration instance for mesh to USD conversion.
The absolute path to the directory where the generated USD files are stored.
The file name of the generated USD file.
The relative path to the USD file with meshes.
The absolute path to the generated USD file.
Methods:
__init__(cfg)Initializes the class.
- cfg: MeshConverterCfg#
The configuration instance for mesh to USD conversion.
- __init__(cfg: MeshConverterCfg)[source]#
Initializes the class.
- Parameters:
cfg – The configuration instance for mesh to USD conversion.
- property usd_instanceable_meshes_path: str#
The relative path to the USD file with meshes.
The path is with respect to the USD directory
usd_dir. This is to ensure that the mesh references in the generated USD file are resolved relatively. Otherwise, it becomes difficult to move the USD asset to a different location.
- class omni.isaac.lab.sim.converters.MeshConverterCfg[source]#
Bases:
AssetConverterBaseCfgThe configuration class for MeshConverter.
Attributes:
Mass properties to apply to the USD.
Rigid body properties to apply to the USD.
Collision properties to apply to the USD.
The absolute path to the asset file to convert into USD.
The output directory path to store the generated USD file.
The name of the generated usd file.
Force the conversion of the asset file to usd.
Make the generated USD file instanceable.
Collision approximation method to use.
The translation of the mesh to the origin.
The rotation of the mesh in quaternion format (w, x, y, z).
The scale of the mesh.
- mass_props: MassPropertiesCfg | None#
Mass properties to apply to the USD. Defaults to None.
Note
If None, then no mass properties will be added.
- rigid_props: RigidBodyPropertiesCfg | None#
Rigid body properties to apply to the USD. Defaults to None.
Note
If None, then no rigid body properties will be added.
- collision_props: CollisionPropertiesCfg | None#
Collision properties to apply to the USD. Defaults to None.
Note
If None, then no collision properties will be added.
- usd_dir: str | None#
The output directory path to store the generated USD file. Defaults to None.
If None, it is resolved as
/tmp/IsaacLab/usd_{date}_{time}_{random}, where the parameters in braces are runtime generated.
- usd_file_name: str | None#
The name of the generated usd file. Defaults to None.
If None, it is resolved from the asset file name. For example, if the asset file name is
"my_asset.urdf", then the generated USD file name is"my_asset.usd".If the providing file name does not end with “.usd” or “.usda”, then the extension “.usd” is appended to the file name.
- force_usd_conversion: bool#
Force the conversion of the asset file to usd. Defaults to False.
If True, then the USD file is always generated. It will overwrite the existing USD file if it exists.
- make_instanceable: bool#
Make the generated USD file instanceable. Defaults to True.
Note
Instancing helps reduce the memory footprint of the asset when multiple copies of the asset are used in the scene. For more information, please check the USD documentation on scene-graph instancing.
- collision_approximation: str#
Collision approximation method to use. Defaults to “convexDecomposition”.
Valid options are: “convexDecomposition”, “convexHull”, “boundingCube”, “boundingSphere”, “meshSimplification”, or “none”
“none” causes no collision mesh to be added.
- translation: tuple[float, float, float]#
The translation of the mesh to the origin. Defaults to (0.0, 0.0, 0.0).
URDF Converter#
- class omni.isaac.lab.sim.converters.UrdfConverter[source]#
Bases:
AssetConverterBaseConverter for a URDF description file to a USD file.
This class wraps around the omni.isaac.urdf_importer extension to provide a lazy implementation for URDF to USD conversion. It stores the output USD file in an instanceable format since that is what is typically used in all learning related applications.
Caution
The current lazy conversion implementation does not automatically trigger USD generation if only the mesh files used by the URDF are modified. To force generation, either set
AssetConverterBaseCfg.force_usd_conversionto True or delete the output directory.Note
From Isaac Sim 2023.1 onwards, the extension name changed from
omni.isaac.urdftoomni.importer.urdf. This converter class automatically detects the version of Isaac Sim and uses the appropriate extension.The new extension supports a custom XML tag``”dont_collapse”`` for joints. Setting this parameter to true in the URDF joint tag prevents the child link from collapsing when the associated joint type is “fixed”.
Attributes:
The configuration instance for URDF to USD conversion.
The absolute path to the directory where the generated USD files are stored.
The file name of the generated USD file.
The relative path to the USD file with meshes.
The absolute path to the generated USD file.
Methods:
__init__(cfg)Initializes the class.
- cfg: UrdfConverterCfg#
The configuration instance for URDF to USD conversion.
- __init__(cfg: UrdfConverterCfg)[source]#
Initializes the class.
- Parameters:
cfg – The configuration instance for URDF to USD conversion.
- property usd_instanceable_meshes_path: str#
The relative path to the USD file with meshes.
The path is with respect to the USD directory
usd_dir. This is to ensure that the mesh references in the generated USD file are resolved relatively. Otherwise, it becomes difficult to move the USD asset to a different location.
- class omni.isaac.lab.sim.converters.UrdfConverterCfg[source]#
Bases:
AssetConverterBaseCfgThe configuration class for UrdfConverter.
Attributes:
Default density used for links.
Import the inertia tensor from urdf.
Decompose a convex mesh into smaller pieces for a closer fit.
Create a fix joint to the root/base link.
Consolidate links that are connected by fixed joints.
The absolute path to the asset file to convert into USD.
The output directory path to store the generated USD file.
The name of the generated usd file.
Force the conversion of the asset file to usd.
Make the generated USD file instanceable.
Activate self-collisions between links of the articulation.
The drive type used for joints.
Override the joint dynamics parsed from the URDF file.
The default stiffness of the joint drive.
The default damping of the joint drive.
- link_density: float#
Default density used for links. Defaults to 0.
This setting is only effective if
"inertial"properties are missing in the URDF.
- import_inertia_tensor: bool#
Import the inertia tensor from urdf. Defaults to True.
If the
"inertial"tag is missing, then it is imported as an identity.
- convex_decompose_mesh: bool#
Decompose a convex mesh into smaller pieces for a closer fit. Defaults to False.
- usd_dir: str | None#
The output directory path to store the generated USD file. Defaults to None.
If None, it is resolved as
/tmp/IsaacLab/usd_{date}_{time}_{random}, where the parameters in braces are runtime generated.
- usd_file_name: str | None#
The name of the generated usd file. Defaults to None.
If None, it is resolved from the asset file name. For example, if the asset file name is
"my_asset.urdf", then the generated USD file name is"my_asset.usd".If the providing file name does not end with “.usd” or “.usda”, then the extension “.usd” is appended to the file name.
- force_usd_conversion: bool#
Force the conversion of the asset file to usd. Defaults to False.
If True, then the USD file is always generated. It will overwrite the existing USD file if it exists.
- make_instanceable: bool#
Make the generated USD file instanceable. Defaults to True.
Note
Instancing helps reduce the memory footprint of the asset when multiple copies of the asset are used in the scene. For more information, please check the USD documentation on scene-graph instancing.
- self_collision: bool#
Activate self-collisions between links of the articulation. Defaults to False.
- default_drive_type: Literal['none', 'position', 'velocity']#
The drive type used for joints. Defaults to
"none".The drive type dictates the loaded joint PD gains and USD attributes for joint control:
"none": The joint stiffness and damping are set to 0.0."position": The joint stiff and damping are set based on the URDF file or provided configuration."velocity": The joint stiff is set to zero and damping is based on the URDF file or provided configuration.