Create Automation Algorithm Function for Labeling

The Lidar Labeler app enables you to label ground truth data in a collection of point clouds or a point cloud sequence.

First, open the Lidar Labeler app and load point cloud data. For more details, see Load and View Point Cloud Data. Then, create label definitions For more details on how to create labels, see Create and Export Labels and Label Definitions.

You can automatically label point cloud data in the app by using an automation algorithm. The app provides a list of built-in algorithms. For more information, see Label Point Cloud Using Automation Algorithm.

You can also create a custom automation algorithm programmatically, using a function or a class template.

• Function — Use this template to easily create an automation algorithm or migrate your functional algorithm to work with the app.

• Class — Use this template when your automation algorithm requires any of these custom capabilities.

  • Access to temporal information.

  • Customized initialization and termination steps.

  • Customized settings dialog.

  • Customized name and description.

  • Customized instructions.

  For more information on creating algorithms with the class template, see Create Automation Algorithm for Labeling.

How to Specify an Automation Function in Lidar Labeler

To create an automation algorithm using the function template:

1. On the LABEL tab of the app toolstrip, click Select Algorithm > Custom Automation Function, and then click Automate.

2. On the Automate tab, click Settings to specify an automation algorithm function. You can browse to the function file or create a new one by selecting the blue information icon, which opens a new automation function template.

3. Click Run on the toolbar to generate automated labels.

The app returns the labels created by the automation algorithm in an autoLabels structure. To automate voxel labeling, the autoLabels structure must be a categorical matrix. Otherwise, autoLabels must be a structure or a table.

Use a Function to Automate Labeling with Your Custom Detector

The built-in algorithms may not work to explicitly detect the features specific to your data. Therefore, you can train a detector using your data, and then create a custom algorithm using the function template provided within the app. The function requires a minimum set of parameters, which are related to the type of labels suited to your detector. Specifying a function handle within the app enables you to quickly test different automation algorithms and change the parameters of your algorithm.

This is an example of a function that runs a pretrained PointPillars object detector to label objects in a point cloud. The function returns the predicted labels autoLabels, which is a structure array that contains the Name, Type, and Position fields.

 Example Using a Custom Detector

function autoLabels = exampleLidarAutomationAlgorithmFunction(ptCloud)
 
% One-time initialization of the detector. A one-time initialization saves
% time on subsequent runs.persistent detector
if isempty(detector)
% Load the pre-trained detector. 
   pretrainedDetector = load("pretrainedPointPillarsDetector.mat","detector");
   detector = pretrainedDetector.detector;

end

% Run the detector on the input point cloud, ptCloud.
 [bboxes,scores,labels] = detect(detector,ptCloud,Threshold=0.25);
 
% Create and fill the autoLabels structure with the predicted bounding box
% locations. The Name and Type of ROI returned by the automation function
% must match one of the labels defined in the labeling app.
autoLabels = struct('Name',{},'Type',{}, 'Position',{});
for i = 1:size(bboxes,1)
    autoLabels(i).Name = 'object';
    autoLabels(i).Type = labelType.Cuboid;
    autoLabels(i).Position = bboxes(i,:);
end

Create an Automation Algorithm Function

The function template contains descriptions for the fields in autoLabels and an example of how to set the fields. The template also specifies where to insert your custom algorithm function by name, or by specifying a function handle. Use a function handle to pass additional inputs to your function, if required. To access the template, select Settings, and then click the blue information icon in the Custom Automation Function Settings dialog box. The template contains this information:

 Template for Automation Function

function autoLabels = myAutomationFunction(I)
% This automation function runs on each input point cloud, I, specified for
% automation in the Lidar Labeler app. The app implements the automation algorithm
% and returns automated labels, autoLabels.


% autoLabels is a categorical matrix for automating voxel labeling. Otherwise,
% autoLabels is a structure or table.
% The autoLabels structure contains these fields:
%     Type        A labelType enumeration that defines the type of label.
%                 The values must be Cuboid, Line, Voxel, or Scene.
%
%     Name        A character vector specifying the label name. Only
%                 existing label names defined in the
%                 Lidar Labeler app must be used.
%
%     Position    Positions of the labels. The type of label determines
%                 the format of the position data. For more information,
%                 see the doc page for lidar.labeler.AutomationAlgorithmFunction.
%
%     Attributes  An array of structs representing the attributes
%                 of the automated labels. Each attribute is specified as
%                 an additional field of the autoLables structure, with the
%                 name of the field representing the name of the
%                 attribute and the value of the field representing
%                 the value of the attribute.
% When autoLabels is table, it contains these columnns: Type, Name, Position and optionally
% Attributes. The Attributes field is valid only when labels with
% attributes are defined in the app.
% For example,autoLabels structure for a cuboid labeled "Car"
% autoLabels(1).Name      = "Car";
% autoLabels(1).Type      = labelType("Cuboid");
% autoLabels(1).Position  = [40 40 6 9 2 2];
%
% % autoLabels strucuture for a line labeled 'LaneMarker' with 3 points
% autoLabels(2).Name      = "LaneMarker";
% autoLabels(2).Type      = labelType("Line");
% autoLabels(2).Position  = [100 100; 100 110; 110 120];
%
% %autoLabels structure for a voxel labeled 'Tree' defined using a categorical matrix
% autoLabels = categorical(zeros(size(I.Location,1),1),0:1,{"None","tree"},"Ordinal",true);
% autoLabels(randi(size(I.Location,1),10000,1)) = "Tree"
%
% % autoLabels structure for a scene labeled 'Sunny'
% autoLabels(3).Name      = "Sunny";
% autoLabels(3).Type      = labelType("Scene");
% autoLabels(3).Position  = true;

%--------------------------------------------------------
% Place your algorithm code here
%--------------------------------------------------------