WWW-POSIM v0.6.16仿真器文档
文档菜单
WWW-POSIM / 仿真器文档

自定义世界

世界 SDF 定义仿真环境。应以所选地形导出的文件为基础,其中包含地形引用、地理原点和引擎所需的系统。

下载并应用世界文件

  1. 选择已就绪的固定范围地形和载具,打开启动前检查页面。
  2. 展开编辑 SDF 文件 → 下载世界 SDF,保存 world.sdf 的副本。
  3. 编辑支持的物理或照明字段。保留地形模型、路径、世界名称和地理原点。
  4. 选择上传修改后的世界 SDF。验证通过的新修订版会出现在世界配置中并自动选中。
  5. 启动世界。地形和载具准备完成后会应用设置。检查物理步长、实际运行速度和照明。

文件与其来源地形修订版绑定。更换地形后,应下载新地形的文件并重新应用设置。选择地形默认配置可恢复初始设置。支持最大 1 MB 的 .world 或 .sdf 文件。此流程适用于不计分的固定世界;按需地形和计分挑战使用各自指定的设置。

支持的设置

SDF 段落 参数与单位
physics / max_step_size 积分间隔,0.001–0.03 s。减小步长会增加计算量。
physics / real_time_factor 请求的仿真时间与实际时间之比,大于 0 且不超过 10。实际结果取决于 CPU/GPU 能力。
gravity 加速度向量,单位 m/s²;标准值为 0 0 -9.81。
magnetic_field 世界磁场向量,单位为特斯拉。
scene 环境光、背景色、阴影、网格和原点显示;颜色采用 RGBA。
light 最多 32 个具名平行光、点光源或聚光灯;可设置位姿、方向、颜色、衰减和聚光角度,角度以弧度计。
wind / linear_velocity SDF 标准风速,单位 m/s。海洋波浪和海流模型有独立的控制及物理含义。

完整模式见 SDFormat 规范。上传会保留地形和必要系统,仅应用支持的世界设置;不会安装插件、下载外部模型或替换地理地形。波浪与海流在场景面板中配置,对载具的作用见海洋动力学与渲染。

预生成地形模板

下载 KMOU world.sdf。完整示例使用 KMOU 地形,展示支持的世界设置。地形网格和影像仍位于地形文件包中,可从工作区下载。

