Main Content

Code Generation For Lidar Object Detection Using PointPillars Deep Learning

This example shows how to generate CUDA® MEX for a PointPillars object detector with custom layers. For more information, see Lidar 3-D Object Detection Using PointPillars Deep Learning example from the Lidar Toolbox™.

Third-Party Prerequisites

Required

  • CUDA enabled NVIDIA® GPU and compatible driver.

Optional

For non-MEX builds such as static and dynamic libraries or executables, this example has the following additional requirements.

Verify GPU Environment

To verify that the compilers and libraries for running this example are set up correctly, use the coder.checkGpuInstall (GPU Coder) function.

envCfg = coder.gpuEnvConfig('host');
envCfg.DeepLibTarget = 'cudnn';
envCfg.DeepCodegen = 1;
envCfg.Quiet = 1;
coder.checkGpuInstall(envCfg);

Pretrained PointPillars Network

Download the PointPillars network trained in the Lidar 3-D Object Detection Using PointPillars Deep Learning example. To train the network yourself, see Lidar 3-D Object Detection Using PointPillars Deep Learning.

outputFolder = fullfile(tempdir, 'Pandaset');
pretrainedNetURL = 'https://ssd.mathworks.com/supportfiles/lidar/data/trainedPointPillarsPandasetNet.zip';
matFile = helperDownloadPretrainedPointPillarsNet(outputFolder, pretrainedNetURL);
load(matFile,'net');

pointpillarsDetect Entry-Point Function

The pointpillarsDetect entry-point function takes pillar features and pillar indices as input and passes them to a trained network for prediction through the pointpillarPredict function. The pointpillarsDetect function loads the network object from the MAT file into a persistent variable and reuses the persistent object for subsequent prediction calls. Specifically, the function uses the dlnetwork representation of the network trained in the Lidar 3-D Object Detection Using PointPillars Deep Learning.

type('pointpillarsDetect.m')
function [bboxes,scores,labels] = pointpillarsDetect(matFile, pillarFeatures, pillarIndices, gridParams, numOutputs, confidenceThreshold, overlapThreshold, classNames)
% The pointpillarsDetect function detects the bounding boxes, scores, and
% labels in the point cloud.

coder.extrinsic('helpergeneratePointPillarDetections');

% Define Anchor Boxes
anchorBoxes = {{1.92, 4.5, 1.69, -1.78, 0}, {1.92, 4.5, 1.69, -1.78, pi/2}, {2.1575, 6.0081, 2.3811, -1.78, 0}, {2.1575, 6.0081, 2.3811, -1.78, pi/2}};

% Predict the output
predictions = pointpillarPredict(matFile,pillarFeatures,pillarIndices,numOutputs);

% Generate Detections
[bboxes,scores,labels] = helpergeneratePointPillarDetections(predictions,gridParams,pillarIndices,...
                         anchorBoxes,confidenceThreshold,overlapThreshold,classNames);

end

function YPredCell = pointpillarPredict(matFile,pillarFeatures,pillarIndices,numOutputs)
% Predict the output of network and extract the following confidence,
% x, y, z, l, w, h, yaw and class.

% load the deep learning network for prediction
persistent net;

if isempty(net)
    net = coder.loadDeepLearningNetwork(matFile);
end

YPredCell = cell(1,numOutputs);
[YPredCell{:}] = predict(net,pillarIndices,pillarFeatures);
end

Evaluate the Entry-Point Function for Object Detection

Evaluate the entry-point function on a point cloud.

  • Define the grid parameters and pillar extraction parameters.

  • Read a point cloud and generate pillar features and indices using the createPillars helper function, attached to this example as a supporting file.

  • Specify the confidence threshold as 0.5 to keep only detections with confidence scores greater than this value.

  • Specify the overlap threshold as 0.1 to remove overlapping detections.

  • Use the entry-point function pointpillarsDetect to get the predicted bounding boxes, confidence scores, and class labels.

  • Display the point cloud with bounding boxes.

Define grid parameters.

xMin = 0.0;     % Minimum value along X-axis.
yMin = -39.68;  % Minimum value along Y-axis.
zMin = -5.0;    % Minimum value along Z-axis.
xMax = 69.12;   % Maximum value along X-axis.
yMax = 39.68;   % Maximum value along Y-axis.
zMax = 5.0;     % Maximum value along Z-axis.
xStep = 0.16;   % Resolution along X-axis.
yStep = 0.16;   % Resolution along Y-axis.
dsFactor = 2.0; % DownSampling factor.

Calculate the dimensions for the pseudo-image.

Xn = round(((xMax - xMin) / xStep));
Yn = round(((yMax - yMin) / yStep));
gridParams = {{xMin,yMin,zMin},{xMax,yMax,zMax},{xStep,yStep,dsFactor},{Xn,Yn}};

