CARLA + AirSim 集成开发进度记录

最后更新：2026-03-11

一、项目概述

目标： 在 CARLA 城镇地图中飞行 AirSim 无人机，两套 API 在同一个 UE4 进程中同时工作。

当前状态： ✅ 完全可用 — ASimWorldGameMode 统一 GameMode，CARLA 所有功能（天气、车辆/行人生成、Traffic Manager、OpenDRIVE）+ AirSim 无人机飞行同时工作。

技术架构： - 单个 UE4 Editor 进程同时运行 CARLA 和 AirSim - GameMode：使用统一的 ASimWorldGameMode（继承自 ACarlaGameModeBase，同时集成 AirSim 引导逻辑） - GameInstance：使用 CARLA 的 CarlaGameInstance（在 DefaultEngine.ini 中配置） - AirSim 的 ASimModeBase 作为普通 Actor 由 GameMode 在 BeginPlay 中 Spawn - CARLA Episode 由 ACarlaGameModeBase 构造函数创建，在 BeginPlay() 中初始化（通过继承自动完成）

硬件环境： - GPU: NVIDIA RTX A4000, 16GB VRAM - 系统: Linux (Ubuntu)

二、关键路径

三、功能状态总览

✅ 已可用功能（基础，早期实现）

✅ 新恢复功能（通过统一 GameMode，2026-03-04）

已解决的根本问题

GameMode 冲突（核心问题）： UE4 每个 World 只允许一个 GameMode。之前使用 AirSim 的 GameMode 导致 30+ 个 CARLA 功能不可用。

解决方案： 创建 ASimWorldGameMode（继承自 ACarlaGameModeBase）： - 所有 CARLA 功能通过继承获得（天气、车辆生成、OpenDRIVE 等） - AirSim 引导逻辑从 ASimHUD 移植到 GameMode 的 BeginPlay 中 - ASimModeBase 作为普通 Actor 被 Spawn，不再竞争 GameMode 槽位 - 构造函数中手动设置 WeatherClass（BP_Weather）和 ActorFactories（8 个工厂类）

四、已修改的源码文件

新建文件

修改文件

五、已修复的关键 Bug

六-B、测试脚本状态

test_script/ 目录（核心应用脚本）

examples/ 目录（示例/验证脚本）

已知限制

六、编译命令

# 设置环境变量
export UE4_ROOT=/mnt/data1/tianle/carla_ue4

# 仅编译 Carla 模块（约 290 秒）
${UE4_ROOT}/Engine/Build/BatchFiles/Linux/Build.sh CarlaUE4Editor Linux Development \
  -project="/mnt/data1/tianle/carla_source/Unreal/CarlaUE4/CarlaUE4.uproject" \
  -module=Carla

# 仅编译 AirSim 模块（约 100 秒）
${UE4_ROOT}/Engine/Build/BatchFiles/Linux/Build.sh CarlaUE4Editor Linux Development \
  -project="/mnt/data1/tianle/carla_source/Unreal/CarlaUE4/CarlaUE4.uproject" \
  -module=AirSim

⚠️ 注意：不要使用 make CarlaUE4Editor，会因 features.h 交叉编译错误而失败。

七、一键启动 — carlaAir.sh

基本用法

cd /mnt/data1/tianle/carla_source

# 默认启动（Town10HD, 1280x720, 低画质）
./carlaAir.sh

# 指定地图
./carlaAir.sh Town03

# 自定义分辨率
./carlaAir.sh Town10HD 1920 1080

# 前台运行（可看到所有日志）
./carlaAir.sh --fg

# 停止运行
./carlaAir.sh --kill

# 查看实时日志
./carlaAir.sh --log

# 查看帮助
./carlaAir.sh --help

启动流程

1. 脚本检查是否有已运行的实例
2. 设置 DISPLAY 和 Vulkan 环境变量
3. 后台启动 UE4Editor
4. 自动轮询 CARLA (2000) 和 AirSim (41451) 端口
5. 两个端口都就绪后打印 "Ready!" 并提供测试命令

启动参数说明

八、AirSim 配置

文件路径： /home/tianle/Documents/AirSim/settings.json

