Autoware.Auto 的工具

该 autoware_auto_create_pkg 脚本设置包以使用 ament_cmake_auto 而不是 ament_cmake 。该 ament_cmake_auto 库包含 CMake 宏 ament_auto_add_library ，它们可以自动执行许多样板任务，例如定位依赖项。例如，如果您使用 ament_auto_find_build_dependencies() ，它会自动将 find_package() package.xml 中所有与构建相关的依赖项。然后，如果您使用 or的 ament_auto_ 形式，它将自动为所有找到的形式。 add_library add_executable ament_target_dependencies()

能见度控制

该脚本通过它包含在每个包中 autoware_auto_create_pkg 的标头对库链接进行更精细的控制。 visibility_control.hpp

可见性控制的目的是使库符号在不同平台上的可见性处于一致的状态（即 Windows 使用的等价物 -fvisibility=hidden ）。例如，ROS2 代码就是这样做的。这意味着要获得良好的跨平台支持，我们需要在 ie 函数前面添加：

FOO_PUBLIC int my_func();
class FOO_PUBLIC bar // 默认所有符号可见
{
上市：
无效 bazzle(); // 公开可见性
私人的：
FOO_LOCAL gaddle(); // 本地可见性 -> 无法链接到
};

这也使我们能够将符号（类、函数、方法等）标记为本地，以便外部用户无法链接到它们。还有一些论点认为它提高了安全性和链接/加载时间。

注意：默认可见性是 LOCAL ，因此请务必将任何类或函数标记为 PUBLIC 您希望能够链接的对象。

用法

要使用该工具，请运行以下命令：

$ ade 输入
ade$ source /opt/AutowareAuto/setup.bash
ade$ cd AutowareAuto/src/<path_to_folder_ contains_your_new_package>
ade$ ros2 run autoware_auto_create_pkg main.py --pkg-name PKG_NAME --maintainer MAINTAINER --email EMAIL --description 描述

在上述命令中，替换 <path_to_folder_containing_your_new_package> 为要在其中创建包的文件夹的路径。或者，添加 --destination <path_to_folder_containing_your_new_package> 参数以在与当前工作目录不同的位置生成包。还将 ALL_CAPS 中的标志值替换为新包的适当值。创建新包后，您需要清理细节（许可证、依赖项、设计文档等）。

要获取有关命令行用法的更多详细信息，请调用：

ade$ ros 运行 autoware_auto_create_pkg main.py --help

使用 example 创建包后 --pkg-name foo ，构建并测试它。

colcon build --packages-select foo
colcon 测试 --packages-select foo

然后按照以下步骤从启动文件运行节点：

源安装/setup.bash
ros2 启动 foo foo.launch.py

输出应类似于：

[component_container-1] 你好世界
[信息] [launch_ros.actions.load_composable_nodes]：在容器“/foo_container”中加载节点“/foo_node”

或者直接运行节点可执行文件：

源安装/setup.bash
ros2 运行 foo foo_node_exe

参考/外部链接

可以在本教程中找到创建新 ROS 2 包的基本说明。
关于ROS2 组成的基本说明

autoware_auto_launch

这是 autoware_auto_launch 包装的设计文件。

目的/用例

AutowareAuto 堆栈的一部分可以拆分为不同的管道，以实现不同 ODD 和用例之间的模块化和组件重用。

设计

启动文件将分为 9 个不同的管道：

本土化
映射
洞察力
规划
传感器
模拟器
系统
车辆
可视化

启动文件使用与 AVP 演示中相同的配置启动节点，因此，启动所有这些启动文件将执行 AVP 演示。

假设/已知限制

该软件包将启动 AutowareAuto 堆栈拆分为更小的管道。为简单起见，启动文件不允许内部输入/输出主题配置。如果需要这种行为，则应为此目的创建一个定制的启动文件，或者任何外部节点都应重新映射其主题。

输入/输出/API

在每个启动文件中，需要参数的节点的参数文件作为参数公开。这些参数文件的默认值位于 autoware_auto_launch 包中的 param . 除了参数文件之外，可以有条件启动的节点已作为参数 with_rviz 和 with_obstacles .

autoware_demos

这是 autoware_demos 包装的设计文件。