Define the pillar extraction parameters.

P = 12000; % Define number of prominent pillars.
N = 100;   % Define number of points per pillar.

Calculate the number of network outputs.

networkOutputs = numel(net.OutputNames);

Read a point cloud from the Pandaset data set [2] and convert it to M-by-4 format.

pc = pcread('pandasetDrivingData.pcd');
ptCloud = cat(2,pc.Location,pc.Intensity);

Create pillar features and pillar indices from the point clouds using the createPillars helper function, attached to this example as a supporting file.

processedPtCloud = createPillars({ptCloud,'',''}, gridParams,P,N);

Extract the pillar features and pillar indices.

pillarFeatures = dlarray(processedPtCloud{1,1},'SSCB');
pillarIndices = dlarray(processedPtCloud{1,2},'SSCB');

Specify the class names.

classNames = {'car','truck'};

Define the desired thresholds.

confidenceThreshold = 0.5;
overlapThreshold = 0.1;

Use the detect method on the PointPillars network and display the results.

[bboxes,~,labels] = pointpillarsDetect(matFile, pillarFeatures, pillarIndices, gridParams, networkOutputs, confidenceThreshold, overlapThreshold, classNames);
bboxesCar = bboxes(labels == 'car',:);
bboxesTruck = bboxes(labels == 'truck',:);

Display the detections on the point cloud.

helperDisplay3DBoxesOverlaidPointCloud(pc.Location, bboxesCar, 'green', bboxesTruck, 'magenta', 'Predicted bounding boxes');

Generate CUDA MEX

To generate CUDA® code for the pointpillarsDetect entry-point function, create a GPU code configuration object for a MEX target and set the target language to C++. Use the coder.DeepLearningConfig (GPU Coder) function to create a cuDNN deep learning configuration object and assign it to the DeepLearningConfig property of the GPU code configuration object.

cfg = coder.gpuConfig('mex');
cfg.TargetLang = 'C++';
cfg.DeepLearningConfig = coder.DeepLearningConfig(TargetLibrary='cudnn');

args = {coder.Constant(matFile), pillarFeatures, pillarIndices, gridParams, coder.Constant(networkOutputs), ...
        confidenceThreshold, overlapThreshold, classNames};

codegen -config cfg pointpillarsDetect -args args -report
Code generation successful: View report

Run the Generated MEX

Call the generated CUDA MEX with the same pillar features and indices as before. Display the results.

[bboxes, ~, labels] = pointpillarsDetect_mex(matFile, pillarFeatures, pillarIndices, gridParams,...
                                    networkOutputs, confidenceThreshold, overlapThreshold, classNames);
bboxesCar = bboxes(labels == 'car',:);
bboxesTruck = bboxes(labels == 'truck',:);

helperDisplay3DBoxesOverlaidPointCloud(pc.Location, bboxesCar, 'green', bboxesTruck, 'magenta', 'Predicted bounding boxes');

Helper Functions

function preTrainedMATFile = helperDownloadPretrainedPointPillarsNet(outputFolder, pretrainedNetURL)
% Download the pretrained PointPillars network.    
    if ~exist(outputFolder,'dir')
        mkdir(outputFolder);
    end
    preTrainedZipFile = fullfile(outputFolder,'trainedPointPillarsPandasetNet.zip');  
    preTrainedMATFile = fullfile(outputFolder,'trainedPointPillarsPandasetNet.mat');
    if ~exist(preTrainedMATFile,'file')
        if ~exist(preTrainedZipFile,'file')
            disp('Downloading pretrained detector (8.4 MB)...');
            websave(preTrainedZipFile, pretrainedNetURL);
        end
        unzip(preTrainedZipFile, outputFolder);   
    end   
end

function helperDisplay3DBoxesOverlaidPointCloud(ptCld, labelsCar, carColor, labelsTruck, truckColor, titleForFigure)
% Display the point cloud with different colored bounding boxes for different
% classes
    figure;
    ax = pcshow(ptCld);
    showShape('cuboid', labelsCar, 'Parent', ax, 'Opacity', 0.1, 'Color', carColor, 'LineWidth', 0.5);
    hold on;
    showShape('cuboid', labelsTruck, 'Parent', ax, 'Opacity', 0.1, 'Color', truckColor, 'LineWidth', 0.5);
    title(titleForFigure);
    zoom(ax,1.5);
end

References

[1] Lang, Alex H., Sourabh Vora, Holger Caesar, Lubing Zhou, Jiong Yang, and Oscar Beijbom. "PointPillars: Fast Encoders for Object Detection From Point Clouds." In 2019 IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR), 12689-12697. Long Beach, CA, USA: IEEE, 2019. https://doi.org/10.1109/CVPR.2019.01298.

[2] Hesai and Scale. PandaSet. https://scale.com/open-datasets/pandaset.