简介：《虚拟测试驾驶（VTD）用户手册》是 VIRES Simulationstechnologie GmbH 发布的官方技术文档，面向使用 VTD 开展自动驾驶仿真测试的工程师、研究人员与第三方开发者，帮助其在真实道路试验之前，于高度还原的虚拟环境中搭建道路网络、交通信号、动态车辆与行人、天气光照等场景，验证感知、决策与控制算法。手册共 140 页，内容从概览与参考文献、故障排查，到资源准备与快速安装（系统要求、全新安装、AddOns 扩展组件、即时更新），再到配置体系中的基本概念、发行版、Setups 与 Projects，并延伸至入门操作，形成由环境搭建到场景运行的完整指引。资源包为 1 个 PDF 文件，约 4.4MB，单文件即涵盖全部章节，便于按目录检索与随查随用。目前已有 749 人学习下载。读者可借助它掌握软硬件配置门槛、安装与许可设置流程、扩展组件管理方法以及常见异常的诊断思路，从而更高效地组织复杂自动驾驶仿真测试，提升测试的安全性与可复现性。
1. 仿真跑不通的时候，我先把这份 140 页的手册摊在桌上
自动驾驶仿真最费时间的环节，往往不是场景建不出来，而是环境搭好了、进程都起来了、画面也有了，车却不动，或者动了但位置偏了十几米。这类问题不会给你堆栈，只会安静地错下去。VTD 的用户手册就是为这种时刻准备的：2021 年 1 月发布的 Issue O，140 页，从系统要求、安装、目录结构一路写到 TaskControl 和图像生成器，把一整套虚拟测试驾驶的配置链路摊开讲。它适合三类人：刚接手一套别人留下的仿真环境、说不清哪个配置在起作用的；要给团队做环境标准化、需要一份可对照的基准文档的；以及已经把场景跑起来、但结果反复对不上的。这不是一本从第一页读到最后一页的教程，读法比读本身更重要。
2. 先立骨架：140 页手册的五段式结构和三级别配置
拿到一份上百页的 PDF，最亏的用法是从第 1 页开始顺序读。这份手册的组织方式其实很清楚：第 1 章讲这套工具是干什么的，第 2 章讲怎么装起来跑通，第 3 章定坐标系和单位，第 4、5 章讲系统组件和文件管理，第 6 章才是各组件的细节。前五章加起来不到 50 页，但决定了后面 90 页你能不能看懂。
2.1 先确认手里是哪一版，再谈操作
手册的封面页信息量比看上去大：Document No. VI2008.076、Issue O、日期 01.01.2021、总页数 140、发行方是某仿真软件厂商、分发对象标注为 VTD 用户和第三方。里面最该记住的是那个 Issue 字母，它代表修订批次。同一份工程在两台机器上跑出不一样的结果，第一件事不是查代码，而是把两边的手册 Issue 对一遍——章节编号、配置字段名、默认值在不同 Issue 之间是会挪位置的。
常见做法是把这个头部信息抄进团队的环境说明文档里，和发行版路径、Setup 名称放在一起。看起来是多此一举，等半年后有人问「这套配置是哪来的」，这份记录就是唯一的线索。
提示：手册第 1.3 节 Troubleshooting 只有一页，别指望它给出完整答案，它的作用更像索引——把你导向后面具体的组件章节。真遇到问题，从第 5 章文件管理和第 6 章组件细节里找，命中率更高。
2.2 Distribution、Setup、Project：三个词搞混，后面全乱
第 2.3 节把配置拆成三层，这是整份手册里最该先吃透的部分。很多翻车现场，根子都在这三个词的边界没划清。
| 层级 | 是什么 | 放在哪 | 谁改它 | 改动影响面 |
|---|---|---|---|---|
| Distribution | 软件发行版本体，含可执行程序、基础数据库、默认资源 | 独立目录，按版本号区分 | 升级时整体替换，不做局部修改 | 所有引用它的 Setup |
| Setup | 一套指向某个 Distribution 的配置集合，定义各组件的路径、通信、搜索顺序 | 用户配置区 | 环境维护者 | 引用它的所有 Project |
| Project | 具体工程，含场景选择、车辆参数、测试用例配置 | 工程目录 | 具体做测试的人 | 仅本项目 |
关系是单向的：Project 引用 Setup，Setup 引用 Distribution。改了 Distribution 里的一份默认数据库，所有 Setup 都会跟着变；改了一个 Setup 的搜索路径，挂在它下面的所有 Project 一起受影响。所以升级时的稳妥做法是新装一个 Distribution、复制一份 Setup 指过去、先让一个 Project 验证，跑通了再切其他工程。直接覆盖旧 Distribution 是最省事也最后悔的操作——旧工程跑不起来的时候，你连回退的锚点都没有。
手册 2.3.1 到 2.3.4 这四小节把这个概念讲得很短，但配图值得反复看：图上标的箭头方向就是依赖方向，顺着箭头排查，比凭记忆猜快得多。
2.3 第一次跑通走 GUI 快速路径，别一上来就动配置文件
第 2.4 节给了两条启动路径：一条是 GUI 快速版，一条是慢速版（配置—启动—再配置的循环）。新手直接上慢速版，多半会在某个中间状态卡住，因为你还不知道「正常」长什么样。
快速路径的顺序是固定的：先核对系统要求，再执行新安装，然后按需装 AddOns、打增量更新，接着选一套配置，最后从 GUI 启动。装完先别急着改任何东西，用默认配置把一次仿真从头跑到尾，看三件事——仿真时间在往前走、场景里的车在动、画面有更新。这三件事都成立，说明链路是通的，后面改配置才有参照。
系统要求那一节（2.2.1）别只看最低配置，重点看图形相关的条目。这套工具的图像生成对显卡驱动版本敏感，驱动落后一两个大版本，表现往往不是报错，而是画面撕裂或者帧率莫名其妙掉一半。装机前的核对我一般用几条命令过一遍，把结果贴进环境记录：
# 核对 CPU 与内存，确认核数和主频满足手册 2.2.1 的推荐档 lscpu | grep -E "Model name|^CPU\(s\)" free -h # 核对显卡与驱动版本，这一项最容易和手册要求对不上 nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv # 核对磁盘余量，场景数据库和录制的仿真数据都很占空间 df -h /opt /home这几条命令本身没什么技术含量，价值在于把「我觉得机器够用」变成可对照的记录。显卡那一行的驱动版本，和你后来遇到的所有渲染类问题都有关联，出问题时能直接比对，省掉一轮猜测。
安装完到 AddOns 这一步（2.2.3），我的建议是第一次只装必需项。附加的车辆模型、地图数据、测试工具，装得越多，出问题时需要排除的变量越多。Ad-hoc 更新（2.2.4）同理，环境刚搭好、还没验证稳定之前不要打增量更新，否则一旦出问题，你分不清是安装本身的问题还是更新引入的。
2.4 目录树不是背下来的，是查出来的
第 5 章讲文件管理，5.5 节的三棵子树各有分工，这个划分方式直接决定了你该往哪儿放东西：
| 目录 | 内容 | 是否该手工修改 |
|---|---|---|
| Data | 场景、路网、车辆模型、天气与纹理等资源数据 | 可以，但要清楚哪些被多个工程共用 |
| Runtime | 可执行程序、动态库、插件 | 不建议，升级会整体替换 |
| Develop | 头文件、样例、自定义组件开发所需材料 | 是，自定义组件通常从这里起步 |
5.4 节的 File Finding 值得单独说：文件不是靠绝对路径找的，而是靠 Setup 里定义的搜索路径按顺序匹配。这意味着同一个文件名在两个目录下都存在时，谁在前面谁生效——这是一种「玄学」式的故障来源，因为配置文件里写的名字完全正确，加载出来的却是另一个东西。排查这类问题的办法是临时把搜索路径收窄到一项，看文件还能不能找到，能就说明问题不在路径而在重名。
3. 坐标系和单位对不上：仿真里最贵的一类错误
场景建得再漂亮，坐标系错一个符号，整场测试的数据就全废了。这类错误的特点是前期完全静默：车在画面里跑得好好的，只是位置往左偏了，或者记录的轨迹和真值对不上。手册第 3 章只有两页多，但它是后面所有数值的地基。
3.1 三个坐标系各管一段，别混着用
手册 3.2 节把坐标系分成惯性系、车辆系、屏幕系，另外还有「其他坐标系」一节留给各组件自己的约定。
| 坐标系 | 原点 | 轴向约定 | 单位 | 典型用途 | 高频错法 |
|---|---|---|---|---|---|
| 惯性系 Inertial | 场景全局参考点 | 右手系，Z 轴向上 | 米 | 场景内所有物体的绝对位置、轨迹记录 | 把场景原点和地图原点当成同一个 |
| 车辆系 Vehicle | 车辆参考点（通常在后轴中心或定义点） | X 纵向、Y 横向、Z 向上 | 米 | 传感器安装位置、相对运动计算 | 参考点选错，导致所有传感器外参偏一个常量 |
| 屏幕系 Screen | 图像左上角 | Y 轴向下 | 像素 | 图像标注、投影框、视觉算法输入 | 直接把像素坐标当米用 |
| 其他 | 由组件定义 | 见各组件章节 | 视组件而定 | 相机、雷达等传感器局部坐标 | 跨组件传递时没做换算 |
最常见的错误组合是惯性系和车辆系混用：外部算法拿到的是惯性系下的绝对位姿，内部传感器模型却按车辆系解释，结果就是每一帧都带着一个随位置变化的偏移量。这个偏移在场景原点附近很小，跑远了就变得离谱，所以调试时如果在原点附近测，很容易得出「没问题」的错误结论。
3.2 用一段脚本把换算关系钉死
坐标换算本身不难，难的是让团队里每个人对「heading 正方向是哪边」有同一个答案。我的做法是写一段往返验证的小脚本，放进工程的工具目录，谁有疑问就跑一遍：
import math def inertial_to_vehicle(px, py, pz, ref_x, ref_y, ref_z, heading_rad): """惯性系坐标转车辆系坐标。 px/py/pz: 待转换点在惯性系下的坐标，单位米 ref_x/ref_y: 车辆参考点在惯性系下的平面坐标 ref_z: 车辆参考点高程 heading_rad: 车体 X 轴相对惯性系 X 轴的偏航角，弧度，逆时针为正 """ dx, dy, dz = px - ref_x, py - ref_y, pz - ref_z # 先平移再旋转，旋转方向与 heading 定义相反，所以取负角 c, s = math.cos(-heading_rad), math.sin(-heading_rad) vx = c * dx - s * dy vy = s * dx + c * dy return vx, vy, dz def vehicle_to_inertial(vx, vy, vz, ref_x, ref_y, ref_z, heading_rad): """反向换算，用于验证上面那个函数没有写反""" c, s = math.cos(heading_rad), math.sin(heading_rad) px = c * vx - s * vy + ref_x py = s * vx + c * vy + ref_y return px, py, vz + ref_z # 往返验证：任取一点，转过去再转回来，误差应在浮点精度内 p = (120.5, -33.2, 0.8) ref = (100.0, -30.0, 0.5) h = math.radians(37.0) v = inertial_to_vehicle(*p, *ref, h) back = vehicle_to_inertial(*v, *ref, h) assert max(abs(a - b) for a, b in zip(p, back)) < 1e-9 print("往返一致，换算方向正确")这段脚本真正的用途不是算数，而是把约定写成可执行的断言。参数里的heading_rad用的是逆时针为正的定义，如果你的手册版本或者上游接口给的是顺时针，那这一行取负号的位置就要跟着改——改了之后往返验证仍然通过，才说明你改对了方向而不是把两个错误抵消了。单位同理：接口给角度、配置给弧度这类混用，靠人眼看不出来，靠断言一眼就露馅。
注意：坐标系定义在不同 Issue 之间调整过，动笔改换算代码之前，先翻到手册 3.2 节对应的图示确认一遍，别拿记忆里的约定当准。
3.3 单位约定要落到配置字段上，而不是留在口头
手册 3.1 节把单位单列出来，说明它是被反复踩的地方。长度米、时间秒、速度米每秒这些没争议，真正容易出问题的是角度和比例。我的经验是把单位写进配置文件的注释里，紧贴字段，而不是集中写在文档某一页：
| 字段类型 | 常见单位 | 检查方式 |
|---|---|---|
| 位置、距离、尺寸 | 米 | 和场景地图的尺度对一遍，看车是不是大得离谱 |
| 角度、朝向、视场角 | 度或弧度，视字段而定 | 在配置里紧贴字段写注释，注明单位 |
| 速度、加速度 | 米每秒、米每二次方秒 | 和场景限速对照，量级明显不对就是单位错了 |
| 时间步长 | 秒 | 和 TaskControl 的步进设置核对，别把毫秒当秒填 |
| 图像尺寸、标注框 | 像素 | 换算到米之前必须先知道相机内参和分辨率 |
角度这一类最典型：视场角字段填了 60，如果程序按弧度解释，那就是 60 弧度，画面会变成一片畸变。这种错误的可怕之处在于它不崩溃，只是结果荒谬，而荒谬的结果如果被下游当成正常数据收进去，就是一条污染链。
4. 组件协同：TC、IG、ScenarioEditor 与 SimServer 的连接方式
单机能跑通，只是证明这套东西装对了。真正开始在自动驾驶项目里用，迟早要面对多组件协同：谁先启动、谁管时间、谁负责渲染、外部算法怎么接进来。手册第 6 章逐组件展开，6.1 节的组件管理和 6.2 节的自定义组件接入是其中最有价值的两段。
4.1 组件不是平级的，先认清谁调度谁
手册 6.1.1 把运行方式分成单机多进程和多机分布两种，6.1.2 单独讲 SimServer。这个安排本身就说明了架构：SimServer 是注册与调度中枢，其他组件向它报到，由它决定谁在什么时候被拉起。
| 组件 | 职责 | 依赖关系 | 启动顺序建议 |
|---|---|---|---|
| SimServer | 组件注册、生命周期管理、跨机调度 | 无，最底层 | 1 |
| TaskControl (TC) | 仿真主控，管时间步进、场景加载、对外接口触发 | 依赖 SimServer | 2 |
| Image Generator (IG) | 场景渲染、图像输出 | 依赖场景数据库与 TC 的时间同步 | 3 |
| VT-GUI | 图形前端，管工程配置与启动 | 依赖以上全部 | 4（或由它统一拉起） |
| ScenarioEditor | 场景编辑 | 相对独立，可与运行时并行 | 按需 |
启动顺序不是形式主义。TC 没起来的时候 IG 就在跑，渲染线程会按自己的节奏推进，等 TC 接管时两边的时间基准已经错开，表现出来就是画面动但数据不动，或者数据动但画面卡在某一帧。这类现象没有报错，只能靠启动日志里的时间戳去倒推。
4.2 从命令行拉起一次最小仿真
GUI 适合调试，但做批量回归、跑夜间的测试集，还是得靠命令行。下面是通用形式，具体脚本名和参数按发行版实际内容替换：
# 环境变量先立住，保证各组件用的是同一套配置 export VTD_DISTRO=/opt/vtd/distributions/current export VTD_SETUP=$HOME/.config/vtd/setups/default export VTD_LOG_LEVEL=info # 1) 起调度中枢，日志单独落盘，便于出问题先看它 "$VTD_DISTRO/runtime/bin/simServer" \ --setup "$VTD_SETUP" \ --log "$HOME/vtd_logs/simserver.log" & SIM_PID=$! # 2) 等注册端口可用再起 TC，避免竞态 sleep 3 # 3) 起主控，指定工程与场景 "$VTD_DISTRO/runtime/bin/taskControl" \ --setup "$VTD_SETUP" \ --project "$HOME/vtd_projects/demo01" \ --log "$HOME/vtd_logs/tc.log" & # 4) 最后起图像生成器 "$VTD_DISTRO/runtime/bin/imageGenerator" \ --setup "$VTD_SETUP" \ --log "$HOME/vtd_logs/ig.log" & wait $SIM_PID脚本里那行sleep 3看着粗糙，但它解决的是实打实的竞态：调度中枢从进程启动到端口可用有个几百毫秒的窗口，组件在这期间连上去就会被拒，然后它自己重试几次失败退出，你在日志里看到的是一串连接错误，而不是「启动太快」。稳妥点的写法是轮询端口，sleep只是最省事的近似。
日志全部单独落盘这一点，是我踩过坑之后改的习惯。所有组件往一个终端里输出，一旦某一行报错被后面的正常输出刷掉，你就失去了唯一的现场。分开落盘，出问题时先看 simserver.log 有没有注册失败，再看 tc.log 的时间步是否在推进，最后看 ig.log 有没有渲染异常，排查路径是线性的。
4.3 接自定义组件，绕不开的三个约束
手册 6.2 节讲添加自定义组件，篇幅不长，但它划定了三条不能越的线：
第一条是注册。自定义组件必须先向 SimServer 报到，让调度器知道你的存在，否则它连被拉起的资格都没有。这一步的常见错误是只在本机启动脚本里加了进程，忘了在配置里登记，结果进程活着但没人管，中止仿真时也不会被清理，下一次启动端口被占用。
第二条是报文格式。组件间的通信走统一的运行时数据总线，字段名、类型、字节序都要按手册给的格式来。自己造一套私有协议在单机测试时可能跑得通，一上多机就散架，因为中间没有任何一层做转换。
第三条是时间同步，也是最容易忽视的一条。自定义组件不能跑自己的时钟，必须跟着 TC 的步进走：TC 发一步，你处理一步，处理完回执，再等下一步。见过不少实现是内部开了个定时器按固定频率跑，短时间看着没问题，跑上十分钟就和主仿真错开几百毫秒，记录的传感器数据整体偏移，而这种偏移在事后分析里几乎无法复原。
5. 避坑记录：五类让仿真静默失败的配置问题
这套工具最折磨人的地方在于，大部分错误不会让程序崩掉，而是让它安静地跑在一条错误的路径上。下面五条是我在不同项目里反复遇到的，按「现象—原因—解决」整理，都是能复现的。
第一条：进程全在，画面全黑，TC 状态一直显示运行中。
现象是所有组件都起来了，日志没有 error，但图像生成器吐出来的帧是纯黑，仿真时间却在往前走。原因通常是场景数据库路径没有解析成功——搜索路径里写的相对路径，在 GUI 启动时按工作目录解析是对的，换到命令行启动、工作目录变了，就解析到一个空目录。空目录不报错，渲染器拿到空场景就渲染背景色。解决方式是把资源路径全部改成基于 Setup 的绝对路径或者相对于配置文件的路径，并且在启动脚本里显式cd到固定目录；验证方法很简单，启动后先看 ig.log 里加载的场景文件名是不是你期望的那一个。
第二条：改了配置文件，重启后行为没变。
现象是明明改了某个参数，重启仿真结果和之前一模一样。原因有两个层面：一是配置文件存在多份，Setup 里的搜索顺序决定了实际生效的是哪一份，你改的那份排在后面，被前面的覆盖了；二是部分组件在退出时会把当前运行状态回写到配置里，你手工改的内容被上一次会话的缓存盖掉了。解决方式是先确认生效文件——在配置里临时改一个显眼的、能立刻看出来的值（比如窗口标题或某个明显的尺寸），重启验证它是否生效，确认路径对了再改真正的参数；同时养成退出仿真后再改配置、改完不再用 GUI 保存的习惯。
第三条：多机部署下，录制的数据和画面回放对不上。
现象是单机跑没问题，拆到两台机器上，事后回放时车辆的位姿和画面里的位置差了一截，而且误差随时间增长。原因是各机器的系统时钟不同步，而组件间的时间戳依赖本机时钟。解决方式是在部署前统一时间源，并在启动脚本里加一步时钟偏差检查，超过阈值就拒绝启动；另一个补充手段是让所有时间戳都从 TC 的仿真时间派生，而不是各组件各自取系统时间。
第四条：图像生成帧率突然掉一半，没有任何报错。
现象是同样的场景，昨天跑得流畅，今天帧率腰斩。原因大多不在代码，而在渲染负载：新增的模型面数过高、纹理分辨率过大、或者场景里动态光源数量上去了。这类问题靠日志查不出来，得看渲染统计。解决方式是先把场景里的动态对象裁到最少做基线测试，再逐个加回去定位；长期做法是给场景资源定一个面数和纹理尺寸的上限，进库前过一遍检查。
第五条：工程换台机器就打不开，或者打开了路径全红。
现象是在 A 机器上正常的工程，拷到 B 机器上配置项全变成无效路径。原因是配置里写了绝对路径，而且指向了 A 机器的用户目录。这个问题没有技术难度，纯粹是习惯问题。解决方式是把工程目录内的引用全部改成相对路径，跨工程的引用通过 Setup 的搜索路径解析；拷贝工程时连同 Setup 一起打包，并在目标机器上重建一次搜索路径映射。这条我吃过不止一次亏，后来在工程模板里就明确规定不允许出现用户目录的绝对路径。
6. 把手册用成资产：版本对齐和一次十五分钟的增量验证
手册看完一遍容易，难的是让它持续起作用。我的做法是把它压缩成两张表，贴在环境文档里，每次动环境之前过一遍。
第一张是版本对齐表，四列就够：Distribution 路径、Setup 名称、手册 Issue、验证日期。每次升级或者换机器，填一行；出问题时先看这张表，两边不一致就先对齐再谈排查。第二张是增量验证清单，改完配置后按顺序跑：
| 步骤 | 检查项 | 通过判据 | 大致耗时 |
|---|---|---|---|
| 1 | 组件启动与注册 | 各组件日志无连接失败，SimServer 列出全部组件 | 2 分钟 |
| 2 | 场景加载 | ig.log 中出现期望的场景文件名，画面非纯色 | 3 分钟 |
| 3 | 时间推进 | TC 仿真时间单调递增，步长与配置一致 | 2 分钟 |
| 4 | 坐标抽查 | 车辆静止时位姿在期望点附近，误差在厘米级 | 3 分钟 |
| 5 | 数据落盘 | 录制文件生成，回放位姿与实时一致 | 5 分钟 |
十五分钟跑完，比事后花两天找一条偏移的来源划算得多。这套流程的价值不在严格，而在固定：每次都按同样的顺序检查同样的五件事，出问题时你至少知道上一次是哪一步过的。
还有一个习惯值得养成：把手册里那些「一句话带过」的地方标出来，比如 6.2 节讲自定义组件的三行约束、5.4 节讲文件查找顺序的两段话。这些地方往往是最容易出问题、又最不容易被注意到的，因为写得太短，读的时候一眼扫过去就忘了。我会在旁边加批注，写上自己踩过的具体现象，久而久之这份 PDF 就变成了带个人注脚的版本，比原版好用得多。
从那以后我每次动仿真环境，哪怕是改一个看起来无关紧要的路径，都强制走一遍这五步验证，不给自己留「应该没问题」的余地。希望帮到你。
本文还有配套的精品资源，点击获取