目的/用例

Autoware.Auto 设计灵活，涵盖许多 ODD 和用例。但是，这种灵活性使得为单个用例构建节点架构变得困难。此软件包的目的是提供演示启动和随附文件，以展示特定用例的功能集或完整架构。

每个 ODD 开发周期的主要启动文件也存储在这里并根据 ODD 命名。

设计

内的每个启动文件都 autoware_demos 应该：

能够独立启动；
针对特定用例展示单个自包含管道或完整架构；
autoware_auto_launch 在可行的情况下使用特定于域的启动文件；
param/ 尽可能使用文件夹下的与用例无关的配置文件；
必要时使用子文件夹下的特定于用例的配置文件 param/ ；

假设/已知限制

不适用

输入/输出/API

每个启动文件应包含至少公开更改每个启动节点的配置 YAML 文件路径的能力的参数。

autoware_testing

这是 autoware_testing 包装的设计文件。

目的/用例

该软件包旨在提供一种统一的方式来向该软件包添加标准测试功能，目前支持：

冒烟测试（ add_smoke_test ）：使用默认配置启动一个节点，并确保它启动并且不会崩溃。

设计

使用 ros_testing （它是的扩展 launch_testing ）并提供一些参数化、可重用的标准测试来运行。

假设/已知限制

参数化仅限于包、可执行文件名、参数文件名和可执行参数。测试命名空间设置为“测试”。包的参数文件应位于包 param 内的目录中。

输入/输出/API

要将冒烟测试添加到您的包测试中，请将测试依赖项添加 autoware_testing 到 package.xml

< test_depend > autoware_testing </ test_depend >

CMakeLists.txt 并在该部分添加以下两行 IF (BUILD_TESTING) ：

find_package（需要 autoware_testing） add_smoke_test(<package_name> <executable_name> [PARAM_FILENAME <param_filename>] [EXECUTABLE_ARGUMENTS <arguments>])

在哪里

<package_name> - [必需] 测试的节点包名称。

<executable_name> - [必需] 测试节点可执行名称。

<param_filename> - [可选] 参数文件名。默认值为 test.param.yaml 。主要在一个包中有多个冒烟测试并且每个都需要不同的参数集的情况下需要

<arguments> - [可选] 参数传递给可执行文件。默认情况下不传递任何参数。

它将 <executable_name>_smoke_test 测试添加到套件。

示例测试结果：

build/<package_name>/test_results/<package_name>/<executable_name>_smoke_test.xunit.xml：1 次测试，0 次错误，0 次失败，0 次跳过

参考/外部链接

未来的扩展/未实现的部分

添加更多类型的标准测试。

相关问题

问题 #700：添加冒烟测试
问题 #1224：使用冒烟测试移植其他包 autoware_testing

benchmark_tool_nodes

目的/用例

Benchmark Tool 是一个 ROS2 包，用于计算其他节点或节点组的性能指标。该工具的各种组件可用于使用许多数据集、指标和支持的节点对其进行扩展。该工具为每个受支持的节点附带一个启动文件，允许轻松使用和可重现的行为。

设计

该工具旨在在“黑盒”系统上运行一些基准测试任务并收集要处理的指标。

基准管道

管道由两个阶段组成。第一阶段用于将数据集播放到黑盒系统中并收集结果输出。作为此阶段的一部分，输出将根据验证要求进行格式化并保存在正确的文件夹中。当要收集的指标是迭代的速度时，该指标将通过观察从发布主题到系统输出主题所经过的时间来计算。

第二阶段用于计算指标，收集前一阶段的所有输出文件并应用每个单个指标所需的计算。

用于度量计算的算法是：

激光雷达障碍物检测精度
- 应用 kitti 3d benchmark SDK 中使用的代码
激光雷达障碍物检测迭代速度
- 收集为每帧计算的速度信息并应用算术平均值
相机障碍物检测精度
- 被定义为
相机障碍物检测迭代速度
- 被定义为
多模态定位迭代速度
- 被定义为
NDT节点迭代速度
- 被定义为
地面滤波器迭代速度
- 被定义为
局部规划器迭代速度
- 被定义为

第一阶段

第一阶段框图解释了基准测试工具的组件和所涉及的交互。

