[Tutorial #2] Spawning prims into the scene

본 글은 Isaac Lab 공식 document를 수행한 내용을 적은 글입니다.
공식 document의 내용으로 이해가 가지 않는 부분들은 ChatGPT를 이용하여 보완하였습니다.
(글의 인용 표시가 되어있는 부분은 ChatGPT를 활용한 내용입니다.)

자세한 사항은 Isaac Lab 공식 document를 참고하세요.
https://isaac-sim.github.io/IsaacLab/main/index.html

Overview — Isaac Lab Documentation

 

이 튜토리얼은 Python에서 Isaac Lab의 scene에 다양한 object(또는 prim)을 spawn하는 방법을 살펴본다.

 

import argparse

from omni.isaac.lab.app import AppLauncher

# create argparser
parser = argparse.ArgumentParser(description="Tutorial on spawning prims into the scene.")
# append AppLauncher cli args
AppLauncher.add_app_launcher_args(parser)
# parse the arguments
args_cli = parser.parse_args()
# launch omniverse app
app_launcher = AppLauncher(args_cli)
simulation_app = app_launcher.app

"""Rest everything follows."""

import omni.isaac.core.utils.prims as prim_utils

import omni.isaac.lab.sim as sim_utils
from omni.isaac.lab.utils.assets import ISAAC_NUCLEUS_DIR


def design_scene():
    """Designs the scene by spawning ground plane, light, objects and meshes from usd files."""
    # Ground-plane
    cfg_ground = sim_utils.GroundPlaneCfg()
    cfg_ground.func("/World/defaultGroundPlane", cfg_ground)

    # spawn distant light
    cfg_light_distant = sim_utils.DistantLightCfg(
        intensity=3000.0,
        color=(0.75, 0.75, 0.75),
    )
    cfg_light_distant.func("/World/lightDistant", cfg_light_distant, translation=(1, 0, 10))

    # create a new xform prim for all objects to be spawned under
    prim_utils.create_prim("/World/Objects", "Xform")
    # spawn a red cone
    cfg_cone = sim_utils.ConeCfg(
        radius=0.15,
        height=0.5,
        visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(1.0, 0.0, 0.0)),
    )
    cfg_cone.func("/World/Objects/Cone1", cfg_cone, translation=(-1.0, 1.0, 1.0))
    cfg_cone.func("/World/Objects/Cone2", cfg_cone, translation=(-1.0, -1.0, 1.0))

    # spawn a green cone with colliders and rigid body
    cfg_cone_rigid = sim_utils.ConeCfg(
        radius=0.15,
        height=0.5,
        rigid_props=sim_utils.RigidBodyPropertiesCfg(),
        mass_props=sim_utils.MassPropertiesCfg(mass=1.0),
        collision_props=sim_utils.CollisionPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.0, 1.0, 0.0)),
    )
    cfg_cone_rigid.func(
        "/World/Objects/ConeRigid", cfg_cone_rigid, translation=(-0.2, 0.0, 2.0), orientation=(0.5, 0.0, 0.5, 0.0)
    )

    # spawn a blue cuboid with deformable body
    cfg_cuboid_deformable = sim_utils.MeshCuboidCfg(
        size=(0.2, 0.5, 0.2),
        deformable_props=sim_utils.DeformableBodyPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.0, 0.0, 1.0)),
        physics_material=sim_utils.DeformableBodyMaterialCfg(),
    )
    cfg_cuboid_deformable.func("/World/Objects/CuboidDeformable", cfg_cuboid_deformable, translation=(0.15, 0.0, 2.0))

    # spawn a usd file of a table into the scene
    cfg = sim_utils.UsdFileCfg(usd_path=f"{ISAAC_NUCLEUS_DIR}/Props/Mounts/SeattleLabTable/table_instanceable.usd")
    cfg.func("/World/Objects/Table", cfg, translation=(0.0, 0.0, 1.05))