kmou.world
<?xml version='1.0' encoding='utf-8'?>
<sdf version="1.4">
  <!--
    此地形版本的世界配置。请保留世界名称、地形资源、地理原点和必需系统。可在启动确认界面上传支持的环境设置。
  -->
  <world name="wwos_gebco">
    <!--
      场景显示设置:ambient 和 background 使用 RGBA 颜色,shadows、grid、origin_visual
      控制对应显示。导出的天空设置等字段是否支持上传,请参阅世界设置表。
    -->
    <scene>
      <ambient>0.01 0.01 0.01 1.0</ambient>
      <sky>
        <clouds>
          <speed>12</speed>
        </clouds>
      </sky>
      <shadows>1</shadows>
      <background>0.7 0.8 0.9 1</background>
      <grid>false</grid>
      <origin_visual>false</origin_visual>
    </scene>
    <!--
      物理时间设置:max_step_size 是积分步长(秒),real_time_factor 是请求的仿真时间与实际时间之比。name
      只是名称,并不决定步长。实际速度取决于可用的 CPU/GPU 性能。
    -->
    <physics name="1ms" type="ignored">
      <max_step_size>.02</max_step_size>
      <real_time_factor>1.0</real_time_factor>
    </physics>
    <!--
      引擎插件。filename 指定已安装的库,name 指定具体实现。上传数值修改时请保留这两个字段;SDF 文件本身不会安装插件。
    -->
    <!--
      执行刚体动力学与接触计算。请保留此必需的世界系统。
    -->
    <plugin filename="gz-sim-physics-system" name="gz::sim::systems::Physics">
    </plugin>
    <!--
      引擎插件。filename 指定已安装的库,name 指定具体实现。上传数值修改时请保留这两个字段;SDF 文件本身不会安装插件。
    -->
    <!--
      提供修改运行中场景的 Gazebo Transport 命令。工作区的场景操作需要此系统。
    -->
    <plugin filename="gz-sim-user-commands-system" name="gz::sim::systems::UserCommands">
    </plugin>
    <!--
      引擎插件。filename 指定已安装的库,name 指定具体实现。上传数值修改时请保留这两个字段;SDF 文件本身不会安装插件。
    -->
    <!--
      发布场景结构与位姿,供查看器显示仿真。
    -->
    <plugin filename="gz-sim-scene-broadcaster-system" name="gz::sim::systems::SceneBroadcaster">
    </plugin>
    <!--
      引擎插件。filename 指定已安装的库,name 指定具体实现。上传数值修改时请保留这两个字段;SDF 文件本身不会安装插件。
    -->
    <!--
      渲染相机图像和 GPU 射线传感器数据。render_engine 选择已安装的渲染后端;请保留当前引擎导出的值。
    -->
    <plugin filename="gz-sim-sensors-system" name="gz::sim::systems::Sensors">
      <render_engine>ogre2</render_engine>
    </plugin>
    <!--
      引擎插件。filename 指定已安装的库,name 指定具体实现。上传数值修改时请保留这两个字段;SDF 文件本身不会安装插件。
    -->
    <!--
      自定义 DVL 传感器所需的世界系统。波束与跟踪参数在载具 SDF 中配置。
    -->
    <plugin filename="gz-sim-dvl-system" name="gz::sim::systems::DopplerVelocityLogSystem">
    </plugin>
    <!--
      地形的地理原点。纬度、经度和航向使用度,高程使用米。ENU 表示东、北、天坐标系。请保留这些值,使地图、地形和 GNSS 保持对齐。
    -->
    <spherical_coordinates>
      <surface_model>EARTH_WGS84</surface_model>
      <world_frame_orientation>ENU</world_frame_orientation>
      <latitude_deg>35.077175</latitude_deg>
      <longitude_deg>129.085815</longitude_deg>
      <elevation>0</elevation>
      <heading_deg>0</heading_deg>
    </spherical_coordinates>
    <!--
      光源。type 选择平行光、点光源或聚光灯;pose 设置位姿,direction 设置光线方向向量。diffuse/specular 使用 RGBA
      颜色,cast_shadows 控制是否投射阴影。
    -->
    <light type="directional" name="sun1">
      <!--
        位姿:x y z 的单位为米,随后 roll pitch yaw 的单位为弧度。未指定 relative_to 时,以父级坐标系为参考。
      -->
      <pose>50 0 150 0 0 0</pose>
      <diffuse>1 1 1 1</diffuse>
      <specular>.1 .1 .1 1</specular>
      <direction>0.3 0.3 -1</direction>
      <cast_shadows>false</cast_shadows>
    </light>
    <!--
      光源。type 选择平行光、点光源或聚光灯;pose 设置位姿,direction 设置光线方向向量。diffuse/specular 使用 RGBA
      颜色,cast_shadows 控制是否投射阴影。
    -->
    <light type="directional" name="sun_diffuse">
      <!--
        位姿:x y z 的单位为米,随后 roll pitch yaw 的单位为弧度。未指定 relative_to 时,以父级坐标系为参考。
      -->
      <pose>-50 0 -150 0 0 0</pose>
      <diffuse>0.6 0.6 0.6 1</diffuse>
      <specular>0 0 0 1</specular>
      <direction>-0.3 -0.3 -1</direction>
      <cast_shadows>false</cast_shadows>
    </light>
    <!--
      光源。type 选择平行光、点光源或聚光灯;pose 设置位姿,direction 设置光线方向向量。diffuse/specular 使用 RGBA
      颜色,cast_shadows 控制是否投射阴影。
    -->
    <light type="directional" name="sun_diffuse_1">
      <!--
        位姿:x y z 的单位为米,随后 roll pitch yaw 的单位为弧度。未指定 relative_to 时,以父级坐标系为参考。
      -->
      <pose>-100 500 -20 0 0 0</pose>
      <diffuse>0.8 0.8 0.8 1</diffuse>
      <specular>1 1 1 1</specular>
      <direction>-1 -1 0</direction>
      <cast_shadows>false</cast_shadows>
    </light>
    <!--
      光源。type 选择平行光、点光源或聚光灯;pose 设置位姿,direction 设置光线方向向量。diffuse/specular 使用 RGBA
      颜色,cast_shadows 控制是否投射阴影。
    -->
    <light type="directional" name="sun_diffuse_2">
      <!--
        位姿:x y z 的单位为米,随后 roll pitch yaw 的单位为弧度。未指定 relative_to 时,以父级坐标系为参考。
      -->
      <pose>-150 -130 50 0 0 0</pose>
      <diffuse>0.6 0.6 0.6 1</diffuse>
      <specular>0.2 0.2 0.2 1</specular>
      <direction>0.5 0.5 -1</direction>
      <cast_shadows>false</cast_shadows>
    </light>
    <!--
      引擎插件。filename 指定已安装的库,name 指定具体实现。上传数值修改时请保留这两个字段;SDF 文件本身不会安装插件。
    -->
    <plugin filename="gz-sim-buoyancy-system" name="gz::sim::systems::Buoyancy">
      <!--
        用于浮力计算的分层流体密度,单位为 kg/m^3。default_density 应用于分界面以下,above_depth 指定密度变化的高度。本例分界面为 z=0。
      -->
      <graded_buoyancy>
        <default_density>1025</default_density>
        <density_change>
          <above_depth>0</above_depth>
          <density>1</density>
        </density_change>
      </graded_buoyancy>
    </plugin>
    <!--
      模型结构:link 定义刚体,joint 连接刚体,plugin 提供仿真功能。模型、连杆和关节名称必须与导出的控制器配置保持一致。
    -->
    <model name="gebco_terrain">
      <!--
        静态模型不会因重力或接触力而运动。地形保持静态,载具连杆则参与动力学计算。
      -->
      <static>true</static>
      <!--
        刚体及其局部坐标系。该连杆的几何形状、质量属性和传感器作为整体运动。
      -->
      <link name="terrain">
        <!--
          物理引擎使用的碰撞几何体。尺寸和位置应与船体一致;简化形状可减少碰撞计算量。
        -->
        <collision name="gebco_collision">
          <geometry>
            <!--
              网格文件及可选的各轴缩放比例。请保留导出的资源路径和配套文件;scale 会乘到网格坐标上。
            -->
            <mesh>
              <uri>terrain.dae</uri>
            </mesh>
          </geometry>
        </collision>
        <!--
          用于渲染和相机成像的可见表面。修改外观不会自动调整碰撞形状或质量。
        -->
        <visual name="seabed">
          <geometry>
            <!--
              网格文件及可选的各轴缩放比例。请保留导出的资源路径和配套文件;scale 会乘到网格坐标上。
            -->
            <mesh>
              <uri>terrain-visual.dae</uri>
            </mesh>
          </geometry>
          <!--
            表面外观。RGBA 颜色与 PBR 纹理影响渲染。请保留地形纹理路径及导出的资源;材质设置不会自动改变质量或摩擦。
          -->
          <material>
            <ambient>0.6 0.6 0.6 1</ambient>
            <diffuse>1 1 1 1</diffuse>
            <specular>0.03 0.03 0.03 1</specular>
            <pbr>
              <metal>
                <albedo_map>/home/docker/wwos-data/terrain/fd128f89b979e7830a34dcd7/seabed-sand-diff-1803d7e2861b304b.jpg</albedo_map>
                <roughness>1</roughness>
                <normal_map>/home/docker/wwos-data/terrain/fd128f89b979e7830a34dcd7/seabed-sand-nor_gl-0f35185b7225fe20.jpg</normal_map>
                <roughness_map>/home/docker/wwos-data/terrain/fd128f89b979e7830a34dcd7/seabed-sand-rough-318b440c109de741.jpg</roughness_map>
                <metalness>0</metalness>
              </metal>
            </pbr>
          </material>
        </visual>
        <!--
          用于渲染和相机成像的可见表面。修改外观不会自动调整碰撞形状或质量。
        -->
        <visual name="land">
          <geometry>
            <!--
              网格文件及可选的各轴缩放比例。请保留导出的资源路径和配套文件;scale 会乘到网格坐标上。
            -->
            <mesh>
              <uri>terrain-visual-land.dae</uri>
            </mesh>
          </geometry>
          <!--
            表面外观。RGBA 颜色与 PBR 纹理影响渲染。请保留地形纹理路径及导出的资源;材质设置不会自动改变质量或摩擦。
          -->
          <material>
            <ambient>0.6 0.6 0.6 1</ambient>
            <diffuse>1 1 1 1</diffuse>
            <specular>0.03 0.03 0.03 1</specular>
            <pbr>
              <metal>
                <albedo_map>/home/docker/wwos-data/terrain/fd128f89b979e7830a34dcd7/land-satellite-eb6fd1423859d847a276a4db49db6db51a61fe8965171639c94f8d3df66e0199.png</albedo_map>
                <roughness>1</roughness>
                <metalness>0</metalness>
              </metal>
            </pbr>
          </material>
        </visual>
      </link>
    </model>
    <!--
      引擎插件。filename 指定已安装的库,name 指定具体实现。上传数值修改时请保留这两个字段;SDF 文件本身不会安装插件。
    -->
    <plugin filename="gz-sim-imu-system" name="gz::sim::systems::Imu" />
    <!--
      引擎插件。filename 指定已安装的库,name 指定具体实现。上传数值修改时请保留这两个字段;SDF 文件本身不会安装插件。
    -->
    <plugin filename="gz-sim-magnetometer-system" name="gz::sim::systems::Magnetometer" />
    <!--
      世界重力向量 x y z,单位为 m/s^2。在此 ENU 世界中,z 的负方向朝下。
    -->
    <gravity>0 0 -9.81</gravity>
    <!--
      世界磁场向量 x y z,单位为特斯拉,用于磁力计仿真。
    -->
    <magnetic_field>5.64e-6 2.29e-5 -4.2e-5</magnetic_field>
    <!--
      标准 SDF 风速,单位为 m/s。力模型需要使用此值才会影响运动。波浪和海流请通过各自的场景控件配置。
    -->
    <wind>
      <linear_velocity>0 0 0</linear_velocity>
    </wind>
  </world>
