%% Export and Explore Ground Truth Labels for Multiple Signals
% After labeling the signals by following the
% <docid:driving_ug#mw_ca250c1b-d575-4cb7-b26b-6ddc83f923dc Label Ground
% Truth for Multiple Signals> procedure, export the labels and explore how
% they are stored.

% Copyright 2019 The MathWorks, Inc.

%% Setup
% Open the *<docid:driving_ref#bvie3n7-1 Ground Truth Labeler>* app session
% containing the labeled signals. You can open the session from the
% MATLAB(R) command line. For example, if you saved the session to a
% MAT-file named |groundTruthLabelingSession|, enter this command.
%
%   groundTruthLabeler groundTruthLabelingSession.mat
%
% On the app toolstrip, select *Export > To Workspace*. In the
% export to workspace window, use the default export variable name,
% |gTruth|, and click *OK*. The app exports a
% |<docid:driving_ref#mw_42782d95-09f4-4844-91ee-44ddd8357f59
% groundTruthMultisignal>| object, |gTruth|, to the MATLAB(R) workspace. This
% object contains the ground truth labels captured from the app session.
%
% If you did not export a |groundTruthMultisignal| object to the workspace,
% load a predefined object from the variable |gTruth|. The function used to
% load this object is attached to this example as a supporting file. If you
% are using your own object, data such as label positions can differ from
% the data shown in this example.

if (~exist('gTruth','var'))
    gTruth = helperLoadGTruthGetStarted;
end

%%
% Display the properties of the |groundTruthMultisignal| object, |gTruth|.
% The object contains information about the signal data sources, label
% definitions, and ROI and scene labels. This information is stored in
% separate properties of the object.

gTruth

%%
% In this example, you examine the contents of each property to learn how
% the object stores ground truth labels.
%% Data Sources
% The |DataSource| property contains information about the data sources.
% This property contains two |MultiSignalSource| objects: one for the video
% source and one for the point cloud sequence source. Display the contents
% of the |DataSource| property.

gTruth.DataSource

%%
% The information stored in these objects includes the paths to the data
% sources, the names of the signals that they contain, and the timestamps
% for those signals. Display the signal names for the data sources.

gTruth.DataSource.SignalName

%% Label Definitions
% The |LabelDefinitions| property contains a table of information about the
% label definitions. Display the label definitions table. Each row contains
% information about an ROI or scene label definition.
% The |car| label definition has two rows: one for when the label is drawn
% as a rectangle on |Image| signals and one for when the label is drawn as
% a cuboid on |PointCloud| signals.

gTruth.LabelDefinitions

%%
% The |Hierarchy| column stores information about the sublabel and attribute
% definitions of a parent ROI label. Display the sublabel and attribute
% information for the |car| label when it is drawn as a rectangle. This
% label contains one sublabel, |brakeLight|, and no attributes.

gTruth.LabelDefinitions.Hierarchy{1}

%%
% Display information about the |brakeLight| sublabel for the parent |car|
% label. The sublabel contains one attribute, |isOn|. Sublabels cannot have
% their own sublabels.

gTruth.LabelDefinitions.Hierarchy{1}.brakeLight

%%
% Display information about the |isOn| attribute for the |brakeLight|
% sublabel. This attribute has no default value, so the |DefaultValue| field
% is empty.

gTruth.LabelDefinitions.Hierarchy{1}.brakeLight.isOn

%% ROI Label Data
% The |ROILlabelData| property contains an
% |<docid:driving_ref#mw_9e8014ba-ee8f-46ec-b952-03596be7e34a
% ROILabelData>| object with properties that contain ROI label data for each
% signal. The names of the properties match the names of the signals.
% Display the object property names.

