简介：面向机器人、生物学仿真与Python开发者的石鱼生态环境模拟项目，基于ROS Noetic分支构建，可在虚拟三维场景中还原石鱼行为、环境互动及多物种交互，涉及环境建模、物理模拟、行为算法、事件驱动与多线程等技术点，适用于生态研究、算法验证与教学演示。压缩包共收纳223个文件，以205个obj三维模型为主体，辅以Python脚本、场景文件、启动配置文件、图片、yaml参数与csv数据，整体仅1.7MB，轻量便于部署测试。目前已有179人学习浏览，适合科研入门与算法验证。内容既有藻类、锚链等场景资产与launch启动文件，又有可参考的源码和文档，能够展示如何组织三维模型、配置物理引擎、编写行为控制脚本并利用ROS话题通信整合模块，帮助读者快速搭建完整仿真流程。整体融合计算机科学、生物学与机器人学知识，对研究智能体模拟、机器人仿真及生态建模均有实用价值。

1. 石鱼的世界模拟：一个能跑水下机器人算法的数字海底世界

如果你做过水下机器人，大概率有过这种体验：算法在电脑上跑得挺正常，一下水就开始乱飘，光线、浮力、暗流全在跟你作对。石鱼的世界模拟这个项目，解决的正是“下水前先跳水”的问题。它用物理引擎搭了一个能反复进入的海底仿真世界，任何一台普通 Linux 电脑都可以把 AUV 放进海里，用 Python 脚本设定地形、布设礁石、挂载相机和声呐，再让机器人自主绕障、下潜、返航。做控制与感知的人，可以用它验证多传感器融合和视觉识别；做系统集成的人，可以用它调试 ROS 话题链路。这篇文章会从技术选型、核心代码、运行步骤到二次开发，把整个仓库的实际玩法完整过一遍。

2. 技术选型与整体架构：Python、ROS 与物理引擎的三层咬合

石鱼这套模拟器没有选择“自己再造一个机器人中间件”，而是把自己定位成补短板的一层：底层是 C++ 写的物理仿真内核，负责刚体解算、碰撞检测、流体阻力和声学传播；中间是一层 Python 绑定，把世界搭建、模型加载、传感器配置全部暴露给脚本；上层再用 ROS 包装成节点和话题，让原本跑在真机上的控制程序不大改就能接进来。

这套“C++ 内核 + Python 布景 + ROS 通信”的结构，在源码里可以直观看到三个层次：engine是引擎本体，python是脚本接口和世界脚本，bridge是 ROS 桥接。理解这个分层，后面改场景和加传感器时就不会动错文件。

2.1 为什么把世界写成 Python 脚本，而不是 C++ 插件

很多人第一眼看到高性能仿真项目，会下意识认为“性能敏感的部分必须写成插件”。但石鱼的开发思路恰好相反：它把世界搭成可回放、可编辑、可参数化的脚本，而不是在 C++ 里硬编码场景。原因很现实：水下试验场地条件经常要改，换一套地形、改一个洋流方向，如果每次都要重编译一个插件，一轮调参就得耗掉大半天；写成 Python 以后，改一个depth_offset就是改一行配置，重新运行就能看到效果。

我一般在实验里会把海盆深度、能见度、水流速度、障碍物位置都抽成 Python 字典，再交给create_world()这类入口函数。好处是测试矩阵能自动化：固定机器人模型不动，遍历三组海流强度，第二天上班就能拿到对比曲线。对于蒙特卡洛类的算法验证来说，脚本化世界配置比 C++ 插件友好一个量级。

Python 侧在项目里承担的职责主要有三块。第一块是场景描述，决定在哪放什么物体；第二块是传感器配置，包含相机数量、安装位置、分辨率和视角；第三块是 ROS 桥接，决定每个传感器对应哪个话题名和发布频率。物理模拟本身仍由内核负责，Python 不会参与刚体力学计算，所以性能瓶颈不会因为在布景层用了脚本而明显放大。

2.2 目录结构：场景、模型、launch、脚本各管一段

拿到源码后第一件事是扫目录。这个布局不算复杂，但分层很干净，我简单给一张职责表：

我最喜欢的地方在于，仿真世界的逻辑和可视化是分开的。engine/core里没有任何具体海区相关的代码，python/worlds里一个文件就是一个世界。想新增一片试验海域，多半只需要复制worlds/bay_demo.py，改一下地形高度图、物体坐标和洋流方向，物理内核不需要碰一行。

