immulticube

R2026b

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

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

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

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

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.

You can import valid data from URLs and remote locations, such as cloud services, for easier collaboration and data management. Depending on the location of your file, file can take one of these forms.

Location	Form
Current folder or folder on the MATLAB path	Specify the name of the file in file. Example: "multispectralData.tif"
File in a folder	If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path name. Example: "C:\myFolder\multispectralData.tif" Example: "\imgDir\multispectralData.tif"
Uniform resource locator (URL)	If you specify the file as an internet URL, then file must contain the protocol type, such as http://. Example: "http://my_hostname/my_path/multispectralData.tif"
Remote location	If the file is stored at a remote location, then file must contain the full path of the file specified as a URL of the form: scheme_name://path_to_file/my_file.ext Based on the remote location, scheme_name can be one of the values in this table. Remote Location scheme_name Amazon S3™ s3 Windows Azure® Blob Storage wasb, wasbs HDFS™ hdfs For more information, see Work with Remote Data. Example: "s3://my_bucket/my_path/multispectralData.tif"

The function downloads each new remote file only once per session to a temporary directory. If you access the same remote data again during the same MATLAB session, the function uses the downloaded file from the temporary directory.

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

R2026b: Import data from remote locations

For easier collaboration and data management, you can import valid multispectral data from URLs and remote locations such as cloud services.