Skip to main content
Version: 10

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​

TypeConstantStatusNotes
ArrowARROW (0)✅ ImplementedBoth pose-and-scale and two-point (points[0] → points[1]) forms are supported.
CubeCUBE (1)✅ Implemented
SphereSPHERE (2)✅ Implemented
CylinderCYLINDER (3)✅ ImplementedHeight extends along the marker's local Z axis to match RViz.
Line stripLINE_STRIP (4)✅ ImplementedPer-vertex colors are honored when the number of colors entries equals the number of points entries.
Line listLINE_LIST (5)✅ ImplementedPer-vertex colors are honored when the number of colors entries equals the number of points entries.
Cube listCUBE_LIST (6)✅ ImplementedAll 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 listSPHERE_LIST (7)✅ ImplementedAll 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.
PointsPOINTS (8)✅ ImplementedEach 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-facingTEXT_VIEW_FACING (9)✅ ImplementedRenders billboarded text from the text field.
Mesh resourceMESH_RESOURCE (10)✅ ImplementedLoads .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 listTRIANGLE_LIST (11)✅ Implementedcolors 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:

Required Version
This feature will not be released until MoveIt Pro version 10.3.

Actions​

ActionConstantStatus
Add / ModifyADD / MODIFY (0)✅ Implemented
DeleteDELETE (2)✅ Implemented
Delete allDELETEALL (3)✅ Implemented — an empty ns clears every marker on the topic; a non-empty ns clears only markers in that namespace.

Other Marker Fields​

FieldStatusNotes
header.frame_id✅ ImplementedResolved against the live TF tree.
header.stampNot implementedThe latest available transform is always used; markers are not transformed at the message timestamp.
ns, id✅ ImplementedTogether they form the marker identity, as in RViz.
pose, scale✅ Implemented
color✅ Implemented
colors✅ ImplementedUsed 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✅ ImplementedMarkers expire and are removed automatically when their lifetime elapses. A zero lifetime means the marker persists until explicitly deleted.
frame_lockedNot implementedThe flag is ignored; transforms are re-resolved every frame regardless of its value.
points✅ ImplementedUsed 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✅ ImplementedUsed 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_LISTtexture_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.