groundTruthMedical

Ground truth label data for medical images

Since R2022b

Description

The groundTruthMedical object contains information about the data sources, label definitions, and label data for a collection of medical image data. You can import or export a groundTruthMedical object to or from the Medical Image Labeler app.

Creation

The Medical Image Labeler app automatically creates a groundTruthMedical object in the session folder for an app session. The app saves the object as a MAT file. To manually export a groundTruthMedical object to a specific file location, on the Home tab of the app toolstrip, select Export and, under Ground Truth, select To File. To create a groundTruthMedical object programmatically, use the groundTruthMedical function.

Syntax

gTruthMed = groundTruthMedical(dataSource,labelDefsNum)

gTruthMed = groundTruthMedical(dataSource,labelDefsNames)

gTruthMed = groundTruthMedical(dataSource,labelDefsTable)

gTruthMed = groundTruthMedical(___,labelData)

Description

gTruthMed = groundTruthMedical(dataSource,labelDefsNum) creates a groundTruthMedical object for the data source dataSource, and specifies the number of label definitions to include.

gTruthMed = groundTruthMedical(dataSource,labelDefsNames) specifies the label definitions as a list of names.

gTruthMed = groundTruthMedical(dataSource,labelDefsTable) specifies the label definitions as a table.

gTruthMed = groundTruthMedical(___,labelData) specifies the location of existing label data files, in addition to any combination of input arguments from previous syntaxes.

Input Arguments

dataSource — Source of ground truth data

VolumeSource object | ImageSource object

Source of the ground truth data, specified as a VolumeSource object or an ImageSource object. The data source object specifies the locations of the unlabeled medical image files from which the ground truth data has been labeled.

This argument sets the DataSource property.

labelDefsNum — Number of label definitions

nonnegative scalar

Since R2025a

Number of label definitions, specified as a nonnegative scalar. When you specify this argument, the groundTruthMedical object contains the specified number of label definitions with default names and colors. The default names follow the pattern Label1, Label2, …, LabelN, where N is the value of labelDefsNum. The default colors are the same as those used by the Medical Image Labeler app.

This argument sets the LabelDefinitions property, which is stored as a table.

Example: groundTruthMedical(dataSource,3) creates a groundTruthMedical object with three label definitions named Label1, Label2, and Label3.

labelDefsNames — Names of label definitions

n-by-1 string array

Since R2025a

Names of label definitions, specified as an n-by-1 string array. When you specify this argument, the groundTruthMedical object contains n label definitions with the specified names and default colors. The default colors are the same as those used by the Medical Image Labeler app.

This argument sets the LabelDefinitions property, which is stored as a table.

Example: groundTruthMedical(dataSource,["lung"; "tumor"]) creates a groundTruthMedical object with two label definitions, lung and tumor.

labelDefsTable — Label definitions table

table

Label definitions table, specified as a table. To create this table, use one of these options:

• In the Medical Image Labeler app, create label definitions, and then export them as a MAT file by clicking Export and, under Label Definitions, selecting To File. Use the load function to load the table from the file into the workspace.

• Create the label definitions table manually using the table function.

This table describes the required and optional columns of the table.

Column	Description	Required or Optional
Name	String scalars or character vectors, each specifying the name of a label definition.	Required All names must be unique and valid MATLAB® variable names. For more details about valid variable names, see Variable Names.
PixelLabelID	Integers in the range [1, 255], each specifying a numeric label ID.	Required All pixel label IDs must be unique.
LabelColor	RGB triplets that specify the label colors. Values must be in the range [0, 1].	Optional When you define labels in the Medical Image Labeler app, you must specify a color. Therefore, an exported label definitions table always includes this column. When you create label definitions programmatically, you can exclude the LabelColor column. When you create a groundTruthMedical object, the object then automatically adds this column with default values. The default colors are assigned in the same order as in the Medical Image Labeler app.

This argument sets the LabelDefinitions property.

labelData — Label data filenames

m-by-1 array of empty strings (default) | m-by-1 string array

Label data filenames, specified as an m-by-1 string array, where m is the number of images or image volumes specified by DataSource. Each element of LabelData contains the name of the label data file for the corresponding image or volume in the data source.

• If the data source is a VolumeSource object, then the label data must be stored as NIfTI files or as MAT files that each contain a single medicalVolume object.

• If the data source is an ImageSource object, then the label data must be stored as MAT files.

• If no labels exist for an image or image volume, specify the corresponding element of LabelData as an empty string, "".

This argument sets the LabelData property.

Properties

DataSource — Source of ground truth data

VolumeSource object | ImageSource object

This property is read-only after object creation. To set this property, use the dataSource argument.

Source of the ground truth data, specified as a VolumeSource object or an ImageSource object. The data source object specifies the locations of the unlabeled medical image files from which the ground truth data has been labeled.

LabelDefinitions — Label definitions

table

Set this property at object creation using the labelDefsNum, labelDefsNames, or labelDefsTable argument. You can update the property after object creation using dot notation.

Label definitions, specified as a table with these columns:

Column	Description	Required or Optional
Name	String scalars, each specifying the name of a label definition.	Required All names must be unique and valid MATLAB variable names. For more details about valid variable names, see Variable Names.
PixelLabelID	Integers in the range [1, 255], each specifying a numeric label ID.	Required All pixel label IDs must be unique.
LabelColor	RGB triplets that specify the label colors. Values must be in the range [0, 1].	Optional When you define labels in the Medical Image Labeler app, you must specify a color. Therefore, an exported label definitions table always includes this column. When you create label definitions programmatically, you can exclude the LabelColor column. When you create a groundTruthMedical object, the object then automatically adds this column with default values. The default colors are assigned in the same order as in the Medical Image Labeler app.

