企业官网建设流程全解析

• 科研
• 自动驾驶
• 物理引擎

导读

本文讲解 Webots 仿真器中的Billboard（公告板）节点：它能让一组子节点在三维世界中自动旋转与平移，始终正面朝向当前视点（Viewpoint）。无论你在场景中如何移动视角，挂在 Billboard 中的内容（如驾驶舱仪表、足球比赛比分牌、信息提示框）都会像真实世界中的"公告板"一样正对着观察者。读完本文你将掌握 Billboard 的字段结构、放置规则、摄像机可见性、阴影行为以及它的源码级实现原理，并能在自己的.wbt世界文件中直接复用它。

一、Billboard 是什么：从需求到节点定义

在 Webots 中，常规的三维物体（如 Shape、Solid）会随视点移动而自然改变在屏幕上的投影角度。如果需要在主视图中"恒定显示"一段信息——无论视点如何移动和旋转都正对着你——就需要一个不受视点变化影响的载体。Billboard节点正是为此设计：

ABillboardnode containschildrennodes that rotate and translate automatically to follow the viewpoint and face it.

该节点在 R2021b 版本中被引入，官方发布说明描述为："A new Billboard node has been introduced to display information in the main view regardless of the position and orientation of the viewpoint."（见 docs/blog/Webots-2021-b-release.md）。典型应用场景包括：座舱仪表（cockpit）显示、足球比赛比分（score of a soccer match）、HUD 信息面板等。

Billboard 的完整字段定义如下（见 docs/reference/billboard.md 与节点声明文件 resources/nodes/Billboard.wrl）：

