immulticube

Read multispectral image

Since R2025a

Syntax

mcube = immulticube(file)

mcube = immulticube(file,wavelength)

mcube = immulticube(image,wavelength)

mcube = immulticube(image,wavelength,metadata)

mcube = immulticube(image)

mcube = immulticube(___,BlockSize=blockSize)

Description

mcube = immulticube(file) reads multispectral image data from the specified file file.

mcube = immulticube(file,wavelength) specifies the wavelength for each spectral band in the input data, and sets the Wavelength property of the output multicube object.

mcube = immulticube(image,wavelength) creates a multicube object from the multispectral data cube image and the specified center wavelength values wavelength.

mcube = immulticube(image,wavelength,metadata) creates a multicube object from the multispectral data cube image, specified center wavelength values wavelength, and metadata metadata. You can use this syntax to modify the Metadata property of a multicube object.

mcube = immulticube(image) creates a multicube object from the multispectral data cube image without wavelengths. The Wavelength property of the returned multicube object mcube is empty.

mcube = immulticube(___,BlockSize=blockSize) specifies the block size to use when loading the multispectral data cube, in addition to any combination of input arguments from previous syntaxes.

Note

This function requires the Hyperspectral Imaging Library for Image Processing Toolbox™. You can install the Hyperspectral Imaging Library for Image Processing Toolbox from Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

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

Examples

Read and Visualize Multispectral Data from ASTER File

Download and unzip ASTER data.

zipFile = matlab.internal.examples.downloadSupportFile("image","data/aster_dataset.zip");
[filepath,folder,~] = fileparts(zipFile);
unzip(zipFile,filepath)

Read multispectral data stored in the ASTER file into the workspace. Create a multicube object by specifying the filename.

filename = fullfile(filepath,"aster_dataset","AST_L1T_00308202024042613_20240821173601_1890485.hdf");
mcube = immulticube(filename);

Display the properties of the multicube object.

mcube

mcube = 
  multicube with properties:

        ImageFiles: "C:\Users\Example\supportfiles\image\data\aster_dataset\AST_L1T_00308202024042613_20240821173601_1890485.hdf"
          BandSize: [8×2 double]
        Wavelength: [8×1 double]
          Metadata: [1×1 struct]
    BandResolution: [8×1 double]
         BlockSize: [1024 1024]

Estimate and visualize a three-channel image from the multispectral data by using the colorize function.

img = colorize(mcube,1:3);
figure
imagesc(img)
title("Three-Channel Image of Data Cube")

Read Data from ASTER File and Replace Wavelength Values

Download and unzip ASTER data.

zipFile = matlab.internal.examples.downloadSupportFile("image","data/aster_dataset.zip");
[filepath,folder,~] = fileparts(zipFile);
unzip(zipFile,filepath)

Read multispectral data stored in the ASTER file into the workspace. Create a multicube object by specifying the filename.

filename = fullfile(filepath,"aster_dataset","AST_L1T_00308202024042613_20240821173601_1890485.hdf");
mcube = immulticube(filename);

Extract the wavelengths of the multispectral data.

mcube.Wavelength

ans = 8×1

         560
         660
         820
        8300
        8650
        9100
       10600
       11300

Assign new center wavelength values for the multispectral data to include the entire visible range. The number of wavelength values must be equal to the number of bands in the multispectral data cube. You must specify a unique value for each wavelength.

minWavelength = 400;
maxWavelength = 700;
numBands = numel(mcube.Wavelength);
newWavelength = linspace(minWavelength,maxWavelength,numBands);

Create a new multicube object with the new wavelength values.

newmcube = immulticube(filename,newWavelength);

Plot the old and the new wavelength values. Display the wavelength range.

figure
plot(mcube.Wavelength,"o")
hold on
plot(newmcube.Wavelength,"or")
xlabel("Band Number")
ylabel("Wavelength")
legend("Original Values","New Values",Location="NorthWest")

Resample the spectral bands to a uniform resolution.

maxResolution = max(mcube.BandResolution);
newmcube = resampleBands(newmcube,maxResolution);

Create Multicube Object from Numeric Data Cube

Read an RGB image into the workspace. An RGB image contains three spectral channels: red, green, and blue.

image = imread("peppers.png");

Specify the center wavelength values for the red, green, and blue channels as 700, 530, and 470 nanometers (nm) respectively.

wavelength = [700 530 470];

Create a multicube object using the image and the wavelength values.

mcube = immulticube(image,wavelength)

mcube = 
  multicube with properties:

        ImageFiles: "in memory"
          BandSize: [3×2 double]
        Wavelength: [3×1 double]
          Metadata: [1×1 struct]
    BandResolution: [0×1 double]
         BlockSize: [384 512]

