[Documentation] [TitleIndex] [WordIndex

Markers

The Markers display allows programmatic addition of various primitive shapes to the 3D view by sending a visualization_msgs/Marker or visualization_msgs/MarkerArray message.

The Markers: Basic Shapes tutorial begins a series of tutorials on sending markers.

Properties

Name

Description

Valid Values

Default

Topic

The topic to subscribe to. Will automatically also subscribe to <topic>_array, assuming it is a visualization_msgs/MarkerArray topic

Any valid Graph Resource Name

visualization_marker

The Marker Message

Example Usage (C++/roscpp)

First, advertise on the visualization_marker topic:

   1 ros::Publisher vis_pub = node_handle.advertise<visualization_msgs::Marker>( "visualization_marker", 0 );

After that it's as simple as filling out a visualization_msgs/Marker message and publishing it:

   1 visualization_msgs::Marker marker;
   2 marker.header.frame_id = "base_link";
   3 marker.header.stamp = ros::Time();
   4 marker.ns = "my_namespace";
   5 marker.id = 0;
   6 marker.type = visualization_msgs::Marker::SPHERE;
   7 marker.action = visualization_msgs::Marker::ADD;
   8 marker.pose.position.x = 1;
   9 marker.pose.position.y = 1;
  10 marker.pose.position.z = 1;
  11 marker.pose.orientation.x = 0.0;
  12 marker.pose.orientation.y = 0.0;
  13 marker.pose.orientation.z = 0.0;
  14 marker.pose.orientation.w = 1.0;
  15 marker.scale.x = 1;
  16 marker.scale.y = 0.1;
  17 marker.scale.z = 0.1;
  18 marker.color.a = 1.0; // Don't forget to set the alpha!
  19 marker.color.r = 0.0;
  20 marker.color.g = 1.0;
  21 marker.color.b = 0.0;
  22 //only if using a MESH_RESOURCE marker type:
  23 marker.mesh_resource = "package://pr2_description/meshes/base_v0/base.dae";
  24 vis_pub.publish( marker );

There is also a visualization_msgs/MarkerArray message, which lets you publish many markers at once. In this case you want to publish in the visualization_marker_array topic.

Note that the timestamp attached to the marker message above is ros::Time(), which is time Zero (0). This is treated differently by RViz than any other time. If you use ros::Time::now() or any other non-zero value, rviz will only display the marker if that time is close enough to the current time, where "close enough" depends on TF. With time 0 however, the marker will be displayed regardless of the current time.

Don't forget to set color.a = 1 or your marker will be invisible!

Message Parameters

ns

id

type

action

pose

scale

color

points

colors [1.1+]

lifetime

frame_locked [1.1+]

text [1.1+]

mesh_resource [1.1+]

Object Types

Arrow (ARROW=0)

Arrow

The arrow type provides two different ways of specifying where the arrow should begin/end:

Position/Orientation

Start/End Points

Cube (CUBE=1)

Cube

Pivot point is at the center of the cube.

Sphere (SPHERE=2)

Sphere

Pivot point is at the center of the sphere.

scale.x is diameter in x direction, scale.y in y direction, scale.z in z direction. By setting these to different values you get an ellipsoid instead of a sphere.

Cylinder (CYLINDER=3)

Cylinder

Pivot point is at the center of the cylinder.

scale.x is diameter in x direction, scale.y in y direction, by setting these to different values you get an ellipse instead of a circle. Use scale.z to specify the height.

Line Strip (LINE_STRIP=4)

Line Strip

Line strips use the points member of the visualization_msgs/Marker message. It will draw a line between every two consecutive points, so 0-1, 1-2, 2-3, 3-4, 4-5...

Line strips also have some special handling for scale: only scale.x is used and it controls the width of the line segments.

Note that pose is still used (the points in the line will be transformed by them), and the lines will be correct relative to the frame id specified in the header.

In visualization 1.1+ will also optionally use the colors member for per-vertex color.

Line List (LINE_LIST=5)

Line List

Line lists use the points member of the visualization_msgs/Marker message. It will draw a line between each pair of points, so 0-1, 2-3, 4-5, ...

Line lists also have some special handling for scale: only scale.x is used and it controls the width of the line segments.

Note that pose is still used (the points in the line will be transformed by them), and the lines will be correct relative to the frame id specified in the header.

In visualization 1.1+ will also optionally use the colors member for per-vertex color. The color of a line segment then gradually changes from its start to end point.

Cube List (CUBE_LIST=6)

Cube List

A cube list is a list of cubes with all the same properties except their positions. Using this object type instead of a visualization_msgs/MarkerArray allows rviz to batch-up rendering, which causes them to render much faster. The caveat is that they all must have the same scale.

The points member of the visualization_msgs/Marker message is used for the position of each cube.

In visualization 1.1+ will also optionally use the colors member for per-cube color.

Sphere List (SPHERE_LIST=7)

Sphere List

A sphere list is a list of spheres with all the same properties except their positions. Using this object type instead of a visualization_msgs/MarkerArray allows rviz to batch-up rendering, which causes them to render much faster. The caveat is that they all must have the same scale.

The points member of the visualization_msgs/Marker message is used for the position of each sphere.

Note that pose is still used (the points in the line will be transformed by them), and the lines will be correct relative to the frame id specified in the header.

In visualization 1.1+ will also optionally use the colors member for per-sphere color.

Points (POINTS=8)

Points

Uses the points member of the visualization_msgs/Marker message.

Points have some special handling for scale: scale.x is point width, scale.y is point height

Note that pose is still used (the points in the line will be transformed by them), and the lines will be correct relative to the frame id specified in the header.

In visualization 1.1+ will also use the colors member for per-point color.

View-Oriented Text (TEXT_VIEW_FACING=9) [1.1+]

View-Oriented Text

This marker displays text in a 3D spot in the world. The text always appears oriented correctly to the view. Uses the text field in the marker.

Only scale.z is used. scale.z specifies the height of an uppercase "A".

Mesh Resource (MESH_RESOURCE=10) [1.1+]

mesh_resource_marker.png

Uses the mesh_resource field in the marker. Can be any mesh type supported by rviz (binary .stl or Ogre .mesh in 1.0, with the addition of COLLADA (.dae) in 1.1). The format is the URI-form used by resource_retriever, including the package:// syntax.

An example of a mesh an its use is

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

Scale on a mesh is relative. A scale of (1.0, 1.0, 1.0) means the mesh will display as the exact size specified in the mesh file. A scale of (1.0, 1.0, 2.0) means the mesh will show up twice as tall, but the same width/depth.

If the mesh_use_embedded_materials flag is set to true and the mesh is of a type which supports embedded materials (such as COLLADA), the material defined in that file will be used instead of the color defined in the marker.

Since version [1.8], even when mesh_use_embedded_materials is true, if the marker color is set to anything other than r=0,g=0,b=0,a=0 the marker color and alpha will be used to tint the mesh with the embedded material.

Triangle List (TRIANGLE_LIST=11) [1.1+]

triangle_list_marker.png

Uses the points and optionally colors members. Every set of 3 points is treated as a triangle, so indices 0-1-2, 3-4-5, etc.

Note that pose and scale are still used (the points in the line will be transformed by them), and the lines will be correct relative to the frame id specified in the header.

Rendering Complexity Notes

A single marker is always less expensive to render than many markers. For example, a single cube list can handle thousands of cubes, where we will not be able to render thousands of individual cube markers.


2023-10-28 13:03