RViz Marker 显示类型

目标： 介绍基本的 Marker 类型及其使用方法。

教程级别： 中级

预计耗时： 15 分钟

背景

Marker 显示功能通过发送 visualization_msgs/msg/Marker 或 visualization_msgs/msg/MarkerArray 消息，在程序中向 3D 视图添加各种基本形状。

Marker 概览

请先阅读 Marker：发送基本形状，其中提供了一个最小化的发布者示例，并介绍了本页面用到的 marker 消息。

Marker 消息

1 示例用法（C++）

首先，我们创建一个简单的发布者节点，从 visualization_messages 包向 visualization_marker 话题发布 Marker 消息：

auto marker_pub = node->create_publisher<visualization_msgs::msg::Marker>("visualization_marker", 1);

之后，填充 visualization_msgs/msg/Marker 消息并发布即可：

visualization_msgs::msg::Marker marker;

marker.header.frame_id = "/my_frame";
marker.header.stamp = rclcpp::Clock().now();

marker.ns = "basic_shapes";
marker.id = 0;

marker.type = visualization_msgs::msg::Marker::SPHERE;

marker.action = visualization_msgs::msg::Marker::ADD;

marker.pose.position.x = 0;
marker.pose.position.y = 0;
marker.pose.position.z = 0;
marker.pose.orientation.x = 0.0;
marker.pose.orientation.y = 0.0;
marker.pose.orientation.z = 0.0;
marker.pose.orientation.w = 1.0;

marker.scale.x = 1.0;
marker.scale.y = 1.0;
marker.scale.z = 1.0;

marker.color.r = 0.0f;
marker.color.g = 1.0f;
marker.color.b = 0.0f;
marker.color.a = 1.0;   // Don't forget to set the alpha!

// only if using a MESH_RESOURCE marker type:
marker.mesh_resource = "package://pr2_description/meshes/base_v0/base.dae";

marker.lifetime = rclcpp::Duration::from_nanoseconds(0);

marker_pub->publish(marker);

此外还有 visualization_msgs/msg/MarkerArray 消息，可用于一次发布多个 marker。

2 消息参数

Marker 消息类型定义在 ROS 2 Common Interfaces 包中。消息定义文件带有详尽的注释，有助于理解各字段的含义。

ns：marker 的命名空间，与 id 共同构成唯一标识符。
id：分配给此 marker 的唯一 ID。需确保同一命名空间内各 ID 互不重复。
type：marker 的类型（Arrow、Sphere 等）。可用类型在消息定义中列出。
action：0 = 添加/修改，1 =（已弃用），2 = 删除，3 = 删除所有
pose：marker 的位姿，由 x/y/z 位置和 x/y/z/w 四元数朝向组成。
scale：marker 的缩放比例，在位置/朝向变换之前应用。缩放比例为 [1, 1, 1] 表示物体大小为 1m × 1m × 1m。
color：物体的颜色，以 r/g/b/a 表示，取值范围为 [0, 1]。其中 a（alpha 值）表示不透明度，1 为不透明，0 为完全透明。默认值为 0，即完全透明。务必将 marker 的 a 值设为非零值，否则它默认不可见！
points：仅用于 Points、Line strips 和 Line/Cube/Sphere-lists 类型的 marker。指定箭头的起点和终点时也会用到此字段。该字段是一个 geometry_msgs/Point 类型的列表，用于指定每个待渲染对象的位置。
colors：仅用于包含 points 成员的 marker。为 points 中的每个顶点指定 r/g/b 颜色（目前不含 alpha 值）。
lifetime：一个 duration 值，表示 marker 在此时间过后自动删除。如果收到相同 namespace/id 的另一个 marker，倒计时会重置。
frame_locked：如果为 false（默认），marker 会根据当前变换定位，之后即使变换发生变化也不会移动。设为 true 则 RViz 会在每次更新时将 marker 重新变换到指定坐标系的新位置。
text：用于 TEXT_VIEW_FACING marker 类型的文本字符串。
mesh_resource：MESH_RESOURCE marker 类型的资源路径。可以是 RViz 支持的任何网格类型（1.0 版本中为 .stl 或 Ogre .mesh，1.1 版本新增 COLLADA）。格式采用 resource_retriever 所用的 URI 形式，包括 package:// 语法。

3 对象类型

3.1 Arrow（ARROW=0）

Arrow Marker

箭头类型支持两种指定起点/终点的方式：

