面向读者

验证等级

仅配置验证，并有重要运行时限制。 两种声明都可以成功编译，但本案例不会启动 PyBullet。Sensor 支持取决于后端与 adapter。FastSim 当前物理运行时投影尚不能 lower light 实体，因此本案例不声称灯光可以原生运行。

文件说明

  • run.yaml 声明一个 RGB 相机和一个 distant light。
  • main.py 验证两个实例从组件继承的默认参数。
  • Sensor manifest 描述相机默认参数和可移植 RGB channel。
  • Light manifest 描述后端中立灯光。

逐行阅读 Sensor manifest

yaml
schema: fastsim-component/1
id: sensor://fastsim/component-demo-camera # 稳定 sensor identity。
version: 1.0.0
kind: sensor                               # 允许放到 scene.sensors。
defaults:
  params:
    width_px: 1280                         # 默认图像宽度。
    height_px: 720                         # 默认图像高度。
    modalities: [rgb]                     # 默认输出选择。
semantics:
  sensor_type: camera                      # 可移植传感器类别。
  channels:
    rgb:
      dtype: uint8                         # channel 元素类型。
      shape: [720, 1280, 3]               # 单张 RGB 图像：高度、宽度、通道。
      unit: pixel                          # 数值含义。
      frame: sensor                        # 坐标 frame 标签。
variants:
  '*': {}                                  # 后端中立声明。

默认参数减少 Run 中的重复内容。本案例直接接受 manifest 的 1280×720 RGB 默认值， 无需在 Run 重复。实例仍可覆盖 params；如果有效 shape 属于 observation 契约， 生产组件必须保持 channel 元数据和参数覆盖一致。

逐行阅读 Light manifest

yaml
schema: fastsim-component/1
id: light://fastsim/component-demo-sun    # 稳定 light identity。
version: 1.0.0
kind: light                               # 允许放到 scene.lights。
defaults:
  params:
    light_type: distant                   # 定向/远光源意图。
    intensity: 3000.0                     # 默认强度值。
    color_rgb: [1.0, 0.95, 0.85]         # 偏暖 RGB 颜色。
variants:
  '*': {}                                 # 声明可为所有后端编译。

'*' 仅表示配置后端中立，不承诺每个 runtime adapter 都实现这个 kind。仍需检查 能力并进行原生验收。当前 FastSim runtime 未实现 light lowering。

逐行阅读 run.yaml

yaml
schema: fastsim/2
name: sensor-and-light-components
backend: pybullet

runtime:
  physics_hz: 60
  control_hz: 30
  seed: 106

scenario:
  scene:
    sensors:
      overview:                           # 本地 ID：sensors.overview。
        use: sensor://fastsim/component-demo-camera
        pose:
          xyz_m: [1.2, -1.2, 1.0]       # 相机世界位置，单位米。
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]
    lights:
      key:                                # 本地 ID：lights.key。
        use: light://fastsim/component-demo-sun
        pose:
          xyz_m: [0.0, 0.0, 2.5]
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]

两个实体都省略了 params，因此有效值来自各自组件 defaults。

main.py 验证什么

程序通过公开 load_project 编译，找到两个解析后的组件，并断言其 kind 和通配 variant。随后检查 ExecutionPlan.entities 中有效的相机与灯光默认值。

它有意不调用 fastsim.app：否则会错误表达当前 light runtime 支持状况。

运行

bash
cd demo/components/06_sensor_and_light_components
fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml scenario.scene.sensors.overview.params.width_px
fastsim config explain run.yaml scenario.scene.lights.key.params.intensity
fastsim config lock run.yaml --output run.lock.yaml
fastsim config verify-lock run.lock.yaml --json
python main.py

预期输出

text
Compiled declaration: sensors.overview (camera, 1280x720 RGB)
Compiled declaration: lights.key (distant, intensity=3000.0)
Runtime note: light lowering is not implemented; this case is compile-only.

常见错误

  • Sensor 或 light 必须放在与其 kind 匹配的场景分组中。
  • 通配 variant 不等于原生 runtime 支持证明。
  • 只有相机位置不能保证看到目标；必须通过原生渲染帧检查方向和坐标约定。
  • manifest defaults 与 Run params 会深度合并；用 config expand 检查有效结果。
  • 在 runtime lowering 和后端验收实现并通过前，不要宣称灯光已经原生跑通。

下一步

上一个：Environment 组件 · 下一个：Deformable 与 Fluid 组件