Gazebo Sim 逻辑音频传感器(LogicalAudioSensorPlugin)完全指南:SDF 配置、音量衰减模型与启停服务

原创2026-10-13 13:53:261,385 阅读
文章标签:机器人ROS3D渲染物理引擎图形学仿真桌面应用IoT协议

Gazebo Sim 逻辑音频传感器(LogicalAudioSensorPlugin)完全指南:SDF 配置、音量衰减模型与启停服务

逻辑音频传感器(LogicalAudioSensorPlugin)是 Gazebo Sim(gz-sim)中用于模拟"声音能否被听到"的系统插件:它在仿真环境中放置逻辑音频源(source)与逻辑麦克风(microphone),在每个仿真步结束时计算麦克风位置处能接收到的音量,并发布检测结果。它不向扬声器等真实音频设备播放任何声音,而是回答"该位置理论上能否听到某声源"这一问题,非常适合用于声学可听性(acoustic detectability)相关的仿真测试,例如机器人感知、安防监控、声音触发事件等场景。读完本文,你将掌握如何在 SDF 中配置音频源与麦克风的全部参数、理解音量衰减的数学原理,并通过话题(topic)与服务(service)完成检测观察与声源启停控制。

Gazebo Sim 逻辑音频传感器示例世界:红、蓝、绿、黄四个盒子分别挂载音频源与麦克风

逻辑音频传感器是什么

LogicalAudioSensorPlugin 是 gz-sim 内置系统插件之一,其核心行为在插件头文件中有明确描述(见 src/systems/logical_audio_sensor_plugin/LogicalAudioSensorPlugin.hh):

  • 每个 <plugin> 标签可以挂载多个传感器,即多个声源(source)和/或麦克风(microphone);
  • 在每个仿真步(simulation step)结束之后,每个麦克风都会检查世界中的所有声源,判断自己是否"听到了"音频;
  • 插件不会向扬声器之类的音频设备播放真实声音,它只计算"某个位置理论上能否听到某个声源"。

从实现上看,插件同时继承并实现了三个系统接口(LogicalAudioSensorPlugin.hh):ISystemConfigure(配置阶段创建实体)、ISystemPreUpdate(更新前处理声源启停状态)、ISystemPostUpdate(更新后计算音量并发布检测消息)。插件在文件末尾通过 GZ_ADD_PLUGIN 与 GZ_ADD_PLUGIN_ALIAS 注册,对外名称为 gz::sim::systems::LogicalAudioSensorPlugin,SDF 中使用的 filename 为 gz-sim-logicalaudiosensorplugin-system(见 LogicalAudioSensorPlugin.cc)。

工作原理总览(源码级)

结合 LogicalAudioSensorPlugin.cc 的实现,插件的工作流程分为三个阶段:

  1. Configure:创建实体。插件克隆 SDF 元素,遍历所有 <source> 与 <microphone> 子元素,分别调用 CreateAudioSource 与 CreateMicrophone(见 LogicalAudioSensorPlugin.cc)。每个源/麦克风都会在 ECM(EntityComponentManager)中创建一个独立实体,并挂载 Name、Sensor、Pose 等组件以及对应的逻辑音频组件。
  2. PreUpdate:维护声源启停状态。插件遍历所有声源实体,读取 LogicalAudioSourcePlayInfo 组件;在首次更新时记录 startTime;随后根据 play/stop 服务调用标志位更新 playing 状态,并检查 DurationExceeded(播放时长是否超限)以自动停止声源(见 LogicalAudioSensorPlugin.cc)。服务调用与 PreUpdate 之间通过 playSourceMutex / stopSourceMutex 互斥锁保证线程安全。
  3. PostUpdate:计算音量并发布检测。对每个麦克风,插件取出其世界位姿,遍历所有 LogicalAudioSource 与 LogicalAudioSourcePlayInfo 组件,调用 logical_audio::computeVolume 计算该麦克风位置接收到的音量,再用 logical_audio::detect 与麦克风的 volumeDetectionThreshold 比较;若达到阈值,则通过 <PREFIX>/mic_<id>/detection 话题发布一条 gz.msgs.Double 消息(见 LogicalAudioSensorPlugin.cc)。

