Ground Truth Labeler

Label ground truth data for automated driving applications

Description

The Ground Truth Labeler app enables you to label ground truth data in multiple videos, image sequences, or lidar point clouds.

Using the app, you can:

• Simultaneously label multiple time-overlapped signals representing the same scene.

• Define an axis-aligned or rotated rectangular region of interest (ROI) labels, polyline ROI labels, pixel ROI labels, cuboid ROI labels for lidar labeling, and scene label definitions. Use these labels to interactively label your ground truth data.

• Use the Projected View option to view the labels in top, front and side views simultaneously.

• Use the XY View, YZ View, and XZ View options to get the top view, front view, and side view of a point cloud scene, respectively.

• Use built-in detection or tracking algorithms to label ground truth data.

• Write, import, and use custom automation algorithms to automatically label ground truth data.

• Evaluate the performance of your label automation algorithms by using a visual summary.

• Export the ground truth labels as a groundTruthMultisignal object. You can use this object for system verification or for training an object detector or semantic segmentation network.

• Display time-synchronized signals, such as CAN bus data, by using the driving.connector.Connector API.

To learn more about this app, see Get Started with Ground Truth Labeling.

Open the Ground Truth Labeler App

• MATLAB^® Toolstrip: On the Apps tab, under Automotive, click the app icon.

• MATLAB command prompt: Enter groundTruthLabeler.

Examples

• Get Started with Ground Truth Labeling
• Automate Ground Truth Labeling Across Multiple Signals
• Automate Ground Truth Labeling of Lane Boundaries
• Automate Ground Truth Labeling for Semantic Segmentation
• Automate Attributes of Labeled Objects
• Evaluate Lane Boundary Detections Against Ground Truth Data
• Evaluate and Visualize Lane Boundary Detections Against Ground Truth

Programmatic Use

groundTruthLabeler

groundTruthLabeler opens a new session of the app, enabling you to label ground truth data.

groundTruthLabeler(videoFileName)

groundTruthLabeler(videoFileName) opens the app and loads the input video. The video file must have an extension supported by VideoReader.

Example: groundTruthLabeler('caltech_cordova1.avi')

groundTruthLabeler(imageSeqFolder)

groundTruthLabeler(imageSeqFolder) opens the app and loads the image sequence from the input folder. An image sequence is an ordered set of images that resembles a video.

imageSeqFolder must be a string scalar or character vector that specifies the folder containing the image files. The image files must have extensions supported by imformats and are loaded in the order returned by the dir function.

groundTruthLabeler(imageSeqFolder,timestamps)

groundTruthLabeler(imageSeqFolder,timestamps) opens the app and loads a sequence of images with their corresponding timestamps. timestamps must be a duration vector of the same length as the number of images in the sequence.

For example, load a sequence of road images and their corresponding timestamps into the app.

imageDir = fullfile(toolboxdir('driving'),'core','drivingdata','roadSequence');
load(fullfile(imageDir,'timeStamps.mat'))
groundTruthLabeler(imageDir,timeStamps)

groundTruthLabeler(___,'ConnectorTargetHandle',connector)

groundTruthLabeler(___,'ConnectorTargetHandle',connector) opens the app and loads both of these components:

• A video or image sequence signal, depending on the input argument combination you specify

• An external analysis or visualization tool that is time-synchronized with the specified signal

The connector input is a handle to a driving.connector.Connector class that implements the external tool.

For example, this syntax opens the app with a video signal and synchronized lidar visualization tool.

groundTruthLabeler('01_city_c2s_fcw_10s.mp4','ConnectorTargetHandle',@LidarDisplay);

When you have an external tool connected to a signal in the app, consider these tips.

• If you remove the signal that is connected to the tool, the app disconnects the tool and closes it.

• The signal connected to the tool must be the main signal, that is, the signal whose timestamps are used in the playback controls at the bottom of the app. If you change the main signal, the app disconnects the tool and closes it.

• If you start a new app session, the app disconnects the tool and closes it.

groundTruthLabeler(projectFile)

groundTruthLabeler(projectFile) opens the app and loads a saved app session from the project file, projectFile. The projectFile input contains the path to and name of the .prj-file corresponding to the saved project. Before R2025a, the app used to save labeling session as a MAT-file. To load a labeling session from MAT files saved before R2025a, use the same syntax with the path to and name of the MAT file instead.

groundTruthLabeler(gTruth)

groundTruthLabeler(gTruth) opens the app and loads a groundTruth object. The ground truth object data source must be an image sequence, video, or a custom data source.

Limitations

• Lidar signals do not support line or pixel ROI labels.

• Pixel ROI labels do not support sublabels or attributes.

• Cuboid ROI labels do not support sublabels.

• The Label Summary window does not support sublabels or attributes

• Importing groundTruth object created from Image Labeler app is not supported.

More About

ROI Labels, Sublabels, and Attributes

