Main Content

detect

Detect objects using Voxel R-CNN object detector

Since R2024b

collapse all in page

    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.

    example

    [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

    collapse all

    This example uses:

    Open Live Script

    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

    collapse all

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

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

    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.

    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.

    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.

    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.

    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 [xctr yctr zctr xlen ylen zlen xrot yrot zrot].

      • xctr, yctr, and zctr specify the center of the cuboid.

      • xlen, ylen, and zlen specify the length of the cuboid along the x-, y-, and z-axes, respectively, before rotation has been applied.

      • xrot, yrot, and zrot 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 [xctr yctr width height yaw].

      • xctr and yctr 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.

    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

    collapse all

    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 [xctr yctr width height yaw], representing the location, dimension, and orientation of the corresponding bounding box.

    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 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.

    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 NameValueDescription
    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.
    ScoresM-element column vectorDetection scores for the bounding boxes.
    LabelsM-by-1 categorical arrayLabels for the bounding boxes.

    To evaluate the detection results, use the evaluateObjectDetection function.

    metrics = evaluateObjectDetection(detectionResults,groundTruthData);

    Version History

    Introduced in R2024b

    See Also

    |

    Topics