def main():
    """Main function."""

    # Initialize the simulation context
    sim_cfg = sim_utils.SimulationCfg(dt=0.01, device=args_cli.device)
    sim = sim_utils.SimulationContext(sim_cfg)
    # Set main camera
    sim.set_camera_view([2.0, 0.0, 2.5], [-0.5, 0.0, 0.5])

    # Design scene by adding assets to it
    design_scene()

    # Play the simulator
    sim.reset()
    # Now we are ready!
    print("[INFO]: Setup complete...")

    # Simulate physics
    while simulation_app.is_running():
        # perform step
        sim.step()


if __name__ == "__main__":
    # run the main function
    main()
    # close sim app
    simulation_app.close()

 

Omniverse의 Scene 디자인은 USD라는 파일 포맷을 기준으로 한다.

USD의 필수 개념은 아래와 같다.

 

1) Primitive(Prims)

• USD Scene의 기본 구성 요소다.
• Scene을 그래프로 생각했을 때, 각 그래프의 노드라고 볼 수 있다.
• Mesh, 조명, 카메라, transform이 될 수 있다.

2) Attribute

• Primitive의 속성이다.
• 키-값 쌍으로 생각할 수 있는데, 예를 들어 색상이라는 키 값에 빨강이라는 값이 들어갈 수 있고, 이 속성이 하나의 prim에 적용되면 해당 prim은 빨간 색상이라는 속성을 가지게 되는 것이다.

3) Relationship

• Primitive간의 연결이다.
• 다른 prim에 대한 포인터로 생각할 수 있는데, 에를 들어 Mesh prim은 셰이딩을 위해 material prim과의 관계를 가질 수 있는 것이다.

USD stage는 위와같은 prim의 속성과 관계를 포함한 컬렉션으로, Scene에 있는 모든 prim을 담고 있는 컨테이너라고 할 수 있다. 즉, Scene을 디자인 한다는 것은 USD stage를 디자인 하는 것이다.

 

간단히 설명하면 다음과 같이 사용할 수 있다.

# Create a configuration class instance
cfg = MyPrimCfg()
prim_path = "/path/to/prim"

# Spawn the prim into the scene using the corresponding spawner function
spawn_my_prim(prim_path, cfg, translation=[0, 0, 0], orientation=[1, 0, 0, 0], scale=[1, 1, 1])
# OR
# Use the spawner function directly from the configuration class
cfg.func(prim_path, cfg, translation=[0, 0, 0], orientation=[1, 0, 0, 0], scale=[1, 1, 1])

 

Spawning a ground plane

    # Ground-plane
    cfg_ground = sim_utils.GroundPlaneCfg()
    cfg_ground.func("/World/defaultGroundPlane", cfg_ground)

sim_utils.GroundPlaneCfg()는 지면을 정의하는 설정 객체를 생성한다.
GroundPlaneCfg는 지면 평면(ground plane)을 설정하기 위해 필요한 파라미터를 포함하고 있다. 예를 들어, 지면의 위치, 크기, 물리적 속성(마찰력 등)을 지정할 수 있다.

cfg_ground.func() 메서드를 호출하여 실제로 시뮬레이션 환경에 지면 평면을 생성하고 적용한다.
첫 번째 인자 "/World/defaultGroundPlane"은 지면 평면이 생성될 위치를 지정하는 경로다. 경로를 통해 지면이 /World/defaultGroundPlane 위치에 배치된다.
두 번째 인자 cfg_ground는 앞서 생성한 GroundPlaneCfg 객체로, 이 객체에 정의된 설정이 지면에 적용된다. 예를 들어, 지면의 위치, 크기, 마찰 등 여러 속성을 설정할 수 있다. (GPT4)

 

Spawning lights

다양한 Light prim을 stage에 spawn할 수 있다. 

Light prim에는 원거리 조명, 구체 조명, 디스크 조명, 원통형 조명 등이 포함된다.

    # spawn distant light
    cfg_light_distant = sim_utils.DistantLightCfg(
        intensity=3000.0,
        color=(0.75, 0.75, 0.75),
    )
    cfg_light_distant.func("/World/lightDistant", cfg_light_distant, translation=(1, 0, 10))