</sdf>

此示例来自 Linux 引擎。应使用自己的主机导出的文件,尤其在 macOS 上,以确保插件库与安装环境匹配。

使用自己生成的地形

生成并选择自己的地形,在启动检查页面下载其 SDF。导出文件包含正确的模型路径和地理原点,应在该文件中重新应用物理或照明修改。

如需保存可迁移副本,同时下载地形 ZIP,并将世界文件与相对路径引用的资源一起保存。世界 SDF 控件将设置应用到对应的已保存地形,不会导入 ZIP 内的地形。请先通过地形准备流程创建或恢复地形。

长时间运行前进行比较

对比测试应使用相同的载具、初始位置和传感器。检查时间步长、实时因子、光源方向、相机和载具运动。请求更高倍率不保证更快的渲染或传感器接收。保留原始文件,以便恢复默认配置或上传旧副本。

性能与显示

实时因子(RTF)表示每实际秒推进的仿真秒数。请求速度是目标;RTF 小于 1 表示当前负载下运行慢于实时。物理步长影响接触、波浪、传感器时序和控制稳定性;网络延迟影响指令和画面传输。超过 1× 时隐藏实时 AIS。显示更新还受相机频率限制。

修改步长后,应使用两种内置载具检查静止、转弯、通行间距、潜航和返回。

