hypercube

Read hyperspectral data

Description

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

The hypercube object represents the hyperspectral data cube and its related properties. Create hypercube objects using the imhypercube or geohypercube function. Use the hypercube object functions to assign new pixel values, crop data, select or remove specific hyperspectral bands, generate a colored image, and write hyperspectral data to the ENVI (environment for visualizing images) file format.

The hypercube object supports hyperspectral data acquired by these satellites.

• Earth Observing-1 (EO-1) Hyperion

• Airborne Visible/Infrared Imaging Spectrometer (AVIRIS)

Note

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

Creation

• Read hyperspectral data without geospatial information using the imhypercube function.

• Read hyperspectral data with geospatial information using the geohypercube function.

  Note

  The geohypercube function requires a Mapping Toolbox™ license.

Properties

ImageDims — Dimensions and data type of hyperspectral data cube

Read-only: string scalar

Since R2025a

This property is read-only.

Dimensions and data type of the hyperspectral data cube, represented as a string scalar.

Data Types: string

Wavelength — Center wavelength value

Read-only: C-element vector

This property is read-only.

Center wavelength value of each spectral band, represented as a C-element vector. C is the spectral dimension, defined as the number of spectral bands, of the input hyperspectral data.

Data Types: double

Metadata — Metadata of hyperspectral data

Read-only: structure

This property is read-only.

Metadata of the hyperspectral data, represented as a structure. The fields of the structure contain the properties of the hyperspectral image and spectral information. The set of fields in the structure depends on the individual image and file format. This table lists the common fields.

Field	Description
Height	Height of the image, in pixels, or number of rows in the data cube, represented as a positive integer.
Width	Width of the image, in pixels, or number of columns in the data cube, represented as a positive integer.
Bands	Number of spectral bands comprising the data cube, represented as a positive integer
DataType	Data type of the hyperspectral data, represented as one of these values. "single" "double" "uint8" "uint16" "int16" "uint32" "int32" "uint64" "int64"
Interleave	Data interleave, represented as one of these values. "bsq" — Band-sequential "bil" — Band-interleaved-by-line "bip" — Band-interleaved-by-pixel
HeaderOffset	Zero-based location of the first element in the image file, represented as a positive integer. The header offset represents the number of bytes from the beginning of the image file to the start of the image data. The default value is 0.
ByteOrder	Endianness of the data, represented as "ieee-le" for little endian or "ieee-be" for big endian.
WavelengthUnits	Units for the wavelengths of the spectral bands, represented as one of these strings. "Nanometers" — All wavelengths are in nanometers (greater than 200 and less than 100000). "Micrometers" — All wavelengths are in micrometers (greater than 0.2 and less than 100). "" — Wavelengths are neither all in nanometers, nor all in micrometers.
RasterReference	Geospatial information of the hyperspectral image, represented as a structure. If you create a hypercube object with geospatial information using the geohypercube function, the RasterReference field contains the geospatial information. When you perform operations such as cropping on the hypercube object, thehypercube updates the geospatial information. If you create a hypercube object without geospatial information using the imhypercube function, the RasterReference field is empty.

Data Types: struct

BlockSize — Size of data blocks

Read-only: 2-element vector of positive integers

This property is read-only.

Size of the data blocks, represented 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. Loading the hyperspectral data cube using blocks enables you to load smaller regions of large data sets without running out of memory.

• A small value for BlockSize reduces the memory usage of the function at the cost of increased execution time.

• A large value for BlockSize reduces execution time at the cost of increased memory usage.

You can set this property using the blockSize name-value argument of the imhypercube or geohypercube function.

• The number of rows in each block must be less than or equal to the number of rows in the hyperspectral image. If you specify a value greater than the number of rows in the hyperspectral image, BlockSize uses the number of rows in the hyperspectral image, instead. If the image contains more than 1024 rows, the default value for the number of rows in each block is 1024.

• The number of columns in each block must be less than or equal to the number of columns in the hyperspectral image. If you specify a value greater than the number of columns in the hyperspectral image, BlockSize uses the number of columns in the hyperspectral image, instead. If the image contains more than 1024 columns, the default value for the number of columns in each block is 1024.

Data Types: double

Object Functions

gather	Read data cube of spectral image into workspace
assignData	Assign new data to spectral image data cube
cropData	Crop regions-of-interest of spectral image
enviwrite	Write hyperspectral data to ENVI file format
selectBands	Select bands from spectral image
removeBands	Remove spectral bands from spectral image
colorize	Estimate color image of spectral image
apply	Apply function to each block of spectral image

Examples

Read and Process Hyperspectral Data

Read hyperspectral data into the workspace.

