简介面向海洋生物学、机器人学研究者及Python开发者的石鱼生态环境仿真资源。项目基于Python与ROS Noetic构建通过三维环境建模和物理引擎模拟石鱼伪装、捕食等生物行为及物种交互为研究提供无需实地干预的可视化实验环境。压缩包共223个文件以205个obj三维模型为主体覆盖岩石、植被、水下物体等场景元素另含4个Python脚本、场景文件、ROS launch/yaml配置、说明文档与图片便于快速了解工程结构与启动流程。整包仅1.7MB轻量易用已有175人学习下载。资源完整呈现环境建模、物理模拟、事件驱动及ROS通信等关键实现并提供从水生模型到运行配置的完整闭环既可支撑石鱼行为仿真研究也可作为机器人学与生态模拟交叉领域的Python实践样例尤其适合正在学习强化学习行为建模或ROS仿真集成的学习者对照实践。整体架构清晰文件分类明确便于按模块拆解学习。 先聊个场景一台水下机器人算法模型已经写好控制逻辑也调得八九不离十唯一的问题是——你不能每次都包条船出海测试。天气、潮汐、装备损耗、电池续航任何一个变量都能把实验计划搅黄。这也是SMARC团队维护smarc_stonefish_sims这套仿真环境的原因在没有下水的条件下尽量在电脑里把水下世界复现得足够真实让机器人先在这片虚拟海底把该踩的坑都踩一遍。通俗点说这项目就是用开源模拟器 Stonefish 给水下机器人搭了一套高保真的海底世界模拟系统面向 ROV/AUV 的感知、导航和控制算法验证。核心关键词smarc挪威科技大学智能海事机器人实验室主要做无人船和水下机器人、stonefish一款专为水下机器人设计、基于物理引擎的仿真器、simssimulation三者合起来就是这个仓库的全部使命。如果你是做水下机器人算法、ROS/ROS 2 开发或者刚接触水下仿真想快速入门这篇文章能帮你省下大量查文档的时间。1. 为什么 SMARC 不直接用现成仿真器水下机器人仿真不是新鲜事Gazebo 里也能通过插件模拟浮力和流体阻力。但真要做起来你会发现通用仿真器有几个很难受的短板。1.1 通用物理引擎在水下的失真Gazebo 默认的物理引擎面向地面和空中场景水下环境需要额外写插件去计算浮力、附加质量、流体阻尼、科里奥利力。就算写了效果也通常很粗糙——机器人在水里转个弯姿态变化跟实际完全对不上。而 Stonefish 的内核直接基于 Bullet Physics但浮力模型、推进器推力模型、海流扰动这些都是原生支持相当于把水下动力学这个模块从外挂变成了内建。1.2 声呐传感器的模拟深度不一样水下机器人最依赖的感知设备不是摄像头而是声呐。Gazebo 里你需要自己写声呐插件且多数插件只是返回一个最近障碍距离根本模拟不了多波束声呐的扇形扫描、旁扫声呐的拖鱼轨迹、机械扫描声呐的回波噪声。Stonefish 从底层实现了多种声呐模型返回的是带噪声、带探测角度、带物理衰减的近似真实点云和图像这对验证感知算法至关重要。1.3 海底地形的来源真实测绘数据水下仿真环境的地形不能用平面代替。SMARC 的方案是使用真实海域的测深数据bathymetric data生成地形网格再灌入 Stonefish 世界文件。这个能力通用仿真器很难开箱即用。这一套下来仿真结果才有资格作为出海前的准测试。我是很赞成这种专门工具干专门事的选型逻辑的。水下机器人不是天上飞的无人机流体环境带来的不确定性比空中大得多用一把不够贴合的螺丝刀去拧一个精密螺丝拧花是早晚的事。2. Stonefish 的物理内核与传感器模型它凭什么能骗过算法对一个仿真环境来说如果算法在里面跑完一切正常到真实水域却完全失效那这个仿真就没价值。Stonefish 能撑起 SMARC 这套系统核心在物理和传感器这两个层面做了足够的真实化处理。2.1 流体动力学不是简单加个阻力Stonefish 的浮力计算会考虑到机器人大量的几何面片而不是把整个机器人当一个质点去算浮心。附加质量added mass效应在浅水、近岸场景影响非常大它本质上是机器人加速时带动周围水体一起动的等效质量。如果你忽视附加质量机器人推进器一启动仿真里的加速度会明显快于真实情况。阻尼模型也是关键。Stonefish 支持线性和二次阻尼组合你可以给机器人的纵荡、横荡、垂荡、横摇、纵摇、艏摇分别设置阻尼系数。这套参数一旦从真实机器人的水池实验标定出来仿真里的运动响应就非常可信——这也是 SMARC 在多个 ROV 平台上反复做的事。2.2 声呐模型的多模态Stonefish 支持的主要声呐类型包括机械扫描声呐MSIS常用于小型 ROV 的水下避障传感器逐角度发射声波返回二维极坐标点云。侧扫声呐SSS用于海底测绘仿真里会输出瀑布图。前视声呐FLS实时生成扇形点云适合做目标识别和避障。多波束回声测深仪MBE输出海底地形剖面。成像声呐imaging sonar给水下视觉匹配算法用。每种声呐都有一套噪声模型。MSIS 的输出受波束宽度、海洋噪声、混响影响你在 rviz 里看到的声呐点云不是一根根干净射线而是带毛刺、有缺失的。这才像真实声呐数据。2.3 光学传感器水下光和空气里完全是两回事水下摄像头在仿真里如果只是简单给画面加一个蓝色滤镜那算法验证就毫无意义。Stonefish 模拟了水体对光的吸收和散射不同波长的光在水中衰减差异很大——红光衰减最快蓝绿光穿透最深。所以仿真图像里随着深度增加画面会呈现真实的变蓝变暗效果而不是整体蒙一层蓝色。悬浮颗粒带来的后向散射也做了模拟这会直接影响视觉 SLAM 和物体识别算法的表现。2.4 世界构建的精度Stonefish 的世界文件支持加载高精度网格地形、静态物体和动态物体。SMARC 在实际使用中会把码头、桩腿、管道等典型水下结构物放进仿真场景用来测试机器人的悬停、对接、管线巡检等任务。这些物体同样有物理碰撞属性不是贴图。3. 把 smarc_stonefish_sims 跑起来编译、启动与验证这个仓库本身不是一个从零开始的大工程而是把 Stonefish、ROS 节点、机器人模型、仿真世界文件全部整合起来的一套模板。你只需要把各层依赖准备好然后启动对应 launch 文件。3.1 版本组合选择Stonefish 官方推荐在 Ubuntu 20.04 ROS Noetic 或 Ubuntu 22.04 ROS 2 Humble 下使用。如果你完全没接触过第一优先级推荐 Ubuntu 20.04 ROS Noetic因为 ROS 1 的生态里集成资料最多很多自定义工具都是基于 ROS 1 写的。依赖库主要有这些sudo apt install build-essential cmake ninja-build libboost-system-dev libboost-thread-dev sudo apt install libeigen3-dev libhdf5-dev libopenexr-dev libglew-dev libglfw3-dev sudo apt install libyaml-cpp-dev libopencv-dev libbullet-dev其中libbullet-dev是仿真物理引擎HDF5 是地形数据存储格式的支持库OpenEXR 处理高动态范围图像OpenCV 用于图像处理相关功能GLFW 和 GLEW 支撑仿真器的可视化窗口。3.2 源码编译 Stonefish 本体Stonefish 需要从源码编译虽然编译时间不长但对 CMake 版本有要求建议先把 CMake 升到 3.16 以上。git clone https://github.com/ujjwal-771/Stonefish.git cd Stonefish mkdir build cd build cmake -DCMAKE_BUILD_TYPERelease .. make -j$(nproc) sudo make install编译完成后会出现 libstonefish 的安装目录。此时先测试一下原生仿真器能不能打开stonefish能看到一个水下场景窗口说明物理内核和图形渲染正常。3.3 编译安装 stonefish_rosSMARC 的整套东西跑在 ROS 生态里所以还需要 Stonefish 的 ROS 接口包。cd ~/catkin_ws/src git clone https://github.com/patrosi/stonefish_ros.git cd ~/catkin_ws catkin_make source devel/setup.bash如果遇到缺少std_srvs、visualization_msgs等依赖直接 apt 安装对应的 ros-noetic 包即可。这里需要注意的坑在于stonefish_ros 的主分支和 Stonefish 本体版本要对应不建议一个用最新版一个用旧版容易遇到 API 不匹配的问题。3.4 启动 smarc_stonefish_sims 仿真世界编译通过后先看一眼仓库里的文件夹结构。正常情况下会包含 launch 文件目录、机器人描述目录、世界配置目录和脚本目录。启动流程通常是roslaunch smarc_stonefish_sims world.launch这个 launch 文件会先把 Stonefish 仿真器节点拉起来加载海底地形世界再启动机器人的模型解析和传感器插件。然后再开一个终端启动机器人模型roslaunch smarc_stonefish_sims robot.launch如果正常你会在 Stonefish 的图形窗口里看到一台 ROV 悬浮在模拟海底场景中水面上方可能还有一搜无人艇的模型在巡航。此时在 rviz 里添加机器人模型显示就能看到完整的三维模型和坐标系变换。3.5 验证仿真环境是否健康能不能用不是看到了画面就算数。建议第一步先看一下 TF 树是否完整在终端里运行rosrun tf view_frames生成的 frames.pdf 里map、world、base_link、sonar_link、camera_link这些坐标系必须连成一条完整链路中间不能断开。很多情况下模型不动不是控制没收到指令而是 TF 树断裂导致坐标变换找不到路。第二步检查声呐话题是否在输出rostopic hz /sonar/msis_points实际运行中频率在 1~5 Hz 之间是正常的。如果话题长时间没有数据大概率是世界文件里声呐传感器的挂载坐标系配置有问题。4. 接入 ROS 生态从话题流到自主导航闭环仿真界面跑起来只是第一步这套环境最大的价值是可以挂上你自己的自主导航和控制算法。4.1 关键话题和 TF 设计SMARC 这套仿真环境里机器人的运动控制通常接口为一个速度指令话题。对 ROV 来说一般是一条cmd_vel话题接收geometry_msgs/Twist消息承载线速度x、y、z和角速度roll、pitch、yaw六个自由度的控制量。在仿真内部这些指令会被转换为推进器推力再经过流体动力学模型计算出机器人的实际加速度。感知相关话题包括水下相机图像、声呐点云、IMU 数据、深度计数据、DVL 数据。这些话题的数据格式和真实传感器完全一致意味着你不需要为仿真环境单独写一套感知处理代码可以用与真机相同的算法来处理仿真数据。4.2 让仿真里的 ROV 动起来我能想到最快验证闭环的方式发一条速度指令给 cmd_vel观察 rviz 中的模型位置变化是否平顺。rostopic pub /cmd_vel geometry_msgs/Twist linear: x: 0.5 y: 0.0 z: 0.2 angular: x: 0.0 y: 0.0 z: 0.3这一下给了一个前向 0.5 m/s、下沉 0.2 m/s、同时向左转 0.3 rad/s 的指令。真实 ROV 在这种指令下会有轻微的耦合运动出现——比如前向加速时因为重心和浮心不完全重合导致纵倾变化。如果仿真里你观察到这种耦合说明流体模型起作用了如果机器人完全笔直地前进可能某个方向的阻尼参数被设成了无穷大或没有正确加载。4.3 用仿真环境做路径规划测试一个经典的验证场景是让 ROV 在仿真世界里走一条甬道巡检路线。你可以用 move_base 配置一个适用于水下环境的局部规划器然后给一个目标点。由于声呐点云存在噪声规划器必须在点云中正确识别出障碍边界。仿真环境的价值就体现在这里你可以完全可重复地调整声道噪声强度、障碍物位置、海流方向验证规划器的鲁棒性这在真实海洋里几乎不可能做到。实际测试中我会建议你把噪声参数设到比真实环境更恶劣的程度来做压力测试。如果规划器在这个恶劣条件下还能稳定避开障碍出海测试时你的底气就足得多。5. 二次开发换地图、加传感器、改 ROV 模型跑通人家的 demo 只是起点真正要为自己的项目服务一定会涉及二次开发。5.1 换一个自己的海底地图Stonefish 的地形数据通常是 HDF5 格式的网格数据。你可以从公开的测深数据源下载某一海域的 elevation 数据然后转成 Stonefish 需要的格式。仓库里通常会有一个脚本目录里面应该有处理地理栅格数据的 Python 脚本将 GeoTIFF 转为 HDF5。这一步的常见坑是坐标单位和分辨率。测深数据如果是以经纬度存储你需要转成合适的米制坐标分辨率过高会导致仿真加载极慢建议先粗采样一次确认地形大致形状后再逐步提高精度。5.2 添加一个自定义传感器想在机器人上加一个探测水温的传感器流程是在机器人描述文件中加一个 link 和 joint然后在 Stonefish 世界文件中挂载一个温度传感器插件再把数据发布到自定义话题上。整个过程不需要改 Stonefish 核心代码完全是配置驱动这也是这个仿真器设计的最大优势。一个实际案例SMARC 在研究水下机械臂抓取时给 ROV 加了一个机械臂模型并在机械臂末端挂了力和力矩传感器。这样可以在仿真里测试接近目标物体时的接触力控制算法实现在真实水下环境很难进行的初版调参。5.3 修改 ROV 的动力学参数关于动力学参数我建议以一份真实 ROV 的标定数据为基准。如果你没有条件做水池实验至少参考同类型机器人的经验参数。阻尼系数矩阵、附加质量矩阵这两个关键矩阵对运动响应的影响最直接在仿真里调试时不要两个矩阵同时乱改先锁定一个调另一个否则出了问题根本不知道是哪个参数引起的。6. 实测踩坑与性能调优经验最后这部分我把实际操作中碰到的、且最影响效率的问题集中列出来希望你能绕过。6.1 图形渲染的黑屏与白屏问题Stonefish 本体依赖 OpenGL 渲染场景不少人第一次启动会遇到图形窗口黑屏或者白屏。排查顺序是检查显卡驱动glxinfo | grep OpenGL是否输出正常字符串。确认环境变量LIBGL_ALWAYS_SOFTWARE1是否被误设置这个变量会强制软件渲染帧率极低且可能显示异常。在虚拟机里运行做不了硬件加速3D 渲染基本不可用。建议在物理机上装 Ubuntu。如果只是做算法验证不关心可视化可以不依赖图形界面运行Stonefish 的场景加载同样支持无头模式这在批量跑实验时非常有用。6.2 声呐参数调得像不像真声呐声呐噪声参数调太高目标被淹没在噪声里无法识别调太低算法在仿真里跑得飞起一到真实环境立刻失效。我自己的经验值是从 Stonefish 官方示例提供的参数开始逐步增大噪声方差在仿真里测试感知算法直到它开始出现偶发误检为止然后取这个临界值的八成作为最终参数。这个留余量的调法基本可以保证算法到真实环境不会直接不工作。6.3 仿真速度变慢的三大原因地形网格面片数量过大。把地形分辨率降到 1 m 或 2 m 一格的量级对机器人感知来说足够用角色性能却明显提升。声呐更新频率设置过高。相比视觉传感器声呐的计算量非常大把更新频率从 10 Hz 降到 2 Hz视觉上几乎看不出区别性能却有显著改善。多台仿真器同时跑。如果你需要跑多机器人协同建议用分布式部署而不是一台电脑上开多个 Stonefish 实例。6.4 Docker 容器的使用建议SMARC 仓库里大概率提供了 Dockerfile封装好所有依赖环境。如果你不想污染宿主机环境使用 Docker 是明智选择。但要注意的是Docker 容器内跑图形界面需要配置 X11 转发跑 GPU 加速渲染需要配置 NVIDIA Container Toolkit。如果只做算法验证容器内不建议开可视化把数据话题引到宿主机上的 rviz 里看就行性能和稳定性都更好。我的个人习惯是宿主机只装一个 rviz 用于数据可视化仿真计算全部跑在容器里。这样无论我怎么捣鼓容器的依赖环境都不会影响宿主机的开发环境也方便把整套环境打包复制给其他同事。另外一个小建议仿真 pid 调参时记录下每组参数对应的机器人响应曲线。这套数据不仅对仿真有用出海前也可以参考来设定真实控制器的初值。毕竟仿真的最终目的不是把仿真做到百分之百真实而是在出海之前把所有能提前验证的问题都提前解决掉。本文还有配套的精品资源点击获取