Writing an Asset Configuration

Writing an Asset Configuration#

This guide walks through the process of creating an ArticulationCfg. The ArticulationCfg is a configuration object that defines the properties of an Articulation in Isaac Lab.

Note

While we only cover the creation of an ArticulationCfg in this guide, the process is similar for creating any other asset configuration object.

We will use the Cartpole example to demonstrate how to create an ArticulationCfg. The Cartpole is a simple robot that consists of a cart with a pole attached to it. The cart is free to move along a rail, and the pole is free to rotate about the cart.

Defining the spawn configuration#

As explained in Spawning prims into the scene tutorials, the spawn configuration defines the properties of the assets to be spawned. This spawning may happen procedurally, or through an existing asset file (e.g. USD or URDF). In this example, we will spawn the Cartpole from a USD file.

When spawning an asset from a USD file, we define its UsdFileCfg. This configuration object takes in the following parameters:

usd_path: The USD file path to spawn from
rigid_props: The properties of the articulation’s root
articulation_props: The properties of all the articulation’s links

The last two parameters are optional. If not specified, they are kept at their default values in the USD file.

spawn=sim_utils.UsdFileCfg(
    usd_path=f"{ISAACLAB_NUCLEUS_DIR}/Robots/Classic/Cartpole/cartpole.usd",
    rigid_props=sim_utils.RigidBodyPropertiesCfg(
        rigid_body_enabled=True,
        max_linear_velocity=1000.0,
        max_angular_velocity=1000.0,
        max_depenetration_velocity=100.0,
        enable_gyroscopic_forces=True,
    ),
    articulation_props=sim_utils.ArticulationRootPropertiesCfg(
        enabled_self_collisions=False,
        solver_position_iteration_count=4,
        solver_velocity_iteration_count=0,
        sleep_threshold=0.005,
        stabilization_threshold=0.001,
    ),
),

To import articulation from a URDF file instead of a USD file, you can replace the UsdFileCfg with a UrdfFileCfg. For more details, please check the API documentation.

Defining the initial state#

Every asset requires defining their initial or default state in the simulation through its configuration. This configuration is stored into the asset’s default state buffers that can be accessed when the asset’s state needs to be reset.

Note

The initial state of an asset is defined w.r.t. its local environment frame. This then needs to be transformed into the global simulation frame when resetting the asset’s state. For more details, please check the Interacting with an articulation tutorial.

For an articulation, the InitialStateCfg object defines the initial state of the root of the articulation and the initial state of all its joints. In this example, we will spawn the Cartpole at the origin of the XY plane at a Z height of 2.0 meters. Meanwhile, the joint positions and velocities are set to 0.0.

init_state=ArticulationCfg.InitialStateCfg(
    pos=(0.0, 0.0, 2.0), joint_pos={"slider_to_cart": 0.0, "cart_to_pole": 0.0}
),

Defining the actuator configuration#

Actuators are a crucial component of an articulation. Through this configuration, it is possible to define the type of actuator model to use. We can use the internal actuator model provided by the physics engine (i.e. the implicit actuator model), or use a custom actuator model which is governed by a user-defined system of equations (i.e. the explicit actuator model). For more details on actuators, see Actuators.

The cartpole’s articulation has two actuators, one corresponding to its each joint: cart_to_pole and slider_to_cart. We use two different actuator models for these actuators as an example. However, since they are both using the same actuator model, it is possible to combine them into a single actuator model.