2.3 运行链路：从推进器命令到声呐点云，数据是怎么流转的

仿真跑起来之后，数据流大概是这么走的：用户脚本先生成控制命令，交给推进器模型，转化为力和力矩；物理内核更新刚体位置和速度；随后传感器回调读取当前状态，生成图像帧和声呐点云；ROS 桥接再把数据发布到指定话题；下游算法节点消费数据，计算新的期望推力，转回给脚本。每一步对应一个仿真步进。

while sim.is_running(): control = controller.get_latest_command() auv.apply_thruster(control) sim.step() ros_bridge.publish(auv.imu) ros_bridge.publish(auv.camera)

这段代码看起来简单，但里面藏着一个容易踩坑的点：仿真时间由sim.step()推进，而不是由time.sleep()推进。step()每次前进一个固定time_step，比如 0.01 秒；而传感器发布频率是在这个话题内部按步数折算的。如果脚本里额外用了sleep，就会导致 ROS 时间戳和物理仿真时间错位，严重时 TF 树会跳变。

参数配合上有几个默认关系需要注意。time_step=0.01意味着 100 次步进等于 1 秒仿真时间；real_time_factor=1.0表示尽量贴近真实时间推进，但渲染能力不够时它会被迫降速。相机默认按每个仿真步进计算一次，相当于 100Hz 初始频率；声呐这类计算量大的传感器通常会隔 N 步采样一次，项目里常见的是每 5 步一次，也就是 20Hz。实际测试时，rostopic hz看到的话题频率会略低于理论值，因为渲染和刚体解算也需要时间。

3. 核心模块拆解：从空海盆到能出数据的仿真世界

这一章讲的是一套最基础也最完整的流程：先建一个海底世界，再放进一台 AUV，挂上相机和声呐，最后把仿真跑起来。对应到项目里，就是一个完整的bay_demo.py世界脚本。

3.1 创建世界与海底地形

第一步是创建仿真器实例，设置步长和重力，再注册一个空海盆。代码如下：

from pyengine import Simulator, World from pyengine import Vector, Terrain sim = Simulator() sim.set_time_step(0.01) # 每个物理步进 10ms sim.set_real_time_factor(1.0) # 尽量按真实时间推进 world = World("bay") world.set_gravity(Vector(0, 0, -9.81)) world.set_fluid("seawater", density=1025.0, temperature=15.0) terrain = Terrain( heightmap="assets/seabed_height.png", # 高度图，灰度值代表深度 size=Vector(120, 120, 0), # 海盆尺寸，单位米 texture="assets/sand.png" # 海底纹理 ) world.add_object(terrain) sim.load_world(world)

这段代码的关键点是：高度图不是一张普通贴图，它的每个像素灰度会被转成海底高度，形成真实起伏的地形。size决定海盆的物理范围，z=0表示水平面。density=1025.0是海水密度，直接影响浮力计算；如果你把机器人换到淡水环境，这里应改成998.0，否则生成模型受到的浮力会偏大。

3.2 给 AUV 挂载相机和声呐

海盆建好后，加载 AUV 模型并挂传感器。模型文件通常是 URDF，同时配套 mesh 目录。

