Rigid object group tutorial

Rigid object group tutorial#

This tutorial shows how to create and use a RigidObjectGroup in SimulationManager. It follows the style used in the create_scene tutorial and references the example script located in scripts/tutorials/sim/create_rigid_object_group.py.

The Code#

The tutorial corresponds to the create_rigid_object_group.py script in the scripts/tutorials/sim directory.

Code for create_rigid_object_group.py
  1# ----------------------------------------------------------------------------
  2# Copyright (c) 2021-2026 DexForce Technology Co., Ltd.
  3#
  4# Licensed under the Apache License, Version 2.0 (the "License");
  5# you may not use this file except in compliance with the License.
  6# You may obtain a copy of the License at
  7#
  8#     http://www.apache.org/licenses/LICENSE-2.0
  9#
 10# Unless required by applicable law or agreed to in writing, software
 11# distributed under the License is distributed on an "AS IS" BASIS,
 12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13# See the License for the specific language governing permissions and
 14# limitations under the License.
 15# ----------------------------------------------------------------------------
 16
 17"""
 18This script demonstrates how to create a rigid object group using SimulationManager.
 19"""
 20
 21from __future__ import annotations
 22
 23import argparse
 24import time
 25
 26from embodichain.lab.sim import SimulationManager, SimulationManagerCfg
 27from embodichain.lab.gym.utils.gym_utils import add_env_launcher_args_to_parser
 28from embodichain.lab.visualization import visualization_cfg_from_args
 29from embodichain.lab.sim.cfg import RigidBodyAttributesCfg, RenderCfg
 30from embodichain.lab.sim.shapes import CubeCfg
 31from embodichain.lab.sim.objects import (
 32    RigidObjectGroup,
 33    RigidObjectGroupCfg,
 34    RigidObjectCfg,
 35)
 36
 37
 38def main():
 39    """Main function to create and run the simulation scene."""
 40
 41    # Parse command line arguments
 42    parser = argparse.ArgumentParser(
 43        description="Create a simulation scene with SimulationManager"
 44    )
 45    add_env_launcher_args_to_parser(parser)
 46    args = parser.parse_args()
 47
 48    # Configure the simulation
 49    sim_cfg = SimulationManagerCfg(
 50        width=1920,
 51        height=1080,
 52        headless=True,
 53        physics_dt=1.0 / 100.0,  # Physics timestep (100 Hz)
 54        sim_device=args.device,
 55        render_cfg=RenderCfg(
 56            renderer=args.renderer
 57        ),  # Enable ray tracing for better visuals
 58        num_envs=args.num_envs,
 59        arena_space=3.0,
 60        visualization=visualization_cfg_from_args(args),
 61    )
 62
 63    # Create the simulation instance
 64    sim = SimulationManager(sim_cfg)
 65
 66    physics_attrs = RigidBodyAttributesCfg(
 67        mass=1.0,
 68        dynamic_friction=0.5,
 69        static_friction=0.5,
 70        restitution=0.1,
 71    )
 72
 73    # Add objects to the scene
 74    obj_group: RigidObjectGroup = sim.add_rigid_object_group(
 75        cfg=RigidObjectGroupCfg(
 76            uid="obj_group",
 77            rigid_objects={
 78                "cube_1": RigidObjectCfg(
 79                    uid="cube_1",
 80                    shape=CubeCfg(size=[0.1, 0.1, 0.1]),
 81                    attrs=physics_attrs,
 82                    init_pos=[0.0, 0.0, 1.0],
 83                ),
 84                "cube_2": RigidObjectCfg(
 85                    uid="cube_2",
 86                    shape=CubeCfg(size=[0.2, 0.2, 0.2]),
 87                    attrs=physics_attrs,
 88                    init_pos=[0.5, 0.0, 1.0],
 89                ),
 90                "cube_3": RigidObjectCfg(
 91                    uid="cube_3",
 92                    shape=CubeCfg(size=[0.3, 0.3, 0.3]),
 93                    attrs=physics_attrs,
 94                    init_pos=[-0.5, 0.0, 1.0],
 95                ),
 96            },
 97        )
 98    )
 99
100    print("[INFO]: Scene setup complete!")
101    print(f"[INFO]: Running simulation with {args.num_envs} environment(s)")
102    print("[INFO]: Press Ctrl+C to stop the simulation")
103
104    # Open window when the scene has been set up
105    if not args.headless:
106        sim.open_window()
107
108    # Run the simulation
109    run_simulation(sim)
110
111
112def run_simulation(sim: SimulationManager):
113    """Run the simulation loop.
114
115    Args:
116        sim: The SimulationManager instance to run
117    """
118
119    # Initialize GPU physics if using CUDA
120    if sim.is_use_gpu_physics:
121        sim.init_gpu_physics()
122
123    step_count = 0
124
125    try:
126        last_time = time.time()
127        last_step = 0
128        while True:
129            # Update physics simulation
130            sim.update(step=1)
131            step_count += 1
132
133            # Print FPS every second
134            if step_count % 100 == 0:
135                current_time = time.time()
136                elapsed = current_time - last_time
137                fps = (
138                    sim.num_envs * (step_count - last_step) / elapsed
139                    if elapsed > 0
140                    else 0
141                )
142                print(f"[INFO]: Simulation step: {step_count}, FPS: {fps:.2f}")
143                last_time = current_time
144                last_step = step_count
145
146    except KeyboardInterrupt:
147        print("\n[INFO]: Stopping simulation...")
148    finally:
149        # Clean up resources
150        sim.destroy()
151        print("[INFO]: Simulation terminated successfully")
152
153
154if __name__ == "__main__":
155    main()

The Code Explained#

Adding a RigidObjectGroup#

The key part of the tutorial demonstrates creating a RigidObjectGroup via sim.add_rigid_object_group. The group is configured with a mapping of object UIDs to RigidObjectCfg entries. Each entry defines a shape (here CubeCfg), physics attributes, and initial pose.

    obj_group: RigidObjectGroup = sim.add_rigid_object_group(
        cfg=RigidObjectGroupCfg(
            uid="obj_group",
            rigid_objects={
                "cube_1": RigidObjectCfg(
                    uid="cube_1",
                    shape=CubeCfg(size=[0.1, 0.1, 0.1]),
                    attrs=physics_attrs,
                    init_pos=[0.0, 0.0, 1.0],
                ),
                "cube_2": RigidObjectCfg(
                    uid="cube_2",
                    shape=CubeCfg(size=[0.2, 0.2, 0.2]),
                    attrs=physics_attrs,
                    init_pos=[0.5, 0.0, 1.0],
                ),
                "cube_3": RigidObjectCfg(
                    uid="cube_3",
                    shape=CubeCfg(size=[0.3, 0.3, 0.3]),
                    attrs=physics_attrs,
                    init_pos=[-0.5, 0.0, 1.0],
                ),
            },
        )
    )

    print("[INFO]: Scene setup complete!")

Running the tutorial#

To run the script from the repository root:

python scripts/tutorials/sim/create_rigid_object_group.py

You can pass flags such as --headless, --num_envs <n>, and --device <cpu|cuda> to customize the run.

Use --viser to publish every constituent object in the group to the browser:

python scripts/tutorials/sim/create_rigid_object_group.py --viser

Each group member has its own pose and browser node. Shared geometry remains batched by the Viser backend. See Browser visualization with Viser for server and environment-selection options.

Contents