第一阶段设计

基准任务

这是该工具的主要组件。它应该管理其他组件之间的交互。它旨在通过封装每个测试的所有特定细节的其他组件进行扩展。

扩展基准任务 的组件列表：

3D激光雷达检测任务
摄像头检测任务
多模式定位任务
无损检测节点任务
地面过滤任务
本地规划任务

每个专门的组件应该：

保存有关要使用的数据集的信息
知道必须发布/订阅哪些主题
知道如何处理输出并使用正确的输出格式化程序对其进行格式化

数据集

数据集 组件应该标准化数据集之间的差异，向其他组件公开统一的接口。它不应该保存有关数据集的任何特定信息，这项工作留给扩展数据集的专门组件。

扩展数据集 的组件列表：

3D 基准数据集

每个专门的组件应该：

保存有关数据集结构（路径、文件）的信息
通过Dataset组件接口统一对数据的访问

播放器

Player 组件用于将数据播放到给定的主题。它负责使用正确的数据类型进行通信。使用 Player 的组件应提供主题和要发送的数据。

时间估计

时间估计 组件测量输入主题和输出主题之间经过的时间。此组件发送到 输出格式化程序 的测量值以微秒为单位。使用 时间估计 块的组件应该提供要收听的主题。

输出格式化程序

输出格式化程序 组件是用于侦听输出数据的通用块。它应该使用专门的组件进行扩展，这些组件包含有关如何格式化输出数据的特定信息。此外，通用格式化程序将原始传入数据打印到文件中。

扩展输出格式化程序 的组件列表：

基蒂格式

每个专门的组件应该：

订阅给定的输出主题
格式化输出数据
使用正确的文件夹结构保存文件

第二阶段

第二阶段设计

第二阶段计算

第二 阶段计算 组件是一个通用块，应该由其他组件专门化。主要任务是从前一阶段保存的输出日志文件开始计算指标。

扩展第二阶段计算 的组件列表：

Kitti 3D 基准计算
速度基准计算

每个专门的组件应该：

保存有关哪个文件用于计算的信息
应用自己的计算算法从数据中提取度量
提供可在 CI 环境中轻松使用的指标输出

如何启动

benchmark_tool_nodes 在用户启动适当的测试用例之前，需要构建一些额外的包（wrt ）。以下是支持的节点列表、用于启动相应测试用例的命令以及所需的包：

euclidean_cluster_nodes 所需包： ros2 launch benchmark_tool_nodes euclidean_cluster_node_benchmark.launch.py
- ray_ground_classifier_nodes
- euclidean_cluster_nodes
apollo_lidar_segmentation_nodes 所需包： ros2 launch benchmark_tool_nodes apollo_lidar_segmentation_node_benchmark.launch.py
- ray_ground_classifier_nodes
- apollo_lidar_segmentation_nodes
ray_ground_classifier_nodes 所需的包： ros2 launch benchmark_tool_nodes ray_ground_classifier_benchmark.launch.py
- ray_ground_classifier_nodes
ray_ground_classifier_euclidean_cluster_nodes 所需的包： ros2 launch benchmark_tool_nodes ray_ground_classifier_euclidean_cluster_node_benchmark.launch.py
- ray_ground_classifier_nodes
- euclidean_cluster_nodes
ndt_matching [1] 所需的包： ros2 launch benchmark_tool_nodes lidar_localization_benchmark.launch.py
- point_cloud_filter_transform_nodes
- autoware_demos

[1] 见激光雷达本地化文档

支持的数据集

支持的数据集列表：

Kitti 目标检测评估 2017（目前只有激光雷达数据）

有关更多信息，请参阅自述文件

Kitti 基准测试的工作原理

KITTI 视觉基准套件是卡尔斯鲁厄理工学院和芝加哥丰田技术学院的一个项目。它以原始格式或预处理的形式提供来自高分辨率彩色和灰度相机、velodyne 点云和 GPS 的数据。它还提供评估指标。他们的目标是通过向社区提供具有新困难的现实世界基准来补充现有基准。

特别是，基准工具利用了 Kitti 对象检测评估 2017 数据集，该数据集由上面列出的数据组成，并提供 matlab 和 c++ 代码来计算基准节点输出与数据集基本事实相比的准确性。