其中涉及的 ECM 组件类型定义在 include/gz/sim/components/LogicalAudio.hh:

  • components::LogicalAudioSource:承载声源属性结构体 logical_audio::Source(id、衰减函数、衰减形状、内半径、衰减距离、发射音量);
  • components::LogicalAudioSourcePlayInfo:承载播放信息结构体 logical_audio::SourcePlayInfo(是否播放中 playing、播放时长 playDuration、最近开始播放时间 startTime);
  • components::LogicalMicrophone:承载麦克风属性结构体 logical_audio::Microphone(id、检测音量阈值)。

在 SDF 中定义逻辑音频源

完整 SDF 示例

以示例世界 examples/worlds/logical_audio_sensor_plugin.sdf 中挂载在 red_box 模型上的音频源为例,SDF 写法如下:

<plugin filename="gz-sim-logicalaudiosensorplugin-system" name="gz::sim::systems::LogicalAudioSensorPlugin">
  <source>
    <id>1</id>
    <pose>.5 0 0 0 0 0</pose>
    <attenuation_function>linear</attenuation_function>
    <attenuation_shape>sphere</attenuation_shape>
    <inner_radius>1.0</inner_radius>
    <falloff_distance>5.0</falloff_distance>
    <volume_level>.8</volume_level>
    <playing>true</playing>
    <play_duration>10</play_duration>
  </source>
</plugin>

source 子标签速查表

<source> 标签的全部子标签说明如下(完整说明见 LogicalAudioSensorPlugin.hh):

子标签 类型/取值 说明
<id> 整数,≥ 0 声源 ID,用于通过服务操作该声源。必填。同一父实体(model)下所有声源的 ID 必须唯一;不同模型下的声源可以共用相同 ID。ID < 0 为未定义行为
<pose> "x y z roll pitch yaw" 声源位姿,各坐标以空格分隔。可选,默认 {0, 0, 0, 0, 0, 0}。位姿相对于插件父实体:插件在 <model> 内则相对模型位姿,插件在 <world> 内则相对世界(即绝对位姿)
<attenuation_function> linear 衰减函数,字符串不区分大小写。当前唯一可用的取值为 linear;无法识别时将置为 UNDEFINED,此时音量计算返回 -1
<attenuation_shape> sphere 衰减形状,字符串不区分大小写。当前唯一可用的取值为 sphere;无法识别时将置为 UNDEFINED
<inner_radius> 浮点数,≥ 0 衰减形状的内半径。必填。距离小于等于该值的听点,接收到的音量等于声源的发射音量 <volume_level>
<falloff_distance> 浮点数,> 内半径 衰减距离。必填。定义音量衰减为 0 的距离
<volume_level> 浮点数,0.0 ~ 1.0 声源发射音量,0.0 表示 0% 音量,1.0 表示 100% 音量。必填
<playing> true / false 声源是否立即开始播放。必填。true 表示仿真开始即播放,false 表示需要手动通过服务启动
<play_duration> 整数(秒),≥ 0 播放时长。必填。0 表示无限时长播放,直到用户手动调用 stop 服务

参数校验规则

源码 LogicalAudio.cc 中提供了参数校验逻辑,理解这些规则可以避免配置出"静默失效"的声源:

  • validateInnerRadiusAndFalloffDistance(LogicalAudio.cc):内半径若为负则被修正为 0.0;若衰减距离 ≤ 内半径,则被强制修正为 内半径 + 1.0。该函数在 CreateAudioSource 解析 SDF 后立即调用(见 LogicalAudioSensorPlugin.cc)。
  • validateVolumeLevel(LogicalAudio.cc):发射音量会被裁剪到 [0.0, 1.0] 区间,小于 0 置 0,大于 1 置 1。
  • 若声源缺失 id、attenuation_function、attenuation_shape、inner_radius、falloff_distance、volume_level、playing、play_duration 中的任一必填标签,插件会在日志中输出 Skipping the creation of this source. 并跳过该声源的创建(见 LogicalAudioSensorPlugin.cc);pose 缺失时仅告警并使用默认位姿。

音量衰减模型(computeVolume 数学原理)

