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 @@
+
+
+
+
+
+
+
+
+
+ 点击 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