ousterFileReader

Read point cloud data from Ouster PCAP file

Since R2022a

expand all in page

Description

The ousterFileReader object reads point cloud data from an Ouster^® packet capture (PCAP) file.

Creation

Syntax

ousterReader = ousterFileReader(fileName,calibrationFile)

ousterReader = ousterFileReader(fileName,calibrationFile,Name=Value)

Description

ousterReader = ousterFileReader(fileName,calibrationFile) creates an ousterFileReader object that reads point cloud data from an Ouster PCAP file. Specify the PCAP file fileName and the calibration file calibrationFile. The inputs set the FileName and CalibrationFile properties, respectively.

For information on supported Ouster sensor models, see DeviceModel property.

example

ousterReader = ousterFileReader(fileName,calibrationFile,Name=Value) specify SkipPartialFrames and CoordinateFrame properties using one or more name-value arguments. For example, ousterFileReader(fileName,calibrationFile,SkipPartialFrames=0) creates an Ouster file reader that does not skip partial frames.

Properties

expand all

`FileName` — Name of Ouster PCAP file
character vector | string scalar

This property is read-only.

Name of the Ouster PCAP file, specified as a character vector or string scalar.

`SkipPartialFrames` — Partial frame processing
`true` or `1` (default) | `false` or `0`

This property is read-only.

Partial frame processing, specified as a logical 1 (true) or 0 (false). To skip partial frames, defined as frames with a horizontal field of view less than the mean horizontal field of view of all frames in the PCAP file, specify this property as true. Otherwise, specify it as false.

To set this property, you must specify it at object creation.

Example: SkipPartialFrames=true skips partial frames in the PCAP file.

`HasIMUData` — PCAP file contains IMU data
`true` or `1` | `false` or `0`

This property is read-only.

PCAP file contains IMU data, stored as a logical 1 (true) or 0 (false).

Data Types: logical

`CoordinateFrame` — Coordinate frame for point cloud data
`"center"` (default) | `"base"`

This property is read-only.

Coordinate frame for point cloud data, specified as one of these options.

"center" — Origin of the coordinate frame is at the center of the sensor.
"base" — Origin of the coordinate frame is at the base of the sensor.

To set this property, you must specify it at object creation.

Example: CoordinateFrame="center" sets the origin of the coordinate frame at the center of the sensor.

Data Types: char | string

`DeviceModel` — Name of device model
character vector

This property is read-only.

Name of the device model, stored as a character vector. The object supports these device models:

OS0-32
OS1-32
OS2-32
OS0-64
OS1-64
OS2-64
OS0-128
OS1-128
OS2-128

`CalibrationFile` — Name of Ouster calibration JSON file
character vector | string scalar

This property is read-only.

Name of the Ouster calibration JSON file, specified as a character vector or string scalar.

Note

Specifying the incorrect calibration file returns no frames or an improperly calibrated point cloud.

`LidarMode` — Mode of lidar sensor
character vector

This property is read-only.

Mode of the lidar sensor, specified as a character vector. The mode defines the horizontal resolution and rotation frequency of the lidar sensor.

`ReturnMode` — Return modes of the point cloud data
`{'strongest'}` | `{'secondStrongest'}` | `{'strongest','secondStrongest'}`

This property is read-only.

Return modes of the point cloud data stored in the file, specified as {'strongest'}, {'secondStrongest'}, or {'strongest','secondStrongest'}.

`FirmwareVersion` — Firmware version of Ouster sensor
character vector

This property is read-only.

Firmware version of the Ouster sensor, stored as a character vector. For more information on supported firmware versions, see Release-by-Release Version Support.

`LidarUDPProfile` — Lidar data packet format
character vector

This property is read-only.

Lidar data packet format in the file, stored as one of these values.

'LEGACY' — Legacy data packet format
'RNG19_RFL8_SIG16_NIR16' — Single return profile that is similar to the channel data block present in the LEGACY format.
'RNG19_RFL8_SIG16_NIR16_DUAL'— Dual return profile that enables the sensor to output strongest and second-strongest returns.
'RNG15_RFL8_NIR8' — Low data rate profile, where the data rate and data packet size are smaller compared to other formats.