sim_utils.DistantLightCfg()는 원거리 광원(Distant Light)의 설정을 정의하는 객체를 생성한다.
이 객체는 광원의 강도, 색상, 방향 등의 다양한 속성을 포함한다.
intensity=3000.0는 광원의 강도를 나타내며, 값이 클수록 더 밝은 조명이 된다. 여기서는 3000.0이라는 값을 설정하여 비교적 강한 조명을 생성한다.
color=(0.75, 0.75, 0.75)는 RGB 형식으로 광원의 색을 정의한다. (0.75, 0.75, 0.75)는 중간 정도의 밝기를 가진 회색 톤의 빛을 의미한다.


func() 메서드를 사용하여 설정한 광원을 시뮬레이션 환경에 생성하고 배치한다.
첫 번째 인자 "/World/lightDistant"는 광원이 배치될 경로를 지정한다. 여기서는 /World/lightDistant 경로에 광원이 배치된다.
두 번째 인자 cfg_light_distant는 앞에서 설정한 DistantLightCfg 객체를 전달한다. 이 객체의 설정 값들이 광원에 적용된다.
세 번째 인자 translation=(1, 0, 10)은 광원의 위치를 설정하는 추가 매개변수로, (1, 0, 10)의 좌표에 원거리 광원을 배치한다. 이 좌표는 광원의 위치를 정의하며, 일반적으로 광원의 위치는 해당 환경에 적합한 빛을 비추기 위해 설정된다.
(GPT4)

 

Spawning primitive shapes

    # create a new xform prim for all objects to be spawned under
    prim_utils.create_prim("/World/Objects", "Xform")

prim_utils.create_prim()을 사용해 "/World/Objects" 경로에 Xform 이라는 새 prim을 생성한다.
여기서 "Xform"은 여러 객체들을 논리적으로 그룹화하기 위한 위치를 정의하는 기본 Transform 역할을 한다.
이렇게 하면 이후에 생성하는 객체들을 /World/Objects 아래에 배치할 수 있어, 환경 구성이나 정리 측면에서 유리하다.
(GPT4)

 

    # spawn a red cone
    cfg_cone = sim_utils.ConeCfg(
        radius=0.15,
        height=0.5,
        visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(1.0, 0.0, 0.0)),
    )

sim_utils.ConeCfg()는 원뿔 모양의 객체를 정의하는 설정 객체로, 생성될 원뿔의 크기와 색상을 설정할 수 있다.
radius=0.15를 통해 원뿔의 밑면 반지름을 설정한다.
height=0.5를 통해 원뿔의 높이를 설정한다.
visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(1.0, 0.0, 0.0))을 통해 원뿔의 시각적 재질(외관)을 설정하며, diffuse_color=(1.0, 0.0, 0.0)는 빨간색을 의미한다.(GPT4)

    cfg_cone.func("/World/Objects/Cone1", cfg_cone, translation=(-1.0, 1.0, 1.0))

cfg_cone.func()을 호출해 첫 번째 원뿔을 생성하고 /World/Objects/Cone1 경로에 배치한다.
첫 번째 인자 "/World/Objects/Cone1"는 첫 번째 원뿔이 생성될 경로를 지정한다.
두 번째 인자 cfg_cone은 원뿔의 구성 설정을 담고 있는 cfg_cone 객체를 전달하여, 설정에 정의된 대로 원뿔의 크기와 색상을 적용한다.
세 번째 인자 translation=(-1.0, 1.0, 1.0)은 원뿔의 위치를 (x, y, z) 좌표 (-1.0, 1.0, 1.0)로 설정하여 시뮬레이션 공간에 배치한다.(GPT4)

    cfg_cone.func("/World/Objects/Cone2", cfg_cone, translation=(-1.0, -1.0, 1.0))

두 번째 원뿔을 생성하며, /World/Objects/Cone2 경로에 배치한다.
translation=(-1.0, -1.0, 1.0)로 위치를 다르게 설정하여 첫 번째 원뿔과 약간 다른 위치에 배치한다.  (GPT4)

    # spawn a green cone with colliders and rigid body
    cfg_cone_rigid = sim_utils.ConeCfg(
        radius=0.15,
        height=0.5,
        rigid_props=sim_utils.RigidBodyPropertiesCfg(),
        mass_props=sim_utils.MassPropertiesCfg(mass=1.0),
        collision_props=sim_utils.CollisionPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.0, 1.0, 0.0)),
    )

