Main Content


Merge two or more ground truth objects

Since R2023b



gTruth = merge(gTruth1,gTruth2, ... gTruthN) merges two or more ground truth objects into a new ground truth object gTruth. The resulting merged ground truth object contains all the data sources, label definitions, and label data from the input ground truth objects.


Only groundTruth objects exported by the Image Labeler app can be merged using this function.

gTruth = merge(___,OutputFolder=name) specifies the folder into which to save merged pixel label data in addition to the input arguments from the previous syntax. name must be the absolute or relative path to the save folder, specified as a character vector or string scalar. By default, the function writes merged pixel label data to a folder named "mergedPixelLabelData" within the current working directory. If this folder does not exist, the function creates it. If the folder already exists, the function adds a unique numeric suffix to the default name, for example "mergedPixelLabelData_1", and creates a new folder.


collapse all

Load two separate ground truth objects into the workspace from a previously saved MAT file.


Merge the two objects into one ground truth object. Use the logical output hasModifiedLabels, to specify any modified label data.

[gTruth] = merge(gTruth1,gTruth2);

Review merged ground truth in the Image Labeler app.


Input Arguments

collapse all

Ground truth data, specified as two or more groundTruth objects. If any of the ground truth objects specifies a groundTruthDataSource or an imageDatastore with a custom read function, then all of the input ground truth objects must use the same custom read function.

Output Arguments

collapse all

Merged ground truth data, returned as a groundTruth object. The merged labels obtain their description and color values from the first (of the input order) ground truth object that defines a non-empty value. The function automatically selects a new color value when required.

The method that the function uses to merge label data depends on the label type:

  • Region-of-interest (ROI) — Merged by using concatenation. ROI labels include labelType.Rectangle, labelType.RotatedRectangle, labelType.Line, labelType.Point, labelType.ProjectedCuboid, labelType.Cuboid, and labelType.Polygon.

    The function merges ROIs that do not have attributes or sublabels, and contain the same position value, into one ROI. The function does not preserve the stacking order of ROI labels when merging ROI label data from ground truth objects that reference the same image.

  • Scene — Merged by using majority consensus. In the case of a tie, the output uses the scene label data from the first input ground truth object.

  • Pixel — Merged by using a per-pixel majority consensus. In the case of a tie, the output uses the pixel label value from the first input ground truth. This merge ignores unlabeled pixels. The function saves the merged pixel label data as PNG-format files, by using the naming convention:

    "Label_<sourceIndex>_<sourceName>.png", where <sourceIndex> is an index into the output ground truth object DataSource property, and <sourceName> is the filename of the data source.

  • Custom — The merge function does not support custom labels.

Version History

Introduced in R2023b