hcube = imhypercube("EO1H0440342002212110PY_cropped.hdr");

Estimate and visualize the RGB image of the hyperspectral data.

rgbImg = colorize(hcube,Method="rgb");
figure
imshow(rgbImg)

Convert the digital numbers to radiance values to perform radiometric calibration of the data.

newhcube = dn2radiance(hcube);

Compute and visualize the NDVI index for the corrected data.

ndviImg = ndvi(newhcube);
figure
imagesc(ndviImg)
axis equal tight
colorbar

More About

Read Small Regions of Large Hyperspectral Image

If a hyperspectral image is too large to fit into memory, you can crop it to a small region of interest and read only that small region into memory. Because you can read the metadata of a hyperspectral image without loading the data cube into memory, you can use the metadata of large hyperspectral images to decide whether to read a small region of one, then crop the data cube to the desired region and work with the cropped data cube. To avoid loading the entire large data cube into memory, you must crop the large hyperspectral image to your desired region before you remove the undesired bands from the data cube. You can colorize the small hyperspectral image using the colorize function, and perform the listed operations that support block processing on the small hyperspectral image. These functions load the small hyperspectral image into memory for processing. (since R2024a)

• dn2radiance

• dn2reflectance

• radiance2Reflectance

• correctOOB

• subtractDarkPixel

• reduceSmile

• spectralIndices

• customSpectralIndex

• ndvi

For an example of processing large hyperspectral images, see Process Large Hyperspectral and Multispectral Images.

Version History

Introduced in R2020a

R2026a: hypercube function: To be removed

• The hypercube function will be removed in a future release. To create a hypercube object, use the imhypercube or geohypercube functions instead.

• The hypercube object no longer has the DataCube property.

• You can no longer read multispectral data using the hypercube object. Use the multicube object to read multispectral data.

R2025a: Create hypercube object using imhypercube or geohypercube functions, load entire image into memory using gather object function, perform block processing using apply object function

• The hypercube object and hypercube function have these changes starting from R2025a.

  • The hypercube function will be removed in a future release. To create a hypercube object, use the imhypercube or geohypercube functions instead. To create a hypercube object for hyperspectral data without geospatial information, use the imhypercube function. To create a hypercube object for hyperspectral data with geospatial information, use the geohypercube function. Creating a hypercube object with geospatial information using the geohypercube function requires a Mapping Toolbox license.

  • The hypercube object no longer has the DataCube property. To load the entire hyperspectral data cube into memory, use the gather object function instead.

  • To perform block processing on the hyperspectral data using built-in or custom functionality without loading the entire hyperspectral data into memory, use the apply object function.

  • You can no longer read multispectral data using the hypercube object. Use the multicube object to read multispectral data.

• Starting from R2025a, if you create hypercube objects using the hypercube function, the created hypercube object has the property DataCube instead of the new property ImageDims. However, the DataCube property does not represent the actual data cube. It represents the size and data type of the hyperspectral data cube as a string scalar. You can use the new gather and apply object functions with this hypercube object. However, you cannot use the new syntax for selectBands that specifies bands using method and value.

• If you have saved hypercube objects created using the hypercube function in older releases prior to R2025a, the DataCube property contains the actual data cube. However, starting from R2025a, the DataCube property will be read as a string. You cannot use the new gather and apply object functions with these hypercube objects. To extract the actual data cube from hypercube objects created in prior releases, use this helper function.

  function [datacube,wavelength,metadata] = classConverter(hcube)
     datacube = str2double(hcube.DataCube);
     metadata = hcube.Metadata;
     datatype = metadata.DataType;
     datacube = cast(datacube,datatype);
     wavelength = hcube.Wavelength;
  end

  If the data is hyperspectral, you can create a hypercube object using the extracted data cube, wavelengths, and metadata as input to the imhypercube or geohypercube function.

  newhcube = imhypercube(datacube,wavelength,metadata);

  If the data is multispectral, you can create a multicube object using the extracted data cube, wavelengths, and metadata as input to the immulticube or geomulticube function.

  newmcube = immulticube(datacube,wavelength,metadata);

R2024b: Specify block size for loading hyperspectral data cube

Specify the block size for loading the hyperspectral data cube using the BlockSize name-value argument.

R2024a: Read small regions of large hyperspectral images

Load and process cropped regions of large hyperspectral images.

R2023b: Read hyperspectral data from .bsq, .bil, .bip, and multipage TIFF files

Read hyperspectral data from .bsq, .bil, .bip, and multipage TIFF files.

R2023a: Support for hyperspectral data from the AVIRIS sensor

Support for hyperspectral data from the AVIRIS sensor.