On the left side of the app, the ROI Label Definitions pane contains the region of interest (ROI) label definitions that you can mark on the frames. You can create label definitions using the Add Label option from the app toolstrip. Alternatively, you can create label definitions programmatically by using a labelDefinitionCreatorMultisignal object and then import these label definitions into an app session.

The app supports the definition of ROI labels, sublabels, and attributes.

ROI Labels

An ROI label is a label that corresponds to a region of interest (ROI) in a signal frame. The table describes the supported label types.

ROI Label	Description	Scene
Rectangle/Cuboid	Draw rectangular or cuboidal ROI labels around objects, depending on the signal type. In image signals, draw rectangular ROI labels (2-D bounding boxes). In lidar signals, draw cuboidal ROI labels (3-D bounding boxes). For more on lidar labeling, see Label Lidar Point Clouds for Object Detection.	Vehicles, pedestrians, road signs Rectangle:
		Cuboid:
Rotated Rectangle	Draw rotated rectangular ROI labels around object.	Rotated Rectangle :
Point	Draw point labels in an image signal to identify objects.
Line	Draw linear ROI labels to represent lines. To draw a polyline ROI, use two or more points.	Lane boundaries, guard rails, road curbs
Projected Cuboid	Draw cuboidal ROI labels (3-D bounding boxes).
Polygon	Draw polygon ROI labels. You can label distinct instances of the same class. For more information on drawing polygon ROI labels for instance and semantic segmentation networks, see Label Objects Using Polygons	Vehicles, road surface, trees, pavement
Pixel	Assign labels to pixels for semantic segmentation. You can label pixels manually using polygons, brushes, or flood fill. For more on pixel labeling, see Label Pixels for Semantic Segmentation.	Vehicles, road surface, trees, pavement

ROI Sublabels

An ROI sublabel is an ROI label that belongs to a parent label. Use ROI sublabels to provide a greater level of detail about the ROIs in your labeled ground truth data. For example, a vehicle label might contain headlight, licensePlate, and wheel sublabels. You can create sublabels only for axis aligned and rotated rectangular and polyline labels. For more details about sublabels, see Use Sublabels and Attributes to Label Ground Truth Data.

Show or Hide Labels and Sublabels

You can show or hide the labels or sublabels in a labeled ground truth data by using the icon on the ROI Label Definitions pane. The appears only after you define a label or sublabel. By default, the app displays all the labels and the sublabels.

To hide a label or sublabel, click on the icon along side the label or sublabel name. The app hides the corresponding label or sublabel and displays the icon.

ROI Attributes

An ROI attribute specifies additional information about an ROI label or sublabel. For example, in a driving scene, attributes might include the type or color of a vehicle. The table describes the supported attribute types.

Attribute Type	Sample Attribute Definition	Sample Default Values
List
Numeric
String
Logical

For more details about attributes, see Use Sublabels and Attributes to Label Ground Truth Data.

Tips

• To avoid having to relabel ground truth with new labels, organize the labeling scheme you want to use before marking your ground truth.

• You can copy and paste labels between signals that are of the same type.

Algorithms

You can use label automation algorithms to speed up labeling within the app. To create your own label automation algorithm to use within the app, see Create Automation Algorithm for Labeling. You can also use one of the built-in algorithms by following these steps:

1. Import the data you want to label, and create at least one label definition.

2. On the app toolstrip, click Select Algorithm and select one of the built-in automation algorithms.

3. If you imported multiple signals, click Select Signals and, in the Select Signals window, select one or more signals to automate. Click OK.

4. Click Automate, and then follow the automation instructions in the right pane of the automation window.

ACF Vehicle Detector

Detect and label vehicles using aggregate channel features (ACF). This algorithm is based on the vehicleDetectorACF function. To use this algorithm, you must define at least one rectangle ROI label. You do not need to draw any ROI labels.

To help improve the algorithm results, first click Settings. You can change any of these settings.

• The pretrained vehicle detector model that the algorithm uses — The 'full-view' model was trained using unoccluded images of the front, rear, left, and right sides of vehicles. The 'front-rear-view' model was trained using images of only the front and rear sides of the vehicle.

• The overlap ratio threshold, from 0 to 1, for detecting vehicles — When rectangle ROIs overlap by more than this threshold, the algorithm discards one of the ROIs.

• The classification score threshold for detecting vehicles — Increase the score to increase the prediction confidence of the algorithm. Rectangles with scores below this threshold are discarded.

You can also configure the detector with a calibrated monocular camera by importing a monoCamera object into the MATLAB workspace. Specify the length and width ranges of the vehicle in world units, such as meters.

ACF People Detector

Detect and label people using aggregate channel features (ACF). This algorithm is based on the peopleDetectorACF function. To use this algorithm, you must define at least one rectangle ROI label. You do not need to draw any ROI labels.

To help improve the algorithm results, first click Settings. You can change any of these settings.

