与可变形对象交互#
生成柔软的方块，设置节点位置与速度，并通过运动学命令移动选定节点。本教程使用体积可变形体；布料请运行 deformables 示例。
资产 API 跨后端共用，PhysX 使用有限元，Newton 使用 VBD。受支持的物体类型见 可变形物体，配置见 可变形物体。PhysX 仿真网格与碰撞网格详情见 PhysX 文档。
备注
本教程会自动对体积可变形物体进行四面体化，默认可视化器为 Kit。运行时选择 isaacsim 和 tetrahedralization 可选依赖组：
uv run --extra isaacsim --extra tetrahedralization python scripts/tutorials/01_assets/run_deformable_object.py --visualizer kit
如需显式安装可选依赖：
uv sync --extra tetrahedralization
代码#
该教程对应于 run_deformable_object.py 脚本，在 scripts/tutorials/01_assets 目录中。
run_deformable_object.py 的代码
1# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
2# All rights reserved.
3#
4# SPDX-License-Identifier: BSD-3-Clause
5
6"""
7This script demonstrates how to work with the deformable object and interact with it.
8
9.. code-block:: bash
10
11 # Usage with default PhysX physics and default kit visualizer.
12 uv run --extra isaacsim --extra tetrahedralization python scripts/tutorials/01_assets/run_deformable_object.py
13
14 # Usage with Newton VBD physics and default kit visualizer.
15 uv run --extra isaacsim --extra tetrahedralization python scripts/tutorials/01_assets/run_deformable_object.py \
16 --backend newton_vbd
17
18 # Usage with OvPhysX physics without a visualizer.
19 uv run --extra ovphysx --extra tetrahedralization python scripts/tutorials/01_assets/run_deformable_object.py \
20 --backend ovphysx
21
22"""
23
24"""Parse CLI first so we can decide whether to launch Isaac Sim Kit."""
25
26import argparse
27from typing import TYPE_CHECKING
28
29from isaaclab.app import add_launcher_args, launch_simulation
30
31# add argparse arguments
32parser = argparse.ArgumentParser(description="Tutorial on interacting with a deformable object.")
33parser.add_argument(
34 "--backend", type=str, default="physx", choices=["physx", "newton_vbd", "ovphysx"], help="Physics backend."
35)
36# append simulation launcher CLI arguments
37add_launcher_args(parser)
38# Kit cannot be combined with OvPhysX, so use no visualizer by default for that backend
39backend_args, _ = parser.parse_known_args()
40parser.set_defaults(visualizer=None if backend_args.backend == "ovphysx" else ["kit"])
41# parse the arguments
42args_cli = parser.parse_args()
43args_cli.physics = args_cli.backend
44
45"""Rest everything follows."""
46
47import torch
48
49import isaaclab.sim as sim_utils
50import isaaclab.utils.math as math_utils
51from isaaclab.assets import AssetBaseCfg, DeformableObjectCfg
52from isaaclab.cloner import CloneCfg
53from isaaclab.scene import InteractiveSceneCfg
54from isaaclab.utils import configclass, index_fill_, instantiate
55
56if TYPE_CHECKING:
57 from isaaclab.assets import DeformableObject
58 from isaaclab.scene import InteractiveScene
59
60
61youngs_modulus = 1e5
62poissons_ratio = 0.4
63density = 500.0
64if args_cli.backend == "newton_vbd":
65 from isaaclab_newton.sim.spawners.materials import NewtonDeformableBodyMaterialCfg
66
67 # Newton's VBD path skips the simulation mesh collider, so collision offsets do not apply
68 collision_props = None
69 physics_material = NewtonDeformableBodyMaterialCfg(
70 k_mu=youngs_modulus / (2.0 * (1.0 + poissons_ratio)),
71 k_lambda=youngs_modulus * poissons_ratio / ((1.0 + poissons_ratio) * (1.0 - 2.0 * poissons_ratio)),
72 density=density,
73 )
74else:
75 from isaaclab_physx.sim.schemas import PhysxCollisionCfg
76 from isaaclab_physx.sim.spawners.materials import PhysxDeformableBodyMaterialCfg
77
78 collision_props = [PhysxCollisionCfg(rest_offset=0.0, contact_offset=0.001)]
79 physics_material = PhysxDeformableBodyMaterialCfg(
80 poissons_ratio=poissons_ratio, youngs_modulus=youngs_modulus, density=density
81 )
82
83
84@configclass
85class DeformableSceneCfg(InteractiveSceneCfg):
86 """Soft cubes on a shared ground plane."""
87
88 filter_collisions = False
89 clone_cfg = CloneCfg(clone_template="/World/env_{}")
90
91 ground = AssetBaseCfg(prim_path="/World/defaultGroundPlane", spawn=sim_utils.GroundPlaneCfg())
92 light = AssetBaseCfg(
93 prim_path="/World/Light", spawn=sim_utils.DomeLightCfg(intensity=2000.0, color=(0.8, 0.8, 0.8))
94 )
95
96 # 3D Deformable Object
97 cube_object = DeformableObjectCfg(
98 prim_path="{ENV_REGEX_NS}/Cube",
99 # PhysX deformables must be parsed from USD while other assets retain native replication.
100 cloning_contexts=("isaaclab.cloner:UsdReplicateContext",) if args_cli.backend == "physx" else None,
101 spawn=sim_utils.MeshCuboidCfg(
102 size=(0.2, 0.2, 0.2),
103 volume_deformable_props=[],
104 collision_props=collision_props,
105 visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.5, 0.1, 0.0)),
106 physics_material=physics_material,
107 ),
108 init_state=DeformableObjectCfg.InitialStateCfg(pos=(0.0, 0.0, 1.0)),
109 debug_vis=True,
110 )
111
112
113def run_simulator(sim: sim_utils.SimulationContext, scene: "InteractiveScene"):
114 """Runs the simulation loop."""
115 # Extract scene entities
116 cube_object: DeformableObject = scene["cube_object"]
117
118 # Define simulation stepping
119 sim_dt = sim.get_physics_dt()
120 sim_time = 0.0
121 count = 0
122
123 # Nodal kinematic targets of the deformable bodies
124 nodal_kinematic_target = cube_object.data.nodal_kinematic_target.torch.clone()
125
126 # Simulate physics
127 while sim.is_running():
128 # reset at start and after 3 seconds
129 if count % int(3.0 / sim_dt) == 0:
130 # reset counters
131 count = 0
132
133 # reset the nodal state of the object
134 nodal_state = cube_object.data.default_nodal_state_w.torch.clone()
135 # apply random pose to the object
136 pos_w = torch.rand(cube_object.num_instances, 3, device=sim.device) * 0.1 + scene.env_origins
137 quat_w = math_utils.random_orientation(cube_object.num_instances, device=sim.device)
138 nodal_state[..., :3] = cube_object.transform_nodal_pos(nodal_state[..., :3], pos_w, quat_w)
139
140 # write nodal state to simulation
141 cube_object.write_nodal_state_to_sim_index(nodal_state)
142
143 # Write the nodal state to the kinematic target and free all vertices
144 nodal_kinematic_target[..., :3] = nodal_state[..., :3]
145 nodal_kinematic_target[..., 3] = 1.0
146 cube_object.write_nodal_kinematic_target_to_sim_index(nodal_kinematic_target)
147
148 # reset buffers
149 cube_object.reset()
150
151 print("----------------------------------------")
152 print("[INFO]: Resetting object state...")
153
154 # update the kinematic target for cubes at the positive and negative diagonal corners
155 kinematic_cubes = [1, 2]
156 # we slightly move the cube in the z-direction by picking the vertex at index 0
157 nodal_kinematic_target[kinematic_cubes, 0, 2] += 0.2 * sim_dt
158 # set vertex at index 0 to be kinematically constrained
159 # 0: constrained, 1: free
160 index_fill_(nodal_kinematic_target[:, 0, 3], kinematic_cubes, 0.0)
161 # write kinematic target to simulation
162 cube_object.write_nodal_kinematic_target_to_sim_index(nodal_kinematic_target)
163
164 # write internal data to simulation
165 cube_object.write_data_to_sim()
166 # perform step
167 sim.step()
168 # update sim-time
169 sim_time += sim_dt
170 count += 1
171 # update buffers
172 cube_object.update(sim_dt)
173
174 # print the root positions every second
175 if count % int(1.0 / sim_dt) == 0:
176 print(f"Time {sim_time:.2f}s: \tRoot position (in world): {cube_object.data.root_pos_w.torch[:, :3]}")
177
178
179def main():
180 """Main function."""
181 sim_cfg = sim_utils.SimulationCfg(dt=0.01, device=args_cli.device)
182 with launch_simulation(sim_cfg, args_cli) as physics_cfg:
183 if args_cli.backend == "newton_vbd":
184 physics_cfg.solver_cfg.iterations = 10
185 physics_cfg.num_substeps = 4
186 sim = sim_utils.SimulationContext(sim_cfg)
187 # Set main camera
188 sim.set_camera_view(eye=[2.0, 2.0, 2.0], target=[0.0, 0.0, 0.75])
189 scene_cfg = DeformableSceneCfg(num_envs=4, env_spacing=0.5)
190 scene = instantiate(scene_cfg)
191 # Play the simulator
192 sim.reset()
193 # Now we are ready!
194 print("[INFO]: Setup complete...")
195 # Run the simulator
196 run_simulator(sim, scene)
197 print("[INFO]: Simulation complete...")
198
199
200if __name__ == "__main__":
201 # run the main function
202 main()
代码解释#
设计场景#
我们在 scene.InteractiveSceneCfg 的子类中声明地面、灯光和可变形立方体。 scene.InteractiveScene 在内部构建资产并处理复制。 DeformableSceneCfg(num_envs=4, env_spacing=0.5) 在以中心对齐的网格上设置四个环境原点，间距为 0.5 m。
在本教程中，我们使用与 Spawn Objects 教程中的可变立方体类似的 spawn 配置来创建一个立方体软体对象。唯一的区别是我们现在将 spawn 配置包装到 assets.DeformableObjectCfg 类中。这个类包含有关资产的 spawn 策略和默认初始状态的信息。当这个类传递给 assets.DeformableObject 类时，它会在仿真播放时生成对象并初始化相应的物理句柄。
备注
可变形体要求通过 volume_deformable_props 字段（布料使用 surface_deformable_props）生成网格，并配置匹配的可变形体物理材质。空列表使用后端默认值。--backend physx 选择 PhysX 实现，--backend newton_vbd 选择实验性的 Newton 实现。
场景根据配置构建可变形物体，并管理其克隆生命周期。仿真循环通过 scene["cube_object"] 访问构建出的资产。
@configclass
class DeformableSceneCfg(InteractiveSceneCfg):
"""Soft cubes on a shared ground plane."""
filter_collisions = False
clone_cfg = CloneCfg(clone_template="/World/env_{}")
ground = AssetBaseCfg(prim_path="/World/defaultGroundPlane", spawn=sim_utils.GroundPlaneCfg())
light = AssetBaseCfg(
prim_path="/World/Light", spawn=sim_utils.DomeLightCfg(intensity=2000.0, color=(0.8, 0.8, 0.8))
)
# 3D Deformable Object
cube_object = DeformableObjectCfg(
prim_path="{ENV_REGEX_NS}/Cube",
# PhysX deformables must be parsed from USD while other assets retain native replication.
cloning_contexts=("isaaclab.cloner:UsdReplicateContext",) if args_cli.backend == "physx" else None,
spawn=sim_utils.MeshCuboidCfg(
size=(0.2, 0.2, 0.2),
volume_deformable_props=[],
collision_props=collision_props,
visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.5, 0.1, 0.0)),
physics_material=physics_material,
),
init_state=DeformableObjectCfg.InitialStateCfg(pos=(0.0, 0.0, 1.0)),
debug_vis=True,
)
运行仿真循环#
继续刚体教程，我们在定期间隔内重置仿真，对可变形物体应用运动学命令，推进仿真，并更新可变形对象的内部缓冲区。
重置仿真状态#
与刚体和关节不同，可变形物体具有不同的状态表示。可变形物体的状态由网格的节点位置和速度定义。节点位置和速度定义在 simulation world frame 中，并存储在 assets.DeformableObject.data 属性中。
通过 assets.DeformableObject.data.default_nodal_state_w 属性，获取所生成物体 prim 的默认节点状态。该状态可通过 assets.DeformableObjectCfg.init_state 配置；本教程将立方体放在环境原点上方 1 m 处。
注意
配置中的初始状态 assets.DeformableObjectCfg 指定了在生成时变形对象的姿态。根据这个初始状态，当仿真第一次播放时，会得到默认的节点状态。
我们对节点位置应用变换，以随机化可变形物体的初始状态。
# reset the nodal state of the object
nodal_state = cube_object.data.default_nodal_state_w.torch.clone()
# apply random pose to the object
pos_w = torch.rand(cube_object.num_instances, 3, device=sim.device) * 0.1 + scene.env_origins
quat_w = math_utils.random_orientation(cube_object.num_instances, device=sim.device)
nodal_state[..., :3] = cube_object.transform_nodal_pos(nodal_state[..., :3], pos_w, quat_w)
要重置可变形对象，我们首先通过调用 assets.DeformableObject.write_nodal_state_to_sim() 方法来设置节点状态。此方法将可变形对象原始的节点状态写入仿真缓冲区。此外，我们通过调用 assets.DeformableObject.write_nodal_kinematic_target_to_sim() 方法来释放在上一个仿真步骤中为节点设置的所有运动学目标。我们将在下一节中解释运动学目标。
最后，我们调用 assets.DeformableObject.reset() 方法来重置任何内部缓冲区和缓存。
# write nodal state to simulation
cube_object.write_nodal_state_to_sim_index(nodal_state)
# Write the nodal state to the kinematic target and free all vertices
nodal_kinematic_target[..., :3] = nodal_state[..., :3]
nodal_kinematic_target[..., 3] = 1.0
cube_object.write_nodal_kinematic_target_to_sim_index(nodal_kinematic_target)
# reset buffers
cube_object.reset()
推进仿真#
可变形体支持用户控制的运动学操作：用户为部分网格节点指定目标位置，其余节点仍由当前可变形求解器仿真。这种 部分运动学控制 适合需要以受控方式与可变形物体交互的应用。
在本教程中，我们将运动学命令应用于场景中的四个立方体中的两个。我们设置索引为 0（左下角）的节点的位置目标，使立方体沿 z 轴移动。
在每一步中，我们通过一个小值来增加节点的运动学位置目标。此外，我们设置标志以指示该目标是仿真缓冲区中该节点的运动学目标。这些设置通过调用 assets.DeformableObject.write_nodal_kinematic_target_to_sim() 方法来写入仿真缓冲区。
# update the kinematic target for cubes at the positive and negative diagonal corners
kinematic_cubes = [1, 2]
# we slightly move the cube in the z-direction by picking the vertex at index 0
nodal_kinematic_target[kinematic_cubes, 0, 2] += 0.2 * sim_dt
# set vertex at index 0 to be kinematically constrained
# 0: constrained, 1: free
index_fill_(nodal_kinematic_target[:, 0, 3], kinematic_cubes, 0.0)
# write kinematic target to simulation
cube_object.write_nodal_kinematic_target_to_sim_index(nodal_kinematic_target)
类似于刚体和关节，我们在进行仿真步进之前执行 assets.DeformableObject.write_data_to_sim() 方法。对于可变形对象，此方法不会对对象施加任何外部力。然而，我们保留此方法以便于完整性和未来扩展。
# write internal data to simulation
cube_object.write_data_to_sim()
更新状态#
在运行仿真后，我们更新可变对象 prims 的内部缓冲区，以反映它们在 assets.DeformableObject.data 属性中的新状态。这是通过 assets.DeformableObject.update() 方法完成的。
在固定的间隔下，我们将可变形物体的根位置打印到终端。如前所述，对于可变形物体来说，没有根状态的概念。然而，我们计算根位置的方法是所有网格节点的平均位置。
# update buffers
cube_object.update(sim_dt)
# print the root positions every second
if count % int(1.0 / sim_dt) == 0:
print(f"Time {sim_time:.2f}s: \tRoot position (in world): {cube_object.data.root_pos_w.torch[:, :3]}")
代码执行#
现在我们已经浏览了代码，让我们运行脚本并查看结果:
uv run --extra isaacsim --extra tetrahedralization python scripts/tutorials/01_assets/run_deformable_object.py --visualizer kit
使用实验性 Newton 可变形后端运行同一教程：
uv run --extra isaacsim --extra tetrahedralization python scripts/tutorials/01_assets/run_deformable_object.py --backend newton_vbd --visualizer kit
这应打开一个包含地面、灯光和若干立方体的舞台。四个立方体中，两个从高处落下并停在地面，另外两个沿 z 轴运动。立方体左下角的节点应显示运动学目标位置标记。关闭窗口或在终端按 Ctrl+C 可停止仿真。
本教程展示了如何生成可变形物体，并用 DeformableObject 类封装它们、初始化物理句柄，从而设置和读取状态。还展示了如何施加运动学命令，以受控方式移动网格节点。 deformables 示例提供了更进阶的用法，包括表面可变形物体、加载 USD 资产和应用可变形材料。