gTruth.ROILabelData
%%
% Each property contains a timetable of ROI labels drawn at each signal
% timestamp, with one column per label. View a portion the video and the
% lidar point cloud sequence timetables. Set a time interval from 8 to 8.5
% seconds. This time interval corresponds to the start of the time interval
% labeled in the <docid:driving_ug#mw_ca250c1b-d575-4cb7-b26b-6ddc83f923dc
% Label Ground Truth for Multiple Signals> procedure. The video timetable
% contains more rows than the point cloud sequence timetable because the
% video contains more label frames.

timeInterval = timerange(seconds(8),seconds(8.5));
videoLabels = gTruth.ROILabelData.video_01_city_c2s_fcw_10s(timeInterval,:)
lidarLabels = gTruth.ROILabelData.lidarSequence(timeInterval,:)

%%
% View the rectangle |car| labels for the first video frame in the time
% interval. The label data is stored in a structure.
%
videoLabels.car{1}

%%
% The |Position| field stores the positions of the |car| labels. This frame
% contains only one |car| label, so in this case, |Position| contains only
% one rectangle bounding box. The bounding box position is of the form |[x
% y w h]|, where:
%
% * |x| and |y| specify the upper-left corner of the rectangle.
% * |w| specifies the width of the rectangle, which is the length of the
% rectangle along the _x_-axis.
% * |h| specifies the height of the rectangle, which is the length of the
% rectangle along the _y_-axis.
%
% The |car| label also contains two |brakeLight| sublabels at this frame.
% View the |brakeLight| sublabels. The sublabels are stored in a structure
% array, with one structure per sublabel drawn on the frame.

videoLabels.car{1}.brakeLight

%%
% View the bounding box positions for the sublabels.

videoLabels.car{1}.brakeLight.Position
%%
% View the values for the |isOn| attribute in each sublabel. For both
% sublabels, this attribute is set to logical |1| (|true|).

videoLabels.car{1}.brakeLight.isOn

%%
% Now view the cuboid |car| labels for the first point cloud sequence frame
% in the time interval. Point cloud sequences do not support sublabels or
% attributes. Instead of storing cuboid labels in the |Position| field of a
% structure, cuboid bounding box positions are stored in an |M|-by-9
% matrix, where |M| is the number of cuboid labels. Because this frame
% contains only one cuboid label, in this case |M| is 1.

lidarLabels.car{1}

%%
% The 1-by-9 bounding box position is of the form |[xctr, yctr, zctr, xlen,
% ylen, zlen, xrot, yrot, zrot]|, where:
%
% * |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_-axis, respectively, before rotation has been applied.
% * |xrot|, |yrot|, and |zrot| specify the rotation angles for the cuboid
% along the _x_-, _y_-, and _z_-axis, respectively. These angles
% are clockwise-positive when looking in the forward direction of their
% corresponding axes.
%
% This figure shows how these values specify the position of a cuboid.
%
% <<../labelers_cuboid_dimensions.png>>
%
%% Scene Label Data
% The |SceneLabelData| property contains a
% |<docid:driving_ref#mw_9b914b1c-f83c-4332-8cd6-2816999484e3
% SceneLabelData>| object with properties that contain scene label data
% across all signals. The names of the properties match the names of the
% scene labels. Display the object property names.

gTruth.SceneLabelData

%%
% The |daytime| label applies to the entire time interval, which is
% approximately 10 seconds.

%% Use Ground Truth Labels
% The labels shown in this example are for illustrative purposes only.
% For your own labeling, after you export the labels, you can use them as
% training data for object detectors. To gather label data from the
% |groundTruthMultisignal| object for training, use the
% |<docid:driving_ref#mw_3a54ddcf-268e-43bc-ae0a-491318facd9f
% gatherLabelData>| function.
%
% To share labeled ground truth data, share the ground truth MAT-file
% containing the |groundTruthMultisignal| object, not the MAT-file
% containing the app session. For more details, see
% <docid:vision_ug#mw_ea908c7d-8075-4ebc-a9d1-60518a943a1b Share and Store
% Labeled Ground Truth Data>.
%%
% Copyright 2019 The MathWorks, Inc.