diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/Marker-Display-types.rst b/source/Tutorials/Intermediate/RViz/Marker-Display-types/Marker-Display-types.rst new file mode 100644 index 00000000000..b49931258c2 --- /dev/null +++ b/source/Tutorials/Intermediate/RViz/Marker-Display-types/Marker-Display-types.rst @@ -0,0 +1,303 @@ +Marker: Display types +===================== + +**Goal:** This tutorial explains the basic Marker types and how to use them. + +**Tutorial level:** Intermediate + +**Time:** 15 Minutes + +.. contents:: Contents + :depth: 2 + :local: + + +Background +---------- +The Markers display allows programmatic addition of various primitive shapes to the 3D view by sending a +`visualization_msgs/msg/Marker `_ or +`visualization_msgs/msg/MarkerArray `_ message. + +.. image:: images/marker_overview.png + +.. + This is a comment, the next line will be added to the file once the Markers-Sending-Basic-Shapes-CPP is merged to point to the start of the tutorial series. + The :doc:`Marker: Sending Basic Shapes <../Markers-Sending-Basic-Shapes-CPP/Markers-Sending-Basic-Shapes-CPP>` that tutorial begins a series of tutorials on sending markers. + +The Marker Message +------------------ +1 Example Usage (C++) +^^^^^^^^^^^^^^^^^^^^^ +First we will create a simple publisher node that publishes ``Marker`` messages from the ``visualization_messages`` package to the ``visualization_marker`` topic: + +.. code-block:: C++ + + auto marker_pub = node->create_publisher("visualization_marker", 1); + +After that it is as simple as filling out a `visualization_msgs/msg/Marker `_ +message and publishing it: + +.. code-block:: C++ + + 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); + +There is also a `visualization_msgs/msg/MarkerArray `_ message, which lets you publish many markers at once. + +2 Message Parameters +^^^^^^^^^^^^^^^^^^^^ + +The Marker message type is defined in `ROS 2 Common Interfaces _` package. +The messages in this package include comments that are helpful in understanding each of the fields in the message. + +* ``ns``: + + Namespace for these markers. This plus the id form a unique identifier. + +* ``id``: + + Unique id assigned to this marker. It is your responsibility to keep these unique within your namespace. + +* ``type``: + + Type of marker (Arrow, Sphere, ...). The available types are specified in the message definition. + +* ``action``: + + 0 = add/modify, 1 = (deprecated), 2 = delete, 3 = deleteall + +* ``pose``: + + Pose marker, specified as x/y/z position and x/y/z/w quaternion orientation. + +* ``scale``: + + Scale of the marker. Applied before the position/orientation. A scale of [1, 1, 1] means the object will be 1m by 1m by 1m. + +* ``color``: + + Color of the object, specified as r/g/b/a, with values in the range of [0, 1]. The, `a` or alpha value, denotes the opacity of the marker with 1 indicating opaque and 0 indicating completely transparent. The default value is 0, or completely transparent. **You must set the a value of your marker to a non-zero value or it will be transparent by default!** + +* ``points``: + + Only used for markers of type ``Points``, ``Line strips``, and ``Line`` / ``Cube`` / ``Sphere`` -lists. + It's also used for the Arrow type, if you want to specify the arrow start and end points. + This entry represents a list of `geometry_msgs/Point` types for the center or each marker object you would like rendered. + +* ``colors``: + + This field is only used for markers that use the points member. This field specifies per-vertex color r/g/b/ color (no alpha yet) for each entry in `points`. + +* ``lifetime``: + + A `duration message value `_ used to automatically delete the marker after this period of time. + The countdown resets if another marker of the same ``namespace`` / ``id`` is received. + +* ``frame_locked``: + + Without the ``frame_locked`` parameter the marker will be placed based on the current transform and will stay there even if the given transform changes later. + Setting this parameter tells RViz to retransform the marker to the new current location of the specified frame on every update cycle. + +* ``text``: + + The text string used for the ``TEXT_VIEW_FACING`` marker type + +* ``mesh_resource``: + + The resource location for the ``MESH_RESOURCE`` marker type. Can be any mesh type supported by RViz (``.stl`` or Ogre ``.mesh`` in 1.0, with the addition of COLLADA in 1.1). + The format is the URI-form used by `resource_retriever `_, including the package:// syntax. + +3 Object types +^^^^^^^^^^^^^^ + +.. _RVizMarkerObjectTypes: + +3.1 Arrow (ARROW=0) +~~~~~~~~~~~~~~~~~~~ + +.. image:: images/ArrowMarker.png + +The arrow type provides two different ways of specifying where the arrow should begin/end: + +* ``Position/Orientation``: + + Pivot point is around the tip of its tail. Identity orientation points it along the +X axis. ``scale.x`` is the arrow length, ``scale.y`` is the arrow width and ``scale.z`` is the arrow height. + +* ``Start/End Points``: + + You can also specify a start/end point for the arrow, using the points member. If you put points into the points member, it will assume you want to do things this way. + + * The point at index 0 is assumed to be the start point, and the point at index 1 is assumed to be the end. + * ``scale.x`` is the shaft diameter, and ``scale.y`` is the head diameter. If ``scale.z`` is not zero, it specifies the head length. + +3.2 Cube (CUBE=1) +~~~~~~~~~~~~~~~~~ + +.. image:: images/CubeMarker.png + +Pivot point is at the center of the cube. + +3.3 Sphere (SPHERE=2) +~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/SphereMarker.png + +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. + +3.4 Cylinder (CYLINDER=3) +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/CylinderMarker.png + +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. + +3.5 Line Strip (LINE_STRIP=4) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/LineStripMarker.png + +Line strips use the points member of the `visualization_msgs/msg/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. + +3.6 Line List (LINE_LIST=5) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/LineListMarker.png + +Line lists use the points member of the `visualization_msgs/msg/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. + +3.7 Cube List (CUBE_LIST=6) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/CubeListMarker.png + +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/msg/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/msg/Marker `_ message is used for the position of each cube. + +3.8 Sphere List (SPHERE_LIST=7) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/SphereListMarker.png + +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/msg/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/msg/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. + +3.9 Points (POINTS=8) +~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/PointsMarker.png + +Uses the ``points`` member of the `visualization_msgs/msg/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. + +3.10 View-Oriented Text (TEXT_VIEW_FACING=9) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/text_view_facing_marker.png + +This marker displays text in a 3D spot in the world. +The text always appears oriented correctly for the RViZ user to see the included text. Uses the ``text`` field in the marker. + +Only ``scale.z`` is used. ``scale.z`` specifies the height of an uppercase "A". + +3.11 Mesh Resource (MESH_RESOURCE=10) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/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: + +.. code-block:: C++ + + marker.type = visualization_msgs::Marker::MESH_RESOURCE; + 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. + +3.12 Triangle List (TRIANGLE_LIST=11) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/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. + +4 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. diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/ArrowMarker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/ArrowMarker.png new file mode 100644 index 00000000000..a10cbecb7b0 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/ArrowMarker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/CubeListMarker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/CubeListMarker.png new file mode 100644 index 00000000000..25ba49d0121 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/CubeListMarker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/CubeMarker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/CubeMarker.png new file mode 100644 index 00000000000..3dd9a964682 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/CubeMarker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/CylinderMarker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/CylinderMarker.png new file mode 100644 index 00000000000..fda540c2f38 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/CylinderMarker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/LineListMarker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/LineListMarker.png new file mode 100644 index 00000000000..f7b92a0296a Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/LineListMarker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/LineStripMarker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/LineStripMarker.png new file mode 100644 index 00000000000..57ecae33050 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/LineStripMarker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/PointsMarker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/PointsMarker.png new file mode 100644 index 00000000000..27e3b3a75e9 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/PointsMarker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/SphereListMarker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/SphereListMarker.png new file mode 100644 index 00000000000..779477c2f36 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/SphereListMarker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/SphereMarker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/SphereMarker.png new file mode 100644 index 00000000000..06e9df30a1a Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/SphereMarker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/marker_overview.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/marker_overview.png new file mode 100644 index 00000000000..698a84048d7 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/marker_overview.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/mesh_resource_marker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/mesh_resource_marker.png new file mode 100644 index 00000000000..ab1966a2be7 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/mesh_resource_marker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/text_view_facing_marker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/text_view_facing_marker.png new file mode 100644 index 00000000000..ddcf03148bb Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/text_view_facing_marker.png differ diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/triangle_list_marker.png b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/triangle_list_marker.png new file mode 100644 index 00000000000..caaa4722b47 Binary files /dev/null and b/source/Tutorials/Intermediate/RViz/Marker-Display-types/images/triangle_list_marker.png differ diff --git a/source/Tutorials/Intermediate/RViz/RViz-Main.rst b/source/Tutorials/Intermediate/RViz/RViz-Main.rst index a9da2f4a04f..59559f5a4e7 100644 --- a/source/Tutorials/Intermediate/RViz/RViz-Main.rst +++ b/source/Tutorials/Intermediate/RViz/RViz-Main.rst @@ -12,3 +12,4 @@ RViz is a 3D visualizer for the Robot Operating System (ROS) framework. RViz-User-Guide/RViz-User-Guide RViz-Custom-Display/RViz-Custom-Display + Marker-Display-types/Marker-Display-types