sim_utils.ConeCfg()를 사용해 강체 속성과 충돌체를 가진 원뿔 객체를 정의한다.
이 객체는 여러 가지 속성을 가지며, 물리 엔진의 영향을 받게된다.
radius=0.15는 원뿔의 밑면 반지름을 설정한다.
height=0.5는 원뿔의 높이를 설정한다.
rigid_props=sim_utils.RigidBodyPropertiesCfg()를 사용하여 원뿔을 강체(Rigid Body)로 설정한다. 강체 속성은 물리 시뮬레이션에서 객체가 외부 힘의 영향을 받아 움직이도록 한다.
mass_props=sim_utils.MassPropertiesCfg(mass=1.0)는 질량을 설정한다. 여기서 mass=1.0은 원뿔의 질량을 1.0으로 설정하여 물리적 반응을 결정한다.
collision_props=sim_utils.CollisionPropertiesCfg()는 충돌 속성을 정의한다. 이 속성은 원뿔이 다른 객체와 충돌할 때 상호작용하도록 한다.
visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.0, 1.0, 0.0))은 원뿔의 색상을 설정하며, (0.0, 1.0, 0.0)은 녹색을 나타낸다. 이 설정은 RGB 값으로서, 원뿔을 녹색으로 시각화한다.  (GPT4)

    cfg_cone_rigid.func(
        "/World/Objects/ConeRigid", cfg_cone_rigid, translation=(-0.2, 0.0, 2.0), orientation=(0.5, 0.0, 0.5, 0.0)
    )

func() 메서드를 호출해 강체 속성을 가진 원뿔을 생성하고 /World/Objects/ConeRigid 경로에 배치한다.
첫 번째 인자 "/World/Objects/ConeRigid"는생성된 원뿔이 위치할 경로를 지정한다.
두 번째 인자 cfg_cone_rigid는 설정된 원뿔 속성 객체를 전달하여 강체 및 충돌 속성이 적용된 원뿔을 생성한다.
세 번째 인자 translation=(-0.2, 0.0, 2.0)는 원뿔의 위치를 (x, y, z) 좌표 (-0.2, 0.0, 2.0)에 설정하여 시뮬레이션 공간에 배치한다.
네 번째 인자 orientation=(0.5, 0.0, 0.5, 0.0)는 원뿔의 회전을 쿼터니언(Quaternion) 형식으로 설정한다. 쿼터니언 (0.5, 0.0, 0.5, 0.0)는 원뿔의 초기 회전 방향을 지정하며, 원하는 각도로 배치할 수 있다.  (GPT4)

 

강체 속성이 없는 경우에 객체는 고정된 상태로 취급되며, 외부 힘이나 물리적 효과의 영향을 받지 않는다.
따라서, 아래와 같은 특징을 가진다.
1) 정지 상태 유지 : 물리 엔진에서 중력이나 다른 힘이 작용하지 않으므로, 객체는 정해진 위치와 회전을 계속 유지한다.
2) 충돌 무시 : 다른 객체가 충돌해도 상호작용이 없으며, 충돌 반응이나 이동이 발생하지 않는다.
3) 고정된 위치 : 초기 설정한 위치와 방향에서 벗어나지 않으며, 어떤 외력(힘)도 적용되지 않으므로 시뮬레이션 내에서 움직이지 않는다.  (GPT4)

 

    # spawn a blue cuboid with deformable body
    cfg_cuboid_deformable = sim_utils.MeshCuboidCfg(
        size=(0.2, 0.5, 0.2),
        deformable_props=sim_utils.DeformableBodyPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.0, 0.0, 1.0)),
        physics_material=sim_utils.DeformableBodyMaterialCfg(),
    )

sim_utils.MeshCuboidCfg()는 변형 가능한 큐보이드의 속성을 정의하는 설정 객체다.
변형 가능 객체는 외부 충돌이나 힘에 의해 모양이 변할 수 있어, 일반적인 강체와는 다르게 처리된다.