Modify Metadata Property of Multicube Object

Download Landsat 8 multispectral data.

zipfile = "LC08_L1TP_113082_20211206_20211215_02_T1.zip";
landsat8Data_url = "https://ssd.mathworks.com/supportfiles/image/data/" + zipfile;
hyper.internal.downloadLandsatDataset(landsat8Data_url,zipfile)
filepath = fullfile("LC08_L1TP_113082_20211206_20211215_02_T1","LC08_L1TP_113082_20211206_20211215_02_T1_MTL.txt");

Read the multispectral data into the workspace.

mcube = immulticube(filepath);

Find and remove the empty fields from the metadata.

metadata = mcube.Metadata;
fields = fieldnames(metadata);
indx = find(structfun(@isempty,metadata)==1);
metadata = rmfield(metadata,fields(indx));

Inspect and observe that the acquisition time is added to the metadata.

isfield(metadata,"AcquisitionTime")

ans = logical
   1

Inspect the acquisition time in the metadata.

metadata.AcquisitionTime

ans = 
"2021-12-06"

Set the value for the AcquisitionTime field to the current date.

newMetadata = metadata;
currentDate = string(datetime("now",Format="yyyy-MM-dd"));
newMetadata.AcquisitionTime = currentDate;

Resample the multispectral data to a uniform resolution.

mcube = resampleBands(mcube,30);

Create a multicube object with the new metadata. The image data and wavelengths of the new multicube object are the same as those of the resampled multispectral data.

datacube = gather(mcube);
newmcube = immulticube(datacube,mcube.Wavelength,newMetadata);

Inspect the Metadata property of the new multicube object.

newmcube.Metadata

ans = struct with fields:
              DataType: "uint16"
            SensorType: 'OLI_TIRS'
          SpacecraftID: 'LANDSAT_8'
           ProductType: "L1TP"
       AcquisitionTime: "2025-01-29"
             BandNames: [11×1 string]
                  Gain: [11×1 double]
                Offset: [11×1 double]
       ReflectanceGain: [11×1 double]
     ReflectanceOffset: [11×1 double]
            CloudCover: 0.8400
            SunAzimuth: 78.0024
          SunElevation: 62.1598
       AdditionalFiles: [1×1 struct]
          QualityBands: [1×1 struct]
          ThermalBands: [1×1 struct]
      PanchromaticBand: [1×1 struct]
      EarthSunDistance: 0.9854
        CloudCoverLand: 0.1600
             Rollangle: -1.0000e-03
       ImageAttributes: [1×1 struct]
    CollectionCategory: "T1"
      CollectionNumber: 2
       RasterReference: []
       WavelengthUnits: "Nanometers"

Input Arguments

file — Input filename

character vector | string scalar

Input filename, specified as a character vector or string scalar. The input filename can refer to an image file or header file, and must be one of these file formats.

File Format	Extensions	Additional Requirements
GeoTIFF metadata files from EO satellites	.txt	Filename must end with the suffix "MTL". For example, geotiffEO1_MTL.txt.
Multipage TIFF files	.tif	File must be a multipage TIFF file containing a volume or time series image stack.
ASTER data	.hdf	File must contain ASTER data of level L1A, L1B, or L1T. Filename must contain the "AST" keyword. Sensor name in the HDF file must be "ASTER".
Sentinel-2 data	.safe	File must be a Sentinel-2 L1C file or Sentinel-2 L2A file with the name manifest.safe.

Data Types: char | string

wavelength — Center wavelength values of spectral bands

C-element numeric vector

Center wavelength values of the spectral bands, specified as a C-element numeric vector. C is the spectral dimension, defined as the number of spectral bands of the input multispectral data.

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

image — Multispectral image data cube

M-by-N-by-C numeric array

Multispectral image data cube, specified as an M-by-N-by-C numeric array. M and N are the number of rows and columns in the multispectral data, respectively. C is the number of spectral bands in the multispectral data.

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

metadata — Metadata of multispectral data

structure array

Metadata of the multispectral data, specified as a structure array. This argument sets the Metadata property of the multicube object.

Data Types: struct

blockSize — Size of data blocks

[1024 1024] (default) | 2-element vector of positive integers

Size of the data blocks, specified as a 2-element vector of positive integers. The first and second elements of the vector correspond to the number of rows and columns in each block, respectively. This argument sets the BlockSize property of the multicube object.

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

Output Arguments

mcube — Multispectral data

multicube object

Multispectral data, returned as a multicube object.

Version History

Introduced in R2025a