Main Content

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.

    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.

    example

    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.

    example

    Input Arguments

    expand all

    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.

    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.

    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.

    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.

    ColumnDescriptionRequired or Optional
    NameString 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.

    PixelLabelIDIntegers in the range [1, 255], each specifying a numeric label ID.

    Required

    All pixel label IDs must be unique.

    LabelColorRGB 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.

    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

    expand all

    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.

    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:

    ColumnDescriptionRequired or Optional
    NameString 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.

    PixelLabelIDIntegers in the range [1, 255], each specifying a numeric label ID.

    Required

    All pixel label IDs must be unique.

    LabelColorRGB 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 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
    removeLabelRemove label definition from groundTruthMedical object
    changeFilePathsChange file paths in ground truth data for medical images
    mergeMerge two or more groundTruthMedical objects

    Examples

    collapse all

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

    expand all