groundTruthSpectralImage

Ground truth label data for spectral images

Since R2026a

Description

Add-On Required: This feature requires the Hyperspectral Imaging Library for Image Processing Toolbox add-on.

The groundTruthSpectralImage object contains information about the data source, label definitions, and label data for a spectral image. You can import or export a groundTruthSpectralImage object to or from the Spectral Image Labeler app. Manage labeled ground truth data for applications such as pixel classification and semantic segmentation using this object and its functions.

Note

The Hyperspectral Imaging Library for Image Processing Toolbox™ requires desktop MATLAB^®, as MATLAB Online™ and MATLAB Mobile™ do not support the library.

Creation

• To manually export a groundTruthSpectralImage object from the Spectral Image Labeler app to a MAT file, on the Labeler tab of the app toolstrip, select Export and, under Labels, select To File.

• To manually export a groundTruthSpectralImage object from the Spectral Image Labeler app to the workspace, on the Labeler tab of the app toolstrip, select Export and, under Labels, select To Workspace.

• To create a groundTruthSpectralImage object programmatically, use the groundTruthSpectralImage function.

Syntax

gTruth = groundTruthSpectralImage(dataSource,labelDefs)

gTruth = groundTruthSpectralImage(dataSource,labelDefs,labelData)

gTruth = groundTruthSpectralImage(___,Resolution=resolution)

Description

gTruth = groundTruthSpectralImage(dataSource,labelDefs) creates a groundTruthSpectralImage object for the data source dataSource, and specifies the label definitions to include.

gTruth = groundTruthSpectralImage(dataSource,labelDefs,labelData) specifies the existing labels for regions of interest (ROI) in the data.

gTruth = groundTruthSpectralImage(___,Resolution=resolution) specifies the resolution to which to resample all spectral bands of the data source, if the data source is a multispectral image, using any combination of input arguments from previous syntaxes.

Input Arguments

dataSource — Source of spectral image data

string scalar | character vector | SpectralImageSource object

Source of spectral image data, specified as a string scalar, character vector, or SpectralImageSource object. The data source specifies the locations of the unlabeled spectral image files from which the ground truth data was labeled. If dataSource is a string scalar or character vector, it must specify the path to a source file that must be of one of these types.

• A file supported by the imhypercube, geohypercube, immulticube, or geomulticube function.

• A MAT File containing a hypercube or multicube object. The hypercube or multicube object must be the only variable in the MAT file.

This argument sets the DataSource property.

labelDefs — Label definitions

table

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

• In the Spectral 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 a label definitions table manually, using the table function, with these columns.

  Column	Description	Required or Optional
  LabelName	Name of the label, specified as a string scalar or character vector.	Required
  LabelColor	Color of the label, specified as a 1-by-3 vector with values between 0 and 1.	Optional
  LabelID	ID to represent the label, specified as an integer in the range [1, 255].	Optional
  LabelGroup	Name of the label group to which the label belongs, specified as a string scalar or character vector.	Optional
  Description	Description of the label, specified as a string scalar or character vector.	Optional
  AttributeList	Attribute information of the label, specified as a structure. In the Spectral Image Labeler app, when you define attributes for a label, the exported label definition and the LabelDefinition property of the exported groundTruthSpectralImage object include this column.	Optional

This argument sets the LabelDefinition property.

Data Types: table

labelData — Label data

[] (default) | table

Label data, specified as a table.

• The table must have one column for each label name in the label definition. The name of the column must exactly match the label name.

• The column for a particular label must include the details of ROIs labeled with that label, as a structure with these fields.

  • ROIName — Name of the ROI, specified as a character vector.

  • ROI — Location of the ROI, specified as a polyshape object.

This argument sets the LabelData property.

Data Types: table

resolution — Resolution of spectral bands

[] (default) | positive integer

Resolution of the spectral bands, specified as a positive integer. If the data source is a multispectral image, you can specify the resolution to which to resample all spectral bands by using this input argument. This argument sets the Resolution property.

When you export a groundTruthSpectralImage object for a multispectral image from the app, the app sets the Resolution property to the resolution to which it has resampled all of the spectral bands. If the app has not resampled any spectral bands, the Resolution property is empty.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

gTruth — Ground truth data

groundTruthSpectralImage object

Ground truth data, returned as a groundTruthSpectralImage object. You can use the groundTruthSpectralImage object to share labels with colleagues. When sharing the groundTruthSpectralImage object, you must also share the corresponding data source file.

Properties

DataSource — Source of spectral image data

SpectralImageSource object

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

Source of spectral image data, represented as a SpectralImageSource object.

LabelDefinition — Label definitions

table

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

Label definitions, represented as a table with these columns.

• LabelName

• LabelColor

• LabelID

• LabelGroup

• Description

• AttributeList

LabelData — Label data

[] (default) | table

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

Label data, represented as a table. This property is empty if you do not specify label data while creating the object.

Resolution — Resolution of spectral bands

[] (default) | positive integer

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

Resolution of the spectral bands, specified as a positive integer. When you export a groundTruthSpectralImage object for a multispectral image from the app, the app sets the Resolution property to the resolution to which it has resampled all of the spectral bands. If the app has not resampled any spectral bands, the Resolution property is empty.

Object Functions

changeFilePaths	Change file paths in ground truth data for spectral images
merge	Merge two or more groundTruthSpectralImage objects
selectLabelsByGroup	Select labels by group in ground truth data for spectral image
selectLabelsByName	Select labels by name in ground truth data for spectral image

Examples

Create Ground Truth for Spectral Image Data

Specify a filename for a data source of hyperspectral data.

dataSource = "indian_pines.dat";

Create a table of label definitions.

labelName = ["Vegetation"; "Water"];
labelColor = {[0 1 0]; [0 0 1]};
labelID = [1; 2];
variableNames = ["LabelName","LabelColor","LabelID"];
labelDefs = table(labelName,labelColor,labelID,VariableNames=variableNames)

labelDefs=2×3 table
     LabelName      LabelColor    LabelID
    ____________    __________    _______

    "Vegetation"    {[0 1 0]}        1   
    "Water"         {[0 0 1]}        2   

Define non-overlapping regions of interest (ROI) for each of the labels.

vegetationROI1 = struct(ROIName='ROI1',ROI=polyshape([1 0 1 1],[4 3 3 4]));
vegetationROI2 = struct(ROIName='ROI2',ROI=polyshape([3 2 3 3],[2 1 1 2]));
vegetationROI = {vegetationROI1; vegetationROI2}

vegetationROI=2×1 cell array
    {1×1 struct}
    {1×1 struct}

waterROI1 = struct(ROIName='ROI3',ROI=polyshape([5 4 5 5],[3 2 2 3]));
waterROI = {waterROI1; []}

waterROI=2×1 cell array
    {1×1 struct}
    {0×0 double}

Create a table for the label data.

labelData = table(vegetationROI,waterROI,VariableNames=labelName)

labelData=2×2 table
     Vegetation        Water    
    ____________    ____________

    {1×1 struct}    {1×1 struct}
    {1×1 struct}    {0×0 double}

Create the spectral image ground truth object.

gTruth = groundTruthSpectralImage(dataSource,labelDefs,labelData)

gTruth = 
  groundTruthSpectralImage with properties:

          DataSource: [1×1 hyper.labeler.loading.SpectralImageSource]
    LabelDefinitions: [2×5 table]
           LabelData: [2×2 table]
          Resolution: []

Version History

Introduced in R2026a