For more information on the data profiles, see the Sensor Data section in the Ouster Firmware User Manual.

`NumberOfFrames` — Total number of point cloud frames in file
positive integer

This property is read-only.

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

`Duration` — Total duration of file
`duration` scalar

This property is read-only.

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

`StartTime` — Time of first point cloud reading
`duration` scalar

This property is read-only.

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

`EndTime` — Time of final point cloud reading
`duration` scalar

This property is read-only.

Time of the final point cloud reading, specified as a duration scalar in seconds.

`CurrentTime` — Time of current point cloud reading
`duration` scalar

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

`Timestamps` — Start time for each point cloud frame
`duration` vector

This property is read-only.

Start time for each point cloud frame, specified as a duration vector with values in seconds. The length of the vector is equal to the value of the NumberOfFrames property. The value of the first element in the vector is same as the value of the StartTime property. You can use this property to read point cloud frames captured at different times.

Object Functions

`hasFrame`	Determine if another Ouster point cloud is available
`readFrame`	Read Ouster point cloud from file
`reset`	Reset `ousterFileReader` object to first frame
`readIMU`	Read IMU data from Ouster PCAP file

Examples

collapse all

Read and Visualize Point Clouds from Ouster PCAP File

Open Live Script

Download a ZIP file containing an Ouster packet capture (PCAP) file and the corresponding calibration file, and then unzip the file.

zipFile = matlab.internal.examples.downloadSupportFile("lidar","data/ouster_RoadIntersection.zip");
saveFolder = fileparts(zipFile);
pcapFileName = [saveFolder filesep 'ouster_RoadIntersection' filesep 'ouster_RoadIntersection.pcap'];
calibFileName = [saveFolder filesep 'ouster_RoadIntersection' filesep 'OS1-128U.json'];
if ~(exist(pcapFileName,"file") && exist(calibFileName,"file"))
    unzip(zipFile,saveFolder);
end

Create an ousterFileReader object.

ousterReader = ousterFileReader(pcapFileName,calibFileName);

Define X-, Y-, and Z-axes limits for pcplayer, in meters.

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

Create a point cloud player.

player = pcplayer(xlimits,ylimits,zlimits);

Set labels for the pcplayer axes.

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

Specify the CurrentTime of the Ouster file reader so that it starts reading from 0.3 seconds after the start time.

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

Display the stream of point clouds from CurrentTime to the final point cloud.

while(hasFrame(ousterReader) && player.isOpen())
    ptCloud = readFrame(ousterReader);
    view(player,ptCloud);
end

Figure Point Cloud Player contains an axes object. The axes object with xlabel X (m), ylabel Y (m) contains an object of type scatter.

Tips

Release-by-Release Version Support

Release	Supported Firmware Versions
R2022a	Support added for: 2.0 2.1
R2023a	Support added for: 2.2 2.3
R2023b	Support added for: 2.4
R2024a	Support added for: 2.5 3.0

Version History

Introduced in R2022a

expand all

R2024b: Read IMU data from Ouster PCAP files

The ousterFileReader object includes a HasIMUData property that indicates whether the PCAP file contains IMU data. To read IMU data from the PCAP file, use the readIMU object function.

R2024a: Support for firmware versions 2.5 and 3.0

The ousterFileReader object supports firmware versions 2.5 and 3.0 of an Ouster lidar sensor.

R2023a: Object has additional properties

The ousterFileReader object includes these additional properties:

ReturnMode
FirmwareVersion
LidarUDPProfile

ousterFileReader

Description

Creation

Syntax

Description

Properties

`FileName` — Name of Ouster PCAP file
character vector | string scalar

`SkipPartialFrames` — Partial frame processing
`true` or `1` (default) | `false` or `0`

`HasIMUData` — PCAP file contains IMU data
`true` or `1` | `false` or `0`

