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 | See MESH_RESOURCE row in the marker types table for limitations. |
mesh_use_embedded_materials | Not implemented | COLLADA meshes always render with their embedded materials; STL meshes always use the marker's 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. |