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,labelDefinitions,labelData)

Description

gTruthMed = groundTruthMedical(dataSource,labelDefinitions,labelData) creates a groundTruthMedical object, gTruthMed, that you can import into the Medical Image Labeler app.

• dataSource specifies the source of the unlabeled ground truth images and sets the DataSource property.

• labelDefs specifies the label definitions of the ground truth data and sets the LabelDefinitions property.

• labelData specifies the location of image label data and sets the LabelData property.

Properties

DataSource — Source of ground truth data

VolumeSource object | ImageSource object

This property is read-only.

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 is labeled. You must set this property at object creation by using the dataSource input argument.

LabelDefinitions — Label definitions

table

This property is read-only.

Label definitions, 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.

• Manually create the label definitions table at the MATLAB^® command line.

This table describes the required and optional columns of the LabelDefinitions 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	Numeric integer scalars 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, this column is automatically added with default values. The default colors are assigned in the same order as in the Medical Image Labeler app.

You must set this property at object creation by using the labelDefs input argument.

Data Types: table

LabelData — Label data file names

n-by-1 string array

This property is read-only.

Label data file names, specified as an n-by-1 string array, where n 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.

• 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, "".

You must set this property at object creation by using the labelData input argument.

Data Types: string

Object Functions

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 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: [1x1 medical.labeler.loading.ImageSource]
           LabelData: [3x1 string]
    LabelDefinitions: [1x3 table]

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);

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

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

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

    "tumor"    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. If a data source image does not have label data, specify the corresponding element of the label data array as an empty string.

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

Create a groundTruthMedical object.

gTruthMed = groundTruthMedical(dataSource,labelDefs,labelData)

gTruthMed = 
  groundTruthMedical with properties:

          DataSource: [1×1 medical.labeler.loading.VolumeSource]
           LabelData: [2×1 string]
    LabelDefinitions: [1×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.

Version History

Introduced in R2022b