diff --git a/docs/dev/Carla_Air.md b/docs/dev/Carla_Air.md new file mode 100644 index 0000000..6d9ecbf --- /dev/null +++ b/docs/dev/Carla_Air.md @@ -0,0 +1,174 @@ + + + + + +
+ CarlaAir Logo + +

CarlaAir

+

在 CARLA 世界里飞无人机。
+ 将 CARLA 与 AirSim 融合为一——地面车辆与空中无人机,同一世界,同一脚本。

+

+ Version + License: MIT + Python 3.8+ + CARLA 0.9.16 + AirSim 1.8.1 + Platform + arXiv +

+

+ English | 简体中文 +

+
+ +

+ + CarlaAir Teaser — 点击观看完整演示视频 + +

+ +

+ 点击 GIF 或 B站观看 30 秒完整演示视频(汉斯·季默配乐) 🎵 | YouTube +

+ +--- + +## 🔥 最新动态 + +- **[2026-03]** `v0.1.7` 发布 — VSync 全屏修复、稳定交通系统、一键环境配置、无人机录制工具、坐标系文档 +- **[2026-03]** `v0.1.6` 发布 — 自动交通生成、UE4 原生 Sweep 碰撞、地面夹紧系统 +- **[2026-03]** `v0.1.5` 发布 — 12 方向碰撞系统、双语帮助菜单(`H`) +- **[2026-03]** `v0.1.4` 发布 — ROS2 验证(63 个话题)、首个官方二进制发布 + +--- + +**CarlaAir** 是一个开源的空地联合仿真平台。它通过在底层 C++ 将全球领先的自动驾驶仿真器(CARLA)与机器人仿真器(AirSim)合并为单一的 `ASimWorldGameMode`,实现了真正的帧级传感器同步、统一的物理引擎,以及无缝的双 Python API 交互。 + +## ✨ 核心亮点 + +- 🚀 **单进程深度集成**:拒绝跨进程通信桥接(Bridge),无延迟损耗。CARLA 与 AirSim 共享同一个 UE4 世界、天气系统与物理引擎。 +- 🎯 **绝对坐标对齐**:彻底解决 CARLA(左手系)与 AirSim(NED)之间的坐标转换问题,误差精确控制在 `0.0000m`。 +- 🚁 **内置 FPS 无人机控制**:无需编写任何代码,在仿真窗口内直接使用 `WASD` + 鼠标 即可像玩 FPS 游戏一样丝滑驾驶无人机。 +- 🚦 **开箱即用的城市交通**:启动器默认自动生成 30 辆背景车辆与 50 个行人,立即构建逼真城市场景。 +- 📸 **18路同步传感器**:支持在地面车辆和空中无人机上同时挂载 RGB、激光雷达、深度图、语义分割、IMU 和 GNSS,数据严格对齐。 +- 🐍 **双 API 无缝协作**:在同一个 Python 脚本中,同时调用 `carla.Client`(端口 2000)和 `airsim.MultirotorClient`(端口 41451)。 + +--- + +## 🎮 快速开始 + +### 选项 A:使用预编译版本(推荐) + +```bash +# 1. 下载并解压 CarlaAir-v0.1.7 +tar xzf CarlaAir-v0.1.7.tar.gz +cd CarlaAir-v0.1.7 + +# 2. 一键环境配置(仅首次需要) +bash env_setup/setup_env.sh # 创建 conda 环境,安装依赖,部署 carla 模块 +conda activate carlaAir +bash env_setup/test_env.sh # 验证环境:应全部显示 PASS + +# 3. 启动仿真器(自动生成交通流) +./CarlaAir.sh Town10HD + +# 4. 运行展示脚本!(另开一个终端) +conda activate carlaAir +python3 examples/quick_start_showcase.py +``` + +> **你将看到:** 一辆特斯拉在城市中自动巡航,无人机从空中追踪。4 分屏同时展示 **RGB · 深度图 · 语义分割 · LiDAR 鸟瞰** — 全部实时同步。天气自动轮换。 + +### 选项 B:从源码编译 + +如果您需要修改底层 C++ 代码,请参考 [源码编译指南](build_guide_ubuntu.md),了解如何使用 UE4.26 编译 CarlaAir。 + +--- + +## 🐍 一个脚本,两个世界 + +两套 API 共享**同一个仿真世界** — 无桥接、无同步烦恼。 + +```python +import carla, airsim + +carla_client = carla.Client("localhost", 2000) +air_client = airsim.MultirotorClient(port=41451) +world = carla_client.get_world() + +# 一次天气调用,影响所有传感器 — 地面和空中 +world.set_weather(carla.WeatherParameters.HardRainSunset) + +# 生成一辆汽车,自动驾驶 +vehicle = world.spawn_actor(vehicle_bp, spawn_point) +vehicle.set_autopilot(True) + +# 无人机起飞 — 同一个世界,同一场雨,同一套物理 +air_client.takeoffAsync().join() +air_client.moveToPositionAsync(80, 30, -25, 5) +``` + +**6 个演示脚本** — 逐个试试: + +```bash +python3 examples/quick_start_showcase.py # 🎬 4分屏传感器 + 无人机追踪 + 天气轮换 +python3 examples/drive_vehicle.py # 🚗 WASD 驾驶特斯拉 +python3 examples/walk_pedestrian.py # 🚶 鼠标+键盘 城市漫步 +python3 examples/switch_maps.py # 🗺️ 自动飞越全部 13 张地图 +python3 examples/sensor_gallery.py # 📸 单车 6 传感器网格展示 +python3 examples/air_ground_sync.py # 🔄 车+无人机分屏:同一场雨,同一世界 +``` + +**录制工具** — 录制车辆、无人机、行人轨迹,然后用导演相机回放: + +```bash +python3 examples/recording/record_vehicle.py # 🚗 键盘驾驶并录制车辆轨迹 +python3 examples/recording/record_drone.py # 🚁 飞行并录制无人机轨迹(零侵入) +python3 examples/recording/record_walker.py # 🚶 行走并录制行人轨迹 +python3 examples/recording/demo_director.py \ # 🎬 多轨迹回放 + 自由相机 + MP4 录制 + trajectories/vehicle_*.json trajectories/drone_*.json +``` + +> **文档:** [坐标系换算 (CARLA↔AirSim)](CarlaAir_Release/guide/COORDINATE_SYSTEMS.md) · [快速入门指南](CarlaAir_Release/guide/Quick-Start.md) · [常见问题](FAQ.md) + +--- + +## ⌨️ 飞行控制说明 + +在 CarlaAir 窗口中,使用内置 FPS 控制器直接驾驶无人机(无需代码): + +| 按键 | 功能 | +|-----|--------| +| `W` / `A` / `S` / `D` | 前进 / 左移 / 后退 / 右移 | +| `Space` / `Shift` | 上升 / 下降 | +| `Mouse` | 偏航转向 | +| `Scroll` | 调节速度 | +| `N` | 切换天气 | +| `P` | 碰撞模式切换 | +| `H` | 帮助菜单 | +| `1` / `2` / `3` | 传感器画面 | + +--- + +## 📚 文档与示例 + +**完整文档:** +- [快速入门指南](quick_start.md) +- [技术架构详解](architecture.md) +- [坐标系换算](coordinate_systems.md) +- [上游代码修改清单](modifications.md) + +--- + +## 📜 许可证与致谢 + +该项目是站在巨人的肩膀上。我们诚挚感谢以下开源项目的开发者: +- [CARLA Simulator](https://github.com/carla-simulator/carla) (MIT License) +- [Microsoft AirSim](https://github.com/microsoft/AirSim) (MIT License) +- [Unreal Engine](https://www.unrealengine.com/) + + +CARLA 相关的资产遵循 CC-BY 许可证。 +其他相关资产(包括湖南工商大学大学场景、长沙中电软件园场景)和代码基于 **MIT 许可证** 开源。 diff --git a/docs/dev/FAQ.md b/docs/dev/FAQ.md new file mode 100644 index 0000000..a283947 --- /dev/null +++ b/docs/dev/FAQ.md @@ -0,0 +1,148 @@ +# CarlaAir FAQ / 常见问题 + +--- + +## 连接问题 / Connection Issues + +### Q: CARLA Client 连接超时 +**A**: 首次启动需要 2-5 分钟加载资源(首次可能需要约 10 分钟编译着色器)。 + +```bash +# 检查端口是否就绪 +ss -tlnp | grep 2000 +``` + +### Q: AirSim 无法连接(端口 41451) +**A**: AirSim 服务器在 CARLA 之后启动,需要额外等待。确认 `~/Documents/AirSim/settings.json` 存在。 + +### Q: 两个 API 可以同时使用吗? +**A**: 是的,这正是 CarlaAir 的核心功能。CARLA API (port 2000) 和 AirSim API (port 41451) 同时运行,操控同一个世界。 + +--- + +## 同步 / 异步模式 / Sync & Async Mode + +### Q: 什么时候用同步模式,什么时候用异步模式? +**A**: +- **异步模式(默认)**: 适合交互式操作 — 键盘驾驶车辆、手动操控无人机、实时探索 +- **同步模式**: 适合数据采集、演示回放、视频录制 — 需要固定时间步和帧帧一致 + +### Q: 如何开启同步模式? +**A**: 需要同时配置 World 和 Traffic Manager: + +```python +settings = world.get_settings() +settings.synchronous_mode = True +settings.fixed_delta_seconds = 1.0 / 30 +world.apply_settings(settings) + +tm = client.get_trafficmanager(8000) +tm.set_synchronous_mode(True) + +# 主循环中每帧调用 +world.tick() +``` + +### Q: 同步模式下仿真器冻结了 +**A**: 脚本退出时**必须恢复异步模式**,否则仿真器会一直等待 `world.tick()` 而冻结: + +```python +settings = world.get_settings() +settings.synchronous_mode = False +settings.fixed_delta_seconds = None +world.apply_settings(settings) +``` + +建议在脚本中使用 `try/finally` 结构确保退出时始终恢复。 + +--- + +## 坐标系统 / Coordinate Systems + +### Q: AirSim 和 CARLA 的坐标系统有什么区别? +**A**: 两套 API 使用不同的坐标约定: + +| | CARLA | AirSim (NED) | +|---|---|---| +| X | 向前 (East) | 向前 (North) | +| Y | 向右 | 向右 (East) | +| Z | **向上为正** | **向下为正** | + +关键换算:AirSim NED z = -CARLA z。 +例如 CARLA 中 30 米高空对应 AirSim NED z = -30。 + +### Q: 无人机位置和 CARLA 车辆位置对不上 +**A**: 两套 API 的世界原点不同,不能直接用一个 API 的坐标去另一个 API 中定位。详细换算方法请参考 `examples_record_demo/COORDINATE_SYSTEMS.md`。 + +--- + +## 车辆和行人 / Vehicles & Pedestrians + +### Q: 车辆行驶异常/抽搐/路径不稳 +**A**: 使用 Traffic Manager 的 `hybrid_physics_mode` 可以改善远距离车辆的物理模拟稳定性: + +```python +tm = client.get_trafficmanager(8000) +tm.set_hybrid_physics_mode(True) +tm.set_hybrid_physics_radius(50.0) # 50 米内使用完整物理 +``` + +### Q: Walker 使用 `go_to_location()` 崩溃 +**A**: 已知限制。Walker AI Controller 在 CarlaAir 中会触发 segfault。**只使用静态 Walker**(不调用 `go_to_location()`)。 + +### Q: 多少车辆才安全? +**A**: +- 纯 CARLA(无无人机):50+ 辆安全 +- AirSim 无人机激活时:建议 ≤ 8 辆 autopilot +- 使用 `try_spawn_actor()` 而非 `spawn_actor()` 避免碰撞点生成失败 + +--- + +## 无人机 / Drone + +### Q: 无人机不响应指令 +**A**: 确保调用了正确的初始化序列: + +```python +client = airsim.MultirotorClient(port=41451) +client.confirmConnection() +client.enableApiControl(True) +client.armDisarm(True) +client.takeoffAsync().join() +``` + +### Q: AirSim 客户端连接后干扰了无人机控制 +**A**: 如果你在交互飞行的同时另一个脚本也连接了 AirSim,可能导致控制冲突。录制无人机轨迹时请使用专用脚本 `examples_record_demo/record_drone.py`,它内部处理了控制权管理。 + +### Q: `simSetCameraPose` 导致崩溃 +**A**: 在 Shipping 构建中 `simSetCameraPose` 会触发 C++ abort。**不要调用此函数**。使用无人机自身的 yaw + 轨道飞行来改变视角。 + +--- + +## 天气和地图 / Weather & Maps + +### Q: 如何切换地图? +**A**: 启动时指定地图名称: + +```bash +./CarlaAir.sh Town03 +``` + +可用地图:Town01, Town02, Town03, Town04, Town05, Town10HD。 + +### Q: 天气变化会影响无人机吗? +**A**: 是的,天气是统一的。CARLA 的 `set_weather()` 会同时影响地面和空中视角(雨、雾、光照等)。 + +--- + +## 性能 / Performance + +### Q: 帧率太低 +**A**: +- 使用较小的地图(Town01 比 Town10HD 轻量得多) +- 减少生成的 Actor 数量 +- 降低窗口分辨率 +- 使用 `-quality-level=Low` 参数 + +### Q: GPU 显存不足 +**A**: Town10HD 需要约 8GB 显存。尝试 Town01/Town02 等小地图,或使用 `_Opt` 变体地图(分层加载,减少显存占用)。 \ No newline at end of file diff --git a/docs/dev/add_plugin.md b/docs/dev/add_plugin.md index 09be3c7..b94970c 100644 --- a/docs/dev/add_plugin.md +++ b/docs/dev/add_plugin.md @@ -124,4 +124,11 @@ PrivateDependencyModuleNames.AddRange(new string[] { "AirSim" }); 2025-09-20T12:56:36.2243331Z C:\actions-runner\_work\hutb\hutb\Unreal\CarlaUE4\Plugins\AirSim\Source\AirBlueprintLib.h(23): fatal error C1083: �޷��򿪰����ļ�: ��common/AirSimSettings.hpp��: No such file or directory 2025-09-20T12:56:36.2273244Z [6/61] Module.AirSim.gen.cpp 2025-09-20T12:56:36.2303779Z C:\actions-runner\_work\hutb\hutb\Unreal\CarlaUE4\Plugins\AirSim\Source/AirBlueprintLib.h(23): fatal error C1083: �޷��򿪰����ļ�: ��common/AirSimSettings.hpp��: No such file or directory -``` \ No newline at end of file +``` + +## 其他(和 Carla 兼容) + + + +* [融合 CARLA 与 AirSim ](Carla_Air.md) + diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md new file mode 100644 index 0000000..ef18e12 --- /dev/null +++ b/docs/dev/architecture.md @@ -0,0 +1,195 @@ +# CarlaAir 详细技术架构 + +## 系统架构图 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Unreal Engine 4.26 │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ ASimWorldGameMode (核心) │ │ +│ │ ┌─────────────────────┐ ┌────────────────────────────┐ │ │ +│ │ │ CARLA 子系统 │ │ AirSim 子系统 │ │ │ +│ │ │ (继承自父类) │ │ (BeginPlay 中引导) │ │ │ +│ │ │ │ │ │ │ │ +│ │ │ ■ CarlaEpisode │ │ ■ ASimModeBase (Actor) │ │ │ +│ │ │ ■ Weather │ │ ■ SimHUDWidget │ │ │ +│ │ │ ■ Traffic Manager │ │ ■ AirSim Settings │ │ │ +│ │ │ ■ ActorDispatcher │ │ ■ API Server (:41451) │ │ │ +│ │ │ ■ SensorManager │ │ ■ PIPCamera System │ │ │ +│ │ │ ■ ActorFactories │ │ ■ Physics Engine │ │ │ +│ │ │ ■ CarlaRecorder │ │ ■ NedTransform │ │ │ +│ │ │ ■ RPC Server(:2000)│ │ │ │ │ +│ │ └─────────────────────┘ └────────────────────────────┘ │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ Town10HD Map │ │ AirSim Assets │ │ +│ │ (Roads, Buildings│ │ (Drone model, │ │ +│ │ Traffic Lights) │ │ Weather, HUD) │ │ +│ └──────────────────┘ └──────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ + │ │ + ▼ ▼ + ┌──────────────┐ ┌──────────────┐ + │ CARLA Python │ │ AirSim Python │ + │ Client API │ │ Client API │ + │ (port 2000) │ │ (port 41451) │ + └──────────────┘ └──────────────┘ +``` + +## 初始化序列 + +``` +UE4 Engine Start + │ + ├── 1. ASimWorldGameMode::Constructor() + │ ├── Super() → ACarlaGameModeBase 初始化 Episode, Recorder, Delegates + │ ├── DefaultPawnClass = nullptr + │ ├── 加载 BP_Weather → WeatherClass + │ ├── 注册 8 个 ActorFactory + │ ├── 初始化 AirSim 日志 + │ └── 加载 AirSim HUD Widget 蓝图 + │ + ├── 2. ASimWorldGameMode::BeginPlay() + │ ├── Super::BeginPlay() + │ │ ├── CARLA Episode 初始化 + │ │ ├── Weather Actor 生成 + │ │ ├── ActorFactory 实例化 + │ │ ├── Traffic Manager 启动 + │ │ └── CARLA RPC Server 启动 (port 2000) + │ │ + │ ├── 创建 SpectatorPawn(不 possess) + │ │ └── 注册到 Episode(可通过 CARLA API 移动 Spectator) + │ │ + │ ├── AirSim 引导 + │ │ ├── InitializeAirSimSettings() — 读取 settings.json + │ │ ├── SetUnrealEngineSettings() — 关闭 MotionBlur, 启用 CustomDepth + │ │ ├── CreateSimMode() — SpawnActor + │ │ │ └── SimModeBase::BeginPlay() + │ │ │ ├── 获取 PlayerStart Transform + │ │ │ ├── 初始化 NedTransform(不移动世界原点!) + │ │ │ ├── 创建 WorldSimApi + │ │ │ └── 创建无人机 Pawn + │ │ ├── CreateAirSimWidget() — HUD Widget 添加到 Viewport + │ │ ├── SetupAirSimInputBindings() — R/T/1/2/3/0 键绑定 + │ │ └── SimMode->startApiServer() — AirSim RPC Server 启动 (port 41451) + │ │ + │ └── 完成!两个 API 服务器同时运行 + │ + ├── 3. Tick Loop (每帧) + │ ├── Super::Tick() — CARLA Recorder tick + │ └── AirSim Debug Report Widget 更新 + │ + └── 4. EndPlay() + ├── SimMode->stopApiServer() + ├── 销毁 Widget, SimMode + └── Super::EndPlay() — CARLA 清理 +``` + +## 关键数据流 + +### 车辆生成流程 +``` +Python: world.spawn_actor(vehicle_bp, transform) + → CARLA RPC Server + → CarlaEpisode::SpawnActor() + → ActorDispatcher → VehicleFactory + → UE4 World SpawnActor() + → 物理引擎接管 (Chaos/PhysX) +``` + +### 无人机控制流程 +``` +Python: client.moveToPositionAsync(x, y, z, speed) + → AirSim RPC Server + → SimModeWorldMultiRotor + → SimpleFlight Controller + → NedTransform 坐标转换 (NED → UE4) + → Drone Pawn 移动 +``` + +### 传感器数据流 +``` +CARLA 传感器: + Camera/Lidar/Radar → SensorManager → Raw Data → RPC → Python numpy array + +AirSim 传感器: + PIPCamera → RenderTarget → simGetImages() → RPC → Python numpy array +``` + +## 文件修改详情 + +### 修改清单(共 3 个文件修改,2 个新文件) + +| 文件 | 修改类型 | 修改行数 | 目的 | +|------|---------|---------|------| +| `SimWorldGameMode.h` | **新建** | 75 行 | 统一 GameMode 类声明 | +| `SimWorldGameMode.cpp` | **新建** | 548 行 | 统一 GameMode 完整实现 | +| `CarlaGameModeBase.h` | 修改 2 处 | ~4 行 | `WeatherClass`/`ActorFactories` → protected | +| `CarlaEpisode.h` | 修改 1 处 | 1 行 | 添加 `friend class ASimWorldGameMode` | +| `SimModeBase.cpp` | 修改 1 处 | ~6 行 | 注释掉 `SetNewWorldOrigin()` | + +### 每个修改的精确位置 + +**CarlaGameModeBase.h**: +```cpp +// 原始: private 区域 +// 修改: 移到 protected 区域 +protected: + UPROPERTY(EditAnywhere) + TSubclassOf WeatherClass; + + UPROPERTY(EditAnywhere) + TArray> ActorFactories; +``` + +**CarlaEpisode.h** (~第 338 行): +```cpp +// 添加: +friend class ASimWorldGameMode; +``` + +**SimModeBase.cpp** (~第 119 行): +```cpp +// 原始: +// this->GetWorld()->SetNewWorldOrigin(FIntVector(player_loc) + FIntVector(0, 0, 0)); + +// 修改为注释 + 说明: +// NOTE: Do NOT call SetNewWorldOrigin() here. In CarlaAir... +global_ned_transform_.reset(new NedTransform(player_start_transform, + UAirBlueprintLib::GetWorldToMetersScale(this))); +``` + +## Town10HD 地图布局 + +``` + Y=-69 + │ + Ocean (x<20) │ Inland City (x>55) + │ + ┌──────────────────┼──────────────────────────┐ + │ │ │ + │ Coast/Beach │ ┌──────────────────┐ │ + │ │ │ City Center │ │ + │ PlayerStart │ │ (80, 30) │ │ + │ (x≈0, NED │ │ │ │ + │ origin) │ │ Buildings, │ │ Y=141 + │ │ │ Roads, │ │ + │ │ │ Intersections │ │ + │ │ └──────────────────┘ │ + │ │ │ + └──────────────────┼──────────────────────────┘ + X=-115 │ X=110 + + NED 原点在 PlayerStart (x≈0) + 城市中心在 NED (80, 0, -30) = CARLA (80, 0, 30m高) +``` + +## 已知限制和约束 + +| 约束 | 原因 | 解决方案 | +|------|------|---------| +| Walker 不能使用 AI Controller | `go_to_location()` 触发四元数错误导致 segfault | 使用静态 Walker | +| `simSetCameraPose` 在 Shipping 包中崩溃 | C++ abort in Shipping build | 不调用,使用无人机轨道 + yaw tracking | +| AirSim 活动时最多 ~8 个 autopilot 车辆 | 概率性四元数崩溃 | 批量启用 autopilot,延迟 0.5s | +| 纯 CARLA 脚本可安全处理 50+ 车辆 | 无 AirSim 干扰 | 展示交通时不启动无人机 | \ No newline at end of file diff --git a/docs/dev/build_guide_ubuntu.md b/docs/dev/build_guide_ubuntu.md new file mode 100644 index 0000000..db1595b --- /dev/null +++ b/docs/dev/build_guide_ubuntu.md @@ -0,0 +1,147 @@ +# HUTB_air 从源码编译指南 + +## 前提条件 + +### 系统要求 +- **操作系统**: Ubuntu 18.04 / 20.04 / 22.04 (推荐 22.04) +- **GPU**: NVIDIA GPU,显存 >= 8GB (推荐 12GB+) +- **内存**: >= 32GB RAM +- **磁盘**: >= 100GB 可用空间 +- **显示**: 需要 X11 显示服务 (或 VNC/Xvfb) + +### 软件依赖 +```bash +# 基础编译工具 +sudo apt install build-essential cmake git clang-10 lld-10 + +# UE4 依赖 +sudo apt install libvulkan1 vulkan-utils mesa-vulkan-drivers + +# Python 环境 +conda create -n simworld python=3.7 +conda activate simworld +pip install carla==0.9.16 airsim numpy opencv-python pygame +``` + +## 源码位置 + +| 组件 | 路径 | +|------|------| +| UE4 4.26 (CARLA fork) | `/mnt/data1/tianle/carla_ue4/` | +| CARLA 源码 | `/mnt/data1/tianle/carla_source/` | +| AirSim 插件 | `Unreal/CarlaUE4/Plugins/AirSim/` | +| CarlaAir 核心文件 | `Plugins/AirSim/Source/SimWorldGameMode.h/.cpp` | + +## 编译步骤 + +### 1. 设置环境变量 + +```bash +export UE4_ROOT=/mnt/data1/tianle/carla_ue4 +cd /mnt/data1/tianle/carla_source +``` + +### 2. 编译 AirSim 模块(~100 秒) + +```bash +# 仅编译 AirSim 插件(快速迭代时使用) +make CarlaUE4Editor ARGS="-module=AirSim" +# 或直接使用 Build.sh +./Util/BuildTools/BuildCarlaUE4.sh --build +``` + +### 3. 编译 CARLA 模块(~290 秒) + +```bash +# 编译 CARLA 插件 +make CarlaUE4Editor ARGS="-module=Carla" +``` + +### 4. 在 Editor 模式中运行(开发调试) + +```bash +# 使用一键启动脚本 +./carlaAir.sh # 默认 Town10HD, 1280x720 +./carlaAir.sh Town03 # 指定地图 +./carlaAir.sh Town10HD 1920 1080 # 指定分辨率 +``` + +### 5. 打包 Shipping 构建(发布用) + +```bash +# 完整打包流程(编译 ~805s + Cook ~2h) +./Util/BuildTools/Package.sh --config=Shipping --no-zip + +# 输出目录 +ls Dist/CARLA_Shipping_*/LinuxNoEditor/ +``` + +**注意**: Package.sh 在最后 rsync PythonAPI wheel 时可能失败(因为 `.whl` 文件未构建),但这不影响主要构建。手动复制 PythonAPI 文件到输出目录即可。 + +### 6. 运行 Shipping 构建 + +```bash +cd Dist/CARLA_Shipping_*/LinuxNoEditor/ +./CarlaUE4.sh /Game/Carla/Maps/Town10HD -nosound -carla-rpc-port=2000 +``` + +## 关键配置文件 + +### DefaultGame.ini + +位于 `Unreal/CarlaUE4/Config/DefaultGame.ini`。打包时需要确保以下条目存在: + +```ini +# AirSim 资源目录(必须) ++DirectoriesToAlwaysCook=(Path="/AirSim/Blueprints") ++DirectoriesToAlwaysCook=(Path="/AirSim/HUDAssets") ++DirectoriesToAlwaysCook=(Path="/AirSim/Models") ++DirectoriesToAlwaysCook=(Path="/AirSim/Weather") ++DirectoriesToAlwaysCook=(Path="/AirSim/StarterContent") ++DirectoriesToAlwaysCook=(Path="/AirSim/VehicleAdv") + +# AirSim 地图 ++MapsToCook=(FilePath="/AirSim/AirSimAssets") +``` + +### settings.json + +位于 `~/Documents/AirSim/settings.json`,控制 AirSim 行为: + +```json +{ + "SettingsVersion": 1.2, + "SimMode": "Multirotor", + "Vehicles": { + "SimpleFlight": { + "VehicleType": "SimpleFlight", + "AutoCreate": true + } + } +} +``` + +## 编译时间参考 + +| 步骤 | 时间 | 说明 | +|------|------|------| +| AirSim 模块编译 | ~100s | 仅 AirSim 相关 C++ | +| CARLA 模块编译 | ~290s | CARLA 插件 C++ | +| Shipping 编译 | ~805s | 656 个编译单元 | +| Cook (资源烘焙) | ~2h | 13459 个包 | +| TaggedMaterials | ~977s | 实例分割材质 | +| **总计 (完整打包)** | **~3.5h** | 首次;增量编译更快 | + +## 常见问题 + +### Q: 首次启动非常慢(~10分钟) +**A**: 首次运行时 UE4 需要编译 DDC (Derived Data Cache) 和着色器。后续启动约 1 分钟。 + +### Q: Package.sh 最后报错 +**A**: 通常是 PythonAPI wheel rsync 失败(`set -e` 导致脚本中断)。主要的可执行文件和资源已经正确打包,手动复制 PythonAPI 即可。 + +### Q: 打包后的构建缺少地图 +**A**: 检查 `DefaultGame.ini` 中的 `MapsToCook` 条目。确保包含所有需要的地图。 + +### Q: AirSim API 无法连接 +**A**: 检查 `~/Documents/AirSim/settings.json` 是否存在且格式正确。Editor 模式下需要等待 AirSim 端口 41451 就绪。 diff --git a/docs/dev/coordinate_systems.md b/docs/dev/coordinate_systems.md new file mode 100644 index 0000000..0e4c286 --- /dev/null +++ b/docs/dev/coordinate_systems.md @@ -0,0 +1,87 @@ +# CarlaAir 坐标系换算说明 + +## 问题 + +CarlaAir 内部同时运行 CARLA 和 AirSim 两套系统,**它们使用不同的坐标系**: + +| | CARLA | AirSim | +|---|---|---| +| 坐标原点 | UE4 世界原点 | AirSim PlayerStart 位置 | +| X 轴 | 同 UE4 | 同 UE4,但有原点偏移 | +| Y 轴 | 同 UE4 | 同 UE4,但有原点偏移 | +| Z 轴 | **向上为正** (z-up) | **向下为正** (NED, z-down) | +| 单位 | 厘米 (UE4) → Python API 返回**米** | 米 | + +## 换算公式 + +在 Town10HD 地图上实测(CarlaAir v0.1.6): + +``` +airsim_x = carla_x + 172.20 +airsim_y = carla_y - 183.86 +airsim_z = -carla_z + 27.45 +``` + +姿态角(pitch/yaw/roll)两侧一致,**不需要换算**。 + +## 换算参数表 + +| 参数 | 值 | 说明 | +|------|-----|------| +| `offset_x` | **+172.20** | AirSim 原点在 CARLA X 方向的偏移 | +| `offset_y` | **-183.86** | AirSim 原点在 CARLA Y 方向的偏移 | +| `offset_z` | **+27.45** | AirSim 原点在 CARLA Z 方向的偏移(取反后加) | +| z 轴翻转 | `airsim_z = -carla_z + offset_z` | CARLA z-up → AirSim NED z-down | + +> **注意:** 偏移量取决于地图和 AirSim PlayerStart 配置。换地图后需要重新标定。 + +## 如何标定 + +在两个系统中同时读取无人机位置即可算出偏移量: + +```python +import carla, airsim + +# CARLA 侧 +client = carla.Client('localhost', 2000) +world = client.get_world() +drone = [a for a in world.get_actors() if 'drone' in a.type_id][0] +cl = drone.get_location() + +# AirSim 侧 +ac = airsim.MultirotorClient() +ac.confirmConnection() +ap = ac.getMultirotorState().kinematics_estimated.position + +# 偏移量 +offset_x = ap.x_val - cl.x +offset_y = ap.y_val - cl.y +offset_z = ap.z_val - (-cl.z) +print(f"offset_x={offset_x:.4f}, offset_y={offset_y:.4f}, offset_z={offset_z:.4f}") +``` + +## 脚本中的处理 + +| 脚本 | 录制坐标系 | 回放方式 | +|------|-----------|---------| +| `record_drone.py` | **CARLA** (`transform` 字段) | — | +| `record_drone_airsim_only.py` | **AirSim NED** (`airsim_ned` 字段) | — | +| `record_vehicle.py` | **CARLA** (`transform` 字段) | CARLA `set_transform` | +| `record_walker.py` | **CARLA** (`transform` 字段) | CARLA `set_transform` | +| `demo_director.py` 车辆/行人 | — | CARLA `set_transform`(直接用) | +| `demo_director.py` 无人机 | — | AirSim `simSetVehiclePose`(自动校准偏移) | +| `replay_drone_airsim_only.py` | — | AirSim `simSetVehiclePose`(需 `airsim_ned`) | + +### demo_director 自动校准 + +`DroneReplayer` 初始化时: +1. 检测 JSON 中是否有 `airsim_ned` 字段 +2. 如果只有 `transform`(CARLA 坐标)→ 读取无人机在 CARLA 和 AirSim 两侧的当前位置,计算偏移量 +3. 回放时每帧 `CARLA transform + 偏移 → AirSim NED → simSetVehiclePose` + +如果 JSON 中有 `airsim_ned` → 直接使用,不做转换。 + +## 为什么不直接用 AirSim API 录制? + +连接 AirSim Python 客户端会导致 CarlaAir 窗口中的无人机**丢失键盘控制并坠落**。 +因此 `record_drone.py` 只从 CARLA 侧读取 `drone_actor.get_transform()`,完全不碰 AirSim。 \ No newline at end of file diff --git a/docs/dev/modifications.md b/docs/dev/modifications.md new file mode 100644 index 0000000..bc83839 --- /dev/null +++ b/docs/dev/modifications.md @@ -0,0 +1,152 @@ +# CarlaAir 所有修改清单 + +本文档列出了 CarlaAir 相对于原版 CARLA 0.9.16 和 AirSim 的所有代码修改,方便开发者精确了解改动范围。 + +## 修改统计 + +| 类型 | 数量 | 说明 | +|------|------|------| +| **新建文件** | 2 | SimWorldGameMode.h, SimWorldGameMode.cpp | +| **修改文件** | 3 | CarlaGameModeBase.h, CarlaEpisode.h, SimModeBase.cpp | +| **配置修改** | 1 | DefaultGame.ini (添加 AirSim 资源条目) | +| **新建脚本** | 30+ | carlaAir.sh, 示例脚本, Demo 脚本 | + +## 详细修改 + +### 1. [新建] SimWorldGameMode.h + +**路径**: `Unreal/CarlaUE4/Plugins/AirSim/Source/SimWorldGameMode.h` +**行数**: 75 行 +**放置在 AirSim 插件目录的原因**: 需要引用 AirSim 头文件 (SimHUDWidget.h, SimModeBase.h, PIPCamera.h, AirSimSettings.hpp) + +**类声明**: +```cpp +UCLASS() +class AIRSIM_API ASimWorldGameMode : public ACarlaGameModeBase +``` + +**公共接口**: +- 构造函数、BeginPlay、Tick、EndPlay(override) +- 8 个输入事件处理函数(Recording, Report, Help, Trace, SubWindow 0/1/2, All) + +**私有成员**: +- `USimHUDWidget* Widget_` — AirSim HUD 控件 +- `ASimModeBase* SimMode_` — AirSim 模拟模式 Actor +- `APIPCamera* SubwindowCameras_[3]` — 子窗口相机 + +### 2. [新建] SimWorldGameMode.cpp + +**路径**: `Unreal/CarlaUE4/Plugins/AirSim/Source/SimWorldGameMode.cpp` +**行数**: 548 行 + +**关键实现**: + +| 函数 | 行号 | 功能 | +|------|------|------| +| 构造函数 | 66-123 | DefaultPawnClass=nullptr, 加载BP_Weather, 注册8个Factory | +| BeginPlay | 127-186 | CARLA初始化 → 创建SpectatorPawn → AirSim引导 | +| Tick | 190-198 | CARLA Recorder + AirSim Widget更新 | +| EndPlay | 202-224 | 停止API → 销毁Widget/SimMode → CARLA清理 | +| InitializeAirSimSettings | 228-244 | 读取settings.json | +| SetUnrealEngineSettings | 246-259 | 关闭MotionBlur, 启用CustomDepth | +| CreateSimMode | 263-286 | 根据SimMode类型SpawnActor | +| CreateAirSimWidget | 290-327 | 创建并初始化HUD Widget | +| SetupAirSimInputBindings | 362-375 | 绑定 R/;/F1/T/1/2/3/0 键 | +| GetSettingsText | 497-503 | 搜索settings.json (4个位置) | + +### 3. [修改] CarlaGameModeBase.h + +**路径**: `Unreal/CarlaUE4/Plugins/Carla/Source/Carla/Game/CarlaGameModeBase.h` +**修改量**: 2 处,约 4 行 + +**修改前** (在 `private:` 区域): +```cpp +private: + UPROPERTY(EditAnywhere) + TSubclassOf WeatherClass; + + UPROPERTY(EditAnywhere) + TArray> ActorFactories; +``` + +**修改后** (移到 `protected:` 区域): +```cpp +protected: + UPROPERTY(EditAnywhere) + TSubclassOf WeatherClass; + + UPROPERTY(EditAnywhere) + TArray> ActorFactories; +``` + +**影响**: 仅影响访问权限,不改变运行时行为。子类 ASimWorldGameMode 可以在构造函数中设置这些属性。 + +### 4. [修改] CarlaEpisode.h + +**路径**: `Unreal/CarlaUE4/Plugins/Carla/Source/Carla/Game/CarlaEpisode.h` +**修改量**: 1 处,1 行 + +**添加位置**: 类声明内部,约第 338 行 + +```cpp +friend class ASimWorldGameMode; +``` + +**影响**: 允许 SimWorldGameMode 直接访问 Episode 的私有成员(主要是 `Spectator` 和 `ActorDispatcher`),用于注册手动创建的 SpectatorPawn。 + +### 5. [修改] SimModeBase.cpp + +**路径**: `Unreal/CarlaUE4/Plugins/AirSim/Source/SimMode/SimModeBase.cpp` +**修改量**: 1 处,约 6 行 + +**修改前** (~第 119 行): +```cpp +this->GetWorld()->SetNewWorldOrigin(FIntVector(player_loc) + FIntVector(0, 0, 0)); +global_ned_transform_.reset(new NedTransform(player_start_transform, + UAirBlueprintLib::GetWorldToMetersScale(this))); +``` + +**修改后**: +```cpp +// NOTE: Do NOT call SetNewWorldOrigin() here. In CarlaAir (CARLA + AirSim integration), +// shifting the world origin breaks CARLA's landscape/road collision, causing all ground +// vehicles to fall through the map (~30m underground). The NedTransform is initialized +// with the original player_start_transform, which correctly serves as the NED origin +// for AirSim coordinate conversion without moving the world. +global_ned_transform_.reset(new NedTransform(player_start_transform, + UAirBlueprintLib::GetWorldToMetersScale(this))); +``` + +**影响**: 车辆不再穿过地面(z≈0.00 正常行驶),AirSim 无人机坐标系不受影响(NedTransform 仍然使用 PlayerStart 作为原点)。 + +### 6. [修改] DefaultGame.ini + +**路径**: `Unreal/CarlaUE4/Config/DefaultGame.ini` +**修改量**: 新增约 8 行 + +**新增内容**: +```ini +# AirSim content directories to cook ++DirectoriesToAlwaysCook=(Path="/AirSim/Blueprints") ++DirectoriesToAlwaysCook=(Path="/AirSim/HUDAssets") ++DirectoriesToAlwaysCook=(Path="/AirSim/Models") ++DirectoriesToAlwaysCook=(Path="/AirSim/Weather") ++DirectoriesToAlwaysCook=(Path="/AirSim/StarterContent") ++DirectoriesToAlwaysCook=(Path="/AirSim/VehicleAdv") + +# AirSim assets map ++MapsToCook=(FilePath="/AirSim/AirSimAssets") +``` + +**影响**: 打包时包含所有 AirSim 资源(无人机模型、HUD、天气特效等),共 340 个文件。 + +## 未修改的关键文件(供参考) + +以下文件是原版 CARLA/AirSim 的,未做修改但对理解系统重要: + +- `CarlaGameModeBase.cpp` — CARLA GameMode 实现 +- `CarlaEpisode.cpp` — Episode 管理 +- `SimModeWorldMultiRotor.cpp` — 多旋翼飞行器模式 +- `SimpleFlight/SimpleFlightApi.cpp` — 简单飞行控制器 +- `PIPCamera.cpp` — AirSim 相机实现 +- `AirBlueprintLib.cpp` — AirSim UE4 工具库 \ No newline at end of file diff --git a/docs/dev/quick_start.md b/docs/dev/quick_start.md new file mode 100644 index 0000000..6c3e536 --- /dev/null +++ b/docs/dev/quick_start.md @@ -0,0 +1,259 @@ +# CarlaAir Quick-Start Guide / 快速入门指南 + +欢迎使用 **CarlaAir** — 空地一体联合仿真平台。 +本指南帮助你从零开始,10 分钟内完成首次体验。 + +--- + +## Prerequisites / 前置条件 + +在开始之前,请确认以下环境已准备好: + +- **Conda** — 已安装 Miniconda 或 Anaconda +- **CarlaAir 二进制包** — 已下载并解压 CarlaAir 发行包 +- **NVIDIA GPU** — 至少 8GB 显存(Town10HD 需要约 8GB) +- **Ubuntu 系统** — 推荐 Ubuntu 20.04 / 22.04 + +--- + +## Environment Setup / 环境配置 + +使用自动化脚本一键配置 Python 环境和依赖: + +```bash +# 创建 conda 环境并安装所有依赖 +bash env_setup/setup_env.sh + +# 验证环境是否正确配置 +bash env_setup/test_env.sh +``` + +`setup_env.sh` 会创建 `carlaAir` conda 环境,安装 CARLA Python API、AirSim、PyGame、OpenCV 等依赖。 +`test_env.sh` 会检查所有依赖是否可导入。 + +配置完成后,激活环境: + +```bash +conda activate carlaAir +``` + +--- + +## Launch / 启动仿真器 + +```bash +./CarlaAir.sh Town10HD +``` + +等待看到 "Ready! Both servers are running." 即表示启动成功。 + +**端口说明 / Ports:** +| 服务 Service | 端口 Port | 用途 Purpose | +|---|---|---| +| CARLA API | `localhost:2000` | 地面仿真:车辆、行人、天气、传感器 | +| AirSim API | `localhost:41451` | 空中仿真:无人机飞行与相机 | + +> **提示**: 首次启动需要 2-5 分钟加载资源和编译着色器,请耐心等待。 + +--- + +## First Experience / 首次体验 + +启动成功后,运行你的第一个 CarlaAir 脚本: + +```bash +python3 examples/quick_start_showcase.py +``` + +这个脚本会自动演示 CarlaAir 的核心能力: +1. 在城市中生成一辆 Tesla,无人机起飞并锁定跟踪 +2. 车辆沿道路行驶,无人机在上方自动跟随 +3. 4 分屏传感器展示:RGB 画面 / 深度图 / 语义分割 / 无人机 FPV +4. 天气自动循环切换(晴天、雨天、雾天、日落等) + +**操作 / Controls:** `N` 手动切换天气,`ESC` 退出。 + +--- + +## Interactive Demos / 交互式示例 + +`examples/` 目录包含 6 个经过测试的示例脚本,涵盖 CarlaAir 的各项能力: + +| 脚本 Script | 功能 Description | 操作 Controls | +|---|---|---| +| `quick_start_showcase.py` | 全自动演示:车辆+无人机跟踪+4分屏传感器+天气循环 | `N` 切换天气, `ESC` 退出 | +| `drive_vehicle.py` | 键盘驾驶车辆,第三人称追踪相机 | `WASD` 驾驶, `Space` 手刹, `R` 倒车, `N` 天气 | +| `walk_pedestrian.py` | 第一人称行人漫游,鼠标控制视角 | `WASD` 行走, `Shift` 加速, `Space` 跳跃, `Mouse` 视角 | +| `switch_maps.py` | 自动遍历所有地图,每张地图无人机飞越展示 | `N` 跳过当前地图, `ESC` 退出 | +| `sensor_gallery.py` | 6 格传感器展示:RGB/深度/语义/实例/LiDAR/光流 | `N` 切换天气, `ESC` 退出 | +| `air_ground_sync.py` | 左右分屏:地面车辆+空中无人机,同一世界同步天气 | `N` 切换天气, `ESC` 退出 | + +运行方式 / Usage: + +```bash +conda activate carlaAir +python3 examples/drive_vehicle.py +``` + +--- + +## Recording Toolkit / 录制工具 + +`examples_record_demo/` 目录提供了轨迹录制与回放工具,用于制作高质量演示视频: + +| 脚本 Script | 用途 Purpose | +|---|---| +| `record_vehicle.py` | 录制车辆行驶轨迹(键盘操控 + 轨迹保存) | +| `record_drone.py` | 录制无人机飞行轨迹(键盘操控 + 轨迹保存) | +| `record_walker.py` | 录制行人行走轨迹 | +| `demo_director.py` | 读取轨迹文件,同步回放并录制高质量视频帧 | +| `trajectory_helpers.py` | 轨迹文件的读写工具函数 | + +**工作流 / Workflow:** +1. 用 `record_*.py` 脚本交互录制轨迹(保存为 JSON 文件) +2. 用 `demo_director.py` 加载轨迹并以同步模式回放,输出帧序列 +3. 用 ffmpeg 将帧序列合成视频 + +详见 `examples_record_demo/README.md`。 + +--- + +## Synchronous vs Asynchronous Mode / 同步与异步模式 + +CarlaAir 支持两种运行模式,不同场景下需要选择合适的模式: + +### Asynchronous Mode / 异步模式(默认) + +适用于**交互式操作**:在 CarlaAir 窗口中驾驶车辆、操控无人机。 + +- 仿真器按自身节奏推进,客户端随时读取最新状态 +- 帧率不固定,画面流畅但时间步不均匀 +- 适合:键盘驾驶、实时飞行、手动探索 + +### Synchronous Mode / 同步模式 + +适用于**数据采集、演示回放、视频录制**等需要精确控制的场景。 + +- 仿真器每帧等待客户端调用 `world.tick()` 后才推进 +- 时间步固定,帧帧一致,适合录制平滑视频 + +**同步模式配置要求 / Configuration:** + +```python +# 开启同步模式 +settings = world.get_settings() +settings.synchronous_mode = True +settings.fixed_delta_seconds = 1.0 / 30 # 固定 30 FPS +world.apply_settings(settings) + +# Traffic Manager 也需要同步 +tm = client.get_trafficmanager(8000) +tm.set_synchronous_mode(True) + +# 主循环中每帧调用 +world.tick() +``` + +> **重要提示**: 脚本退出时**必须恢复异步模式**,否则仿真器会冻结: +> +> ```python +> settings = world.get_settings() +> settings.synchronous_mode = False +> settings.fixed_delta_seconds = None +> world.apply_settings(settings) +> ``` + +--- + +## Coordinate Systems / 坐标系统 + +CarlaAir 中有两套坐标系统并存,编写脚本时需注意转换: + +| | CARLA | AirSim (NED) | +|---|---|---| +| X | 向前 (East) | 向前 (North) | +| Y | 向右 | 向右 (East) | +| Z | **向上为正** | **向下为正** | + +**关键换算**: AirSim NED z = -CARLA z。例如 CARLA 中 30 米高空 = AirSim NED z = -30。 + +两套 API 的世界原点不同,具体换算关系详见: +`examples_record_demo/COORDINATE_SYSTEMS.md` + +--- + +## Available Maps / 可用地图 + +CarlaAir 内置 6 张城市地图: + +| 地图 Map | 描述 Description | +|---|---| +| **Town01** | 小镇,T 字路口为主,简单路网 | +| **Town02** | 小镇,住宅区风格 | +| **Town03** | 较大城区,环岛和隧道 | +| **Town04** | 高速公路 + 小镇,8 字形高架桥 | +| **Town05** | 多车道城市,方格路网 | +| **Town10HD** | 高清滨海城市(默认地图),最丰富的场景 | + +启动时指定地图 / Launch with specific map: + +```bash +./CarlaAir.sh Town03 +``` + +> **关于 _Opt 变体**: 从 CARLA 官方包中可以获取 `Town01_Opt` 等优化版地图。`_Opt` 变体使用分层加载(Level Streaming),减少显存占用,适合低配 GPU。 + +--- + +## API Reference / API 参考 + +### CARLA Python API (port 2000) + +核心类 / Core classes: +- `carla.Client` — 连接仿真器 +- `carla.World` — 世界管理(天气、Actor、传感器) +- `carla.Actor` — 车辆、行人、传感器等实体 +- `carla.Transform` / `carla.Location` — 位姿与坐标 + +官方文档 / Official docs: https://carla.readthedocs.io/en/0.9.16/ + +### AirSim Python API (port 41451) + +核心类 / Core classes: +- `airsim.MultirotorClient` — 无人机控制 +- `airsim.ImageRequest` — 图像采集请求 + +官方文档 / Official docs: https://microsoft.github.io/AirSim/ + +--- + +## FAQ / Troubleshooting / 常见问题 + +### 仿真器启动相关 + +| 问题 Problem | 解决方案 Solution | +|---|---| +| CARLA 连接超时 | 首次启动需要 2-5 分钟加载资源,请耐心等待。用 `ss -tlnp \| grep 2000` 检查端口 | +| AirSim 连接失败 | AirSim 在 CARLA 之后启动,需额外等待。确认 `~/Documents/AirSim/settings.json` 存在 | +| GPU 显存不足 | Town10HD 需约 8GB 显存。尝试更小地图(Town01)或添加 `-quality-level=Low` | +| 帧率低 | 减少 Actor 数量,降低窗口分辨率,使用较小地图 | + +### 脚本运行相关 + +| 问题 Problem | 解决方案 Solution | +|---|---| +| 无人机不响应指令 | 确保调用了 `enableApiControl(True)` + `armDisarm(True)` + `takeoffAsync().join()` | +| Walker AI Controller 崩溃 | 已知限制,不要对 Walker 调用 `go_to_location()`,仅使用静态 Walker | +| 10+ 车辆 + 无人机崩溃 | 使用 `try_spawn_actor()` 并限制 autopilot 车辆 ≤ 8 辆 | +| 同步模式下仿真器冻结 | 脚本退出前必须恢复异步模式(见上方同步模式章节) | +| `simSetCameraPose` 崩溃 | 在 Shipping 构建中此函数会触发 C++ abort,不要调用。用无人机 yaw + 轨道飞行替代 | +| 车辆行驶异常/抽搐 | 使用 `hybrid_physics_mode` 启用混合物理模式 | +| AirSim 客户端干扰无人机控制 | 使用 `examples_record_demo/record_drone.py` 进行无人机录制 | + +### 坐标与地图相关 + +| 问题 Problem | 解决方案 Solution | +|---|---| +| 无人机位置和 CARLA 车辆位置对不上 | 两套 API 的坐标原点和 Z 轴方向不同,详见 COORDINATE_SYSTEMS.md | +| 如何切换地图 | 启动时指定:`./CarlaAir.sh Town03` | +| 天气变化是否影响无人机 | 是的,`set_weather()` 同时影响地面和空中视角 | \ No newline at end of file