支持的指标

支持的指标列表：

精度（在 kitti 对象评估 2017 的意义上）
迭代速度
- 从接收数据的标题或从发布数据和接收输出之间经过的时间估计得出。

参数

以下是基准工具常用参数的说明。根据每个特定于节点的启动文件，可能会有更多参数。

范围	类型	描述	默认
task	string	要启动的基准任务的名称	取决于启动文件
dataset_path	string	数据集根文件夹的路径	$(env HOME)/kitti_data/3d_bench/
input_topic	string	发布数据的主题	取决于启动文件
output_topic	string	监听输出数据的主题	取决于启动文件
benchmarked_input_topic	string	基准节点的输入主题	取决于启动文件
benchmarked_output_topic	string	基准节点的输出主题	取决于启动文件
result_path	string	保存基准测试结果的路径	$(env HOME)/benchmark_tool_result/
node_start_delay	int	在启动基准工具节点之前等待的秒数	0
rosbag_record	boolean	在 rosbag 上记录基准测试期间的输入和输出主题	false
rosbag_record_subfolder	string	文件系统上保存rosbag记录文件的子文件夹，必须是 result_path	“”
node_name	string	正在运行的节点的名字，改成启动节点的多个实例	benchmark_tool_node
node_output	string	在哪里显示运行信息（ screen 或 log ）	screen
force_end_at_frame_n	int	限制播放帧数（-1 表示无限制）	取决于启动文件
ros_info_record	boolean	在基准测试期间记录 ROS 节点拓扑和带宽信息	false
sys_info_record	boolean	在基准测试期间记录系统指标（cpu 时间、I/O、内存）	false
cyclone_dds_info_record	boolean	在基准测试期间记录 Cyclone DDS 指标（吞吐量和延迟）	false

信息记录

可选 *_info_record 参数在目录的根 result_path 目录生成文本文件。之后用户可以手动处理这些文件。在的情况下 cyclone_dds_info_record ，用户可以选择使用 Cyclone DDS latency-test-plot 或 throughput-test-plot 脚本来绘制结果。

未来的扩展/未实现的部分

如何扩展工具

该工具附带了几个组成通用基准测试任务的类。根组件是：

基准任务
- 任务的基类 (BenchmarkTask)。扩展它并实现所需的方法以在感兴趣的节点上执行基准测试。此包中的模块只允许一个类。
数据集
- 数据集的基类。扩展它以添加对新数据集的支持。
公制
- 通用指标的基类。扩展它以添加新的指标支持。
输出格式化程序
- 通用输出格式化程序的基类。它的工作是接收来自基准节点的输出并格式化并以给定的结构保存这些数据。在将新节点添加到基准时扩展它，因为每个节点具有不同的输出数据特征。
播放器
- 播放器类用于将数据发布到基准节点。目前有两种不同的播放器实现。可能不需要创建另一个播放器。
time_estimator
- time_estimator 包包含用于测量速度的类。每个班级都会进行测量并在主题上发布结果。该组件有两种实现：一种从接收到的数据的标头中提取度量，另一种测量发布数据和接收测量节点的输出之间经过的时间。因此，时间估计器订阅了这两个主题。如果需要，可以在此处实现另一个时间估计器。

要为新任务添加新的启动文件，请以可用的启动文件为例，在启动文件中包含基准测试节点以及所需的参数，然后插入基准工具节点以及任何修改后的公共参数（列出的参数）以上）。

该 task 参数非常重要，因为它会将节点指向启动文件中正在调用的任务的具体实现（例如：''ray_ground_classifier_task'` 将指向基准工具加载 ray_ground_classifier_task.py 模块并实例化里面唯一的类，一个 BenchmarkTask 派生类）。

跟踪新 BenchmarkTask 派生类文件名的名称，因为在添加新任务时，必须在 task 参数中传递文件名（不带扩展名）。

汽车件指标

基准工具要实现的指标如下：

激光雷达障碍物检测
- 迭代速度
- 结果的准确性
相机障碍物检测
- 迭代速度
- 结果的准确性
多模式定位
- 迭代速度
无损检测节点
- 迭代速度
接地过滤器
- 迭代速度
本地规划师
- 迭代速度

