Visualize Custom Messages from ROS or ROS 2 Bag Files

The ROS Data Analyzer app enables you to visualize custom ROS and ROS 2 messages by converting them into supported standard message types using the Adapter Manager. Adapters specify how the app converts data from a custom message into a format that supported visualizers can display.

Note

To visualize custom messages, MATLAB^® must recognize the message definitions. If the messages are not already registered, generate the message package using the rosgenmsg function for ROS or ros2genmsg function for ROS 2. You can verify that MATLAB recognizes the custom message types by listing them using rosmsg list or ros2 msg list.

Supported Message Type Conversions for Visualization

The ROS Data Analyzer app visualizes custom messages by converting them into supported standard message types. You can create adapters only for custom messages whose data can be meaningfully mapped to a supported standard message type that has an associated visualizer. Typically, these are custom messages that contain image-based or spatial data suitable for visualization.

Target Standard Message Type	Supported Visualizer
sensor_msgs/Image sensor_msgs/CompressedImage	Image Viewer
sensor_msgs/PointCloud2	Point Cloud Viewer 3D Viewer
sensor_msgs/LaserScan	Laser Scan Viewer 3D Viewer
nav_msgs/Odometry	Odometry Viewer
sensor_msgs/NavSatFix gps_common/GPSFix	Map Viewer
visualization_msgs/Marker visualization_msgs/MarkerArray	Marker Viewer 3D Viewer

Tip

Adapters can also modify or transform standard message data before visualization. For example, you can apply the conversion logic of an active adapter to image data before rendering it in the Image viewer.

When to Use Message Adapters

Use message adapters to convert, modify, or transform message data at visualization, without changing the contents of the input ROS or ROS 2 bag file.

Adapters allow you to apply restructuring logic or processing algorithms, such as field remapping, filtering, or data transformation, so that you can visualize data using the supported visualizers in the app. You can update adapter logic and immediately revisualize the data, which makes adapters useful for iterative analysis and experimentation.

The following examples illustrate how adapters support different visualization workflows.

 Convert Custom Foxglove Image Messages for Visualization

This example shows how to convert image data published as foxglove_msgs/RawImage into the standard sensor_msgs/Image message type using an adapter. This conversion enables the ROS Data Analyzer app to interpret the data and make it available to supported viewers for visualization.

When a ROS 2 bag file contains image data published in a custom message type, the ROS Data Analyzer app is unable to interpret the message directly. In such cases, use an adapter to convert the custom message into a supported standard message type without modifying the contents of the bag file.

Because foxglove_msgs are not shipped with MATLAB, you must first generate the message package using the ros2genmsg function so that MATLAB recognizes the message types used by the adapter.

