AirSim Python API 入门指南：从安装、连接控制到多旋翼与汽车示例

AirSim Python API 入门指南：从安装、连接控制到多旋翼与汽车示例

【免费下载链接】AirSimOpen source simulator for autonomous vehicles built on Unreal Engine / Unity, from Microsoft AI & Research项目地址: https://gitcode.com/gh_mirrors/ai/AirSim

本篇技术指南以 AirSim 仓库中 PythonClient/README.md 为主体，系统讲解 Python API 包的安装方式、依赖关系、模块结构，以及hello_car.py与hello_drone.py两个官方入门示例的完整运行流程，并结合 client.py、types.py 等源码补充底层调用机制，帮助读者快速掌握用 Python 驱动多旋翼无人机与汽车、采集图像与传感器数据的实战能力。

一、Python API 包概览：AirSim 的 Python 客户端

AirSim 是一个基于 Unreal Engine / Unity 的开源自驾仿真器，其核心仿真逻辑运行在 C++ 侧，而 Python API 包则是面向研究者和算法工程师的官方客户端。该包位于仓库的PythonClient/目录下，通过msgpack-rpc协议与仿真端通信，为无人机（多旋翼）和汽车两类载体提供了统一的操作接口。

包的核心模块结构如下：

• PythonClient/airsim/client.py：定义VehicleClient基类及其两个子类MultirotorClient与CarClient，封装了绝大多数 RPC 调用；
• PythonClient/airsim/types.py：定义与 C++ 侧一一对应的数据结构，如Vector3r、Quaternionr、Pose、GeoPoint、ImageRequest、ImageResponse、CarControls、DrivetrainType、WeatherParameter等；
• PythonClient/airsim/utils.py：提供类型转换与文件写入工具，例如将二进制字符串转为 NumPy 数组、读写 PFM 深度图、四元数与欧拉角互转等；
• PythonClient/airsim/init.py：汇总导出client、utils、types三个子模块的符号，并声明包版本号__version__ = "1.8.1"。

1.1 连接机制：msgpack-rpc 与默认端口

VehicleClient的构造函数（client.py）展示了客户端连接的关键参数：

class VehicleClient: def __init__(self, ip = "", port = 41451, timeout_value = 3600): if (ip == ""): ip = "127.0.0.1" self.client = msgpackrpc.Client(msgpackrpc.Address(ip, port), timeout = timeout_value, pack_encoding = 'utf-8', unpack_encoding = 'utf-8')

• ip：仿真端主机地址，默认空字符串时回退为127.0.0.1；
• port：默认端口41451，与 C++ 侧 RpcLibServer 保持一致；
• timeout_value：RPC 超时时间，默认 3600 秒，适合长时间运行的训练任务。

MultirotorClient与CarClient均继承该基类并沿用相同的默认参数（见 client.py 与 client.py）。调用confirmConnection()会每秒检查一次连接状态并在控制台报告进度（client.py），是官方示例中首选的握手方式。

1.2 消息序列化与版本协商

所有调用经由msgpackrpc序列化后发送到仿真端。types.py中的MsgpackMixin提供了to_msgpack与from_msgpack两个方法（types.py），使得自定义数据结构可以自动与 msgpack 编解码格式互相转换。

客户端还实现了版本协商机制：getClientVersion()返回本地客户端版本号 1，getServerVersion()获取服务端版本，而getMinRequiredServerVersion()与getMinRequiredClientVersion()用于检查双向最低兼容版本（client.py）。若版本不匹配，confirmConnection()会抛出异常提示升级。

二、安装与依赖：最小化起步

2.1 核心依赖：msgpack-rpc-python

根据 PythonClient/README.md，Python 包的核心运行依赖是msgpack-rpc-python，其内部会传递依赖msgpack。官方 README 给出的安装命令为：

pip install msgpack-rpc-python

在 Windows 等受限环境下，该安装可能需要管理员/提权提示（administrator/sudo prompt）。同时，setup.py 中install_requires声明了完整的安装依赖：

install_requires=[ 'msgpack-rpc-python', 'numpy', 'opencv-contrib-python' ]

即numpy（用于图像数组处理）与opencv-contrib-python（用于图像读写与部分示例的视觉处理）也是必要依赖。

2.2 直接 pip 安装