LabelData — Label data filenames

m-by-1 array of empty strings (default) | m-by-1 string array

This property is read-only after object creation. To set this property, use the labelData argument.

Label data filenames, specified as an m-by-1 string array, where m is the number of images or image volumes specified by DataSource. Each element of LabelData contains the name of the label data file for the corresponding image in DataSource.

• If the data source is a VolumeSource object, then the label data must be stored as NIfTI files or as MAT files each containing a single medicalVolume object.

• If the data source is an ImageSource object, then the label data must be stored as MAT files.

• If no labels exist for an image or image volume, specify the corresponding element of LabelData as an empty string, "".

Object Functions

addLabel	Add label definition to groundTruthMedical object
removeLabel	Remove label definition from groundTruthMedical object
changeFilePaths	Change file paths in ground truth data for medical images
merge	Merge two or more groundTruthMedical objects

Examples

Create Ground Truth for Medical Image Volume Data

Create ground truth data for two chest CT volumes and their corresponding label images, stored in the NIfTI file format. The files are a subset of the Medical Segmentation Decathlon data set [1]. Download the MedicalVolumNIfTIData.zip file from the MathWorks® website, then unzip the file. The size of the data file is approximately 76 MB.

zipFile = matlab.internal.examples.downloadSupportFile("medical","MedicalVolumeNIfTIData.zip");
filepath = fileparts(zipFile);
unzip(zipFile,filepath)
dataFolder = fullfile(filepath,"MedicalVolumeNIfTIData");

Create a VolumeSource object specifying the two CT volumes.

filePath1 = fullfile(dataFolder,"lung_027.nii.gz");
filePath2 = fullfile(dataFolder,"lung_043.nii.gz");
source = {filePath1; filePath2};
dataSource = medical.labeler.loading.VolumeSource(source);

You can specify label definitions as a nonnegative scalar, as a string array of names, or as a complete label definitions table. For this example, specify two label definition by name.

labelDefName = ["lung","tumor"];

Create a groundTruthMedical object.

gTruthMed = groundTruthMedical(dataSource,labelDefName)

gTruthMed = 
  groundTruthMedical with properties:

          DataSource: [1×1 medical.labeler.loading.VolumeSource]
           LabelData: [2×1 string]
    LabelDefinitions: [2×3 table]

Alternatively, if your ground truth already contains label data, you can also specify the label data as a string array of paths to the label images. For any data source images without labels, specify the corresponding element of labelData as an empty string.

labelDataFile = fullfile(dataFolder,"LabelData","lung_027.nii.gz");
labelData = [labelDataFile ""];
gTruthMedLabeled = groundTruthMedical(dataSource,labelDefName,labelData)

gTruthMedLabeled = 
  groundTruthMedical with properties:

          DataSource: [1×1 medical.labeler.loading.VolumeSource]
           LabelData: [2×1 string]
    LabelDefinitions: [2×3 table]

[1] Medical Segmentation Decathlon. "Lung." Tasks. Accessed May 10, 2018. http://medicaldecathlon.com/.

The Medical Segmentation Decathlon data set is provided under the CC-BY-SA 4.0 license. All warranties and representations are disclaimed. See the license for details.

Create Ground Truth for Medical Image Data

Create ground truth data for three 2-D X-rays of forearms, stored as DICOM files, and their corresponding label images, stored as MAT files. The images are attached to this example as supporting files. Specify the data directory as the current example directory.

dataFolder = pwd;

Create a table of the X-ray image file information by using the dicomCollection function, and specify the table as the sourceTable for an ImageSource object.

sourceTable = dicomCollection(dataFolder);
dataSource = medical.labeler.loading.ImageSource(sourceTable);

Define the labels used to specify the ground truth. Specify the name, display color, and numeric label ID for the bone label data.

labelName = "radiusBone";
labelColor = [1 0 0];
labelId = 1;
variableNames = ["Name","LabelColor","PixelLabelID"];
labelDefs = table(labelName,labelColor,labelId,VariableNames=variableNames)

labelDefs=1×3 table
        Name        LabelColor     PixelLabelID
    ____________    ___________    ____________

    "radiusBone"    1    0    0         1      

Specify the file paths to the label images for each of the images in the data source as a string array. For ground truth data containing an ImageSource object, the label images must be in the MAT file format.

labelData = [fullfile(dataFolder,"forearmXrayLabels1.mat");
    fullfile(dataFolder,"forearmXrayLabels2.mat");
    fullfile(dataFolder,"forearmXrayLabels3.mat")];

Create a groundTruthMedical object.

gTruthMed = groundTruthMedical(dataSource,labelDefs,labelData)

gTruthMed = 
  groundTruthMedical with properties:

          DataSource: [1×1 medical.labeler.loading.ImageSource]
           LabelData: [3×1 string]
    LabelDefinitions: [1×3 table]

Tips

• To load a groundTruthMedical object into the Medical Image Labeler, open the app using the syntax medicalImageLabeler(gTruthMed). Alternatively, within an app session, in the app toolstrip click Import, and under Ground Truth, select From File to load a ground truth object saved as a MAT file or From Workspace to load a ground truth object from the MATLAB workspace.

Version History

Introduced in R2022b

R2025a: More flexible options for specifying labels

Create a new groundTruthMedical object more easily using these enhancements:

• If your ground truth data contains no labels, you can omit the labelData input argument, which is now optional, instead of specifying an array of empty strings.

• You can specify the LabelDefinitions property more flexibly using the new labelDefsNum and labelDefsNames input arguments.

R2024b: Support for new file format

Specify the LabelData property of a new groundTruthMedical object for 3-D data as a MAT file containing a medicalVolume object. In prior releases, LabelData must be specified as a NIfTI file containing label data.