第3章 CarMaker Python API入门

第3章：CarMaker Python API入门：连接CarMaker、启动/停止仿真、获取车辆状态数据

说实话，很多刚接触CarMaker的朋友，第一反应都是：“这工具界面挺炫，但脚本怎么搞？”

我当年也一样。记得第一次打开CarMaker的Python API文档，密密麻麻的类和方法，看得我头皮发麻。但后来我发现，真正核心的操作其实就三件事：连上它、让它跑起来、拿到数据。今天咱们就把这三件事彻底讲透。

3.1 环境准备：你需要的就这几样

在写第一行代码之前，先确认你的环境没问题。我个人习惯用Python 3.8以上版本，CarMaker 8.0及以上都支持。

核心依赖：

CarMaker安装目录下的 PythonAPI 文件夹
确保 PYTHONPATH 环境变量指向该目录
或者直接在代码里 sys.path.append() 添加路径

嗯，这里要注意：千万别用pip install，CarMaker的API是专有的，你得用安装包自带的。

import sys
sys.path.append(r'C:\IPG\CarMaker\8.0\PythonAPI')

import pycar
import pycar.car
import pycar.simulation

我在项目中遇到过有人直接复制路径但忘了改版本号，结果折腾了半小时。你想想看，这种低级错误多冤。

3.2 连接CarMaker：建立你的“通话通道”

连接CarMaker，说白了就是让你的Python脚本和CarMaker的仿真引擎建立通信。CarMaker支持两种模式：

模式	说明	适用场景
本地模式	脚本和CarMaker在同一台机器上运行	日常开发、调试
远程模式	脚本通过网络连接另一台机器上的CarMaker	集群测试、HIL台架

我个人习惯先用本地模式快速验证逻辑。代码很简单：

# 创建CarMaker实例
cm = pycar.CarMaker()

# 连接到本地CarMaker（默认端口9090）
cm.connect('localhost', 9090)

# 检查连接状态
if cm.is_connected():
    print("连接成功！")
else:
    print("连接失败，检查CarMaker是否启动")

小技巧：如果连接失败，先手动打开CarMaker GUI，确认它处于“等待连接”状态。我经常忘了先启动CarMaker，然后对着黑窗口发呆。

3.3 启动/停止仿真：让车跑起来

连接成功后，下一步就是控制仿真。CarMaker的仿真状态机其实就几个状态：IDLE、RUNNING、PAUSED、FINISHED。

启动仿真前，你得先加载一个测试用例（TestRun）。我建议你准备一个简单的测试场景，比如直线加速或者稳态圆周。

# 加载测试用例
cm.load_test_run(r'C:\IPG\CarMaker\8.0\Data\TestRun\MyTest.tst')

# 启动仿真
cm.start_simulation()

# 让仿真跑一会儿（比如5秒）
import time
time.sleep(5)

# 停止仿真
cm.stop_simulation()

我曾经犯过一个错：启动仿真后立刻读取数据，结果全是0。为什么？因为仿真还没开始计算。所以记得加个 time.sleep(0.5) 或者轮询状态。

避坑指南：我曾经在循环里频繁调用 start_simulation() 和 stop_simulation()，结果CarMaker直接卡死。后来发现每次停止后要等状态变为 IDLE 再启动，不能连续操作。

3.4 获取车辆状态数据：真正有价值的部分

仿真跑起来了，怎么拿到车速、方向盘转角、加速度这些数据？CarMaker把车辆状态封装在 Vehicle 对象里。

我个人习惯先获取 Vehicle 引用，然后通过属性名直接读取：

# 获取车辆对象
vehicle = cm.vehicle

# 读取常用状态
speed = vehicle.v     # 车速 (m/s)
steer_angle = vehicle.steer_angle   # 方向盘转角 (deg)
yaw_rate = vehicle.yaw_rate         # 横摆角速度 (deg/s)
accel_x = vehicle.ax                # 纵向加速度 (m/s²)
accel_y = vehicle.ay                # 横向加速度 (m/s²)

print(f"当前车速: {speed*3.6:.1f} km/h")
print(f"方向盘转角: {steer_angle:.1f} deg")

你想想看，这些数据在GUI里也能看，但脚本的优势在于：你可以批量采集、实时判断、自动记录。

3.5 实战：一个完整的采集循环

把上面三步串起来，就是一个完整的脚本化测试流程。我经常用这种结构：

import pycar
import time

# 1. 连接
cm = pycar.CarMaker()
cm.connect('localhost', 9090)

# 2. 加载并启动
cm.load_test_run('MyTest.tst')
cm.start_simulation()

# 3. 等待仿真稳定
time.sleep(1)

# 4. 循环采集数据
data_log = []
for i in range(100):
    speed = cm.vehicle.v * 3.6  # 转成km/h
    steer = cm.vehicle.steer_angle
    data_log.append((i, speed, steer))
    time.sleep(0.1)  # 10Hz采集

# 5. 停止
cm.stop_simulation()
cm.disconnect()

# 6. 打印结果
for t, v, s in data_log[:5]:
    print(f"t={t:.1f}s, v={v:.1f}km/h, steer={s:.1f}deg")

核心要点：

采集频率不要太高，10-50Hz足够，太高会影响仿真实时性
数据采集和仿真控制要分开线程？不需要，CarMaker API是线程安全的
记得在 finally 块里做清理，防止脚本崩溃后CarMaker一直跑着

3.6 知识体系总览

下面这张图是我自己整理的，把本章的核心逻辑串起来了。你一看就明白：

3.7 常见问题与避坑

最后，我把自己踩过的坑整理成清单，你遇到类似问题直接对照：

连接不上：检查CarMaker是否启动、端口是否被占用、防火墙是否拦截
读取数据全是0：仿真还没开始跑，加个 time.sleep(1) 或者轮询 cm.simulation_state
脚本卡死：不要在回调函数里做耗时操作，CarMaker的API调用是同步的
数据跳变：采集频率太高，或者仿真步长太大，建议步长设1ms，采集10ms

我的习惯：每次写脚本前，先手动跑一遍测试用例，确认场景没问题。然后写一个最小化的连接-启动-采集-停止脚本，验证API通路。这一步花不了5分钟，但能省下后面排查问题的一小时。

好了，这一章的内容就到这里。连接、启动、采集，这三板斧你掌握了，CarMaker脚本化测试的大门就算正式打开了。下一章咱们会深入更复杂的场景——参数化测试和批量运行。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录