Main Content

velodyneROSMessageReader

Read Velodyne ROS messages

Description

The velodyneROSMessageReader object reads point cloud data from VelodyneScan ROS messages, collected from a Velodyne® lidar sensor. To read this point cloud data into the workspace as point cloud object, use the readFrame object function. To check for additional point clouds in the message set, use the hasFrame object function.

Creation

Description

example

veloReader = velodyneROSMessageReader(msgs,devicemodel) creates a Velodyne ROS message reader object for a set of VelodyneScan ROS messages msgs from a specified device model devicemodel.

veloReader = velodyneFileReader(fileName,deviceModel,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, (OrganizePoints=true) returns an organized point cloud.

Input Arguments

expand all

Velodyne scan ROS messages, specified as a cell array of VelodyneScan message objects or a structure array. The message type is velodyne_msgs/VelodyneScan. This argument sets the VelodyneMessages property.

Name of the device model, specified as a character vector:

  • 'VLP16'

  • 'VLP32C'

  • 'HDL32E'

  • 'HDL64E'

Note

Specifying a device model other than the one that captured the scans may result in improperly calibrated point clouds.

Properties

expand all

This property is read-only.

Raw Velodyne ROS messages, specified as a cell array of VelodyneScan message objects or structure array. The ROS messages are of type velodyne_msgs/VelodyneScan.

This property is read-only.

Velodyne device model name, specified as 'VLP16', 'VLP32C', 'HDL32E', 'HDL64E', or 'VLS128'.

Note

Specifying a device model other than the one that captured the scans may result in improperly calibrated point clouds.

This property is read-only.

Name of the Velodyne calibration XML file, specified as a character vector or string scalar. Each device model includes a default calibration file.

This property is read-only.

Total number of point clouds in the file, specified as a positive integer.

This property is read-only.

Total duration of the file, specified as a duration scalar, in seconds.

This property is read-only.

Timestamp of the first point cloud, specified as a duration scalar in seconds.

Start and end times are specified relative to the previous whole hour. For instance, if the file is recorded for 7 minutes from 13:58 to 14:05, then:

  • StartTime = 58 min = 3480 s

  • EndTime = StartTime + 7 min = 65 min = 3900 s

This property is read-only.

Timestamp of the last point cloud reading, specified as a duration scalar, in seconds.

Start and end times are relative to the whole hour. For example, if the data is recorded over the 7 minutes from 1:58 PM to 2:05 PM, then:

  • StartTime = 58 min = 3840 s

  • EndTime = StartTime + 7 min = 65 min = 3900 s

This property is read-only.

Timestamps of the point cloud frames in seconds, specified as a duration vector. The length of the vector is equal to the value of the NumberOfFrames property. The value of the first element in the vector is the same as that of the StartTime property. You can use this property to read point cloud frames captured at different times.

For example, read the timestamp of a point cloud frame from the Timestamps property. Use the start time as an input for the readFrame object function to read the corresponding point cloud frame.

veloReader = velodyneROSMessageReader(msgs,'HDL32E')
frameTime = veloReader.Timestamps(10);
ptCloud = readFrame(veloReader,frameTime);

Timestamp of the current point cloud reading, specified as a duration scalar, in seconds. As you read point clouds using the readFrame object function, the object updates this property with the most recently read point cloud. You can use the reset object function to reset this property to the default value. The default value matches the StartTime property.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: (OrganizePoints=true) returns an organized point cloud.

Calibration XML file, specified as a string. If you do not specify a calibration file, the reader selects a default calibration file containing data from the Velodyne device manual.

Logical to set the structure for the output point cloud, specified as a numeric or logical 1 (true) or 0 (false).

To return an organized point cloud structure, set OrganizePoints to true. For an organized point cloud, every row represents a separate laser scan, and the number of columns is based on the horizontal angle resolution of the sensor.

To return an organized point cloud structure, set OrganizePoints to false.

Object Functions

hasFrameDetermine if another Velodyne point cloud is available in the ROS messages
readFrameRead point cloud frame from ROS message
resetReset CurrentTime property of velodyneROSMessageReader object to default value

Examples

collapse all

Velodyne ROS messages store data in a format that requires some interpretation before it can be used for further processing. MATLAB® can help you by formatting Velodyne ROS messages for easy use. In this example, you can explore how VelodyneScan messages from a Velodyne LiDAR are handled.

Prerequisites: Work with Basic ROS Messages

Load Sample Messages

Load sample Velodyne messages. These messages are populated with data gathered from Velodyne LiDAR sensor.

load("lidarData_ConstructionRoad.mat")

VelodyneScan Messages

VelodyneScan messages are ROS messages that contain Velodyne LIDAR scan packets. You can see the standard ROS format for a VelodyneScan message by creating an empty message of the appropriate type. Use messages in structure format for better performance.

emptyveloScan = rosmessage("velodyne_msgs/VelodyneScan","DataFormat","struct")
emptyveloScan = struct with fields:
    MessageType: 'velodyne_msgs/VelodyneScan'
         Header: [1×1 struct]
        Packets: [0×1 struct]

Since you created an empty message, emptyveloScan does not contain any meaningful data. For convenience, the loaded lidarData_ConstructionRoad.mat file contains a set of VelodyneScan messages that are fully populated and stored in the msgs variable. Each element in the msgs cell array is a VelodyneScan ROS message struct. The primary data in each VelodyneScan message is in the Packets property, it contains multiple VelodynePacket messages. You can see the standard ROS format for a VelodynePacket message by creating an empty message of the appropriate type.

emptyveloPkt = rosmessage("velodyne_msgs/VelodynePacket","DataFormat","struct")
emptyveloPkt = struct with fields:
    MessageType: 'velodyne_msgs/VelodynePacket'
          Stamp: [1×1 struct]
           Data: [1206×1 uint8]

Create Velodyne ROS Message Reader

The velodyneROSMessageReader object reads point cloud data from VelodyneScan ROS messages based on their specified model type. Note that providing an incorrect device model may result in improperly calibrated point clouds. This example uses messages from the "HDL32E" model.

veloReader = velodyneROSMessageReader(msgs,"HDL32E")
veloReader = 
  velodyneROSMessageReader with properties:

    VelodyneMessages: {28×1 cell}
         DeviceModel: 'HDL32E'
     CalibrationFile: 'M:\jobarchive\Bdoc21b\2021_06_16_h16m50s15_job1697727_pass\matlab\toolbox\shared\pointclouds\utilities\velodyneFileReaderConfiguration\HDL32E.xml'
      NumberOfFrames: 55
            Duration: 2.7477 sec
           StartTime: 1145.2 sec
             EndTime: 1147.9 sec
          Timestamps: [1145.2 sec    1145.2 sec    1145.3 sec    1145.3 sec    1145.4 sec    1145.4 sec    1145.5 sec    1145.5 sec    1145.6 sec    1145.6 sec    1145.7 sec    1145.7 sec    1145.8 sec    1145.8 sec    1145.9 sec    1145.9 sec    …    ]
         CurrentTime: 1145.2 sec

Extract Point Clouds

You can extract point clouds from the raw packets message with the help of this velodyneROSMessageReader object. By providing a specific frame number or timestamp, one point cloud can be extracted from velodyneROSMessageReader object using the readFrame object function. If you call readFrame without a frame number or timestamp, it extracts the next point cloud in the sequence based on the CurrentTime property.

Create a duration scalar that represents one second after the first point cloud reading.

timeDuration = veloReader.StartTime + seconds(1);

Read the first point cloud recorded at or after the given time duration.

ptCloudObj = readFrame(veloReader,timeDuration);

Access Location data in the point cloud.

ptCloudLoc = ptCloudObj.Location;

Reset the CurrentTime property of veloReader to the default value

reset(veloReader)

Display All Point Clouds

You can also loop through all point clouds in the input Velodyne ROS messages.

Define x-, y-, and z-axes limits for pcplayer in meters. Label the axes.

xlimits = [-60 60];
ylimits = [-60 60];
zlimits = [-20 20];

Create the point cloud player.

player = pcplayer(xlimits,ylimits,zlimits);

Label the axes.

xlabel(player.Axes,"X (m)");
ylabel(player.Axes,"Y (m)");
zlabel(player.Axes,"Z (m)");

The first point cloud of interest is captured at 0.3 second into the input messages. Set the CurrentTime property to that time to begin reading point clouds from there.

veloReader.CurrentTime = veloReader.StartTime + seconds(0.3);

Display the point cloud stream for 2 seconds. To check if a new frame is available and continue past 2 seconds, remove the last while condition. Iterate through the file by calling readFrame to read in point clouds. Display them using the point cloud player.

while(hasFrame(veloReader) && isOpen(player) && (veloReader.CurrentTime < veloReader.StartTime + seconds(2)))
    ptCloudObj = readFrame(veloReader);
    view(player,ptCloudObj.Location,ptCloudObj.Intensity);
    pause(0.1);
end

Tips

  • Providing an incorrect device model will result in improperly calibrated point clouds.

  • Not providing a calibration file can lead to inaccurate results.

Version History

Introduced in R2020b