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.1port默认端口41451与 C 侧 RpcLibServer 保持一致timeout_valueRPC 超时时间默认 3600 秒适合长时间运行的训练任务。MultirotorClient与CarClient均继承该基类并沿用相同的默认参数见 client.py 与 client.py。调用confirmConnection()会每秒检查一次连接状态并在控制台报告进度client.py是官方示例中首选的握手方式。1.2 消息序列化与版本协商所有调用经由msgpackrpc序列化后发送到仿真端。types.py中的MsgpackMixin提供了to_msgpack与from_msgpack两个方法types.py使得自定义数据结构可以自动与 msgpack 编解码格式互相转换。客户端还实现了版本协商机制getClientVersion()返回本地客户端版本号 1getServerVersion()获取服务端版本而getMinRequiredServerVersion()与getMinRequiredClientVersion()用于检查双向最低兼容版本client.py。若版本不匹配confirmConnection()会抛出异常提示升级。二、安装与依赖最小化起步2.1 核心依赖msgpack-rpc-python根据 PythonClient/README.mdPython 包的核心运行依赖是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.pyPythonClient/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.pymoveToPositionAsync(x, y, z, velocity)以指定速度此处 5 m/s飞到目标坐标坐标系为 NED北东地世界系-10高度表示向上 10 米client.pyhoverAsync()悬停。异步 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 arrayImageRequest构造参数为(camera_name, image_type, pixels_as_floatFalse, compressTrue)types.pyImageType枚举types.py支持枚举值含义典型返回Scene场景 RGB 图像压缩 PNG 或未压缩数组DepthPlanar平面深度图浮点数组DepthPerspective透视深度图浮点数组DepthVis深度可视化图PNGDisparityNormalized归一化视差图浮点数组Segmentation语义分割图PNGSurfaceNormals表面法线PNGInfrared红外图像PNGOpticalFlow/OpticalFlowVis光流 / 光流可视化PNG响应对象ImageResponsetypes.py包含image_data_uint8、image_data_float、width、height、camera_position、camera_orientation、time_stamp等字段。示例脚本根据pixels_as_float与compress标志选择三种保存策略浮点像素深度→ 通过airsim.write_pfm()与airsim.get_pfm_array()写出.pfm深度图文件压缩 PNG → 通过airsim.write_file()直接写出.png文件未压缩数组 → 用 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.pyPythonClient/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字段说明throttle油门范围-1 ~ 1正值为前进steering转向-1 ~ 11为右满舵brake刹车0 ~ 11为全力制动handbrake手刹布尔is_manual_gear/manual_gear手动挡开关与挡位倒车时置True与-1gear_immediate是否立即换挡示例中倒车动作的关键写法为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 的完整步骤为准备仿真环境启动 AirSimUnreal/Unity 环境确保 RPC 服务监听默认端口 41451安装依赖执行pip install msgpack-rpc-python如需图像示例再安装 numpy 与 opencv-contrib-python或直接pip install .运行示例进入PythonClient/目录后执行python car/hello_car.py或python multirotor/hello_drone.pysetup_path.py会自动处理模块路径观察输出控制台实时打印状态与传感器数据图像保存到系统临时目录多旋翼为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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考