从 setup.py 可以看出，该包符合标准 setuptools 结构（包名airsim，版本号取自airsim.__version__，即 1.8.1），因此既可以直接从仓库根目录安装，也可以作为本地包使用：

cd PythonClient pip install .

2.3 免安装直接运行：setup_path 机制

官方示例脚本（如hello_car.py、hello_drone.py）第一行都会import setup_path。这个模块的核心作用是自动把本地airsim包目录加入sys.path：它会先检查当前脚本的父目录是否存在airsim文件夹及其client.py，若存在则将其加入模块搜索路径；否则回退使用 pip 已安装的airsim包（见 PythonClient/car/setup_path.py）。这意味着：

• 从PythonClient/仓库目录直接运行示例，无需提前pip install；
• 已通过 pip 安装的用户，setup_path不会覆盖已安装的包。

三、官方入门示例解析

3.1 多旋翼示例：hello_drone.py

PythonClient/multirotor/hello_drone.py 完整演示了一架多旋翼从连接、起飞、飞行到复位清理的完整生命周期，其流程为：

import setup_path import airsim import numpy as np import os import tempfile import pprint import cv2 # connect to the AirSim simulator client = airsim.MultirotorClient() client.confirmConnection() client.enableApiControl(True) state = client.getMultirotorState() s = pprint.pformat(state) print("state: %s" % s)

3.1.1 API 控制与传感器数据读取

• enableApiControl(True)：启用 API 控制，之后仿真端才接受来自 Python 端的运动指令（client.py）。不调用该接口时，API 调用默认会被忽略；
• getMultirotorState()：返回飞行状态；示例还依次打印getImuData()（IMU）、getBarometerData()（气压计）、getMagnetometerData()（磁力计）、getGpsData()（GPS）等传感器数据。

3.1.2 起飞与移动

airsim.wait_key('Press any key to takeoff') print("Taking off...") client.armDisarm(True) client.takeoffAsync().join() client.moveToPositionAsync(-10, 10, -10, 5).join() client.hoverAsync().join()

• armDisarm(True)：解锁（armed），是起飞前的必调操作；
• takeoffAsync()：默认起飞至离地 3 米，可传timeout_sec参数，默认 20 秒（client.py）；
• moveToPositionAsync(x, y, z, velocity)：以指定速度（此处 5 m/s）飞到目标坐标，坐标系为 NED（北东地）世界系，-10高度表示向上 10 米（client.py）；
• hoverAsync()：悬停。

异步 API 约定：所有*Async方法均返回msgpackrpc.future.Future对象，必须调用.join()阻塞等待指令完成，这是 AirSim Python API 的核心使用模式。除上述移动指令外，MultirotorClient还提供moveByVelocityAsync、moveOnPathAsync、moveToZAsync、landAsync、goHomeAsync等成套运动控制接口（见 client.py），以及 Yaw 偏航控制参数YawMode与DrivetrainType驱动类型枚举（定义于 types.py 与 types.py）。

3.1.3 图像采集与保存