Billboard { MFNode children [ ] # {node, PROTO} }

它仅继承自 Group 节点的children字段，没有新增任何可配置参数。字段含义：

从节点继承关系看，Billboard是Group的直接派生节点（见 docs/reference/group.md 中 "Direct derived nodes: Pose, Billboard"），因此它的行为与Group基本一致，只是额外附加了"自动朝向视点"的变换。

二、核心行为与放置规则

2.1 自动旋转 + 平移，与 Group 别无二致

除自动朝向视点外，Billboard 与 Group 节点完全类似：children之间不引入新的坐标变换，子节点按照在场景树中的层级摆放。

2.2 新增子节点的放置要点：沿 x 轴正方向平移

当一个节点被加入 Billboard 的children列表时，它是相对于视点的位置与朝向被放置在世界中的。这意味着：

When a node is added to thechildrenlist of aBillboard, it is placed in the world relatively to the viewpoint position and orientation. To see the newly added nodes, they should be translated positively along their x-axis.

也就是说，为了让刚加入的子节点可见，需要让它在自身局部坐标系的 x 轴正方向上进行平移。这是因为 Billboard 内部会把自己的朝向同步为视点的朝向，此时子节点的局部 x 轴恰好对应"从视点指向远方"的方向——把内容沿 x 轴正方向推出，才能保证它出现在视点正前方而不是视点所在位置（或视点背后）。

来看仓库测试用例 tests/api/worlds/billboard.wbt 中的标准写法：子内容（一个红色小立方体）被包在translation 2 0 0的 Pose 中，即沿 x 轴正方向平移 2 米，这正是"放在视点前方两米处"的典型做法：

Billboard { children [ Pose { translation 2 0 0 children [ Group { children [ Shape { appearance PBRAppearance { baseColor 1 0 0 roughness 1 metalness 0 } geometry Box { size 0.1 0.1 0.1 } } ] } ] } ] }

2.3 摄像机视角可见性：主视图可见，Camera 不可见

Billboard 有两个重要的渲染限制：

1. Billboard 中的物体对 Camera 节点不可见（The objects contained in the Billboard are not visible by Cameras）；
2. Billboard 内部的 Shape 不能投射或接收阴影（cannot cast or receive shadows）。

这两条限制都能在源码中得到印证：

• 在 src/webots/nodes/WbGeometry.cpp 中，几何体设置渲染可见性时会检查WbNodeUtilities::isDescendantOfBillboard(this)，若位于 Billboard 之下，则使用VF_INVISIBLE_FROM_CAMERA可见性标志——即对仿真摄像机隐藏，但仍在主视图可见；
• 可见性标志VF_INVISIBLE_FROM_CAMERA在 src/webots/wren/WbWrenRenderingContext.hpp 中被注释为 "flag for selected outlines and billboards"，说明该标志正是为 Billboard 这类"主视图专用"内容准备的。

所以，Billboard 只能服务于人眼所在的主视图，仿真摄像机（Robot 上挂载的 Camera 设备）是拍不到这些内容的。若你的用例需要"让机器人也看到 HUD"，请改用普通 Group 或 Pose 布局。

三、源码级实现原理：每帧跟随视点的 Wren 变换

要深入理解 Billboard 的"始终面向视点"，可以阅读它的 C++ 实现 src/webots/nodes/WbBillboard.cpp 与头文件 src/webots/nodes/WbBillboard.hpp。

3.1 继承与节点类型

WbBillboard继承自WbGroup（对应 Group 节点），其nodeType()返回WB_NODE_BILLBOARD，并以WbTokenizer方式支持从.wbt文件解析、复制与克隆。

3.2 关键调用链：视点位置与朝向 → Wren Transform

Billboard 的实现核心是把视点的位置与朝向同步到内部 Wren 变换节点上：

• postFinalize()：连接视点的cameraParametersChanged信号，任何相机参数变化都会触发updatePosition()重新定位；
• createWrenObjects()：创建一个新的WrTransform（即wr_transform_new()），挂到自身的 Wren 节点下作为子节点，随后创建所有子节点的 Wren 对象，并立即执行一次updatePosition()；
• applyTranslationToWren()：读取WbWorld::instance()->viewpoint()->position()，把视点位置写入该 Transform 的 position；
• applyRotationToWren()：读取视点的orientation()（WbSFRotation），写入该 Transform 的 orientation。

也就是说，Billboard 通过把整个内容子树绑定到视点坐标系来实现"跟随"，子节点在世界中的实际位置/朝向 = 视点位置/朝向 ⊕ 子节点自身的局部变换。这就是"子节点相对于视点摆放、需要沿 x 轴平移才可见"这一规则的直接来源。

3.3 Web 端的同步实现

Web 前端（web模块）中有对应的 JS 实现 resources/web/wwi/nodes/WbBillboard.js，逻辑与 C++ 一致：构造时将自身 id 登记到WbWorld.instance.billboards，updatePosition()同样将视点的 orientation（四元数）与 position 写入 Wren Transform。它还提供了isDescendantOfBillboard(node)静态方法，沿父链向上遍历判断某个节点是否位于 Billboard 之内——与 C++ 端WbNodeUtilities::isDescendantOfBillboard（见 src/webots/nodes/utils/WbNodeUtilities.cpp）一一对应。

四、使用限制与注意事项

从源码还可以确认两条额外的使用限制：

1. Billboard 节点不能使用USE引用：在 WbNodeUtilities.cpp 中，Billboard与 Solid、Joint 等节点一起被禁止用于 DEF/USE 复用，违反时会提示 "Billboard nodes cannot be USEd."。因此需要多块信息面板时，请创建多个 Billboard 实例，而不是DEF/USE一份。

2. Billboard 会放大"机器人可插入"的判定范围：在场景树编辑器中进行插入/粘贴校验时，WbNodeUtilities会在多处检查isDescendantOfBillboard(node)，例如 WbNodeUtilities.cpp 中判定"Robot 能否作为子节点插入"时，若目标位于 Billboard 内则放宽限制（!WbNodeUtilities::isDescendantOfBillboard(node)才会报错）。这表明 Billboard 是一个纯粹的可视化容器，可以容纳 Robot 等原本只能作为顶层节点的内容，但请结合渲染限制理解其用途边界。

另外，由于 Billboard 内容不可被 Camera 捕捉且不参与阴影，它不会影响物理仿真，也不能被用作传感器探测目标；它是纯粹的 HUD/信息展示层。

五、实战：构建一个跟随视点的比分牌

结合以上规则，给出一个可直接运行的完整示例。将下面内容保存为hud.wbt并在 Webots 中打开：

#VRML_SIM R2025a utf8 WorldInfo { } Viewpoint { } Billboard { children [ Pose { translation 2 0 0 children [ Shape { appearance PBRAppearance { baseColor 0.9 0.2 0.2 roughness 0.5 metalness 0 } geometry Box { size 0.8 0.4 0.05 } } ] } ] }

要点回顾：

• translation 2 0 0：沿局部 x 轴正方向平移 2 米，让面板出现在视点正前方；
• 运行后移动/旋转视点，面板会始终正对着你，尺寸和文字方向不变；
• 若在 Robot 上挂 Camera 并切换至其画面，面板将不可见；
• 面板无法参与阴影投射与接收。

更复杂的 HUD（文字、图标、多面板）只需在 Billboard 的children中继续堆叠 Pose、Shape 等节点，并注意"沿 x 轴正方向摆放"即可。

六、与其他节点及文档体系的关联

• 继承关系：Billboard 是 Group 的直接派生节点，与 Pose 同级；
• 节点总览：见 docs/reference/node-chart.md（Group --> Billboard）与 docs/reference/nodes-and-api-functions.md；
• 语法关键字：Billboard 在 docs/reference/nodes-and-keywords.md 的关键字清单中出现，因此可被.wbt世界文件直接解析（由 src/webots/core/WbLanguage.cpp 注册到语言关键字表中）；
• 引入历史：见 docs/reference/changelog-r2021.md；
• 回归测试：官方 API 测试 tests/api/worlds/billboard.wbt 配合控制器 tests/api/controllers/billboard/billboard.c 验证了"移动视点位置、旋转视点朝向，主视图渲染结果（导出的三张图片）保持逐字节一致"，即 Billboard 内容始终跟随视点、画面不随视点改变——这是理解其行为的最直观实证。

七、常见问题小结

• Q：为什么我把 Shape 加进 Billboard 后看不到它？A：需要把它沿局部x 轴正方向平移，例如包在translation 2 0 0的 Pose 中；不加平移时内容与视点重合，可能被视点吞没。

• Q：为什么仿真摄像机的画面里没有 Billboard 内容？A：这是设计行为——Billboard 内容对 Camera 节点不可见（VF_INVISIBLE_FROM_CAMERA），它只服务于主视图。

• Q：Billboard 内的模型为什么没有阴影？A：Billboard 内的 Shape 不参与阴影投射/接收，这是官方文档明确声明的限制。

• Q：能对 Billboard 使用 DEF/USE 复用吗？A：不能，源码会在 DEF/USE 校验时给出 "Billboard nodes cannot be USEd." 的警告；需要多个面板时请分别实例化。

• 科研
• 自动驾驶
• 物理引擎