Fake Test Node

这个包提供了什么

当使用 GTest 在 C++ 中为节点编写集成测试时，需要编写相当多的样板代码来设置一个假节点，该节点将发布预期主题的预期消息并订阅其他主题的消息。这通常实现为自定义 GTest 夹具。

这个包包含一个库，它引入了两个实用程序类，可以用来代替上面描述的自定义夹具来为节点编写集成测试：

autoware::tools::testing::FakeTestNode - 用作带有 TEST_F 测试的自定义测试夹具
autoware::tools::testing::FakeTestNodeParametrized - 使用带有参数化测试的自定义测试夹具 TEST_P （接受转发到的模板参数 testing::TestWithParam<T> ）

这些装置负责初始化和重新初始化 rclcpp 以及检查所有订阅者和发布者是否匹配，从而减少用户需要编写的样板代码量。

如何使用这个库

包含相关标头后，用户可以使用 typedef 来使用自定义夹具名称，并将提供的类用作夹具 TEST_F 并 TEST_P 直接进行测试。

示例用法

假设有一个 NodeUnderTest 需要测试的节点。它只是订阅 std_msgs::msg::Int32 消息并发布 a std_msgs::msg::Bool 以指示输入是肯定的。要测试这样的节点，可以使用以下代码 autoware::tools::testing::FakeTestNode ：

使用FakeNodeFixture = autoware::tools::testing::FakeTestNode；
TEST_F（FakeNodeFixture，测试）{
Int32 味精{};
msg.data = 15;
常量自动节点= std::make_shared<NodeUnderTest>();
Bool::SharedPtr last_received_msg{};
auto fake_odom_publisher = create_publisher<Int32>( "/input_topic" );
auto result_odom_subscription = create_subscription<Bool>( "/output_topic" , * node ,
[&last_received_msg]( const Bool::SharedPtr msg) {last_received_msg = msg;});
const auto dt{std::chrono::milliseconds{100LL}};
常量自动max_wait_time{std::chrono::seconds{10LL}};
自动time_passed{std::chrono::milliseconds{0LL}};
而（！last_received_msg）{
fake_odom_publisher->发布（味精）；
rclcpp::spin_some(节点);
rclcpp::spin_some(get_fake_node());
std::this_thread::sleep_for(dt);
time_passed += dt;
如果（time_passed > max_wait_time）{
FAIL() << "没有很快收到消息。" ;
}
}
EXPECT_TRUE(last_received_msg->data);
成功（）;
}

此处仅显示 TEST_F 示例，但 TEST_P 用法非常相似，需要更多样板来设置所有参数值，请参阅 test_fake_test_node.cpp 示例用法。

使用命名空间

当测试依赖于 ROS 通信时，它变得容易受到来自测试之外的节点（例如，来自并行运行的其他测试）的干扰。 ROS 命名空间可用于隔离测试并确保它不会受到外部消息的干扰。为了为设置命名空间 FakeTestNode ，应该将其扩展为一个新类，该类通过 set_namespace() 函数在其构造函数中设置命名空间。然后这个新类可以用作测试夹具而不是 FakeTestNode .

{C++}
FakeNodeFixtureWithNamespace 类：公共 FakeTestNode
{
上市：
FakeNodeFixtureWithNamespace() {set_namespace("/namespace");}
};

命名空间也适用于 tf 和 tf_static 主题。如果您正在测试使用这些主题的节点（例如，当节点使用 a 时 TransformListener ），那么对节点使用以下内容很重要 NodeOptions 。

{C++}
rclcpp::NodeOptions node_options;
node_options.arguments(
{"--ros-args",
// 设置节点命名空间
"-r", "__ns:=/命名空间"
// 重新映射 tf 和 tf_static 以便它们使用节点命名空间
"-r", "/tf:=tf",
"-r", "/tf_static:=tf_static"});

Lidar integration

这是 lidar_integration 包装的设计文件。

目的/用例

该软件包包含 3D 感知节点的测试实用程序。

目的是促进节点的各种形式的测试。

设计

这个包提供了欺骗器、监听器和一些实用功能来将它们捆绑在一起。

