交通编辑

本节介绍流量编辑器 GUI 和模拟工具。

简介和目标

异构机器人车队的交通管理并非易事。协调管理的挑战之一来自于车队使用的信息模型中不同的语义。航路点、车道、充电/停靠站、禁区、门和电梯等基础设施系统的表示由供应商自行决定。然而，传达共享设施中车队能力和意图的标准化惯例对于规划至关重要。其他交通方式（如公路）中的多智能体参与者共同遵守一套规则和惯例，以最大限度地减少混乱。更重要的是，它们允许新参与者通过遵循规定的规则轻松融入系统。现有智能体可以容纳新参与者，因为它的行为是显而易见的。

多机器人系统的交通惯例并不存在。 traffic_editor 的目标是通过图形界面以标准化、中立的方式表达各个车队的意图，从而填补这一空白。然后可以导出来自不同车队的整理后的交通信息，以进行规划和控制。traffic_editor 的第二个目标和好处是促进生成准确反映物理环境的 3D 模拟世界。

概述

traffic_editor 存储库 是 traffic_editor GUI 和工具的所在地，这些工具可从 GUI 输出自动生成模拟世界。 GUI 是一个易于使用的界面，可以创建和注释带有机器人交通以及建筑基础设施信息的 2D 楼层平面图。 通常，环境有现有的楼层平面图，例如建筑图纸，这简化了任务并为特定于供应商的地图提供了“参考”坐标系。 对于这种情况，traffic-editor 可以导入这些类型的“背景图像”作为画布，在其上绘制预期的机器人交通地图，并轻松跟踪模拟所需的重要墙段。

traffic_editor GUI 项目存储为带有 .building.yaml 文件扩展名的 yaml 文件。 尽管典型的工作流程使用 GUI 并且不需要直接手动编辑 yaml 文件，但我们使用了 yaml 文件格式，以便在需要时使用自定义脚本轻松解析。 每个 .building.yaml 文件都包含用户注释的站点每个级别的几个属性。 下面显示一个空的 .building.yaml 文件。 GUI 尝试使向这些文件添加和更新内容变得容易。

levels:
  L1:
    doors:
      - []
    drawing:
      filename:
    fiducials:
    elevation: 0
    flattened_x_offset: 0
    flattened_y_offset: 0
    floors:
      - parameters: {}
        vertices: []
    lanes:
      - []
    layers:
      {}
    measurements:
      - []
    models:
      -{}
    vertices:
      {}
    walls:
      {}
lifts:
  {}
name: building

GUI Layout

traffic_editor 的布局包括 Toolbar、Working Area 和 Sidebar，如下图所示：

Traffic Editor GUI

工具栏包含各种工具，用于支持设置绘图比例、对齐多层场景的级别、向模拟环境添加虚拟模型、添加机器人交通车道、模拟地板等操作。

与现代 GUI 中通常的情况一样，顶部工具栏包含各种工具，用于与主工作区中的项目进行交互。

本文档将在创建示例项目时介绍和解释这些工具。 但是，工具栏中的前三个工具通常出现在 2D 绘图工具中，并且应该按预期运行：

IconNameShortkeyFunction
Select iconSelectEscSelect an entity in the Working Area
Move iconMovemMove an entity in the Working Area
Rotate iconRotaterRotate an entity in the Working Area

工作区 是渲染楼层及其注释的地方。 用户可以通过鼠标滚轮缩放，并通过按下滚轮并移动鼠标光标来平移视图。

窗口右侧的 侧边栏 包含具有各种功能的多个选项卡：

  • 楼层：为建筑物添加新楼层。这可以从头开始完成，也可以通过导入平面图图像文件来完成。
  • 图层：将其他图像（例如激光雷达地图）叠加在楼层上
  • 电梯：配置和添加建筑物的电梯
  • 交通：选择当前正在编辑哪个“导航图”，并切换正在渲染的图形。

注释指南

本节将介绍注释设施的过程，同时重点介绍 traffic_editor GUI 的功能。

要创建新的流量编辑器 Building 文件，请从终端窗口启动流量编辑器（如果 traffic-editor 是从源代码构建的，则首先获取工作区）。 然后，单击 Building -> New... 并为 .building.yaml 文件选择位置和文件名。

添加楼层

可以通过单击 Sidebar 的 levels 选项卡中的 Add 按钮来添加建筑物中的新楼层。 该操作将打开一个对话框，您可以在其中指定 name、elevation（以米为单位）和 2D drawing 文件（.png）的路径。 在大多数用例中，楼层的平面图用作绘图。 如果未指定，用户可以在提供的字段中明确输入楼层的尺寸。

