Visualize 3D Markers
The MoveIt Pro 3D Visualizer renders visualization_msgs/MarkerArray messages — the same spec RViz uses. To draw shapes, lines, text, or meshes in the 3D scene, publish a MarkerArray to the /visual_markers topic from any ROS 2 node, Behavior, or external script.
# Minimal example: publish a red sphere at the origin of the world frame
publisher = node.create_publisher(MarkerArray, "/visual_markers", 1)
marker = Marker()
marker.header.frame_id = "world"
marker.ns = "demo"
marker.id = 0
marker.type = Marker.SPHERE
marker.action = Marker.ADD
marker.pose.orientation.w = 1.0
marker.scale.x = marker.scale.y = marker.scale.z = 0.1
marker.color.r = 1.0
marker.color.a = 1.0
publisher.publish(MarkerArray(markers=[marker]))
Markers are grouped by their ns (namespace) field in the 3D Visualization view dropdown, where each namespace can be toggled on or off independently.
tip
For one-off pose visualization inside a Behavior Tree, the TransformPose Behavior has a built-in visualize_pose port that publishes a coordinate-frame marker for you — no separate publisher needed.
Specification Coverage
The 3D Visualizer implements nearly all of the visualization_msgs/Marker specification.
Marker Types
| Type | Constant | Status | Notes |
|---|---|---|---|
| Arrow | ARROW (0) | ✅ Implemented | Both pose-and-scale and two-point (points[0] → points[1]) forms are supported. |
| Cube | CUBE (1) | ✅ Implemented | |
| Sphere | SPHERE (2) | ✅ Implemented | |
| Cylinder | CYLINDER (3) | ✅ Implemented | Height extends along the marker's local Z axis to match RViz. |
| Line strip | LINE_STRIP (4) | ✅ Implemented | |
| Line list | LINE_LIST (5) | ✅ Implemented | Per-vertex colors are honored when the number of colors entries equals the number of points entries. |
| Cube list | CUBE_LIST (6) | ✅ Implemented | All cubes share the marker's scale and color. |
| Sphere list | SPHERE_LIST (7) | ✅ Implemented | All spheres share the marker's scale and color. |
| Points | POINTS (8) | Not implemented | The marker is dropped and an error is logged. Use SPHERE_LIST or CUBE_LIST for discrete point clouds. |
| Text view-facing | TEXT_VIEW_FACING (9) | ✅ Implemented | Renders billboarded text from the text field. |
| Mesh resource | MESH_RESOURCE (10) | ✅ Implemented | Only package:// URLs ending in .stl or .dae are loaded. |
| Triangle list | TRIANGLE_LIST (11) | ✅ Implemented |
Actions
| Action | Constant | Status |
|---|---|---|
| Add / Modify | ADD / MODIFY (0) | ✅ Implemented |
| Delete | DELETE (2) | ✅ Implemented |
| Delete all | DELETEALL (3) | ✅ Implemented — an empty ns clears every marker on the topic; a non-empty ns clears only markers in that namespace. |
Other Marker Fields
| Field | Status | Notes |
|---|---|---|
header.frame_id | ✅ Implemented | Resolved against the live TF tree. |
header.stamp | Not implemented | The latest available transform is always used; markers are not transformed at the message timestamp. |
ns, id | ✅ Implemented | Together they form the marker identity, as in RViz. |
pose, scale | ✅ Implemented | |
color | ✅ Implemented | |
colors | ✅ Implemented for LINE_LIST only. | Other list-type markers ignore colors and use the single color field. |
lifetime | ✅ Implemented | Markers expire and are removed automatically when their lifetime elapses. A zero lifetime means the marker persists until explicitly deleted. |
frame_locked | Not implemented | The flag is ignored; transforms are re-resolved every frame regardless of its value. |
points | ✅ Implemented | Used by LINE_*, *_LIST, and the two-point ARROW form. |
text | ✅ Implemented for TEXT_VIEW_FACING only. | |
mesh_resource | ✅ Implemented | Only .stl and .dae are loaded; a marker naming any other format (for example .obj) is skipped with a console warning rather than failing the view. See the MESH_RESOURCE row in the marker types table for limitations. |
mesh_use_embedded_materials | ✅ Implemented for COLLADA (.dae) only. | When set, the mesh keeps its embedded materials; otherwise it is drawn in the marker's color, alpha included. A marker that leaves color fully zeroed is treated as expressing no preference and also keeps its embedded materials, rather than rendering fully transparent. STL meshes carry no embedded materials and always use color. |
mesh_file | Not implemented | Inline mesh data is not loaded — only package:// URLs in mesh_resource are supported. |
texture_resource, texture, uv_coordinates | Not implemented | Textured meshes and textured TRIANGLE_LIST markers are not supported; untextured TRIANGLE_LIST markers are supported. |