responses = client.simGetImages([ airsim.ImageRequest("0", airsim.ImageType.DepthVis), #depth visualization image airsim.ImageRequest("1", airsim.ImageType.DepthPerspective, True), #depth in perspective projection airsim.ImageRequest("1", airsim.ImageType.Scene), #scene vision image in png format airsim.ImageRequest("1", airsim.ImageType.Scene, False, False)]) #scene vision image in uncompressed RGBA array

ImageRequest构造参数为(camera_name, image_type, pixels_as_float=False, compress=True)（types.py），ImageType枚举（types.py）支持：

响应对象ImageResponse（types.py）包含image_data_uint8、image_data_float、width、height、camera_position、camera_orientation、time_stamp等字段。示例脚本根据pixels_as_float与compress标志选择三种保存策略：

1. 浮点像素（深度）→ 通过airsim.write_pfm()与airsim.get_pfm_array()写出.pfm深度图文件；
2. 压缩 PNG → 通过airsim.write_file()直接写出.png文件；
3. 未压缩数组 → 用 NumPy 转成H x W x 3形状后经cv2.imwrite()保存。

3.1.4 复位与收尾

client.reset() client.armDisarm(False) client.enableApiControl(False)

reset()将载具复位到初始状态，但复位后必须重新调用enableApiControl与armDisarm（见 client.py 的 docstring 说明）。最后关闭 API 控制并退出。

3.2 汽车示例：hello_car.py

PythonClient/car/hello_car.py 演示了CarClient的用法：连接后启用 API 控制，然后通过CarControls结构循环执行“前进 → 前进+右转 → 倒车 → 刹车”四个动作，每步time.sleep(3)让车辆实际行驶，并同步打印getCarState()返回的速度与挡位信息：

client = airsim.CarClient() client.confirmConnection() client.enableApiControl(True) print("API Control enabled: %s" % client.isApiControlEnabled()) car_controls = airsim.CarControls() # go forward car_controls.throttle = 0.5 car_controls.steering = 0 client.setCarControls(car_controls) print("Go Forward") time.sleep(3)

CarControls的全部字段定义于 types.py：

示例中倒车动作的关键写法为car_controls.is_manual_gear = True; car_controls.manual_gear = -1，结束后再恢复自动挡。刹车段则将car_controls.brake = 1后再清零。循环末尾同样使用simGetImages()采集四种图像并保存到系统临时目录airsim_car下，最后reset()并关闭 API 控制。

四、底层实现：Python 客户端与 C++ 服务端的调用链

从源码结构看，Python API 的每次调用都遵循“msgpack-rpc 请求 → 服务端 RPC 分发 → C++ 仿真内核”的链路：client.py中的方法通过self.client.call('methodName', args...)（同步）或self.client.call_async('methodName', args...)（异步）发出请求；请求由 C++ 侧 RpcLibServer 接收并分发到对应载具实现。enableApiControl、armDisarm、reset、simPause、simContinueForTime、getHomeGeoPoint等通用接口定义在VehicleClient基类中，保证两类载具的行为一致性。

• 同步调用如client.simGetImages()会阻塞等待完整响应（client.py），返回的原始数据经ImageResponse.from_msgpack()反序列化为结构化对象；
• 异步调用如takeoffAsync()、moveToPositionAsync()返回 Future，适合编排复杂飞行序列。

这种设计使得 Python 客户端仅需维护 msgpack 序列化协议即可对接 C++ 内核，无需直接操作仿真引擎。

五、快速上手清单与延伸资源

按照官方 README 与示例脚本，从零开始运行 Python API 的完整步骤为：

1. 准备仿真环境：启动 AirSim（Unreal/Unity 环境），确保 RPC 服务监听默认端口 41451；
2. 安装依赖：执行pip install msgpack-rpc-python（如需图像示例，再安装 numpy 与 opencv-contrib-python，或直接pip install .）；
3. 运行示例：进入PythonClient/目录后执行python car/hello_car.py或python multirotor/hello_drone.py（setup_path.py会自动处理模块路径）；
4. 观察输出：控制台实时打印状态与传感器数据，图像保存到系统临时目录（多旋翼为airsim_drone，汽车为airsim_car）。

PythonClient/目录下还提供了大量面向具体场景的进阶示例，可作为进一步学习的起点：

• 计算机视觉：computer_vision/（图像采集、分割、深度、光流）、eventcamera_sim/（事件相机仿真）；
• 传感器与点云：multirotor/drone_lidar.py、sensorframe_lidar_pointcloud.py、vehicleframe_lidar_pointcloud.py；
• 强化学习：reinforcement_learning/dqn_car.py、dqn_drone.py；
• 多机与复现：multirotor/multi_agent_drone.py、car/multi_agent_car.py。

六、总结

本文围绕 PythonClient/README.md 展开，完整覆盖了 AirSim Python API 的依赖安装、setup_path免安装运行机制、MultirotorClient与CarClient的连接与状态读取、异步飞行控制、ImageRequest/ImageResponse图像采集与三种保存策略，以及CarControls的驾驶控制字段，并结合 client.py、types.py、setup.py 等源码进行了底层印证。掌握这些内容后，即可编写自己的 Python 脚本控制 AirSim 中的无人机与汽车，开展数据采集、算法验证与强化学习实验。

【免费下载链接】AirSimOpen source simulator for autonomous vehicles built on Unreal Engine / Unity, from Microsoft AI & Research项目地址: https://gitcode.com/gh_mirrors/ai/AirSim