size=(0.2, 0.5, 0.2)는 큐보이드의 크기를 (x, y, z) 축 방향으로 설정한다. 이 예에서는 폭 0.2, 높이 0.5, 깊이 0.2로 정의되어 있다.
deformable_props=sim_utils.DeformableBodyPropertiesCfg()는 객체를 변형 가능(Deformable) 객체로 정의하는 속성이다. 이를 통해 외부 힘이나 충돌에 의해 객체의 모양이 변형될 수 있도록 한다.
visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.0, 0.0, 1.0))은 시각적 재질(외관)을 정의하며, (0.0, 0.0, 1.0)은 파란색을 의미한다. 이 설정은 RGB 값을 사용해 객체의 색상을 파란색으로 설정한다.
physics_material=sim_utils.DeformableBodyMaterialCfg()는 물리적 속성을 정의하는 데 사용된다. 예를 들어, 객체의 탄성, 마찰력, 변형에 대한 저항력 등이 설정될 수 있으며, 변형 가능 객체의 물리적 반응을 제어한다.  (GPT4)

cfg_cuboid_deformable.func("/World/Objects/CuboidDeformable", cfg_cuboid_deformable, translation=(0.15, 0.0, 2.0))

func() 메서드를 호출해 변형 가능한 큐보이드를 생성하고 /World/Objects/CuboidDeformable 경로에 배치한다.
첫 번째 인자 "/World/Objects/CuboidDeformable"는 큐보이드가 위치할 경로를 지정한다.
두 번째 인자 cfg_cuboid_deformable는 설정된 큐보이드 속성 객체를 전달하여, 변형 가능 속성과 시각적 속성이 적용된 큐보이드를 생성한다.
세번째 인자 translation=(0.15, 0.0, 2.0)는 큐보이드의 위치를 (x, y, z) 좌표 (0.15, 0.0, 2.0)로 설정하여 시뮬레이션 공간에 배치한다.  (GPT4)

 

Spawning from another file

다른 USD, URDF, OBJ와 같은 형식의 prim도 spawn할 수 있다.

    # spawn a usd file of a table into the scene
    cfg = sim_utils.UsdFileCfg(usd_path=f"{ISAAC_NUCLEUS_DIR}/Props/Mounts/SeattleLabTable/table_instanceable.usd")

sim_utils.UsdFileCfg()는 외부 USD 파일을 불러오고 그 속성을 설정하는 객체다.

USD(Universal Scene Description) 파일은 3D 모델 데이터를 포함하며, 모델의 모양, 재질, 변형 등의 정보를 정의하고 있다.

usd_path=f"{ISAAC_NUCLEUS_DIR}/Props/Mounts/SeattleLabTable/table_instanceable.usd"는 불러올 USD 파일의 경로다. 여기서는 ISAAC_NUCLEUS_DIR이라는 환경 변수를 이용해 Nucleus 서버의 특정 디렉토리에서 table_instanceable.usd라는 테이블 모델 파일을 불러온다. 이 파일에는 시뮬레이션에 배치될 테이블의 3D 모델 정보가 포함되어 있다.  (GPT4)

cfg.func("/World/Objects/Table", cfg, translation=(0.0, 0.0, 1.05))

func() 메서드를 호출해 지정된 경로에서 USD 파일을 불러와 시뮬레이션 내에 배치한다.
첫 번째 인자 "/World/Objects/Table"은 테이블 객체가 시뮬레이션 내에서 위치할 경로를 지정한다. 여기서는 /World/Objects/Table 경로에 테이블이 배치된다.
두 번째 인자 cfg는 앞서 생성한 cfg 객체를 전달하여, USD 파일의 경로와 기타 속성을 적용한다.
세 번째 인자 translation=(0.0, 0.0, 1.05)는 테이블의 위치를 (x, y, z) 좌표 (0.0, 0.0, 1.05)로 설정하여 시뮬레이션 내에 배치한다. 이 위치에 따라 테이블이 시뮬레이션 환경의 특정 위치에 나타난다. (GPT4)