{
    "SettingsVersion": 1.2,
    "SimMode": "Multirotor",
    "Vehicles": {
        "SimpleFlight": {
            "VehicleType": "SimpleFlight",
            "AutoCreate": true,
            "Cameras": {
                "0": {
                    "CaptureSettings": [
                        { "ImageType": 0, "Width": 1280, "Height": 960 }
                    ],
                    "X": 0.5, "Y": 0.0, "Z": 0.1,
                    "Pitch": 0.0, "Roll": 0.0, "Yaw": 0.0
                }
            }
        }
    }
}

注意：统一 GameMode 下 level_name 设置被忽略，地图由启动命令指定。

九、可用地图

各地图均有 _Opt 变体版本可用。切换地图：./carlaAir.sh Town03

十、开发时间线

十一、Shipping 独立包

打包过程

export UE4_ROOT=/mnt/data1/tianle/carla_ue4
cd /mnt/data1/tianle/carla_source
./Util/BuildTools/Package.sh --config=Shipping --no-zip

编译：656 个编译单元，~805 秒 Cook：13459 个 packages，~2 小时 输出：/mnt/data1/tianle/carla_source/Dist/CARLA_Shipping_1ae5356-dirty/LinuxNoEditor/（19GB）

打包前配置修改

DefaultGame.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")
+MapsToCook=(FilePath="/AirSim/AirSimAssets")

包含地图（13 张）

Town01, Town01_Opt, Town02, Town02_Opt, Town03, Town03_Opt, Town04, Town04_Opt, Town05, Town05_Opt, Town10HD, Town10HD_Opt, Town10HD_Opt_NavMesh

独立包启动

cd /mnt/data1/tianle/carla_source/Dist/CARLA_Shipping_1ae5356-dirty/LinuxNoEditor
./SimWorld.sh Town10HD              # 默认启动
./SimWorld.sh Town03 --res 1920x1080  # 指定地图和分辨率
./SimWorld.sh --kill                # 停止

独立包脚本清单

十二、坐标系映射（CARLA ↔ AirSim）

2026-03-11 更新：修复 SetNewWorldOrigin Bug 后，NED 坐标与 CARLA 坐标对齐（x 相同，y 相同，z 取反）。

坐标转换： - CARLA (x, y, z) → AirSim NED: x 相同，y 相同，z 取反 - 无人机到城市中心：moveToPositionAsync(80, 30, -25, speed) 对应 CARLA (80, 30) 上方 25m

跟随策略：使用相对偏移法 1. 记录车辆初始 CARLA 坐标 (car_x0, car_y0) 和无人机初始 AirSim 坐标 (drone_x0, drone_y0) 2. 每帧计算车辆位移 dx = car_x - car_x0, dy = car_y - car_y0 3. 目标无人机位置 = (drone_x0 + dx, drone_y0 + dy, -altitude)

十三、全面 API 测试报告 (2026-03-06)

89 项测试，全部通过 (89 PASS / 0 FAIL / 0 SKIP)

关键数据

十四、车辆穿地 Bug 修复 (2026-03-11)

问题描述

在 CarlaAir 中通过 CARLA API 生成的地面车辆会立即穿过地面，掉落约 30 米（从 z≈0.6 到 z≈-29.6）。而在原版 CARLA（无 AirSim 插件）中，相同操作完全正常（z≈0.0）。此 Bug 影响 Editor 和 Shipping 两种构建。

排查过程

1. 对比测试：原版 CARLA（/home/tianle/carla/CARLA_Latest/）加载 Town10HD_Opt，车辆 z≈0.0 正常；CarlaAir 加载 Town10HD，车辆 z≈-29.6 穿地
2. 排除地图因素：CarlaAir 使用 Town10HD_Opt 仍然穿地 → 不是地图问题
3. 确认 AirSim 插件为根因：唯一区别是 AirSim 插件的存在

根本原因

文件: Plugins/AirSim/Source/SimMode/SimModeBase.cpp，第 121 行

// BeginPlay() 中：
this->GetWorld()->SetNewWorldOrigin(FIntVector(player_loc) + this->GetWorld()->OriginLocation);

机制： 1. ASimModeBase::BeginPlay() 获取 PlayerStart/ViewTarget 的位置（Town10HD 中 PlayerStart 在海岸，z≈30m） 2. 调用 SetNewWorldOrigin() 将 UE4 世界坐标原点移到该位置 3. 此操作导致 Landscape/道路碰撞几何体失效 — UE4 的 PhysX 不正确地更新了地面碰撞 4. CARLA 车辆生成在 z=0.6（来自 OpenDRIVE 数据），但地面碰撞已不存在 5. 重力将车辆拉到 z≈-30（穿过不可见的地面）