欺骗器包括 lidar_integration::Vlp16IntegrationSpoofer ，它以非常规则的合成模式模仿 Velodyne VLP16-Hires 传感器的 (UDP) 有线协议。此外，还有随机生成点云的lidar_integration::PointCloudMutationSpoofer，用于模糊测试。

Lidar_integration ::LidarIntegrationListener 系列节点提供了测试节点，用于检查特定的周期性和数据大小。

最后， lidar_integration::lidar_integration_test 提供了一种将多个节点一起运行的简单方法，以便可以在单个可执行文件或单元测试环境中对它们进行测试。

point_type_adapter

这是 point_type_adapter 包装的设计文件。

目的/用例

Autoware.Auto 使用 PointCloud2 具有以下字段结构和顺序的消息：

字段名称	字段数据类型
“X”	FLOAT32
“是”	FLOAT32
“z”	FLOAT32
“强度”	FLOAT32

原因是，如果算法提前知道这个结构，我们可以使用 point_cloud_msg_wrapper .

各种激光雷达驱动程序可能会输出 PointCloud2 带有额外字段或具有不同字段顺序的消息。该节点有助于将这些点云转换为 Autoware.Auto 期望的类型。

用例：SVL 模拟器

SVL Simulator 输出具有以下字段的点云：

字段：x、y、z、强度、时间戳
类型：FLOAT32、FLOAT32、FLOAT32、UINT8、FLOAT64
偏移量：0、4、8、16、24

但是 Autoware.Auto 堆栈当前期望：

场：x、y、z、强度
类型：FLOAT32、FLOAT32、FLOAT32、FLOAT32
偏移量：0、4、8、12

此节点使用文件将数据转换为 Autoware.Auto 格式 point_type_adapter.launch.py 。

设计

节点订阅 PointCloud2 消息，该消息应包含（至少）：

字段名称	字段数据类型
“X”	FLOAT32
“是”	FLOAT32
“z”	FLOAT32
“强度”	FLOAT32 或者 UINT8

并将其转换为点类型的 PointCloud2 消息 autoware::common::types::PointXYZI 并发布。

输入点云允许包含额外的字段。
输入点云可以包含不同顺序的必填字段。

假设/已知限制

如果输入点云没有所需类型的所有字段，它将抛出异常并且不会发布任何内容。

输入/输出/API

输入：PointCloud2 消息

输出：PointCloud2 消息

对于 SVL 模拟器，只需使用：

ros2 启动 lgsvl_cloud_converter lgsvl_cloud_converter.launch.py

它将转换主题名称和类型，如下所示：

“/lidar_front/points_raw” -> “/lidar_front/points_xyzi”
“/lidar_rear/points_raw” -> “/lidar_rear/points_xyzi”

可以使用 Topic Remapping 更改这些主题名称。

内部工作/算法

它只是使用迭代旧云 sensor_msgs::PointCloud2Iterator ，创建一个由 x,y,z,intensity 字段组成的点，使用它将其放入新云 point_cloud_msg_wrapper::PointCloud2Modifier 并发布。

错误检测和处理

如果由于输入 PointCloud2 没有预期的类型而发生异常，它会捕获它并在回调中报告它，结束节点。

scenario_simulator_launch

目的/用例

该软件包提供了一个启动文件，用于使用场景模拟器运行 Autoware.Auto。场景模拟器是一种工具，可以运行用户定义的场景来测试特定情况下的自动驾驶堆栈行为。它可以由开发人员和测试人员手动使用，也可以与 CI 集成。

设计

场景通过定义来描述要创建的情况：

环境;
自我车辆：初始状态和期望行为；
环境中的其他代理 (NPC)、它们的初始状态和行为。

根据场景提供的描述，在模拟环境中创建情境。 Ego 车辆由自动驾驶堆栈使用此软件包提供的启动来控制。 NPC 由模拟器控制。场景的过程不断受到监督。场景以成功（例如当自我车辆到达目标时）或以失败（例如当自我撞到行人或当场景超时）结束并报告结果。

此软件包仅启动所需的堆栈：映射、感知和规划。

请注意，此包不提供场景模拟器本身，而仅提供模拟器的启动。

参考/外部链接