## 1. 环境准备与基础依赖安装 在 Ubuntu 20.04 上跑通 Flightmare 的 Python API，前提是 ROS 已经装好——但这里有个关键细节很多人忽略：**ROS Noetic 的桌面完整版（desktop-full）不是可选项，而是必选项**。为什么？因为 Flightmare 后续调试时会高频调用 rviz 查看姿态、轨迹和传感器数据，而 desktop-full 自带的 rqt、rosbag、tf 工具链能帮你快速定位坐标系错位、时间戳不同步这类“看不见却致命”的问题。我第一次在 minimal 版本上折腾了三天，最后发现连 `rostopic echo /tf` 都报错，换 desktop-full 之后重启终端就直接好了。 系统级依赖要一次性配齐，不能边跑边装。除了官方文档里写的 cmake 和 libzmqpp-dev，你必须额外加装 libopencv-dev——别信某些教程说“只在编译 C++ 时才需要”，Flightmare 的 Python API 在底层调用 C++ 渲染模块时，会通过 OpenCV 做图像格式转换，缺了它，`env.reset()` 会卡死在初始化阶段，终端只显示一行 `Starting Unity render process...` 就不动了。实测下来，这四个包缺一不可： ```bash sudo apt-get update sudo apt-get install -y build-essential cmake libzmqpp-dev libopencv-dev ``` Python 侧依赖也得提前理清楚。`pip3 install gym` 是基础，但 `rpg_baselines` 这个包容易被漏掉。它不光提供强化学习训练脚本，更重要的是封装了 `flightgym` 模块的自动注册逻辑——没有它，`import flightgym` 会直接抛 `ModuleNotFoundError`，而且错误提示非常模糊，只说“找不到模块”，根本不会告诉你缺的是哪个依赖。我踩过这个坑，在虚拟环境里反复重装 flightlib 十几次，最后才发现是 `rpg_baselines` 没装。 另外提醒一句：所有操作必须用 `python3` 和 `pip3`，Ubuntu 20.04 默认的 `python` 指向 Python 2.7，而 Flightmare 全栈基于 Python 3.8+，混用会导致 pip 安装的包在 python 解释器里完全不可见。你可以用 `ls -l /usr/bin/python*` 确认软链接指向，如果看到 `python -> python2.7`，那就立刻在命令里显式写 `python3`，别图省事。 ## 2. Flightmare 源码获取与渲染引擎部署 克隆源码不能简单 `git clone` 就完事。Flightmare 是 submodule 结构，官方推荐用 `--recursive` 参数一次性拉取全部子模块，否则 `flightrender` 目录下会是空的。我试过先 clone 再手动 init submodule，结果 `git submodule update --init --recursive` 执行到一半失败，因为某个子模块的远程地址已经失效，最后只能删掉整个 src 目录重来。所以最稳的做法就是一步到位： ```bash mkdir -p ~/flightmare_ws/src cd ~/flightmare_ws/src git clone --recursive https://github.com/uzh-rpg/flightmare.git ``` 接下来是 Unity 渲染引擎的部署——这是 Flightmare 区别于其他仿真器的核心环节。它不像 Gazebo 那样纯 C++ 实现，而是把物理仿真和图形渲染拆成两个进程：C++ 的 flightlib 负责动力学计算，Unity 的二进制程序负责画面渲染，两者通过 ZeroMQ 通信。这意味着你必须手动下载并解压 Unity 构建好的可执行文件，路径必须严格匹配。官方 release 页面只提供 `.tar.xz` 包，解压后是一个叫 `RPG_Flightmare` 的文件夹，里面包含 `RPG_Flightmare.x86_64`（Linux 可执行文件）和 `RPG_Flightmare_Data`（资源目录）。正确路径应该是： ``` ~/flightmare_ws/src/flightmare/flightrender/RPG_Flightmare/RPG_Flightmare.x86_64 ``` 如果放错位置，比如放在 `flightrender/` 根目录下，或者解压后多了一层文件夹嵌套，`env = VisionEnv_v0(use_render=True)` 就会报 `OSError: Cannot find Unity executable`。更隐蔽的问题是权限：`.x86_64` 文件默认没有执行权限，必须手动加 `chmod +x`。我第一次运行时看到报错信息里写着“Permission denied”，还以为是 SELinux 之类的安全机制限制，查了半天才发现只是少了一句 `chmod`。 还有一点容易被忽略：Unity 渲染进程启动后会监听一个 TCP 端口（默认 10253），这个端口必须空闲。如果你之前跑过其他 Flightmare 实例没正常退出，或者系统里有其他程序占用了 10253，`env.reset()` 就会卡住。解决方法很简单：`lsof -i :10253` 查进程，`kill -9 <PID>` 杀掉；或者改配置文件里的 `render_socket` 字段，比如改成 10254，然后在 Python 初始化时显式传入。 ## 3. 关键编译配置修复与工作空间构建 Flightmare 的 C++ 底层大量使用 pybind11 绑定 Python 接口，而官方仓库里 `pybind11_download.cmake` 文件默认拉取的是较新版本（v2.11 或更高），但在 Ubuntu 20.04 + ROS Noetic 的 GCC 9.3 环境下会编译失败，典型报错是 `error: ‘make_unique’ is not a member of ‘std’`。这个问题不是你的 GCC 版本太低，恰恰相反，是 pybind11 新版本用了 C++14 的特性，而 Flightmare 的 CMakeLists.txt 里强制设了 `-std=c++11`。我试过改 CMakeLists.txt 加 `-std=c++14`，结果又引发 OpenCV 头文件冲突，最终发现最干净的解法是降级 pybind11。 路径在 `~/flightmare_ws/src/flightmare/flightlib/cmake/pybind11_download.cmake`，打开后找到类似这样的行： ```cmake GIT_TAG v2.11 ``` 把它改成： ```cmake GIT_TAG v2.12 ``` 注意是 v2.12，不是 v2.10 或 v2.9——v2.12 是经过社区验证的兼容版本，既支持 C++11 编译，又修复了早期版本的内存泄漏问题。改完保存，不用重启终端，直接进工作空间编译就行。 工作空间构建推荐用 Release 模式，不是 Debug。原因很实在：Flightmare 的物理仿真对实时性要求高，Debug 模式下断言检查和调试符号会让单步 `env.step()` 耗时增加 3~5 倍，导致控制回路频率掉到 20Hz 以下，飞控策略根本没法收敛。Release 模式下 `catkin_make` 编译出的库体积更小、运行更快，而且 Flightmare 官方所有 benchmark 数据都是基于 Release 测试的。命令就是： ```bash cd ~/flightmare_ws catkin_make -DCMAKE_BUILD_TYPE=Release source devel/setup.bash ``` 这里有个隐藏陷阱：`catkin_make` 必须在 `~/flightmare_ws` 目录下执行，不能在 `src` 或 `devel` 子目录里。我有次手快 cd 进了 `src`，敲 `catkin_make` 报错说 “No CMakeLists.txt in current directory”，其实是因为 catkin 工具链会自动向上找 workspace 根目录，但路径错了它就不会识别。正确流程永远是：`cd` 到 workspace 根目录 → `catkin_make` → `source devel/setup.bash`。 编译完成后，`devel/lib` 下会生成 `libflightlib.so`，`devel/include` 下有头文件，这些是 ROS 节点能调用 C++ 接口的基础。但 Python API 不依赖这些，它走的是 `flightlib` 目录下的 `setup.py` 安装路径，所以下一步必须单独处理 Python 包。 ## 4. Python 包安装与环境变量配置 `flightlib` 目录下的 `setup.py` 是整个 Python API 的入口，但它不能用 `pip install .` 简单安装——因为 `setup.py` 里硬编码了相对路径，要求当前工作目录必须是 `flightlib` 本身。我试过在 workspace 根目录下 `pip install src/flightmare/flightlib`，结果安装成功但 `import flightgym` 报错，原因是 `__init__.py` 里写的 `from .envs import *` 找不到模块。正确姿势是： ```bash cd ~/flightmare_ws/src/flightmare/flightlib pip3 install --verbose . ``` 加 `--verbose` 很重要，它会打印出实际安装到哪个路径。正常输出末尾应该有类似 `Copying flightgym.egg-info to /home/yourname/.local/lib/python3.8/site-packages/flightgym-1.0.0-py3.8.egg-info` 的行。如果看到 `Installing flightgym script to /home/yourname/.local/bin`，说明安装成功；如果卡在 `running build_ext` 阶段，大概率是前面的 pybind11 版本没改对，或者 `libzmqpp-dev` 没装。 装完之后，还要让 Python 解释器知道去哪里找这个包。不能只靠 pip 安装路径，因为 ROS 的 `catkin_make` 会修改 `PYTHONPATH`，有时会覆盖 pip 的路径。最稳妥的方式是显式导出： ```bash echo "export PYTHONPATH=\$PYTHONPATH:/home/$(whoami)/flightmare_ws/src/flightmare" >> ~/.bashrc source ~/.bashrc ``` 注意路径是 `src/flightmare`，不是 `src/flightmare/flightlib`——因为 `flightgym` 模块的 `__init__.py` 在 `flightmare` 根目录下，Python 导入时会从 `PYTHONPATH` 的每个路径开始递归查找 `flightgym` 子目录。如果路径写错，`import flightgym` 就会报 `ImportError: No module named 'flightgym'`，而不是更具体的 `No module named 'flightgym.envs'`。 验证是否成功，开个新终端，直接运行： ```bash python3 -c "from flightgym import QuadrotorEnv_v0; print('OK')" ``` 如果输出 OK，说明 Python 层通了；如果报错，重点检查三件事：一是 `pip3 list | grep flightgym` 是否有输出，二是 `echo $PYTHONPATH` 是否包含刚才添加的路径，三是 `ls -l ~/flightmare_ws/src/flightmare/flightgym` 是否存在且非空。这三个检查项我每次配新机器都会列个 checklist，比盲目重装高效得多。 ## 5. ROS 节点开发与跨进程通信实践 Flightmare 和 ROS 的集成不是“把 ROS 包塞进 Flightmare”，而是“让 Flightmare 成为 ROS 生态里的一个节点”。核心思路是：用 Python 写一个 ROS node，它内部创建 `QuadrotorEnv_v0` 实例，接收 `/cmd_vel` 这类标准话题的指令，调用 `env.step()` 更新状态，再把 IMU、相机、激光雷达等观测数据发布到对应的 ROS topic。这样下游的导航栈、SLAM 或可视化工具就能无缝接入。 举个具体例子：你想让 MoveBase 发送速度指令控制无人机，那就要订阅 `/cmd_vel`。ROS 的 `Twist` 消息结构是线速度 x/y/z 加角速度 x/y/z，而 Flightmare 的动作空间是 `[vx, vy, vz, wz]`（四维向量），所以需要做映射。我的做法是在 node 里加一层转换函数： ```python def twist_to_action(self, msg): return [ msg.linear.x, msg.linear.y, msg.linear.z, msg.angular.z ] ``` 然后在 callback 里调用 `self.env.step(self.twist_to_action(msg))`。注意这里不能直接 `env.step(msg)`，因为 msg 是 ROS 消息对象，不是 numpy 数组。 发布传感器数据时，相机图像是最典型的。Flightmare 的 `env.get_observation()` 返回一个 dict，其中 `'rgb'` 键对应 `(H, W, 3)` 的 uint8 numpy 数组。要发到 ROS，得用 `cv_bridge` 转成 `sensor_msgs/Image`： ```python from cv_bridge import CvBridge bridge = CvBridge() ros_img = bridge.cv2_to_imgmsg(obs['rgb'], encoding="rgb8") self.image_pub.publish(ros_img) ``` 关键点是 `encoding="rgb8"`，不是 `"bgr8"`——因为 Flightmare 输出的是 RGB 格式，OpenCV 默认是 BGR，如果写错，rviz 里看到的图像是紫红色调的。我第一次调的时候没注意这个参数，以为是相机内参问题，调了两个小时白费劲。 还有一个实战经验：ROS 和 Flightmare 的循环频率要对齐。ROS 默认 `rospy.Rate(50)` 是 50Hz，但 Flightmare 的 `env.step()` 在 Release 模式下实测约 45Hz，如果强行塞满 50Hz，`step()` 会被阻塞，导致 ROS node 卡顿。我的解决方案是加个计数器，每 10 次 ROS 循环调 9 次 `step()`，保证时间戳连续。代码片段如下： ```python self.step_counter = 0 def run(self): rate = rospy.Rate(50) while not rospy.is_shutdown(): if self.step_counter % 10 < 9: self.env.step(self.last_action) self.step_counter += 1 # ... publish sensors rate.sleep() ``` 这样既满足 ROS 时间精度要求，又不拖慢仿真。