Position/Orientation：枢轴点位于箭头尾部尖端，默认朝向沿 +X 轴。scale.x 是箭头长度，scale.y 是箭头宽度，scale.z 是箭头高度。
Start/End Points：也可以使用 points 成员指定箭头的起点和终点。一旦在 points 成员中放入了点，就会自动采用这种方式。
- 索引 0 处的点作为起点，索引 1 处的点作为终点。
- scale.x 是杆部直径，scale.y 是头部直径。如果 scale.z 不为零，则指定头部长度。

3.2 Cube（CUBE=1）

Cube Marker

枢轴点位于立方体的中心。

3.3 Sphere（SPHERE=2）

Sphere Marker

枢轴点位于球体的中心。scale.x、scale.y、scale.z 分别是 x、y、z 方向的直径。将它们设为不同的值即可得到椭球而非球体。

3.4 Cylinder（CYLINDER=3）

Cylinder Marker

枢轴点位于圆柱体的中心。scale.x、scale.y 分别是 x、y 方向的直径，设为不同值可以得到椭圆截面而非圆形截面。scale.z 指定高度。

3.5 Line Strip（LINE_STRIP=4）

LineStrip Marker

Line strip 使用 visualization_msgs/msg/Marker 消息的 points 成员，在每两个连续点之间画一条线，即 0-1、1-2、2-3、3-4、4-5……

Line strip 对缩放也有特殊处理：只使用 scale.x 来控制线段宽度。注意 pose 仍然生效（线段中的点会据此进行变换），线条将相对于 header 中指定的 frame id 正确显示。

3.6 Line List（LINE_LIST=5）

LineList Marker

Line list 使用 visualization_msgs/msg/Marker 消息的 points 成员，在每对点之间画一条线，即 0-1、2-3、4-5……

Line list 对缩放也有特殊处理：只使用 scale.x 来控制线段宽度。注意 pose 仍然生效。

3.7 Cube List（CUBE_LIST=6）

CubeList Marker

Cube list 是一组共享相同属性（位置除外）的立方体。相比于使用 visualization_msgs/msg/MarkerArray，使用此类型可以让 RViz 进行批量渲染，大幅提升性能。注意列表中的立方体必须具有相同的缩放比例。

3.8 Sphere List（SPHERE_LIST=7）

SphereList Marker

Sphere list 是一组共享相同属性（位置除外）的球体。相比于使用 MarkerArray，此类型可以让 RViz 进行批量渲染。

3.9 Points（POINTS=8）

Points Marker

使用 visualization_msgs/msg/Marker 消息的 points 成员。Points 对缩放有特殊处理：scale.x 是点的宽度，scale.y 是点的高度。

3.10 View-Oriented Text（TEXT_VIEW_FACING=9）

text_view_facing Marker

此 marker 在 3D 世界中的指定位置显示文本，文本始终自动朝向用户，确保从 RViz 视角中清晰可读。使用 marker 中的 text 字段设置内容。只使用 scale.z，表示大写字母「A」的高度。

3.11 Mesh Resource（MESH_RESOURCE=10）

mesh_resource Marker

使用 marker 中的 mesh_resource 字段。可以是 RViz 支持的任何网格类型（1.0 版本中为二进制 .stl 或 Ogre .mesh，1.1 版本新增 COLLADA (.dae)）。格式采用 resource_retriever 所用的 URI 形式，包括 package:// 语法。

以下是一个网格使用示例：

marker.type = visualization_msgs::Marker::MESH_RESOURCE;
marker.mesh_resource = "package://pr2_description/meshes/base_v0/base.dae";

网格的缩放是相对的。缩放比例为 (1.0, 1.0, 1.0) 时，网格按文件中指定的原始大小显示；缩放比例为 (1.0, 1.0, 2.0) 时，网格高度变为两倍，宽度和深度不变。

如果 mesh_use_embedded_materials 标志设为 true，且网格属于支持嵌入材质的类型（如 COLLADA），则使用文件中定义的材质，而非 marker 中定义的颜色。

从 [1.8] 版本起，即使 mesh_use_embedded_materials 为 true，只要 marker 的 color 设为 r=0、g=0、b=0、a=0 以外的值，marker 的 color 和 alpha 就会用于为带嵌入材质的网格着色。

3.12 Triangle List（TRIANGLE_LIST=11）

triangle_list Marker

使用 points 和可选的 colors 成员。每三个点为一组，构成一个三角形，即索引 0-1-2、3-4-5 等。注意 pose 和 scale 仍然生效。

4 渲染复杂度说明

单个 marker 的渲染成本总是低于多个 marker。例如，一个 cube list 可以处理数千个立方体，而渲染数千个单独的 cube marker 则几乎不可行。