readPointCloud

Read point cloud data from E57 file

Since R2023a

Syntax

ptCloud = readPointCloud(e57Reader,ptCloudNum)

[ptCloud,pcMetadata] = readPointCloud(___)

Description

ptCloud = readPointCloud(e57Reader,ptCloudNum) reads the point cloud specified by the point cloud number ptCloudNum from the E57 file specified by the e57FileReader object e57Reader.

[ptCloud,pcMetadata] = readPointCloud(___) returns the metadata of the point cloud read from the file using all input arguments from the previous syntax.

Examples

Read and Visualize Point Cloud Data from E57 File

Download a ZIP file containing an E57 file, and then unzip the file.

zipFile = matlab.internal.examples.downloadSupportFile("lidar","data/e57ParkingLot.zip");
saveFolder = fileparts(zipFile);
e57FileName = [saveFolder filesep 'parkingLot.e57'];
if ~exist(e57FileName,"file")
    unzip(zipFile,saveFolder)
end

Create an e57FileReader object using the downloaded E57 file.

e57Reader = e57FileReader(e57FileName);

Define a variable for storing point clouds, ptCloudArr and their corresponding poses, tformArr.

ptCloudArr = [];
tformArr = []; 

Read the point cloud data.

for i = 1:e57Reader.NumPointClouds
   [ptCloud,pcMetadata] = readPointCloud(e57Reader,i);
    for j = 1:numel(ptCloud)
        ptCloudArr = [ptCloudArr ptCloud(j)];
        tformArr = [tformArr pcMetadata.RelativePose];
    end
end

Align the point clouds from the file to create a map.

pcMap = pcalign(ptCloudArr,tformArr); 

Display the map.

figure
pcshow(pcMap)

Input Arguments

e57Reader — E57 file reader

e57FileReader object

E57 file reader, specified as an e57FileReader object.

ptCloudNum — Point cloud number

positive integer

Point cloud number to read from the file, specified as a positive integer. This value must be less than or equal to the total number of point clouds in the file, as indicated by the value of the NumPointClouds property of the e57Reader input.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

ptCloud — Point cloud read from file

pointCloud object

Point cloud read from the file, returned as a pointCloud object. The function returns organized point clouds when the file contains organization information. Otherwise, it returns unorganized point clouds.

Note

The function returns an array of organized point clouds when the file contains organization information for multiple returns.

pcMetadata — Point cloud metadata

structure

Point cloud metadata, returned as a structure with these fields.

Field	Description
PointAttributes	Attributes of the points in the point cloud, returned as a structure containing these fields. Classification — Classification value, returned as a nonnegative integer. ReturnCount — Return count, returned as a positive integer. ReturnIndex — Return index, returned as a nonnegative integer. TimeStamp — Timestamp value, in seconds. For an unorganized point cloud, each of these fields is an M-element vector. M is the number of points in the point cloud. For an organized point cloud, each of these fields is an M-by-N matrix. M and N are the number of rows and columns of the point cloud, respectively. Note The function returns PointAttributes as an array of structures when it returns an array of point clouds.
RelativePose	Rigid transformation of the point cloud from the sensor local coordinate system to the file coordinate system, returned as a rigidtform3d object.
AcquisitionPeriod	Absolute start time and end time between which the sensor records the point cloud, respectively returned as a two-element datetime vector.
GUID	Globally unique identifier (GUID) of the point cloud in the Data3D element of the file, returned as a character vector.
OriginalGUIDs	GUIDs of the data sets to which the points in the Data3D element belong, returned as a cell array of character vectors.
Name	User-defined name of the Data3D element, returned as a character vector.
Description	User-defined description for the Data3D element, returned as a character vector.
CartesianBounds	Allowed bounds for the Cartesian coordinates of the points in the Data3D element, returned as a six-element vector of the form [xmin xmax ymin ymax zmin zmax]. Values are in meters.
SphericalBounds	Allowed bounds for the Spherical coordinates of the points in the Data3D element, returned as a structure with these fields. Field Description Range Minimum and maximum bounds for the range, returned as respective elements of a two-element nonnegative vector. Values are in meters. Elevation Minimum and maximum bounds for the elevation angle, returned as respective elements of a two-element vector. Values are in radians. Azimuth Minimum and maximum bounds for the azimuth angle, returned as respective elements of a two-element vector. Values are in radians.
IndexBounds	Bounds for point indices, returned as a structure with these fields. Field Description Row Minimum and maximum bounds for the row indices of the points in the point cloud, returned as respective elements of a two-element nonnegative vector. Column Minimum and maximum bounds for the column indices of the points in the point cloud, returned as respective elements of a two-element nonnegative vector. Return Minimum and maximum bounds for the return indices of the points in the point cloud, returned as respective elements of a two-element nonnegative vector.
SensorData	Metadata of the lidar sensor capturing the point cloud, returned as a structure with these fields. Name Description Vendor Name of the lidar sensor vendor, returned as a character vector. Model Model name or model number of the lidar sensor, returned as a character vector. SerialNumber Serial number of the lidar sensor, returned as a character vector. HardwareVersion Hardware version of the lidar sensor, returned as a character vector. SoftwareVersion Software version of the lidar sensor, returned as a character vector. FirmwareVersion Firmware version of the lidar sensor, returned as a character vector. IntensityLimits Minimum and maximum producible intensity of the lidar sensor, returned as respective elements of a two-element vector. ColorLimits Minimum and maximum producible color limits of the sensor, returned as six-element vector of the form [redmin redmax greenmin greenmax bluemin bluemax].
WeatherData	Weather data, returned as a structure with these fields. Temperature — Temperature in degree Celsius. RelativeHumidity — Relative humidity in percentage. AtmosphericPressure — Atmospheric pressure in Pascals.

For more information on the E57 file format, see E57 File Format.

Version History

Introduced in R2023a

R2025a: Reading point cloud from E57 file returns entire point cloud without cropping

The readPointCloud function now returns the entire point cloud without truncating any points. As a result, you might notice more number of points in the returned point cloud than in the previous release.

To get the same number of point cloud points as in the previous release, you must crop the point cloud based on the bounds for the Cartesian coordinates of the points. For example, this code crops the first point cloud of the input E57 file fileName.

% Load E57 file
e57Reader = e57FileReader(fileName);

% Read the first point cloud
[ptCloud,pcMetaData] = readPointCloud(e57Reader,1);

% Iterate through each point cloud for multiple returns and crop it based
% on bounds for the Cartesian coordinates
ptCropped = pointCloud.empty;
for i = 1:numel(ptCloud)
    validIdx = findPointsInROI(ptCloud(i),pcMetaData.CartesianBounds);
    if ~ismatrix(ptCloud(i).Location)
        ptCropped(i) = select(ptCloud(i),validIdx,OutputSize="full");
    else
        ptCropped(i) = select(ptCloud(i),validIdx);
    end
end