Share and Store Labeled Ground Truth Data

The Image Labeler, Video Labeler, and Ground Truth Labeler (Automated Driving Toolbox) apps enable you to label images, videos, and other ground truth data sources. You can then export the ground truth labels as a groundTruth object or, for the Ground Truth Labeler (Automated Driving Toolbox) app, a groundTruthMultisignal (Automated Driving Toolbox) object. The ground truth object contains information about the:

Data source (or data sources)
Label definitions
Drawn ground truth labels

You can share this object with:

Other labeling colleagues, who can use it to continue labeling
Algorithm developers, who can use it to train algorithms, such as an object detector or semantic segmentation network
Validation engineers, who can use it to validate algorithms

Share Ground Truth

To export and share labeled ground truth data from one of the labeling apps, select Export Labels > To File. Then, either share the exported MAT-file directly with individuals on your team or place it in a shared network location.

If the exported ground truth data contains pixel labels, the app also generates a PixelLabelData folder containing the pixel label data. The label data table stored in the ground truth object references the path to this folder. Share this folder along with the ground truth object.

The labeling apps also enable you to save a MAT-file of the entire app session. Do not share this file. Because the session file contains app preferences that are specific to your local machine, this file might not work on other machines.

If you re-export a ground truth object containing pixel label data, the app generates a new PixelLabelData folder. Even if you overwrite the original ground truth object, the app generates a new PixelLabelData folder. When re-exporting the ground truth object, the generated folders are named PixelLabelData_1, PixelLabelData_2, and so on, depending on how many times you re-export the object to the same folder.

When sharing a ground truth object, share the correct PixelLabelData folder associated with it. For example, if you overwrite the original ground truth object, share the overwritten object and the newly created PixelLabelData_1 folder.

In addition to sharing the ground truth object, you must also share the data source (or data sources) and any associated files. These tables show the files to share for each data source in each app.

Image Labeler App Files to Share

Data Source	Files to Share
Image collection	`groundTruth` object MAT-file `PixelLabelData` folder (pixel labels only) Folders containing image collections (if not in a shared location)

Video Labeler App Files to Share

Data Source	Files to Share
Video	`groundTruth` object MAT-file `PixelLabelData` folder (pixel labels only) Video source file (if not in a shared location)
Image sequence	`groundTruth` object MAT-file `PixelLabelData` folder (pixel labels only) Folder containing image sequence (if not in a shared location) Timestamps `duration` vector (if specified)
Custom image data source reader	`groundTruth` object MAT-file `PixelLabelData` folder (pixel labels only) Data source files (if not in a shared location) Custom reader function

Ground Truth Labeler App Files to Share

Data Source	Files to Share
Video	`groundTruthMultisignal` object MAT-file `PixelLabelData` folder (pixel labels only) Video source file (if not in a shared location)
Image sequence	`groundTruthMultisignal` object MAT-file `PixelLabelData` folder (pixel labels only) Folder containing image sequence (if not in a shared location) Timestamps `duration` vector (if specified)
Custom image data source reader	`groundTruthMultisignal` object MAT-file `PixelLabelData` folder (pixel labels only) Data source files (if not in a shared location) Custom reader function
Point cloud sequence	`groundTruthMultisignal` object MAT-file `PixelLabelData` folder (pixel labels only) Folder containing point cloud sequence (if not in a shared location) Timestamps `duration` vector (if specified)
Velodyne^® packet capture (PCAP) file	`groundTruthMultisignal` object MAT-file `PixelLabelData` folder (pixel labels only) PCAP source file (if not in a shared location) PCAP calibration file Timestamps `duration` vector (if specified)
Rosbag	`groundTruthMultisignal` object MAT-file `PixelLabelData` folder (pixel labels only) Rosbag file

Move Ground Truth

In the exported ground truth object, the DataSource property contains the absolute paths to the data source files. For example, suppose you want to view the paths for a groundTruth object, gTruth, that was exported from the Image Labeler app. At the MATLAB^® command prompt, enter this code.

gTruth.DataSource

ans = 

groundTruthDataSource for an image collection with properties

                      Source: {
                              ' ...\matlab\toolbox\vision\visiondata\imageSets\cups\bigMug.jpg';
                              ' ...\matlab\toolbox\vision\visiondata\imageSets\cups\blueCup.jpg';
                              ' ...\matlab\toolbox\vision\visiondata\imageSets\cups\handMade.jpg'
                               ... and 9 more
                              }

If you move the ground truth object to a new location, you might need to change the file paths stored in the data source (or data sources). Even if the data source files are on a shared network, if other people map a different drive letter to their network folder, the file paths can be incorrect.

To update these paths, use the changeFilePaths function. Specify the ground truth object as an input argument to this function. If the paths changed but the files names did not, specify a string vector containing the old and new path. The function returns any paths that it is unable to resolve. For example, this code sample shows how to change the drive letter for an image folder.

alternativePaths = ["C:\Shared\ImgFolder" "D:\Shared\ImgFolder"];
unresolvedPaths = changeFilePaths(gTruth,alternativePaths);

If the file names also changed, specify a cell array of string vectors containing the old and new paths. For example, this code sample shows how to change the drive letter for individual files and how to append a suffix to each file.

alternativePaths =  ...
    {["C:\Shared\ImgFolder\Img1.png" "D:\Shared\ImgFolder\Img1_new.png"], ...
     ["C:\Shared\ImgFolder\Img2.png" "D:\Shared\ImgFolder\Img2_new.png"], ...
     .
     .
     .
     ["C:\Shared\ImgFolder\ImgN.png" "D:\Shared\ImgFolder\ImgN_new.png"]};
unresolvedPaths = changeFilePaths(gTruth,alternativePaths);

If the ground truth object contains pixel label data, you can also use the changeFilePaths function to update the path names to the pixel label data stored in the PixelLabelData folder.

Store Ground Truth

Store the ground truth object in a location that is on the MATLAB search path. For more details, see What Is the MATLAB Search Path?.

For data sources whose contents reside in a single folder, consider storing the ground truth object in the parent folder of the data source. For image collections containing images from different folders, no specific recommendations exist for where to store the object. To label image collections, use the Image Labeler app.

Extract Labeled Video Scenes

You can extract labeled video scenes and corresponding labels from a groundTruth or groundTruthMultisignal (Automated Driving Toolbox) object exported by the Video Labeler or Ground Truth Labeler (Automated Driving Toolbox) apps in a form that can be loaded using a datastore. These labeled video scenes can be used for training, validation, and evaluation. Extracted videos scenes enable you to employ video labels on specific durations of a long video and apply deep learning techniques to detect anomalies or recognize a specific activity in a video.

Use the sceneTimeRanges function to obtain labeled scene time ranges from a ground truth object.
Use the writeVideoScenes function to take a ground truth object array and labeled scene time ranges information from the sceneTimeRanges function to write video scenes to a folder. This data can be directly used with datastore based deep learning training and evaluation workflows.