添加楼层对话框

在上图中，添加了一个位于海拔 0m 的新楼层 L1 和一个楼层平面图，如 levels 选项卡所示。 默认比例为 1px = 5cm。 可以通过添加测量值来设置实际比例。 用于对齐楼层的任何偏移都将反映在 X 和 Y 列中。 保存项目将更新 tutorial.building.yaml 文件，如下所示：

levels:
  L1:
    drawing:
      filename: office.png
    elevation: 0
    flattened_x_offset: 0
    flattened_y_offset: 0
    layers:
      {}
lifts:
  {}
name: building

Adding a vertex

IconShortkey
Vertex iconv

顶点是多个注释的基本组成部分。 墙壁、测量、门、地板多边形和交通车道都是从两个或多个顶点创建的。 要创建顶点，请单击“工具栏”中的顶点图标，然后单击画布上的任意位置。 顶点的默认属性是其坐标以及一个空的名称字段。 可以通过首先选择顶点（将其变为红色），然后单击图中的“添加”按钮来添加其他属性。 这些的简短描述如下：

  • **is_holding_point：**如果为真，并且航路点是车道的一部分，则 rmf_fleet_adapter 将在路径规划期间将其视为 等待点，即允许机器人在此航路点等待一段无限期的时间。
  • is_parking_spot: 机器人的停车位。 Definition
  • is_passthrough_point: 机器人不应停止的航点. Definition
  • is_charger: 如果为真，并且航路点是车道的一部分，则 rmf_fleet_adapter 将把这里当作充电站。
  • is_cleaning_zone 指示当前航点是否为清洁区域，专门用于“清洁”任务。
  • dock_name: 如果指定，并且航路点是交通车道的一部分，则 当机器人接近该航路点时，rmf_fleet_adapter 将向机器人发出 rmf_fleet_msgs::ModeRequest 消息，其中 MODE_DOCKING 和 task_id 等于指定名称。当机器人执行其自定义对接序列（或自定义行进路径）时，使用此消息。
  • spawn_robot_type: 在模拟中在此航点生成的机器人模型的名称。该值必须与资产存储库中模型的文件夹名称匹配。有关模拟所需的机器人模型和插件的更多详细信息，请参阅 模拟
  • spawn_robot_name: 在此航路点生成的机器人的唯一标识符。此机器人发布的 rmf_fleet_msgs::RobotState 消息将具有与此值相等的 name 字段。
  • pickup_dispenser 用于“交付”任务的分配器工作单元的名称，通常是模型的名称。请参阅 [Workcell section] (https://osrf.github.io/ros2multirobotbook/simulation.html#workcells) 请参阅模拟章节以了解更多详细信息。
  • dropoff_ingestor “交付”任务的摄取器工作单元的名称，通常是模型的名称。请参阅 [Workcell section] (https://osrf.github.io/ros2multirobotbook/simulation.html#workcells) of the Simulation Chapter for more details.
  • human_goal_set_name The goal_sets.set_area 名称，由人群模拟使用。有关“crowd_sim”的更多信息，请参阅 [Crowdsim section] (https://osrf.github.io/ros2multirobotbook/simulation.html#crowdsim) 请参阅模拟章节以了解更多详细信息。

Vertex attributes

每个顶点都以 x 坐标、y 坐标、海拔、vertex_name 和一组附加参数的列表形式存储在 tutorial.building.yaml 文件中。

  vertices:
    - [1364.76, 1336.717, 0, magni1_charger, {is_charger: [4, true], is_parking_spot: [4, true], spawn_robot_name: [1, magni1], spawn_robot_type: [1, Magni]}]

Adding a measurement

Icon
Measurement icon

添加测量值可设置导入的 2D 图纸的比例，这对于规划和模拟准确性至关重要。 平面图中的比例尺或参考尺寸有助于完成此过程。通常，您可以在图纸中的参考比例尺上直接绘制测量线。 在编辑器处于_建筑_模式时，选择_添加测量_工具并单击两个已知尺寸的点。 地图上会呈现一条粉红色的线，其两端在选定点处有两个顶点。

注意： 可以通过单击现有顶点来绘制测量线。 在这种情况下，不会在其末端创建其他顶点。

选择该线会填充“侧边栏”属性窗口中的各种参数。 将“距离”参数设置为点之间的物理距离（以米为单位），然后将更新关卡的“比例”。 目前，您必须保存项目并重新启动“traffic-editor”才能看到反映的更改（待办事项：修复此问题...）。

测量属性

上述过程将两个“顶点”和一个“测量”字段添加到“tutorial.building.yaml”文件，如下所示。 对于测量字段，前两个元素表示代表线端点的顶点的索引。 “距离”值存储在参数的子列表中。

levels:
  L1:
    drawing:
      filename: office.png
    elevation: 0
    flattened_x_offset: 0
    flattened_y_offset: 0
    layers:
      {}
    measurements:
      - [1, 0, {distance: [3, 8.409]}]
    vertices:
      - [2951.728, 368.353, 0, ""]
      - [2808.142, 1348.9, 0, ""]

lifts:
  {}
name: building

Adding a wall

IconShortkey
Wall iconw

要在地图中注释墙壁，请从“工具栏”中选择“添加墙壁”图标，然后单击代表墙壁角落的连续顶点。 添加墙壁段的过程是连续的，可以按“Esc”键退出。 地图上呈现顶点之间的蓝线，代表绘制的墙壁。 如果不存在角顶点，则使用此工具时会自动创建它们。 注释墙壁的网格是在使用“building_map_generator”生成 3D 世界期间自动生成的。 默认情况下，墙壁厚度为 10 厘米，高度为 2.5 米。 “wall_height”和“wall_thickness”属性可以 修改 in the source code.

墙面纹理选项可用 here in the source code.

Annotating walls

墙壁存放在 tutorial.building.yaml 文件作为一个列表，其中包含墙段起点和终点顶点的索引以及一个空参数集。

    walls:
      - [3, 4, {}]
      - [4, 5, {}]
      - [5, 6, {}]
      - [6, 7, {}]
      - [6, 8, {}]
      - [8, 9, {}]

Adding a floor

Icon
Floor icon

地板对于模拟至关重要，因为它为机器人提供了行走的地面。 使用“建筑”编辑模式中“主工具栏”中的“添加地板多边形”工具对地板进行注释。 要定义地板，请选择连续的顶点以创建一个准确表示地板面积的多边形，如下所示。 需要在此步骤之前手动添加这些顶点。 创建后，保存项目并重新加载。 选择定义的地板会突出显示其纹理属性。同样， default list of available textures 可以在源代码中找到。

Highlighting floor's textures

某些场景可能需要带有空腔的地板，例如，用来表示电梯井。 添加孔洞多边形 工具可用于此目的。 此外，可以使用 编辑多边形 工具修改绘制的多边形（地板或孔洞）的形状。 选择现有多边形后单击该工具，用户可以修改多边形的顶点。

Each polygon is stored in the tutorial.building.yaml file in the format below:

    floors:
      - parameters: {texture_name: [1, blue_linoleum], texture_rotation: [3, 0], texture_scale: [3, 1]}
        vertices: [11, 10, 14, 15, 13, 12]

Adding a door

Icon
Door icon

可以在“建筑”编辑模式下添加两个顶点之间的门，方法是从“主工具栏”中选择“添加门”工具，然后单击代表门末端的顶点。 选择带注释的门会突出显示其属性，如下图所示。 目前，支持四种门“类型”：“铰链”、“双铰链”、“滑动”和“双滑动”。 “motion_degrees”参数指定铰链门的运动范围，而“motion_direction”指示摆动的方向。 为了使门在模拟中工作，必须为门指定一个“名称”。

Door type properties

门以列表形式存储在 tutorial.building.yaml 文件中，其中包含起始和结束顶点的索引以及描述门的一组参数。

 doors:
      - [24, 25, {motion_axis: [1, start], motion_degrees: [3, 90], motion_direction: [2, 1], name: [1, D001], type: [1, double_sliding]}]

Adding a traffic lane

traffic_editor GUI 中最重要的工具之一是 Add lane 工具。 设施中运行的每个车队的允许运动通过其各自的图表传达，该图表由航路点和连接车道组成。 在这种方法中，我们假设机器人沿着航路点之间的有效直线路径行进。 虽然这可能被视为对能够自主导航的机器人所走路径的过度简化，但在实践中，该假设相当成立，因为这些机器人大多沿着走廊或过道行进，很少在无约束的开放空间中行进。 例如，即使在理论上无约束的空间（如建筑大厅或购物中心中庭），现场操作员也可能希望机器人在空间边缘的“交通车道”中运行，以免妨碍典型的人类交通流。

Sidebar 中的 traffic 选项卡默认为九个不同的车队提供了九个图表。要注释图形（例如图形 0）的车道，请从“交通”选项卡中选择图形，然后单击“添加车道”工具。 可以通过单击要连接的顶点来绘制此图形的车道。 如果顶点不存在，则会自动添加。 可以按照上一节所述为每个顶点分配属性。 要向需要机器人在任何航路点终止的航路点发出任务，必须为航路点分配名称。

Graphs' lane colors

每个图表的车道都有独特的颜色，可以使用“交通”选项卡中的复选框切换车道的可见性。

在两个航路点之间定义的车道可以配置以下附加属性：

  • 双向：如果为“真”，则“rmf_fleet_adapter”将为其机器人规划路线，假设车道可以双向行驶。

非双向车道有箭头指示其方向性（上图中的靛蓝车道）。一个方便的快捷方式是，当选择车道段时，您可以

按“b”键在该车道的单向和双向运动之间切换。

  • graph_idx：车道对应的图表编号

  • 方向：限制车道以使机器人以“向前”或“向后”方向行驶。例如，这对于接近对接点或充电器的最终车道段很有用。

虽然 traffic_editor 现在支持在楼层之间移动的电梯，但 demo_mock_floor_name 和 demo_mock_lift_name 属性最初是为了展示单层演示环境中的共享电梯访问而设计的，其中的“模拟”电梯接收电梯命令并传输电梯状态，但实际上并不在建筑物的任何不同楼层之间移动。 但是，由于可能对此类功能感兴趣，用于测试旨在模拟多层场景的单层硬件设置，因此保留了这些属性。

  • demo_mock_floor_name：机器人在穿越车道时所在的楼层名称
  • demo_mock_lift_name：机器人在穿越车道时进入或退出的电梯名称 为了进一步解释这些属性，请考虑以下导航图的表示，其中数字是航点，字母是车道：
1 <---a---> 2 <---b---> 3

Waypoint 1 is on floor L1
Waypoint 2 is inside the "lift" named LIFT001
Waypoint 3 is on floor L3
The properties of edge "a" are:
    bidirectional: true
    demo_mock_floor_name: L1
    demo_mock_lift_name: LIFT001
The properties of edge "b" are:
    bidirectional: true
    demo_mock_floor_name: L3
    demo_mock_lift_name: LIFT001

如果机器人要从路点 1 行进到路点 3，当机器人接近路点 1 时，rmf_fleet_adapter 将请求“模拟升降机”到达 L1。 在确认“升降机”位于 L1 且其门处于“打开”状态后，机器人将被指示进入“升降机”前往路点 2。 一旦“升降机”指示已到达 L3，机器人将沿着车道 b 驶出前往路点 3。

注意：注释图形时，强烈建议遵循图形索引的升序顺序，而不跳过中间数字。只有在“交通”选项卡中首先选择其关联的图形时，才能与绘制的车道进行交互。

注释的图形最终使用“building_map_generator”导出为“导航图”，然后由相应的“rmf_fleet_adapters”用于路径规划。

车道以以下格式存储在 tutorial.building.yaml 中。 数据结构是一个列表，其中前两个元素代表车道两个顶点的索引和一组具有配置属性的参数。

    lanes:
      - [32, 33, {bidirectional: [4, true], demo_mock_floor_name: [1, ""], demo_mock_lift_name: [1, ""], graph_idx: [2, 2], orientation: [1, forward]}]

Deriving coordinate-space transforms

坐标空间令人困惑！ 由于历史原因，GUI 在内部通过注释图像来创建交通地图，因此“原始”注释实际上是在“基本”平面图图像的像素坐标中编码的，在像素坐标中，+X=右，+Y=下，原点位于基本平面图图像的左上角。 然而，在建筑地图生成步骤中，垂直轴被翻转以最终位于笛卡尔平面中，因此绝大多数 RMF（即交通编辑器和建筑地图生成器下游的所有内容）使用“正常”笛卡尔坐标系。 （顺便说一句——下一个版本的交通编辑器在这方面会更加灵活，默认使用普通笛卡尔坐标系（而不是基于图像的坐标系），甚至是全局坐标（纬度/经度）。虽然前期工作正在进行中，但在撰写本文时，这款下一代编辑器还没有硬性时间表，因此本章的其余部分将描述现有的“交通编辑器”。）

虽然“交通编辑器”目前使用基础平面图图像的左上角作为参考框架，但机器人生成的地图可能起源于其他地方，并且可能以不同的方向和比例缩放。

在“交通编辑器”地图和机器人地图中推导出坐标系之间的正确变换至关重要，因为

“rmf_fleet_adapters”期望所有机器人在 RMF 坐标系中发布其位置，而“rmf_fleet_adapters”也在同一框架中发出路径请求。

为了获得此类变换，traffic_editor GUI 允许用户将机器人地图叠加在平面图上，并应用比例、平移和旋转变换，以使两个地图正确对齐。 然后，用户可以在为机器人编程接口时应用相同的变换来在机器人地图和 RMF 坐标之间进行转换。

可以通过单击“侧边栏”中“图层”选项卡上的“添加”按钮来导入机器人地图。 然后，对话框将提示用户上传机器人地图图像。 同一框包含用于设置图像比例以及应用平移和旋转的字段。 通过视觉反馈，用户可以确定这些字段的适当值。 如下图所示，将机器人生成的地图导入 GUI 后，其位置和方向与平面图不同。 使用正确的变换值，可以使两个地图重叠。

Overlap robot-generated map

Adding fiducials

Icon
Fiducial icon

对于具有多个级别的地图，基准点提供了一种相对于参考级别缩放和对齐不同级别的方法。 这对于确保不同级别注释的尺寸准确性以及对齐模拟至关重要。 基准点是放置在两个或多个级别之间预计垂直对齐的位置的参考标记。 例如，结构柱可能贯穿多个楼层，其位置通常在楼层平面图上标明。 如果在级别和参考级别之间有两对或更多对相应的标记，则可以在两个级别之间得出几何变换（平移、旋转和缩放）。 然后可以将此变换应用于新定义级别中的所有顶点和模型。

首先，使用“添加基准点”工具向参考级别添加两个或更多具有唯一“名称”属性的非共线基准点（下图左图）。 在新创建的级别中，在预计垂直对齐的位置添加与参考级别相同数量的基准点，并使用匹配的名称（下图右图）。 保存并重新加载项目会计算级别之间的转换，这可以从“级别”选项卡中显示的新级别的比例和 X-Y 偏移中看出。 此级别现已准备好进行注释。

Adding fiducials

For each level, fiducials are stored in a list of their X & Y coordinates along with their name.

    fiducials:
      - [936.809, 1323.141, F1]
      - [1622.999, 1379.32, F2]
      - [2762.637, 346.69, F3]

Adding a lift

电梯是多层设施中人类和机器人车队共享的不可或缺的资源。 要向建筑物添加电梯，请单击“侧边栏”中“电梯”选项卡中的“添加”按钮。 将加载一个具有各种可配置属性的对话框。 必须指定其轿厢中心的名称、参考级别和 X&Y 坐标（像素单位）。 可以进一步添加偏航（弧度）以根据需要定位电梯。 轿厢的宽度和深度（米）也可以自定义。 电梯可以设计为具有多个轿厢门，可以在多个楼层打开。 要添加轿厢门，请单击轿厢图像下方框中的“添加”按钮。 每个轿厢门都需要一个名称以及位置和方向信息。 在这里，X&Y 坐标相对于轿厢中心。

Configuring lift properties

配置的升降机存储在 tutorial.building.yaml 文件中，如下所述：

lifts:
  LF001:
    depth: 2
    doors:
      door1:
        door_type: 2
        motion_axis_orientation: 1.57
        width: 1
        x: 1
        y: 0
      door2:
        door_type: 2
        motion_axis_orientation: 1.57
        width: 1
        x: -1
        y: 0
    level_doors:
      L1: [door1]
      L2: [door2]
    reference_floor_name: L1
    width: 2
    x: 827
    y: 357.7
    yaw: 1.09

添加电梯后，我们还希望让机器人横穿电梯。 为了实现这一点，用户需要创建位于每层电梯轿厢内的顶点/航点。 完成后，通过 add_lane 将电梯轿厢内的航点连接到其他顶点。

Adding environment assets

可以使用 建筑 编辑模式下的 添加模型 工具，用可用于模拟的模型缩略图注释楼层。 选择此工具将打开一个对话框，其中包含可导入地图的模型名称和匹配缩略图列表。 一旦进入地图，就可以使用 移动 和 旋转 工具调整它们的位置和方向。提供示例模型 here

The thumbnail_generator documentation 包含有关扩展其他型号缩略图列表的说明。

Note: If no models are shown on the add models window, Go to "Edit -> Preference", then indicate the thumbnail path. (e.g. $HOME/rmf_ws/src/rmf/rmf_traffic_editor/rmf_traffic_editor_assets/assets/thumbnails)

Model name and thumbnails dialog

Conclusion

本章介绍了 traffic_editor 的各种功能，这些功能可用于注释设施地图，同时遵循标准化的语义集。 可以在 rmf_demos 存储库中找到其他交通编辑器项目的示例。 在 Simulation 一章中描述了在注释站点中使用 RMF 运行基于物理的模拟。