logical_audio::computeVolume(LogicalAudio.cc)实现了当前唯一的组合:球形衰减形状(SPHERE)+ 线性衰减函数(LINEAR)。设源发射音量为 V0、内半径为 r_inner、衰减距离为 r_falloff,听点与源的距离为 d,则:

  • 声源未播放(playing == false)或发射音量为 0:返回 0.0;
  • 衰减函数或形状为 UNDEFINED:返回 -1.0(非法状态标记);
  • d <= r_inner:接收音量 = V0;
  • d >= r_falloff:接收音量 = 0.0;
  • r_inner < d < r_falloff:按线性插值计算,斜率 m = -V0 / (r_falloff - r_inner),接收音量 V(d) = m * (d - r_inner) + V0。

该实现同样被单元测试 LogicalAudio_TEST.cc 覆盖,测试用例逐一验证了内半径内、内半径处、内外半径之间、衰减距离处、衰减距离之外、未播放、非法函数/形状等多种边界情形。值得注意的是,setAttenuationFunction 与 setAttenuationShape(LogicalAudio.cc)先将输入字符串转为小写再查映射表,因此 "linear"、"LINEAR"、"LiNeA r" 等写法均有效,但带首尾空格(如 " linear"、"sphere ")会被判为无效——这正是示例文件中出现 <attenuation_function> linear</attenuation_function> 这种带空格写法的原因,不过测试表明这会导致 UNDEFINED,因此生产配置中不建议在取值前后加空格。

在 SDF 中定义逻辑麦克风

完整 SDF 示例

以挂载在 green_box 模型上的麦克风为例:

<plugin filename="gz-sim-logicalaudiosensorplugin-system" name="gz::sim::systems::LogicalAudioSensorPlugin">
  <microphone>
    <id>1</id>
    <pose>0 .5 0 0 0 0</pose>
    <volume_threshold>.4</volume_threshold>
  </microphone>
</plugin>

microphone 子标签速查表

<microphone> 标签的全部子标签说明如下(完整说明见 LogicalAudioSensorPlugin.hh):

子标签 类型/取值 说明
<id> 整数,≥ 0 麦克风 ID。必填。同一父实体(model)下所有麦克风的 ID 必须唯一;不同模型下的麦克风可以共用相同 ID。ID < 0 为未定义行为
<pose> "x y z roll pitch yaw" 麦克风位姿,规则与声源的 <pose> 完全相同:相对插件父实体,可选,默认 {0, 0, 0, 0, 0, 0}
<volume_threshold> 浮点数,0.0 ~ 1.0 麦克风可检测的最低音量。可选,默认 0.0。阈值越低,麦克风能"听到"的范围越大

麦克风的判定逻辑 logical_audio::detect(LogicalAudio.cc)为:接收音量小于 0.00001 一律视为不可检测(即使阈值为 0.0 也如此,避免静默状态被误报);否则当接收音量 ≥ 阈值时判定为检测到。

示例世界剖析:四个盒子

示例世界 examples/worlds/logical_audio_sensor_plugin.sdf 定义了 4 个挂载音频对象的盒子模型:red_box 与 blue_box 挂载逻辑音频源,green_box 与 yellow_box 挂载逻辑麦克风。四个模型的完整配置对比如下:

模型 模型位姿 传感器类型 id 传感器位姿(相对模型) 内半径 衰减距离 发射音量/阈值 播放状态
red_box (0, 0, 0.5) source 1 (0.5, 0, 0) 1.0 5.0 0.8 playing,时长 10 秒
blue_box (3, 3, 0.5) source 1 (0, 0, 0) 5.0 100.0 0.6 未播放,时长无限(0)
green_box (0, 2, 0.5) microphone 1 (0, 0.5, 0) — — 阈值 0.4 —
yellow_box (-5, 4, 0.5) microphone 1 (0.5, 0.5, 0.5) — — 阈值 0.3 —

关于 <id> 与 <pose> 的语义,从该世界可以直观验证两点:

  • ID 作用域:red_box 与 blue_box 的源 ID 都是 1,这是合法的——ID 只需要在同一父实体(模型)内唯一。一个模型可以挂多个源/麦克风,各自 ID 必须互不相同。
  • 位姿相对性:源/麦克风的 <pose> 相对其挂载模型的位姿。例如 red_box 模型位姿为 (0, 0, 0.5)(相对世界),其源位姿 (0.5, 0, 0)(相对模型),则源在世界坐标系下的位姿为 (0.5, 0, 0.5)。