• The pretrained people detector model that the algorithm uses — The 'inria-100x41' model was trained using the INRIA person data set. The 'caltech-50x21' model was trained using the Caltech Pedestrian data set.

• The overlap ratio threshold, from 0 to 1, for detecting people — When rectangle ROIs overlap by more than this threshold, the algorithm discards one of the ROIs.

• The classification score threshold for detecting people — Increase the score to increase the prediction confidence of the algorithm. Rectangles with scores below this threshold are discarded.

Point Tracker

Track and label one or more axis-aligned or rotated rectangle ROI labels over short intervals by using the Kanade-Lucas-Tomasi (KLT) algorithm. This algorithm is based on the vision.PointTracker System object™. To use this algorithm, you must define at least one rectangle ROI label, but you do not need to draw any ROI labels.

To change the feature detector used to obtain the initial points for tracking, click Settings. This table shows the feature detector options.

Feature Detector	Description	Equivalent Function
Minimum Eigen Value	Detect corners by using the minimum eigenvalue algorithm.	detectMinEigenFeatures
Harris	Detect corners by using the Harris–Stephens algorithm.	detectHarrisFeatures
FAST	Detect corners by using the features from accelerated segment test (FAST) algorithm.	detectFASTFeatures
BRISK	Detect features by using the binary robust invariant scalable keypoints (BRISK) algorithm.	detectBRISKFeatures
KAZE	Detect features by using nonlinear diffusion to construct a scale space of an image, and then detecting multiscale corner features (KAZE features) from that scale space.	detectKAZEFeatures
SURF	Detect blob features by using the speeded-up robust features (SURF) algorithm.	detectSURFFeatures
MSER	Detect regions by using the maximally stable extremal regions (MSER) algorithm.	detectMSERFeatures

Temporal Interpolator

Estimate axis-aligned or rotated rectangle ROIs or projected cuboid ROIs between frames by interpolating the ROI locations across the time range. To use this algorithm, you must draw a rectangle ROI or a projected cuboid ROI on a minimum of two frames: one at the beginning of the interval and one at the end of the interval. The interpolation algorithm estimates and draws ROIs in the intermediate frames.

Consider a video with 10 frames. The first frame has a rectangle ROI centered at [5, 5]. The 10th frame has a rectangle ROI centered at [25, 25]. At each frame, the algorithm moves the ROI 2 pixels in the x-direction and 2 pixels in the y-direction. Therefore, the algorithm centers the ROI at [7, 7] in the second frame, [9, 9] in the third frame, and so on, up to [23, 23] in the second-to-last frame.

Point Cloud Temporal Interpolator

Estimate cuboid ROIs between point cloud frames by interpolating the ROI locations across the time range. To use this algorithm, you must draw a cuboid ROI on a minimum of two frames: one at the beginning of the interval and one at the end of the interval. The interpolation algorithm estimates and draws ROIs in the intermediate frames.

Consider a point cloud sequence with 10 frames. The first frame has a cuboid ROI centered at [5, 5, 0]. The 10th frame has a cuboid ROI centered at [25, 25, 0]. At each frame, the algorithm moves the ROI 2 points in the x-direction, 2 points in the y-direction, and 0 points in the z-direction. Therefore, the algorithm centers the ROI at [7, 7, 0] in the second frame, [9, 9, 0] in the third frame, and so on, up to [23, 23, 0] in the second-to-last frame.

Lane Boundary Detector

Detect and label lane boundaries using an estimated bird’s-eye-view projected image. To use this algorithm, you must define at least one line ROI label. You do not need to draw any ROI labels. To detect lane boundaries, the algorithm follows these steps:

1. It makes an initial guess at the placement of the lane boundaries in the image.

2. It transforms the ROI around the lanes into a bird's-eye view image to make the lanes parallel and remove distortion.

3. It uses this image to segment the lane boundaries.

To help improve the algorithm results, first click Settings. You can change any of these settings.

• The placement of the lane lines for generating the bird's-eye view image

• The ROI around the lanes, which you can expand to include more than just the ego lane boundaries in the image

• The pixel width of detected lane boundaries in the image

You can also change the number of lane boundaries that you want to detect. The default number of lane boundaries is 2.

Version History

Introduced in R2017a

R2025a: Ground Truth Labeler app saves labeling session as a Project instead of MAT file

Starting in R2025a, the Ground Truth Labeler app saves the current labeling session as a Project file. The app creates a project folder with a .prj file which you can share and use to load the current labeling session with app preferences, label and sublabel definitions, and labeled ground-truth data.

Previously, the app used to save the labeling session as a MAT file.

R2020a: Ground Truth Labeler app no longer exports groundTruth objects

If you import labels or open an app session created before R2020a, the Ground Truth Labeler exports labeled data as a groundTruthMultisignal object instead of as a groundTruth object.

If you do not need to label multiple signals simultaneously and do not require lidar labeling, import the labels or session into the Video Labeler app instead. The Video Labeler app continues to export groundTruth objects.