Main Content

readImage

(To be removed) Convert ROS image data into MATLAB image

Since R2019b

readImage will be removed in a future release. Use rosReadImage instead. For more information, see ROS Message Structure Functions.

Description

example

img = readImage(msg) converts the raw image data in the message object, msg, into an image matrix, img. You can call readImage using either 'sensor_msgs/Image' or 'sensor_msgs/CompressedImage' messages.

ROS image message data is stored in a format that is not compatible with further image processing in MATLAB®. Based on the specified encoding, this function converts the data into an appropriate MATLAB image and returns it in img.

[img,alpha] = readImage(msg) returns the alpha channel of the image in alpha. If the image does not have an alpha channel, then alpha is empty.

Examples

collapse all

Load sample ROS messages including a ROS image message, img.

exampleHelperROSLoadMessages

Read the ROS image message as a MATLAB® image.

image = readImage(img);

Display the image.

imshow(image)

Input Arguments

collapse all

'sensor_msgs/Image' or 'sensor_msgs/CompressedImage' ROS image message, specified as an Image or Compressed Image object handle.

Output Arguments

collapse all

Image, returned as a matrix representing a grayscale or RGB image or as an m-by-n-by-3 array, depending on the sensor image.

Alpha channel, returned as a uint8 grayscale image. If no alpha channel exists, alpha is empty.

Note

For CompressedImage messages, you cannot output an Alpha channel.

Tips

ROS image messages can have different encodings. The encodings supported for images are different for 'sensor_msgs/Image' and 'sensor_msgs/CompressedImage' message types. Fewer compressed images are supported. The following encodings for raw images of size M-by-N are supported using the 'sensor_msgs/Image' message type ('sensor_msgs/CompressedImage' support is in bold):

  • rgb8, rgba8, bgr8, bgra8: img is an rgb image of size M-by-N-by-3. The alpha channel is returned in alpha. Each value in the outputs is represented as a uint8.

  • rgb16, rgba16, bgr16, and bgra16: img is an RGB image of size M-by-N-by-3. The alpha channel is returned in alpha. Each value in the output is represented as a uint16.

  • mono8 images are returned as grayscale images of size M-by-N-by-1. Each pixel value is represented as a uint8.

  • mono16 images are returned as grayscale images of size M-by-N-by-1. Each pixel value is represented as a uint16.

  • 32fcX images are returned as floating-point images of size M-by-N-by-D, where D is 1, 2, 3, or 4. Each pixel value is represented as a single.

  • 64fcX images are returned as floating-point images of size M-by-N-by-D, where D is 1, 2, 3, or 4. Each pixel value is represented as a double.

  • 8ucX images are returned as matrices of size M-by-N-by-D, where D is 1, 2, 3, or 4. Each pixel value is represented as a uint8.

  • 8scX images are returned as matrices of size M-by-N-by-D, where D is 1, 2, 3, or 4. Each pixel value is represented as a int8.

  • 16ucX images are returned as matrices of size M-by-N-by-D, where D is 1, 2, 3, or 4. Each pixel value is represented as a int16.

  • 16scX images are returned as matrices of size M-by-N-by-D, where D is 1, 2, 3, or 4. Each pixel value is represented as a int16.

  • 32scX images are returned as matrices of size M-by-N-by-D, where D is 1, 2, 3, or 4. Each pixel value is represented as a int32.

  • bayer_X images are returned as either Bayer matrices of size M-by-N-by-1, or as a converted image of size M-by-N-by-3 (Image Processing Toolbox™ is required).

The following encoding for raw images of size M-by-N is supported using the 'sensor_msgs/CompressedImage' message type:

  • rgb8, rgba8, bgr8, and bgra8: img is an rgb image of size M-by-N-by-3. The alpha channel is returned in alpha. Each output value is represented as a uint8.

Version History

Introduced in R2019b

collapse all

R2021a: ROS Message Structure Functions

You can now create messages as structures with fields matching the message object properties. Using structures typically improves performance of creating, updating, and using ROS messages, but message fields are no longer validated when set. Message types and corresponding field values from the structures are validated when sent across the network.

To support message structures as inputs, new functions that operate on specialized ROS messages have been provided. These new functions are based on the existing object functions of message objects, but support ROS and ROS 2 message structures as inputs instead of message objects.

The object functions will be removed in a future release.

Message TypesObject Function NameNew Function Name

Image

CompressedImage

readImage

writeImage

rosReadImage

rosWriteImage

LaserScan

readCartesian

readScanAngles

lidarScan

plot

rosReadCartesian

rosReadScanAngles

rosReadLidarScan

rosPlot

PointCloud2

apply

readXYZ

readRGB

readAllFieldNames

readField

scatter3

rosApplyTransform

rosReadXYZ

rosReadRGB

rosReadAllFieldNames

rosReadField

rosPlot

QuaternionreadQuaternion

rosReadQuaternion

OccupancyGrid

readBinaryOccupanyGrid

readOccupancyGrid

writeBinaryOccupanyGrid

writeOccupanyGrid

rosReadOccupancyGrid

rosReadBinaryOccupancyGrid

rosReadOccupancyGrid

rosWriteBinaryOccupancyGrid

rosWriteOccupancyGrid

OctomapreadOccupancyMap3D

rosReadOccupancyMap3D

PointStamped

PoseStamped

QuaternionStamped

Vector3Stamped

TransformStamped

apply

rosApplyTransform

All messagesshowdetails

rosShowDetails