auv = world.load_vehicle( "models/auv.urdf", pose=Vector(0, 0, -8) # 从海面下 8 米处启动 ) camera = auv.attach_sensor( "camera", topic="camera/image_raw", width=640, height=480, fov=1.2, # 水平视场角，单位弧度 enable=True ) sonar = auv.attach_sensor( "scan_sonar", topic="sonar/scan", range_min=0.2, range_max=30.0, beams=256, # 每条扫描线的波束个数 update_rate=20 )

相机挂在 AUV 的camera坐标框架下，fov=1.2换算成角度约 68 度，属于水下机器人常用的宽视角配置。声呐是成像声呐，beams=256表示一次扫描生成 256 个波束的强度剖面，range_max=30意味着只能探到 30 米内的目标。这里要注意，传感器话题名一旦确定，后续 ROS 节点就必须按这个名字订阅；改话题名时最好在配置里统一维护，不要硬编码到多个脚本里。

3.3 让仿真跑起来：步进循环与速度控制

传感器挂好后，真正驱动控制逻辑的是下面这套循环：

auv.set_controller_mode("velocity") target = Vector(1.0, 0.0, 0.0) # 期望前进速度 1m/s auv.set_velocity_target(target, angular=Vector(0, 0, 0)) for step in range(10000): sim.step() if step % 50 == 0: pose = auv.get_pose() print("sim_time", sim.get_time(), "depth", pose.z, "yaw", auv.get_rpy().z)

set_controller_mode的作用是把推进器控制权交给内置速度控制器。常见模式有两种：velocity模式让它跟踪线速度和角速度目标；direct模式则直接给每个推进器单独设推力值。做控制算法验证时常倾向用direct模式，这样可以绕开内置控制器，完全复现你在真实电机上算出来的输出。

步进循环里的step % 50意思是每 50 步打印一次，对应 0.5 秒仿真时间输出一条日志。通过日志能明显看到：如果机器人初始位置定深不够稳，前几百步深度值会上下波动，这是正常现象，因为仿真开始时浮力和重力之间存在过渡过程。

3.4 一级参数速查表

项目里每个场景脚本顶部的参数，基本可以总结成下面这张表：

调整这些参数时要记住一个约束：缩小time_step和增大beams同时做，仿真速度会急剧下降。我自己的经验是先调好的参数组合跑一次基准测试，再动其中一项，这样才能定位性能损失的来源。

4. 从零跑通：下载、编译、启动与验证

这一章面向第一次拿到源码的开发者，按步骤走就能把默认海盆场景跑起来。

4.1 环境准备与编译

项目依赖的基础环境是 Ubuntu 20.04、ROS Noetic、Python 3.8 和 CMake。核心物理内核需要 Eigen 和 GLFW 做矩阵运算和渲染窗口。安装命令如下：

sudo apt update sudo apt install build-essential cmake python3-dev python3-pip \ ros-noetic-desktop libeigen3-dev libglfw3-dev # 把源码放进 catkin 工作区 mkdir -p ~/catkin_ws/src cp -r /path/to/source ~/catkin_ws/src/sim_src cd ~/catkin_ws catkin_make source devel/setup.bash

编译结束后，必须source devel/setup.bash，否则 ROS 找不到新生成的可执行文件。如果你没有用 catkin 工作区，只做纯 Python 运行，也可以把python目录直接加进PYTHONPATH，但传感器话题发布功能会连不上 ROS，所以还是推荐完整编译。

4.2 启动一个基础海盆场景

先启动 ROS 主节点，再运行世界脚本。两个命令需要分别在两个终端执行：

# 终端 1 roscore # 终端 2 source ~/catkin_ws/devel/setup.bash python3 python/worlds/bay_demo.py

脚本启动后，会出现一个仿真窗口，显示海底高度图和 AUV 位姿。如果只看到一片蓝色而没有地形，优先检查高度图路径是否正确。项目里通常用相对路径写资源，但直接从别的目录执行 Python 时，相对路径会失效，导致高度图和纹理加载失败。

4.3 通过 ROS 话题验证相机与声呐输出

另一个终端下，用rostopic查看话题列表和发布频率：

source ~/catkin_ws/devel/setup.bash rostopic list rostopic hz /camera/image_raw rostopic echo /sonar/scan

rostopic list能看到camera/image_raw和sonar/scan出现在列表中。rostopic hz会统计相机图像话题的发布时间间隔，正常应该在 20Hz 到 30Hz 左右，低于 10Hz 说明实时因子或传感器参数拖慢了渲染。rostopic echo显示声呐扫描数据，如果数据里的距离全部是inf，说明声呐前方没有可探测目标，或者range_max设置得太小。

可视化可以用rqt_image_view来看相机画面。画面里如果出现大面积黑色，往往是水下光照不足；需要检查世界脚本里是否配置了光源，或者相机曝光参数是否过低。

4.4 实时因子、步长与资源占用怎么实测

仿真跑起来后，实时因子是否达标取决于硬件。用下面命令看进程 CPU 占用：

# 找到仿真进程 PID pgrep -f bay_demo # 查看 CPU 和内存占用 top -p <PID>

如果 CPU 占用率长时间达到 100%，说明渲染线程已经满载，real_time_factor=1.0实际达不到 1.0。这种情况下，我一般会把time_step从 0.01 调到 0.02，步数减半，物理精度略微下降，但实时性能能拉回来。还有一种办法是把声呐beams从 256 降到 128，因为声呐仿真是最吃 CPU 的模块之一。

需要特别说明的是，物理步长不是越大越好。步长太大时，AUV 高速运动会出现穿模现象，表现为模型直接穿过海床或障碍物。判断步长是否合理，最简单的方法是看机器人落地后是否稳定：如果深度值持续震荡且越震越厉害，大概率是步长太大，碰撞求解已经发散。

5. 常见问题与排查：跑仿真时最容易翻车的五个点

这一章整理了我自己拆这个项目时踩过的坑，以及带其他开发者跑通时被高频问到的问题。每条按“现象、原因、解决”的方式记录。

5.1 排查套路：先看数据，再改世界，最后动引擎

遇到仿真表现不对，我习惯按三条线定位：第一看话题频率，确认数据通没通；第二看仿真日志，确认物理状态在不在合理范围；第三看资源加载，确认模型和纹理是否完整。很多问题表面是“机器人乱飞”，实际是模型碰撞体没配好，或者 URDF 里 base_link 的惯性参数太小，导致物理引擎计算炸了。

5.2 五条高频踩坑记录

第一条：模型从空中掉到海底后直接穿模。原因是 URDF 里只有视觉 mesh，没有碰撞体。解决方法是给每个 link 补一个简化碰撞盒或圆柱体，通常用collision标签指定box，尺寸略小于视觉模型即可，检测效率和稳定性都更好。

第二条：相机话题有频率但没有图像。原因多半是光源没有配置，或者相机安装深度过深，环境光几乎为零。解决方法是增加一个随 AUV 移动的点光源，保证相机视角内有可见光照；如果是深海场景，要考虑给相机开人工照明，否则识别算法在仿真里根本拿不到有效图像。

第三条：仿真时间与 ROS 时间对不上，TF 树持续报错。原因是use_sim_time没有开启，或者世界脚本里混用了rospy.sleep和sim.step()。解决方式是统一使用仿真时间源，在启动文件里设<param name="use_sim_time" value="true"/>，步进循环中不要用墙钟睡眠。

第四条：调大beams后声呐帧率跌到不到 5Hz。原因是 256 个波束的声学计算本身就不轻，256 再翻倍，耗时接近线性增长。解决方式是降低波束数，或把声呐更新率从 20Hz 降到 10Hz。通常水下目标探测场景 128 波束已经够用，用户不必追求纸面参数。

第五条：加载新的地形高度图后，机器人初始位置不在期望深度。原因是高度图尺寸和size参数不匹配，灰度比例不同导致实际地形深度比视觉上更陡。解决方法是先打印terrain.get_height(x, y)来查看指定坐标的真实深度，再根据这个值设定 AUV 的初始z，不要凭肉眼估。

6. 二次开发：把你的 AUV 模型和算法塞进这个世界

如果你想换一台自己的机器人进来测试，建议按这三步走：先做模型文件，再做运动学验证，最后挂感知算法。

第一步是在python/models下准备 URDF 和配套 mesh。URDF 里至少要定义base_link、base_footprint和推进器坐标系。碰撞体一定要单独给，这是最容易忽略的部分。我给新人推荐一个最小化做法：先用一个圆柱体代替整个机器人本体，跑通运动控制后，再逐步替换成完整的六个 link 结构。这样排错时，可以判断问题是来自模型还是来自算法。

第二步是验证运动学。加载模型后先不做任何闭环控制，直接给每个推进器设固定推力值，观察机器人是否按预期方向运动。这个过程会暴露推力方向定义错误、左右推进器装反的问题。我习惯打印get_pose()和get_velocity()，如果 z 轴速度不为零，说明推力方向和浮力中心设置不对。

第三步是在 ROS 里订阅自己的算法输出，把话题接到仿真脚本的控制接口。核心技巧是保持接口最小化：仿真侧只提供一个cmd_vel和一个pose话题，算法侧只管输出速度指令，不关心底层的推进器映射。这样你的控制代码在仿真里测完，换到真机上时，只需要替换硬件驱动节点。

最后说一个我自己的习惯教训：以前我每次改完地形高度图，只换图片不校验尺寸，结果三次实验数据全偏了。从那以后，我每次加载新世界，都强制走一遍“高度图打印校验、碰撞体检查、话题频率测试”这三步流程。仿真项目最怕的不是复杂，而是你以为它是对的，它其实错得很安静。希望这篇解析能帮你少走这些弯路，把更多时间花在算法本身。

本文还有配套的精品资源，点击获取