`CoordinateFrame` — Coordinate frame for point cloud data
`"center"` (default) | `"base"`

`DeviceModel` — Name of device model
character vector

`CalibrationFile` — Name of Ouster calibration JSON file
character vector | string scalar

`LidarMode` — Mode of lidar sensor
character vector

`ReturnMode` — Return modes of the point cloud data
`{'strongest'}` | `{'secondStrongest'}` | `{'strongest','secondStrongest'}`

`FirmwareVersion` — Firmware version of Ouster sensor
character vector

`LidarUDPProfile` — Lidar data packet format
character vector

`NumberOfFrames` — Total number of point cloud frames in file
positive integer

`Duration` — Total duration of file
`duration` scalar

`StartTime` — Time of first point cloud reading
`duration` scalar

`EndTime` — Time of final point cloud reading
`duration` scalar

`CurrentTime` — Time of current point cloud reading
`duration` scalar

`Timestamps` — Start time for each point cloud frame
`duration` vector

Object Functions

Examples

Read and Visualize Point Clouds from Ouster PCAP File

Tips

Version History

R2024b: Read IMU data from Ouster PCAP files

R2024a: Support for firmware versions 2.5 and 3.0

R2023a: Object has additional properties

See Also

Functions

Objects

Topics

External Websites

ousterFileReader

Description

Creation

Syntax

Description

Properties

FileName — Name of Ouster PCAP file character vector | string scalar

SkipPartialFrames — Partial frame processing true or 1 (default) | false or 0

HasIMUData — PCAP file contains IMU data true or 1 | false or 0

CoordinateFrame — Coordinate frame for point cloud data "center" (default) | "base"

DeviceModel — Name of device model character vector

CalibrationFile — Name of Ouster calibration JSON file character vector | string scalar

LidarMode — Mode of lidar sensor character vector

ReturnMode — Return modes of the point cloud data {'strongest'} | {'secondStrongest'} | {'strongest','secondStrongest'}

FirmwareVersion — Firmware version of Ouster sensor character vector

LidarUDPProfile — Lidar data packet format character vector

NumberOfFrames — Total number of point cloud frames in file positive integer

Duration — Total duration of file duration scalar

StartTime — Time of first point cloud reading duration scalar

EndTime — Time of final point cloud reading duration scalar

CurrentTime — Time of current point cloud reading duration scalar

Timestamps — Start time for each point cloud frame duration vector

Object Functions

Examples

Read and Visualize Point Clouds from Ouster PCAP File

Tips

Version History

R2024b: Read IMU data from Ouster PCAP files

R2024a: Support for firmware versions 2.5 and 3.0

R2023a: Object has additional properties

See Also

Functions

Objects

Topics

External Websites

`FileName` — Name of Ouster PCAP file
character vector | string scalar

`SkipPartialFrames` — Partial frame processing
`true` or `1` (default) | `false` or `0`

`HasIMUData` — PCAP file contains IMU data
`true` or `1` | `false` or `0`

`CoordinateFrame` — Coordinate frame for point cloud data
`"center"` (default) | `"base"`

`DeviceModel` — Name of device model
character vector

`CalibrationFile` — Name of Ouster calibration JSON file
character vector | string scalar

`LidarMode` — Mode of lidar sensor
character vector

`ReturnMode` — Return modes of the point cloud data
`{'strongest'}` | `{'secondStrongest'}` | `{'strongest','secondStrongest'}`

`FirmwareVersion` — Firmware version of Ouster sensor
character vector

`LidarUDPProfile` — Lidar data packet format
character vector

`NumberOfFrames` — Total number of point cloud frames in file
positive integer

`Duration` — Total duration of file
`duration` scalar

`StartTime` — Time of first point cloud reading
`duration` scalar

`EndTime` — Time of final point cloud reading
`duration` scalar

`CurrentTime` — Time of current point cloud reading
`duration` scalar

`Timestamps` — Start time for each point cloud frame
`duration` vector