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.
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 | Per-vertex colors are honored when the number of colors entries equals the number of points entries. |
| 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. Each cube takes its entry in colors when the number of colors entries equals the number of points entries; otherwise all cubes use color. |
| Sphere list | SPHERE_LIST (7) | ✅ Implemented | All spheres share the marker's scale. Each sphere takes its entry in colors when the number of colors entries equals the number of points entries; otherwise all spheres use color. |
| Points | POINTS (8) | ✅ Implemented | Each point is drawn as a square dot scale.x meters wide that keeps its size in meters as the camera zooms. scale.y is ignored, so dots are always square. Per-point colors are honored when the number of colors entries equals the number of points entries. |
| Text view-facing | TEXT_VIEW_FACING (9) | ✅ Implemented | Renders billboarded text from the text field. |
| Mesh resource | MESH_RESOURCE (10) | ✅ Implemented | Loads .stl, .dae, .obj, .glb, and .gltf meshes from a package:// URL, or from mesh_file when mesh_resource is embedded://<name>. glTF meshes are turned from Y-up to ROS Z-up, as in RViz. The whole glTF scene is turned, so a glTF whose single top-level node has its own rotation or offset can sit differently than in RViz. Compressed glTF (Draco, meshopt, or KTX2) is not supported. glTF allocation metadata must fit a 64 MiB geometry budget, including accessor copies and instance matrices; simplify a model that exceeds this budget. |
| Triangle list | TRIANGLE_LIST (11) | ✅ Implemented | colors can hold one entry per vertex (blended across each triangle) or one entry per triangle; each entry's alpha is multiplied by color.a. With any other number of entries, the whole list uses color. With texture_resource and one uv_coordinates entry per point, the list is textured. |
For OBJ and glTF meshes, embedded mesh_file data, and textured TRIANGLE_LIST markers:
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 | Used by POINTS, LINE_STRIP, LINE_LIST, CUBE_LIST, SPHERE_LIST, and TRIANGLE_LIST. Each entry's alpha is honored. When the number of entries does not match what the marker type expects, the marker uses the single color field, as in RViz. |
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 POINTS, LINE_*, *_LIST, and the two-point ARROW form. |
text | ✅ Implemented for TEXT_VIEW_FACING only. | |
mesh_resource | ✅ Implemented | .stl, .dae, .obj, .glb, and .gltf are loaded; a marker naming any other format (for example .ply) 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), OBJ, and glTF. | When set, the mesh preserves its embedded colors and textures. Hardware-accelerated rendering uses a matte finish and ignores Collada specular and shininess; software rendering preserves those material properties. 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 uses its embedded colors and textures, rather than rendering fully transparent. An OBJ mesh's .mtl file is not loaded, so its embedded material is a plain default one. STL meshes carry no embedded materials and always use color. |
mesh_file | ✅ Implemented | Used when mesh_resource is embedded://<name>. The format comes from the extension of mesh_file.filename. Use a different <name> for each mesh's content and format. Once sent, the data may be left empty in later messages with the same <name>. Reuse lasts only while the Desktop App still caches that data. It keeps names used by shown markers and up to 1024 recent unused names; older unused names or data can be dropped. A publisher that cannot tell when a marker is shown again should send mesh_file.data in every message. If a marker arrives with empty data after its data was dropped, resend mesh_file.data under the same ns and id to display it; deleting the marker first is not required. An embedded mesh must be self-contained: it cannot reference external files such as a .mtl, a .bin, or textures, so glTF must be .glb or .gltf with data: URIs. |
texture_resource, texture, uv_coordinates | ✅ Implemented for TRIANGLE_LIST | texture_resource is a package:// PNG or JPEG image URL, or embedded://<name> for a PNG or JPEG image sent in texture; v = 0 is the image's top row, as in RViz. The texture applies only when uv_coordinates has one entry per point; any other scheme draws the list untextured with a console warning. Embedded meshes and textures are limited to 64 MiB, textures to 16384 pixels a side, and a package:// glTF can reference only files in packages. MESH_RESOURCE meshes use their own textures instead. |