视图 渲染器
传感器图像 引擎主机上的 Gazebo
个人载具/世界视图,选择浏览器时 浏览器 GPU
个人载具/世界视图,选择 Gazebo 时 引擎主机上的 Gazebo;桌面应用默认设置
公共 LIVE 的载具/世界视图 Gazebo 观察相机

先减少不必要的相机、更新频率和分辨率。浏览器照明控制天空、反射、色调映射和水面法线;波浪几何使用物理模型的采样。

在同一场景比较图形诊断:FPS、帧耗时第 95 百分位、绘制调用、三角形数量、纹理和几何使用量。移动地形会简化远处的可视几何,见地形生成流程与算法。碰撞和传感器有独立开销。即使选择浏览器场景,载具相机和 GPU 激光雷达仍由 Gazebo 处理,应分别比较视频 FPS、传感器 Hz 和物理 RTF。

评估硬件时应固定世界、载具、传感器频率和目标速度,从一个会话开始逐步增加数量,并包含地形准备的负载峰值。测量 RTF 中位数和第 5 百分位、物理步耗时、相机接收频率与数据年龄、CPU、内存、GPU 和显存。物理计算依赖单核性能,地形和传感器也会使用多核。更多相机和更高分辨率会增加 GPU 负载。公共航行的观众共享一个世界。

Apple Silicon 使用 Metal。Ubuntu 和 Windows/WSL 的 Docker 引擎需要与镜像兼容的驱动和运行环境。LIVE 不消耗个人时长;模型、上传文件和缓存受存储额度限制。请为引擎和模型下载预留空间。另见账号与使用时长。

搜索文档