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 环境和依赖：

# 创建 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 会检查所有依赖是否可导入。

配置完成后，激活环境：

conda activate carlaAir

Launch / 启动仿真器

./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 脚本：

python3 examples/quick_start_showcase.py

这个脚本会自动演示 CarlaAir 的核心能力： 1. 在城市中生成一辆 Tesla，无人机起飞并锁定跟踪 2. 车辆沿道路行驶，无人机在上方自动跟随 3. 4 分屏传感器展示：RGB 画面 / 深度图 / 语义分割 / 无人机 FPV 4. 天气自动循环切换（晴天、雨天、雾天、日落等）

操作 / Controls: N 手动切换天气，ESC 退出。

Interactive Demos / 交互式示例

examples/ 目录包含 6 个经过测试的示例脚本，涵盖 CarlaAir 的各项能力：

运行方式 / Usage:

conda activate carlaAir
python3 examples/drive_vehicle.py

Recording Toolkit / 录制工具

examples_record_demo/ 目录提供了轨迹录制与回放工具，用于制作高质量演示视频：

工作流 / 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:

# 开启同步模式
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()

重要提示: 脚本退出时必须恢复异步模式，否则仿真器会冻结：

settings = world.get_settings()
settings.synchronous_mode = False
settings.fixed_delta_seconds = None
world.apply_settings(settings)

Coordinate Systems / 坐标系统

CarlaAir 中有两套坐标系统并存，编写脚本时需注意转换：

关键换算: AirSim NED z = -CARLA z。例如 CARLA 中 30 米高空 = AirSim NED z = -30。

两套 API 的世界原点不同，具体换算关系详见： examples_record_demo/COORDINATE_SYSTEMS.md

Available Maps / 可用地图

CarlaAir 内置 6 张城市地图：

启动时指定地图 / Launch with specific map:

./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 / 常见问题

仿真器启动相关

脚本运行相关

坐标与地图相关