ros2genmsg("custom_msgs\", BuildRoot='C:/shortBuildPath')

Identifying message files in folder 'C:/Users/user/OneDrive - MathWorks/Documents/MATLAB/ExampleManager/user.myBdocUpdated/ros-ex78414578/custom_msgs'...Validating message files in folder 'C:/Users/user/OneDrive - MathWorks/Documents/MATLAB/ExampleManager/user.myBdocUpdated/ros-ex78414578/custom_msgs'...Done.
Done.
[1/1] Generating MATLAB interfaces for custom message packages... Done.
Running colcon build in folder 'C:/shortBuildPath/matlab_msg_gen_R2026a/win64'.
Build in progress. This may take several minutes...
Build succeeded.build_log.

Verify the generated message types.

ros2 msg list

To convert image data from foxglove_msgs/RawImage to sensor_msgs/Image, first understand how the two message types relate. Both message types represent a grid of pixels, and the underlying pixel data is typically compatible. Foxglove image messages use a flat layout, where metadata such as timestamp and frame ID appear at the top level of the message, while standard ROS 2 image messages store this information inside a nested header field. As a result, the adapter logic restructures metadata rather than performing complex data conversion.

Implement the adapter logic in a MATLAB® plugin (.m) file by defining how fields from the input custom message map to the corresponding fields of the standard message type. The following adapter function converts a Foxglove image message into a sensor_msgs/Image message by restructuring metadata and copying compatible image data fields.

function output_msg = FoxGloveImageAdapter(input_msg, output_msg)

% Map timestamp and frame information into the ROS 2 header
output_msg.header.frame_id = input_msg.frame_id;
output_msg.header.stamp    = input_msg.timestamp;

% Copy image dimensions
output_msg.width  = input_msg.width;
output_msg.height = input_msg.height;

% Map encoding and memory layout
output_msg.encoding = input_msg.encoding;
output_msg.step     = input_msg.step;

% Copy pixel data directly
output_msg.data = input_msg.data;

% Set endianness (ROS 2 default)
output_msg.is_bigendian = 0;
end

You can visualize the foxglove_msgs/RawImage message converted to a sensor_msgs/Image message in the Image viewer.

 Visualize Custom Point Cloud Data Using Predefined Adapter

The following video walkthrough shows a similar adapter-based workflow using point cloud data from the foxglove_msgs/PointCloud message type. In this example, the app loads a bag file that contains point cloud data published in a nonstandard message type. Instead of creating a new adapter, the workflow imports a predefined adapter that converts the custom point cloud message into a supported sensor_msgs/PointCloud2 format for visualization.

Video Transcript

 Invert RGB Image Data for Visualization

This example shows how to invert RGB image data stored as sensor_msgs/Image messages using an adapter. This workflow enables the ROS Data Analyzer app to display inverted image data for visual inspection without modifying the contents of the input ROS 2 bag file.

When a ROS 2 bag file contains image data that you want to transform for analysis, the ROS Data Analyzer app visualizes the data as recorded. In such cases, use an adapter to apply image-processing logic at visualization time so that you can inspect transformed image data without altering the stored bag file.

To invert RGB image data, both the input and output message types use the standard sensor_msgs/Image format. The adapter therefore acts as a processing step rather than a structural converter. The adapter preserves metadata such as timestamps, frame ID, and image dimensions, accesses the image pixel data, and applies an inversion operation to the RGB channels. This operation transforms each pixel value by subtracting it from the maximum intensity value.

Implement the adapter logic in a MATLAB® plugin (.m) file by defining how the adapter processes pixel data and updates message fields. The following adapter function inverts RGB image data at visualization time.

function output_msg = InvertRGBAdapter(input_msg, output_msg)

% Preserve metadata
output_msg.header = input_msg.header;
output_msg.height = input_msg.height;
output_msg.width  = input_msg.width;
output_msg.encoding = input_msg.encoding;
output_msg.step     = input_msg.step;
output_msg.is_bigendian = input_msg.is_bigendian;

% Invert pixel values (uint8 range [0, 255])
output_msg.data = uint8(255 - input_msg.data);
end

You can now visualize the inverted sensor_msgs/Image data in the Image viewer.

Specify Message Adapter Store Location

From the Message Adapters tab in the app toolstrip, click Create to specify a path to store adapter files if you are creating or working with adapters for the first time. The app saves this folder as a preference and reuses it in future sessions.

After you select the adapter store location, the app opens the Adapter Creation Utility dialog box to generate the adapter.

You can also create adapters without opening the bag file containing the custom messages.

Define Message Conversion and Generate Adapter

In the Adapter Creation Utility dialog box:

1. Select the ROS Version based on whether you are working with a ROS bag file or ROS 2 bag file.

2. Select the From Message Type to specify the custom message type in use.

3. Select the To Message Type to specify the supported standard message type for conversion.

4. Enter a name for the adapter.

5. Click Generate Adapter to generate the MATLAB plugin file (.m), that opens in the MATLAB Editor. Edit this file to implement the conversion logic that maps your custom message fields to the target visualization message type.

The Adapter Manager updates automatically as we remove or edit an existing adapter.

Manage Adapters Using Adapter Manager

From the Message Adapters tab, click Manage to open Adapter Manager. The Adapter Manager displays all the registered message adapters in a table. For each adapter, the table shows the source message type, the target message type after conversion, the ROS version, and the adapter name.

Use the Adapter Manager to:

• Create new adapters in the adapter store.

• Edit adapters to update conversion logic in the associated MATLAB plugin file (.m).

• Remove selected adapters from the list.

• Export selected adapters for sharing by packing them in a ZIP file.

• Import adapters from ZIP files.

• Filter adapters by name or message type using the search bar.

• Change the adapter store location using the folder icon next to the Adapter Store option that lists the current path to store adapters.

The Adapter Manager updates automatically when you remove or edit an existing adapter.

Visualize Custom Messages

After you register an adapter, the app adds the custom message types to the Topic List.

Open a supported visualizer and specify an adapter in the Active Adapter to apply the appropriate message conversion. After you apply the adapter, select the custom message from the Select Data Source drop-down list to visualize the data.