另外,blue_box 的 <play_duration> 为 0,表示该源将无限时长播放,除非用户手动调用 stop 服务停止它(源码中 DurationExceeded 对 playDuration.count() == 0 的声源不做超时判定,见 LogicalAudioSensorPlugin.cc)。

音量计算的实战推演

利用前面给出的线性衰减公式,可以手工复现文档中的检测输出,验证对原理的理解:

  • green_box 麦克风听到 red_box 源,音量 ≈ 0.49:green_box 麦克风的世界位姿为 (0, 2.5, 0.5)(模型 (0, 2, 0.5) + 麦克风 (0, 0.5, 0)),red_box 源的世界位姿为 (0.5, 0, 0.5),两者距离 d = sqrt(0.5² + 2.5²) = sqrt(6.5) ≈ 2.5495。因 1.0 < d < 5.0,代入线性衰减公式:V = 0.8 - (0.8 / (5.0 - 1.0)) * (2.5495 - 1.0) ≈ 0.490098,与下文观察到的消息数据 0.4900980486407216 完全一致。
  • green_box 麦克风听到 blue_box 源,音量 = 0.6:blue_box 源世界位姿 (3, 3, 0.5),与 green 麦克风距离 d = sqrt(3² + 0.5²) ≈ 3.041 < 5.0(内半径),因此接收音量直接等于发射音量 0.6。
  • yellow_box 麦克风听不到 red_box 源:yellow 麦克风世界位姿 (-4.5, 4.5, 1.0),与 red 源距离约 6.75 > 5.0(衰减距离),音量为 0。

运行示例世界并观察检测

启动仿真

在终端中运行以下命令启动示例世界:

gz sim logical_audio_sensor_plugin.sdf

启动后可以看到四个彩色盒子悬浮在网格地面上(如上图所示)。

列出检测话题

仿真保持运行,另开一个终端,列出当前可用的话题:

gz topic -l

输出中应包含以下两个检测话题(_1 后缀是 SDF 中为麦克风分配的 ID):

/model/green_box/sensor/mic_1/detection
/model/yellow_box/sensor/mic_1/detection

话题命名规则为 <PREFIX>/mic_<id>/detection,其中 <PREFIX> 是麦克风实体的作用域名(scoped name),<id> 来自 SDF 的 <id> 标签。同理,每个源实体也会生成 <PREFIX>/source_<id>/play 与 <PREFIX>/source_<id>/stop 两个服务(见 LogicalAudioSensorPlugin.hh)。

观察无检测的情况

先观察 yellow_box 的麦克风能否听到任何声音:

gz topic -e -t /model/yellow_box/sensor/mic_1/detection

该命令没有任何输出——这意味着 yellow_box 的麦克风检测不到任何正在播放的声源(red_box 的源距离已超过其 5.0 的衰减距离,blue_box 的源当前未播放)。

观察检测消息与时间戳

接着观察 green_box 的麦克风:

gz topic -e -t /model/green_box/sensor/mic_1/detection

此时会看到类似如下的输出:

header {
  stamp {
  }
  data {
    key: "world/logical_audio_sensor/model/red_box/sensor/source_1"
  }
}
data: 0.4900980486407216

消息类型为 gz.msgs.Double:header.data 中的 key 字段是被检测到声源的完整作用域名(world/logical_audio_sensor/model/red_box/sensor/source_1),data 字段是麦克风位置检测到的音量(0.0 为 0% 音量,1.0 为 100% 音量)。这里 data: 0.49 说明该麦克风听到了 red_box 的源,接收音量约为 49%。

注意此时消息的 stamp 为空——因为仿真尚未开始(处于暂停状态)。点击界面左下角的 play 按钮启动仿真后,检测消息会带上时间戳:

header {
  stamp {
    sec: 8
    nsec: 925000000
  }
  data {
    key: "world/logical_audio_sensor/model/red_box/sensor/source_1"
  }
}
data: 0.4900980486407216

