Isaac Lab 场景搭建入门使用 Python 与 Spawner 配置在 USD Stage 中生成 Prims【免费下载链接】IsaacLabUnified framework for robot learning with multi-physics/renderer support项目地址: https://gitcode.com/GitHub_Trending/is/IsaacLab本教程基于 Isaac Lab 官方教程spawn_prims.pyscripts/tutorials/00_sim/spawn_prims.py与sim.spawners模块讲解如何通过 Python 在 USD Stage 中生成地面、光源、几何体与来自文件的资产覆盖配置类驱动、刚体/柔体物理属性、材质绑定与参考reference机制等核心概念。读完本文你将能够脱离 GUI用纯 Python 搭建一个可运行、可交互的仿真场景。从一个最小可运行场景开始本文对应的完整脚本位于 scripts/tutorials/00_sim/spawn_prims.py它建立在从独立脚本运行仿真器教程之上展示四类最常见的生成操作生成地面Ground Plane生成光源Light生成基础几何体Primitive Shapes从文件USD生成资产。脚本的核心结构分为design_scene()负责所有生成操作与main()负责初始化仿真上下文、设置相机、推进物理循环def main(): Main function. # Initialize the simulation context sim_cfg sim_utils.SimulationCfg(dt0.01, deviceargs_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 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()sim.set_camera_view([2.0, 0.0, 2.5], [-0.5, 0.0, 0.5])中第一个参数是相机位置第二个是相机注视的目标点sim.step()每调用一次推进一个物理步长dt0.01即 100 Hz。注意所有场景搭建必须在仿真开始sim.reset()之前完成。仿真开始后建议保持场景冻结仅修改已有 prim 的属性。这在 GPU 仿真下尤为重要——仿真中途新增 prim 可能改变 GPU 上的物理仿真缓冲区导致不可预期的行为。USD 核心概念Prim、Attribute、Relationship 与 StageIsaac Lab 的场景设计基于USDUniversal Scene Description一种类似文件系统的、具有层级结构的 3D 场景描述格式。要熟练使用 spawner必须先掌握四个核心概念PrimitivesPrimsUSD 场景的基本构建单元可视为场景图中的节点。每个节点可以是网格mesh、光源light、相机camera或变换transform也可以是一个包含其他 prim 的分组。Attributesprim 的属性可视为键值对。例如一个 prim 可以有color属性值为red。Relationshipsprim 之间的连接可视为指向其他 prim 的指针。例如网格 prim 可以通过 relationship 关联到材质 prim 进行着色。USD Stage上述 prim、attribute、relationship 的集合容器。当我们说设计场景时实际上就是在设计一个 USD stage。配置驱动生成Spawner 的工作原理直接使用底层 USD API 虽然灵活但学习曲线陡峭。Isaac Lab 在 USD API 之上封装了**配置驱动configuration-driven**的生成接口集中在 sim.spawners 模块。核心思想是每个 prim 对应一个配置类Cfg实例配置类描述了该 prim 的属性与关系材质、着色信息随后将配置实例交给对应的生成函数并指定 prim 路径与变换平移、旋转、缩放即可把 prim 生成到场景中。通用流程如下# 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])这两种方式完全等价——cfg.func默认指向该配置类对应的生成函数见 spawner_cfg.py 中SpawnerCfg的定义。配置基类SpawnerCfg 的公共字段所有 spawner 配置类都继承自SpawnerCfg其中包含一组通用字段见 spawner_cfg.py字段默认值说明func必须指定用于生成资产的函数接收 prim 路径、配置实例与变换返回生成的源 primvisibleTrue生成的资产是否可见semantic_tagsNone语义标签列表遵循 Replicator Semantic 标注系统每个标签为(type, data)元组如[(class, avocado)]copy_from_sourceTrue克隆 prim 时是否从源 prim 复制若为False则继承源 prim对源 prim 的 USD 修改会反映到克隆体spawn_pathNone原型prototype生成路径此外用于刚体/柔体对象的配置类还支持mass_props质量属性、rigid_props刚体属性设为kinematic_enabledTrue可使对象静止、collision_props碰撞属性、deformable_props柔体属性等字段默认均为None不添加或修改任何属性。可用的 Spawner 家族sim.spawners 模块按功能分为多个子模块from_files从文件生成如GroundPlaneCfg、UsdFileCfg、UrdfFileCfg、MjcfFileCfgshapes基础几何体如ConeCfg、CuboidCfg、SphereCfg、CylinderCfg、CapsuleCfgmeshes网格几何体如MeshCuboidCfg、MeshSphereCfg等支持柔体属性lights光源如DistantLightCfg、SphereLightCfg、DiskLightCfg、CylinderLightCfg、DomeLightCfgmaterials视觉材质与物理材质sensors、wrappers传感器与包装器相关生成器。生成地面Ground Plane地面通过GroundPlaneCfg配置生成见 from_files_cfg.py。它默认使用 Isaac Sim 标准网格世界地面并支持颜色、尺寸与物理材质等可配置属性# Ground-plane cfg_ground sim_utils.GroundPlaneCfg() cfg_ground.func(/World/defaultGroundPlane, cfg_ground)GroundPlaneCfg的关键字段字段默认值说明usd_path{ISAAC_NUCLEUS_DIR}/Environments/Grid/default_environment.usd生成地面所用的 USD 文件color(0.0, 0.0, 0.0)地面颜色设None则保持原样size(100.0, 100.0)地面尺寸单位米physics_material默认刚体材质物理材质属性生成光源LightsUSD 支持多种光源 prim包括distant light远距离光、sphere light球光、disk light盘光、cylinder light柱光。其中 distant light 可理解为无限远处、沿单一方向照射的光源适合模拟太阳/月光。本教程生成一盏远距离光见 lights_cfg.py# spawn distant light cfg_light_distant sim_utils.DistantLightCfg( intensity3000.0, color(0.75, 0.75, 0.75), ) cfg_light_distant.func(/World/lightDistant, cfg_light_distant, translation(1, 0, 10))所有灯光配置类共享的公共字段字段默认值说明color(1.0, 1.0, 1.0)光色采用能量线性energy-linear表示默认白色intensity1.0线性缩放光功率exposure0.0以 2 的幂指数缩放光功率结果与intensity相乘normalizeFalse是否按光源表面积归一化功率便于独立调节功率与形状enable_color_temperatureFalse是否启用色温color_temperature6500.0色温开尔文有效范围[1000, 10000]仅当enable_color_temperature为True时生效DistantLightCfg特有的angle字段默认0.53度表示光源的角尺寸例如从地球看太阳约为 0.53 度增大该值会柔化阴影边缘。本教程中intensity3000.0是一个相对较亮的设定color(0.75, 0.75, 0.75)是浅灰色调。生成基础几何体从 Xform 到 ConeXform仅含变换的分组节点在生成几何体之前先引入transform primXform的概念它是只包含变换属性的 prim用于将其他 prim 分组并对整组进行统一变换。# create a new xform prim for all objects to be spawned under sim_utils.create_prim(/World/Objects, Xform)sim_utils.create_prim实现见 utils/prims.py接收 prim 路径、prim 类型如Xform以及可选的position、translation、orientation、scale、usd_path等参数。这里在/World下创建名为Objects的 Xform作为后续所有几何体的父节点。无物理属性的视觉圆锥接下来用ConeCfg生成圆锥见 shapes_cfg.py。ConeCfg支持指定半径、高度、物理属性与材质属性默认情况下物理与材质属性是关闭的。前两个圆锥Cone1、Cone2是纯视觉元素没有启用物理# spawn a red cone cfg_cone sim_utils.ConeCfg( radius0.15, height0.5, visual_materialsim_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))这里使用PreviewSurfaceCfg作为视觉材质见 visual_materials_cfg.py其常用字段包括字段默认值说明diffuse_color(0.18, 0.18, 0.18)表面基色RGB本教程设为红色(1.0, 0.0, 0.0)emissive_color(0.0, 0.0, 0.0)表面自发光颜色roughness0.5高光粗糙度范围[0, 1]0 光滑、1 粗糙metallic0.0金属度范围[0, 1]opacity1.0不透明度范围[0, 1]仅在交互渲染时影响外观启用刚体物理的绿色圆锥第三个圆锥ConeRigid通过配置类启用了刚体物理。RigidObjectSpawnerCfg支持mass_props质量、rigid_props刚体、collision_props碰撞三类属性未指定时回退到 USD Physics 的默认值# spawn a green cone with colliders and rigid body cfg_cone_rigid sim_utils.ConeCfg( radius0.15, height0.5, rigid_propssim_utils.RigidBodyPropertiesCfg(), mass_propssim_utils.MassPropertiesCfg(mass1.0), collision_propssim_utils.CollisionPropertiesCfg(), visual_materialsim_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) )各物理配置类说明RigidBodyPropertiesCfg()为对象添加刚体属性默认按 USD/PhysX 默认值定义见 isaaclab_physx/sim/schemas/schemas_cfg.pyMassPropertiesCfg(mass1.0)显式指定质量为 1 kg定义见 schemas_cfg.pyCollisionPropertiesCfg()为所有碰撞网格启用碰撞属性定义见 isaaclab_physx/sim/schemas/schemas_cfg.py。注意orientation(0.5, 0.0, 0.5, 0.0)这是四元数w, x, y, z表示给圆锥一个初始旋转使其落地姿态更有观赏性。启用柔体物理的蓝色长方体最后生成一个带deformable body柔体物理属性的长方体。与刚体不同柔体的顶点之间存在相对运动适合模拟布料、橡胶、果冻等软体。柔体有两条硬性要求仅在 GPU 仿真下支持且必须以网格mesh形式生成同时绑定柔体物理属性与柔体物理材质。因此这里使用 PhysX 专属的柔体属性与材质配置类# spawn a blue cuboid with deformable body cfg_cuboid_deformable sim_utils.MeshCuboidCfg( size(0.2, 0.5, 0.2), deformable_propsPhysxDeformableBodyPropertiesCfg(), visual_materialsim_utils.PreviewSurfaceCfg(diffuse_color(0.0, 0.0, 1.0)), physics_materialPhysxDeformableBodyMaterialCfg(), ) cfg_cuboid_deformable.func(/World/Objects/CuboidDeformable, cfg_cuboid_deformable, translation(0.15, 0.0, 2.0))这里引用了两个 PhysX 专属配置PhysxDeformableBodyPropertiesCfg柔体物理属性见 isaaclab_physx/sim/schemas/schemas_cfg.pyPhysxDeformableBodyMaterialCfg柔体物理材质见 isaaclab_physx/sim/spawners/materials/physics_materials_cfg.py其生成函数为spawn_deformable_body_material。它们从isaaclab_physx.sim导入from isaaclab_physx.sim.schemas import PhysxDeformableBodyPropertiesCfg from isaaclab_physx.sim.spawners.materials import PhysxDeformableBodyMaterialCfgMeshCuboidCfg位于 meshes_cfg.py。需要强调的是刚体属性与柔体属性互斥——MeshCfg的文档明确指出若同时设置刚体与柔体属性或同时设置碰撞与柔体属性会抛出错误。柔体没有独立的碰撞网格其碰撞网格与视觉网格相同碰撞相关属性rest offset 等在deformable_props中配置。从文件生成资产USD 文件与 Reference 机制场景搭建的最后一步是从文件生成资产。Isaac Lab 的FileCfg家族支持USD、URDF、MJCF、OBJ等格式见 from_files_cfg.py其中UrdfFileCfg与MjcfFileCfg会先通过对应的转换器UrdfConverter、MjcfConverter把源文件转换为 USD再生成到场景中。本教程生成一张桌子其网格与材质信息都存储在 USD 文件中# spawn a usd file of a table into the scene cfg sim_utils.UsdFileCfg(usd_pathf{ISAAC_NUCLEUS_DIR}/Props/Mounts/SeattleLabTable/table_instanceable.usd) cfg.func(/World/Objects/Table, cfg, translation(0.0, 0.0, 1.05))ISAAC_NUCLEUS_DIR来自isaaclab.utils.assets指向 Isaac 资产库Nucleus根目录usd_path使用 f-string 拼出桌子的 USD 资产路径。UsdFileCfg见 from_files_cfg.py的核心参数字段说明usd_path要生成的 USD 文件路径必填variants选择 USD 文件中的变体variant可为 configclass 或dictscale资产缩放None表示不修改visual_material/physics_material覆盖视觉/物理材质articulation_props、joint_drive_props等关节/传动等进阶属性为什么是引用而不是复制本教程强调一个关键机制这张桌子是以 Reference引用方式加入场景的。通俗地说桌子并不是被真正复制进场景而是添加了一个指向桌资产文件的指针。由此带来非破坏性non-destructive编辑能力你可以修改场景中的桌子例如更换材质不会改动磁盘上原始的 USD 文件只有变更本身被记录在 USD stage 中原始数据保持原样这种机制同样解释了SpawnerCfg.copy_from_source字段克隆 prim 时若设为False则克隆体继承源 prim对源的修改会同步到克隆体。运行脚本与验证结果运行命令与上一篇教程一致./isaaclab.sh -p scripts/tutorials/00_sim/spawn_prims.pyisaaclab.sh是仓库根目录下的启动脚本-p指定用项目自带的 Python 解释器运行目标脚本。仿真启动后你应看到包含地面、光源、若干圆锥和一张桌子的窗口启用了刚体物理的绿色圆锥会受重力下落与桌子和地面发生碰撞两个红色圆锥是纯视觉元素保持静止不动蓝色柔体长方体会表现出顶点间的相对运动需要 GPU 仿真支持。停止仿真的方式有两种直接关闭窗口或在终端按CtrlC。小结Spawner 的核心使用模式回顾本教程Isaac Lab 的场景搭建遵循一个高度统一的模式创建配置实例用对应配置类GroundPlaneCfg、DistantLightCfg、ConeCfg、MeshCuboidCfg、UsdFileCfg等描述 prim 的属性、物理特性与材质调用生成函数通过cfg.func(prim_path, cfg, translation..., orientation..., scale...)或等价的spawn_xxx()函数生成 prim分层组织利用 Xform 等分组 prim 维护场景层级物理可选视觉元素默认无物理按需通过rigid_props/deformable_props/collision_props/mass_props组合启用刚体或柔体物理场景冻结所有生成必须在sim.reset()之前完成。掌握这一模式后你就可以在此基础上自由组合各类 spawner为机器人任务定制任意仿真环境后续教程将进一步讲解如何与场景及仿真进行交互。【免费下载链接】IsaacLabUnified framework for robot learning with multi-physics/renderer support项目地址: https://gitcode.com/GitHub_Trending/is/IsaacLab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考