imhypercube

Read hyperspectral image

Since R2025a

collapse all in page

    Syntax

    hcube = imhypercube(file)
    hcube = imhypercube(file,wavelength)
    hcube = imhypercube(image,wavelength)
    hcube = imhypercube(image,wavelength,metadata)
    hcube = imhypercube(image)
    hcube = imhypercube(___,BlockSize=blockSize)

    Description

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

    hcube = imhypercube(file) reads hyperspectral image data from the specified file file.

    example

    hcube = imhypercube(file,wavelength) specifies the wavelength for each spectral band in the input data, and sets the Wavelength property of the output hypercube object.

    example

    hcube = imhypercube(image,wavelength) creates a hypercube object from the hyperspectral data cube image and the specified center wavelength values wavelength.

    example

    hcube = imhypercube(image,wavelength,metadata) creates a hypercube object from the hyperspectral data cube image, specified center wavelength values wavelength, and metadata metadata. You can use this syntax to modify the Metadata property of a hypercube object.

    example

    hcube = imhypercube(image) creates a hypercube object from the hyperspectral data cube image without wavelengths. The Wavelength property of the returned hypercube object hcube is empty.

    hcube = imhypercube(___,BlockSize=blockSize) specifies the block size to use when loading the hyperspectral 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

    collapse all

    This example uses:

    Open Live Script

    Read hyperspectral data stored in the ENVI format into the workspace. Create a hypercube object by specifying an ENVI data file. 

    hcube = imhypercube("paviaU.dat");

    Display the properties of the hypercube object.

    hcube
    hcube = 
  hypercube with properties:

     ImageDims: "[610x340x103 double]"
    Wavelength: [103×1 double]
      Metadata: [1×1 struct]
     BlockSize: [610 340]

    Estimate an RGB image from the hyperspectral data by using the colorize function. Visualize the RGB image. 

    rgbImg = colorize(hcube,Method="rgb");
figure
imagesc(rgbImg)
title("RGB Image of Data Cube")

    Figure contains an axes object. The axes object with title RGB Image of Data Cube contains an object of type image.

    This example uses:

    Open Live Script

    Read ENVI format data into the workspace by specifying a header file that contains information about hyperspectral data. The associated ENVI binary data file must be stored in the same folder as the ENVI header file.

    hcube = imhypercube("paviaU.hdr");

    Display the properties of the hypercube object.

    hcube
    hcube = 
  hypercube with properties:

     ImageDims: "[610x340x103 double]"
    Wavelength: [103×1 double]
      Metadata: [1×1 struct]
     BlockSize: [610 340]

    Estimate an RGB image from the data cube by using the colorize function. Increase the contrast of the RGB image using contrast stretching. Visualize the RGB image. 

    rgbImg = colorize(hcube,Method="rgb",ContrastStretching=true);
figure
imagesc(rgbImg)
title("RGB Image of Data Cube")

    Figure contains an axes object. The axes object with title RGB Image of Data Cube contains an object of type image.

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

    minWavelength = 500;
maxWavelength = 1010;
newWavelength = minWavelength:5:maxWavelength;

    Create a new hypercube object with the new wavelength values.

    newhcube = imhypercube("paviaU.hdr",newWavelength);

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

    figure
plot(hcube.Wavelength,"o")
hold on
plot(newhcube.Wavelength,"or")
xlabel("Band Number")
ylabel("Wavelength")
str1 = "Original wavelength range: " + num2str(min(hcube.Wavelength)) + "nm to " + num2str(max(hcube.Wavelength)) + "nm";
text(5,1075,str1)
str2 = "New wavelength range: " + num2str(min(newhcube.Wavelength)) + "nm to " + num2str(max(newhcube.Wavelength)) + "nm";
text(5,1035,str2)
legend("Original Values","New Values",Location="SouthEast")

    Figure contains an axes object. The axes object with xlabel Band Number, ylabel Wavelength contains 4 objects of type line, text. One or more of the lines displays its values using only markers These objects represent Original Values, New Values.

    This example uses:

    Open Live Script

    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 hypercube object using the image and the wavelength values. 

    hcube = imhypercube(image,wavelength)
    hcube = 
  hypercube with properties:

     ImageDims: "[384x512x3 uint8]"
    Wavelength: [3×1 double]
      Metadata: [1×1 struct]
     BlockSize: [384 512]

    This example uses:

    Open Live Script

    Read the hyperspectral data into the workspace.

    hcube = imhypercube("paviaU.dat");

    Find and remove the empty fields from the metadata.

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

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

    isfield(metadata,"AcquisitionTime")
    ans = logical
   0

    Set the value for the AcquisitionTime field to current date.

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

    Create a hypercube object with the new metadata. The image data and wavelengths of the new hypercube object are the same as those of the input hyperspectral data.

    datacube = gather(hcube);
newhcube = imhypercube(datacube,hcube.Wavelength,newMetadata);

    Inspect the Metadata property of the new hypercube object.

    newhcube.Metadata
    ans = struct with fields:
             Height: 610
              Width: 340
              Bands: 103
           DataType: "double"
         Interleave: "bsq"
       HeaderOffset: 0
          ByteOrder: "ieee-le"
    AcquisitionTime: "2026-01-24"
    RasterReference: []
    WavelengthUnits: "Nanometers"

    Input Arguments

    collapse all

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

    ENVI image files

    ENVI header files

    Image files:

    • .dat

    • .img

    • .raw

    • .bsq

    • .bil

    • .bip

    Header files:

    • .hdr

    		The corresponding image and header files must be in the same folder and have the same filename.
    NITF files

    .ntf

    .nsf

    		None.

    Hyperion level 1R image files

    Hyperion header files

    Image files:

    • .L1R

    Header files:

    • .hdr

    		The corresponding image and header files must be in the same folder and have the same filename.
    GeoTIFF metadata files from EO satellites.txtFilename 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.

    Data Types: char | string

    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 hyperspectral data.

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

    Hyperspectral 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 hyperspectral data, respectively. C is the number of spectral bands in the hyperspectral data.

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

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

    Data Types: struct

    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 hypercube object.

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

    Output Arguments

    collapse all

    Hyperspectral data, returned as a hypercube object.

    Version History

    Introduced in R2025a

    See Also

    | | | |

    Topics