由于 red_box 的源在 SDF 中配置了 <play_duration>10</play_duration>,green_box 检测话题发布的最后一条消息时间戳为 10 秒——10 秒(仿真时间)后该源自动停止播放,不再有新的检测消息。这正是 play_duration 的自动停止机制:源码在 PreUpdate 中计算 当前仿真时间 - 开始播放时间,一旦超过 playDuration 就置 playing = false(见 LogicalAudioSensorPlugin.cc)。

通过服务启停音频源

逻辑音频源可以通过 Gazebo 服务手动启动/停止。仿真运行期间,另开终端执行:

gz service -l

在服务列表中可以看到如下 4 个音频源服务(_1 是 SDF 中为源分配的 ID):

/model/blue_box/sensor/source_1/play
/model/blue_box/sensor/source_1/stop
/model/red_box/sensor/source_1/play
/model/red_box/sensor/source_1/stop

启动 blue_box 的音频源

blue_box 的源在 SDF 中配置为 playing: false,默认不播放。调用其 play 服务启动它:

gz service -s /model/blue_box/sensor/source_1/play --reqtype gz.msgs.Empty --reptype gz.msgs.Boolean --timeout 1000 --req 'unused: false'

回到显示 green_box 麦克风检测输出的终端,可以看到该麦克风开始检测到 blue_box 的源(key 字段中出现 blue_box):

header {
  stamp {
    sec: 255
    nsec: 673000000
  }
  data {
    key: "world/logical_audio_sensor/model/blue_box/sensor/source_1"
  }
}
data: 0.6

同时,yellow_box 的麦克风也能检测到 blue_box 的源(可对其检测话题执行 gz topic -e -t /model/yellow_box/sensor/mic_1/detection 验证)。

移动模型观察音量阈值效果

由于 blue_box 的源配置了 <play_duration>0</play_duration>,它不会自动停止,必须手动调用 stop 服务。在调用 stop 之前,用**变换控制工具(transform control tool)**拖动 blue_box 远离麦克风:当源到达麦克风位置的接收音量低于麦克风的检测阈值(SDF 中的 <volume_threshold>)时,麦克风检测话题将停止发布消息。拖动回来,音量恢复到阈值之上,消息又会恢复发布——这是观察"音量衰减 + 阈值判定"最直观的方式。

停止 blue_box 的音频源

将 blue_box 拖回原位附近,直到看到 green_box 和/或 yellow_box 的麦克风重新发布检测消息,然后调用 stop 服务:

gz service -s /model/blue_box/sensor/source_1/stop --reqtype gz.msgs.Empty --reptype gz.msgs.Boolean --timeout 1000 --req 'unused: false'

此时两个麦克风话题都不再发布新消息——因为当前没有任何声源在播放。

play/stop 服务的幂等性

  • 对已经在播放的源调用 play 服务不会生效:例如 red_box 的源正在播放时再次调用 play,它并不会重新计时 10 秒,仍会在原定的 10 秒节点停止。源码中的处理是:仅当 playInfo.playing 为 false 时才重置 startTime(见 LogicalAudioSensorPlugin.cc)。
  • 对已经停止的源调用 stop 服务同样不会生效。

这些行为也在集成测试 test/integration/logical_audio_sensor_plugin.cc 中得到了验证:测试分别对"播放中的源(id=1)"调用 stop、对"未播放的源(id=2)"调用 play,并确认服务调用后 ECM 中两个源的 playing 状态正确翻转。

测试验证

该插件在仓库中配有完整的单元测试与集成测试,可作为理解行为边界的可靠参考:

小结与进一步阅读

LogicalAudioSensorPlugin 提供了一种轻量、确定性的"声音可听性"仿真手段:通过 <source> 与 <microphone> 两组 SDF 标签即可完成配置,音量随距离按线性函数在球形衰减形状内衰减,检测结果通过话题发布、源启停通过服务控制。它适合用于验证"机器人/传感器在给定布局下能否听到某个声源"这类逻辑判定,而不需要引入真实音频渲染。

本文涉及的关键仓库文件汇总:

登录后查看全文
gz-sim