面向读者
验证等级
仅配置验证。 本案例会解析真实门 URDF、校验关节声明并生成 ExecutionPlan。
不会启动后端，也不声称门已经真实运动。
文件说明
run.yaml创建一个具有初始铰链角度的门实例。main.py检查关节名称、单位、group 和初始状态。- Articulation manifest 封装模型及其可移植关节词汇。
逐行阅读组件 manifest
yaml
schema: fastsim-component/1
id: articulation://fastsim/component-demo-door # 可复用铰接物体 identity。
version: 1.0.0
kind: articulation # 有关节，但不是机器人。
semantics:
joints: [door_hinge] # 稳定的作者侧关节名称。
links: [frame, door_panel] # 稳定的作者侧 link 名称。
joint_units:
door_hinge: rad # 控制和状态使用弧度。
groups:
door: [door_hinge] # 具名控制资源 group。
variants:
pybullet:
resources:
model:
uri: ../../_shared/assets/door.urdf # 相对于 manifest 的资产。
format: model/vnd.urdf+xml
role: simulation
semantics 是上层使用的可移植词汇。不同 variant 的后端原生名称与文件可以不同，
但使用方仍可稳定访问 door_hinge 和 group door。
编写其他 articulation 时，应列出全部可控关节、单位、相关 link 和有用 group。
铰接物体不会自动成为机器人；仅当组件确实表示机器人 actor 时才使用 kind: robot。
逐行阅读 run.yaml
yaml
schema: fastsim/2
name: articulation-component
backend: pybullet # 选择 URDF variant。
runtime:
physics_hz: 60
control_hz: 30
seed: 103
scenario:
scene:
articulations: # 非机器人有节资产的正确分组。
cabinet_door: # 本地实体别名。
use: articulation://fastsim/component-demo-door
pose:
xyz_m: [0.60, 0.0, 0.0] # 世界根位置，单位米。
quat_xyzw: [0.0, 0.0, 0.0, 1.0]
initial_state:
joints:
door_hinge: 0.35 # 初始角度，单位由 manifest 声明为弧度。
编译器会检查 door_hinge 是否存在于所选组件 semantics 中。拼写错误会在启动
仿真器前被拒绝。
main.py 验证什么
程序使用 load_project 编译相邻 Run，并断言：
- 解析后的 kind 是
articulation； door_hinge及其rad单位保留到 plan；- group
door展开为预期关节； - 初始值进入
articulations.cabinet_door。
运行
bash
cd demo/components/03_articulation_component
fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml scenario.scene.articulations.cabinet_door.initial_state.joints.door_hinge
fastsim config lock run.yaml --output run.lock.yaml
fastsim config verify-lock run.lock.yaml --json
python main.py
预期输出
text
Entity: articulations.cabinet_door
Kind: articulation
Joints: ('door_hinge',)
Control group 'door': ('door_hinge',)
Initial door_hinge: 0.35 rad
常见错误
- 把门放到
objects:下会破坏 kind 契约并被拒绝。 - 初始关节 key 必须与 manifest semantics 完全一致。
- 显式声明角度单位，不要让使用方猜测角度还是弧度。
- group 只能包含所选组件 semantics 已声明的关节。
- 本案例仅编译，不证明 actuator 参数或碰撞行为正确。