为什么无人机不受影响：AirSim 的 Multirotor 使用自定义 FastPhysicsEngine，不依赖 UE4 Landscape 碰撞；而 CARLA 车辆使用 UE4 原生 PhysX，依赖 Landscape 碰撞体。

修复方案

注释掉 SetNewWorldOrigin() 调用，保留 NedTransform 使用原始 player_start_transform 作为 NED 坐标原点：

// 修复前（SimModeBase.cpp:117-125）:
player_start_transform = fpv_pawn->GetActorTransform();
player_loc = player_start_transform.GetLocation();
this->GetWorld()->SetNewWorldOrigin(FIntVector(player_loc) + this->GetWorld()->OriginLocation);
player_start_transform = fpv_pawn->GetActorTransform();
global_ned_transform_.reset(new NedTransform(player_start_transform, ...));

// 修复后:
player_start_transform = fpv_pawn->GetActorTransform();
player_loc = player_start_transform.GetLocation();
// NOTE: Do NOT call SetNewWorldOrigin() — it breaks CARLA's landscape collision
global_ned_transform_.reset(new NedTransform(player_start_transform, ...));

验证结果

坐标系影响

修复后坐标系映射更新：

十五、示例脚本完整列表 (2026-03-09)

时间线

• 2026-03-06: 创建前 8 个脚本 (walk_fpv, fly_drone_pygame, drive_car, 4 个 showcase, showcase_maps)
• 2026-03-09: 修复 showcase_traffic.py 崩溃问题，创建并测试最后 4 个脚本

已知限制

脚本分类与测试结果

A. 交互控制 (3 个) — 用户手动操控

B. 展示 (5 个) — 自动运行，展示功能

C. 联合应用 (4 个) — CARLA + AirSim 协同

合计: 12 个脚本，全部通过测试

• 纯 CARLA: 5 个
• 纯 AirSim: 2 个
• CARLA + AirSim 联合: 5 个

十五、分发包 (2026-03-10)

打包信息

排除内容（节省 ~2GB）

• Debug 符号：CarlaUE4-Linux-Shipping.debug（1.6GB）+ .sym（80MB）
• Manifest 文件、Dockerfile、__pycache__
• 根目录测试脚本（test_package.py、comprehensive_api_test.py 等）

包内目录结构

SimWorld/
├── SimWorld.sh              # 主启动器
├── README_SimWorld.md       # 使用文档
├── AirSimConfig/            # AirSim 配置模板
├── examples/                # 16 个 Python 示例脚本
├── CarlaUE4/                # UE4 二进制 + 内容 + 插件
├── Engine/                  # UE4 引擎依赖
├── PythonAPI/               # CARLA Python API 源码
├── HDMaps/                  # HD 点云地图
└── Co-Simulation/           # 联合仿真桥接

目标机器要求

• Ubuntu 18.04/20.04/22.04 (x86_64)
• NVIDIA GPU + 驱动 470+（Vulkan 支持）
• 16GB+ RAM, 20GB+ 磁盘空间
• Python 3.8+, pip: carla==0.9.15 airsim pygame numpy Pillow

部署步骤

# 1. 解压
tar xzf SimWorld_20260309.tar.gz

# 2. 安装 Python 依赖
pip install carla==0.9.15 airsim pygame numpy Pillow

# 3. 配置 AirSim
mkdir -p ~/Documents/AirSim
cp SimWorld/AirSimConfig/settings.json.example ~/Documents/AirSim/settings.json

# 4. 启动模拟器
cd SimWorld && ./SimWorld.sh

# 5. 运行示例
python3 examples/drive_car.py

十六、v0.1 Release 测试 (2026-03-10)

时间线

• 2026-03-10: 执行 v0.1 Release 前全部测试任务（T1-T6）
• 2026-03-10: 编写测试报告，判定 Release Readiness

测试结果总览

Release Readiness: ✅ Ready for Release

更新后的已知限制

详细报告

完整测试报告：/mnt/data1/tianle/carla_source/Progress_record/v0.1_release_test_report.md