detect

Detect objects using Voxel R-CNN object detector

Since R2024b

Syntax

bboxes = detect(detector,ptCloud)

[bboxes,scores] = detect(detector,ptCloud)

[bboxes,scores,labels] = detect(detector,ptCloud)

detectionResults = detect(detector,ds)

[___] = detect(___,Name=Value)

Description

bboxes = detect(detector,ptCloud) detects objects within the input point cloud, ptCloud, using a voxel region-based convolutional neural network (Voxel R-CNN) object detector, detector. The function returns the locations of detected objects as a set of bounding boxes.

To use this function, your system must have a CUDA^® enabled NVIDIA^® GPU. For information on the supported compute capabilities, see GPU Computing Requirements (Parallel Computing Toolbox).

[bboxes,scores] = detect(detector,ptCloud) returns the class-specific confidence score for each bounding box.

[bboxes,scores,labels] = detect(detector,ptCloud) additionally returns the label assigned to each bounding box.

detectionResults = detect(detector,ds) detects objects within a set of point clouds, ds.

[___] = detect(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, Threshold=0.7 specifies a detection threshold of 0.7.

Note

This functionality requires Deep Learning Toolbox™, Parallel Computing Toolbox™, Lidar Toolbox™, and the Lidar Toolbox Interface for OpenPCDet Library support package. You can download and install the Lidar Toolbox Interface for OpenPCDet Library from Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

Examples

Detect Vehicles Using Voxel R-CNN

Create a Voxel R-CNN object detector.

detector = voxelRCNNObjectDetector;

Read the input point cloud.

filename = "PandasetLidarData.pcd";
ptCloud = pcread(filename);

Run the pretrained Voxel R-CNN object detector on the input point cloud.

[bboxes,scores,labels] = detect(detector,ptCloud); 

Display the detected bounding boxes. For better visualization, select a region of interest, roi, from the point cloud data.

roi = [0.0 89.12 -49.68 49.68 -5.0 5.0];
indices = findPointsInROI(ptCloud,roi);
figure
ax = pcshow(select(ptCloud,indices).Location);
zoom(ax,1.5)
showShape("cuboid",bboxes,Parent=ax,Color="green",Opacity=0.1,LineWidth=0.5);

Input Arguments

detector — Voxel R-CNN object detector

voxelRCNNObjectDetector object

Voxel R-CNN object detector, specified as a voxelRCNNObjectDetector object.

ptCloud — Input point cloud

pointCloud object

Input point cloud, specified as a pointCloud object. This object can be unorganized or organized.

ds — Collection of point clouds

array of pointCloud objects | cell array of pointCloud objects | valid datastore object

Collection of point clouds, specified as an array of pointCloud objects, a cell array of pointCloud objects, or a valid datastore object. To use a datastore, you must configure it such that using the read function on the datastore object returns a cell array, the first column of which contains point clouds. For more information on creating datastore objects, see the datastore function.

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.

Example: detect(detector,ptCloud,Threshold=0.5) detects objects within the input point cloud with a detection threshold of 0.5.

Threshold — Detection threshold

0.3 (default) | scalar in range [0, 1]

Detection threshold, specified as a scalar in the range [0, 1]. The function removes detections that have scores lower than this threshold value. To reduce false positives, increase this value.

SelectStrongest — Strongest bounding box selection

true or 1 (default) | false or 0

Strongest bounding box selection for each detected object, specified as a logical 1 (true) or 0 (false).

• true — The function returns the strongest bounding box per object. Use this option to eliminate overlapping bounding boxes by using nonmaximal suppression based on their confidence scores.

• false — The function returns all the detected bounding boxes. You can then use a custom process to eliminate overlapping bounding boxes.

MiniBatchSize — Size of each mini-batch

2 (default) | positive scalar

Size of each mini-batch, specified as a positive scalar. Use the MiniBatchSize argument to process a large collection of point clouds. The function groups point clouds into mini-batches of the specified size and processes them as a batch to improve computational efficiency. Increase the mini-batch size to decrease processing time. Decrease the mini-batch size to use less memory.

PredictedBoxType — Format of output bounding boxes

"cuboid" (default) | "rotated-rectangle"

Format of output bounding boxes, specified as one of these options:

• "cuboid" — The function returns cuboid bounding boxes, each represented as a nine-element row vector of the form [x_ctr y_ctr z_ctr x_len y_len z_len x_rot y_rot z_rot].

  • x_ctr, y_ctr, and z_ctr specify the center of the cuboid.

  • x_len, y_len, and z_len specify the length of the cuboid along the x-, y-, and z-axes, respectively, before rotation has been applied.

  • x_rot, y_rot, and z_rot specify the rotation angles for the cuboid along the x-, y-, and z-axes, respectively. These angles are clockwise-positive when looking in the forward direction of their corresponding axes. Units are in degrees.

• "rotated-rectangle" — The function returns rotated rectangles, each represented as a five-element row vector of the form [x_ctr y_ctr width height yaw].

  • x_ctr and y_ctr specify the center of the rectangle.

  • width and height specify the width and height of the rectangle along the x- and y-axes, respectively.

  • yaw specifies the rotation angle, which is clockwise-positive around the center of the rectangle.

Verbose — Progress information display

true or 1 (default) | false or 0

Progress information display, specified as a logical 1 (true) or 0 (false).

Note

This argument is applicable only when the input is a datastore ds. Otherwise, the function ignores this argument.

Output Arguments

bboxes — Locations of detected objects

M-by-9 matrix | M-by-5 matrix

Locations of the detected objects, returned as a matrix of numeric values. The format of bboxes depends on the specified value of the PredictedBoxType argument.

• If you specify the PredictedBoxType argument as "cuboid", then the function returns an M-by-9 matrix. M is the number of detected objects. Each row of the matrix is of the form [x y z length width height roll pitch yaw], representing the location, dimension, and orientation of the corresponding bounding box.

• If you specify the PredictedBoxType argument as "rotated-rectangle", then the function returns an M-by-5 matrix. M is the number of detected objects. Each row of the matrix is of the form [x_ctr y_ctr width height yaw], representing the location, dimension, and orientation of the corresponding bounding box.

scores — Detection confidence scores

M-element column vector

Detection confidence scores for the bounding boxes, returned as an M-element column vector. M is the number of bounding boxes. Each score is in the range [0, 1]. A higher score indicates higher confidence in the detection.

labels — Labels for bounding boxes

M-by-1 categorical array

Labels for bounding boxes, returned as an M-by-1 categorical array. M is the number bounding boxes in the point cloud. You can define the class names used to label the objects when you train the object detector.

detectionResults — Detection results

table

Detection results, returned as a table with columns, Boxes, Scores, and Labels. Each row of the table corresponds to a point cloud from the input datastore.

Column Name	Value	Description
Boxes	The value of this column depends on the specified value of the PredictedBoxType argument. "cuboid" — Returned as an M-by-9 matrix. M is the number of bounding boxes. Each row of the matrix is of the form [x y z length width height roll pitch yaw], representing the location, dimension, and orientation of the corresponding bounding box. "rotated-rectangle" — Returned as an M-by-5 matrix. M is the number of bounding boxes. Each row of the matrix is of the form [xctr yctr width height yaw], representing the location, dimension, and orientation of the corresponding bounding box.	Bounding boxes for objects found in the corresponding point cloud.
Scores	M-element column vector	Detection scores for the bounding boxes.
Labels	M-by-1 categorical array	Labels for the bounding boxes.

To evaluate the detection results, use the evaluateObjectDetection function.

metrics = evaluateObjectDetection(detectionResults,groundTruthData);

Version History

Introduced in R2024b