Skip to content
174 changes: 174 additions & 0 deletions docs/dev/Carla_Air.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
<table>
<tr>
<td width="160" valign="middle" align="center">
<img src="logo_upload.png" alt="CarlaAir Logo" width="140"/>
</td>
<td valign="middle" align="left">
<h1>CarlaAir</h1>
<p><b>在 CARLA 世界里飞无人机。</b><br/>
将 CARLA 与 AirSim 融合为一——地面车辆与空中无人机,同一世界,同一脚本。</p>
<p>
<a href="https://youtu.be/a0fZG2dmT1Q"><img src="https://img.shields.io/badge/版本-v0.1.7-blue" alt="Version"/></a>
<img src="https://img.shields.io/badge/许可证-MIT-yellow.svg" alt="License: MIT"/>
<img src="https://img.shields.io/badge/python-3.8+-blue" alt="Python 3.8+"/>
<img src="https://img.shields.io/badge/CARLA-0.9.16-green" alt="CARLA 0.9.16"/>
<img src="https://img.shields.io/badge/AirSim-1.8.1-orange" alt="AirSim 1.8.1"/>
<img src="https://img.shields.io/badge/平台-Ubuntu%2020.04%20%7C%2022.04-lightgrey" alt="Platform"/>
<img src="https://img.shields.io/badge/arXiv-即将发布-b31b1b" alt="arXiv"/>
</p>
<p>
<a href="README.md">English</a> | <a href="README_CN.md">简体中文</a>
</p>
</td>
</tr>
</table>

<p align="center">
<a href="https://www.bilibili.com/video/BV1pTQzBkES7/">
<img src="teaser_upload.gif" alt="CarlaAir Teaser — 点击观看完整演示视频" width="100%"/>
</a>
</p>

<p align="center">
<i>点击 GIF 或 </i><a href="https://www.bilibili.com/video/BV1pTQzBkES7/"><b>B站观看 30 秒完整演示视频(汉斯·季默配乐)</b></a> 🎵 | <a href="https://youtu.be/a0fZG2dmT1Q">YouTube</a>
</p>

---

## 🔥 最新动态

- **[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 许可证** 开源。
148 changes: 148 additions & 0 deletions docs/dev/FAQ.md
Original file line number Diff line number Diff line change
@@ -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` 变体地图(分层加载,减少显存占用)。
9 changes: 8 additions & 1 deletion docs/dev/add_plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
```

## 其他(和 Carla 兼容)

<!-- 更新至 b3178ba -->

* [融合 CARLA 与 AirSim ](Carla_Air.md)

Loading
Loading