hypercube

Read hyperspectral data

Since R2020a

Description

The hypercube function reads hyperspectral data and returns a hypercube object. The object contains the hyperspectral data cube and its related properties. Use the object functions to remove or select a desired hyperspectral band, assign new pixels values, generate colored image, and write hyperspectral data to the ENVI (environment for visualizing images) file format.

Creation

Syntax

hcube = hypercube(filename)

hcube = hypercube(img,hdr)

hcube = hypercube(___,wavelength)

hcube = hypercube(tifFile,wavelength)

hcube = hypercube(image,wavelength)

hcube = hypercube(image,wavelength,metadata)

hcube = hypercube(___,BlockSize=blockSize)

Description

hcube = hypercube(filename) reads hyperspectral data from the specified input file filename. The input file can be a national imagery transmission format (NITF) file, Hyperion level 1R (L1R) file stored in hierarchical data format (HDF), ENVI header or image file, or metadata text extension (MTL) file that contains satellite data from earth observing (EO) satellites. The hypercube object supports hyperspectral and multispectral data acquired by these satellites.

EO-1 Hyperion — Hyperspectral data
EO-1 Advanced Land Imager (EO-1 ALI) — Multispectral data
Landsat Multispectral Scanner (Landsat MSS) — Multispectral data
Landsat Thematic Mapper (Landsat TM) — Multispectral data
Landsat Enhanced Thematic Mapper Plus (Landsat ETM+) — Multispectral data
Landsat Operational Land Imager / Thermal Infrared Scanner (Landsat OLI / TIRS) — Multispectral data
Airborne Visible/Infrared Imaging Spectrometer (AVIRIS) — Hyperspectral data

Note

The hypercube function reads satellite data stored in the georeferenced tagged image file format (GeoTIFF).

example

hcube = hypercube(img,hdr) reads hyperspectral data from the data file img. The data file can be an ENVI image file or Hyperion L1R file. The function uses the metadata in the header file hdr to interpret the data from img.

example

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

example

hcube = hypercube(tifFile,wavelength) reads hyperspectral data from a tagged image file format (TIFF) file tifFile.

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

example

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

example

hcube = hypercube(___,BlockSize=blockSize) specifies the block size for loading the hyperspectral 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™ or MATLAB Mobile™ do not support the library.

Input Arguments

expand all

`filename` — Input filename
character vector | string scalar

Input filename, specified as a character vector or string scalar. The input filename must be one of these file types.

File Format	Extensions	Additional Requirements
NITF files	`.ntf` `.nsf`	None
GeoTIFF metadata files from EO satellites	`.txt`	Filename must end with suffix "MTL".
ENVI image files ENVI header files	Image files: `.dat` `.img` `.raw` `.bsq` (since R2023b) `.bil` (since R2023b) `.bip` (since R2023b) Header files: `.hdr`	Image and header file must be in the same folder and have the same filename.
Hyperion level 1R image files Hyperion header files	Image files: `.L1R` Header files: `.hdr`	Image and header file must be in the same folder and have the same filename.
Multipage TIFF files (since R2023b)	`.tif`	File must be a multipage TIFF file containing a volume or time series image stack.

Data Types: char | string

`img` — Image filename
character vector | string scalar

Image filename, specified as a character vector or string scalar. The input file must be a flat binary raster file with one of these file extensions.

.dat
.raw
.L1R
.bsq (since R2023b)
.bil (since R2023b)
.bip (since R2023b)

The binary data must be in band sequential (BSQ), band-interleaved-by-pixel (BIP), or band-interleaved-by-line (BIL) interleave format.

Data Types: char | string

`hdr` — Header filename
character vector | string scalar

Header filename, specified as a character vector or string scalar. The header file contains the metadata for the image file img and must have the extension .hdr. The header file must contain at least these fields.

Field	Description
`Height`	Height of the image or number of rows in the image, specified as a positive integer.
`Width`	Width of the image or number of columns in the image, specified as a positive integer.
`Bands`	Number of spectral bands, specified as a positive integer.
`DataType`	Data type of data in the ENVI file, specified as any of these values: `"single"` `"double"` `"uint8"` `"uint16"` `"int16"` `"uint32"` `"int32"` `"uint64"` `"int64"`
`HeaderOffset`	Zero-based location of the first element in the image file,specified 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.
`ByteOrder`	Endianness of the data, specified as the string `"ieee-le"` for little endian or `"ieee-be"` for big endian.

The hypercube function also requires data interleave information to read the hyperspectral image associated with the header. If the image file does not have a .bsq (band-sequential), .bil (band-interleaved-by-line), or .bip (band-interleaved-by-pixel) extension, then your header file must include an Interleave field with one of these values.

"bsq" — Band-sequential
"bil" — Band-interleaved-by-line
"bip" — Band-interleaved-by-pixel

Data Types: char | string

`wavelength` — Center wavelength values
C-element vector

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

`tifFile` — TIFF file name
character vector | string scalar

TIFF file name, specified as a character vector or string scalar. The file name must include the extension .tiff or .tif.

Data Types: char | string

`image` — Input hyperspectral data
3-D numeric array

Input hyperspectral data, specified as a 3-D numeric array of size M-by-N-by-C. 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.

`metadata` — Metadata of hyperspectral data
structure array

Metadata of hyperspectral data, specified as a structure array.

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

Properties

expand all

`DataCube` — Hyperspectral data cube
3-D numeric array

This property is read-only.

Hyperspectral data cube, stored as a 3-D numeric array of size M-by-N-by-C. The data cube stores the hyperspectral data read from a file or numeric array as an array of 2-D monochromatic images. C is the number of images or spectral bands, M and N are the spatial resolution of the images in pixels. The data cube is of the same size and data type as the input data.

`Wavelength` — Center wavelength values
C-element vector

This property is read-only.

Center wavelength values of each spectral band, specified as a C-element vector. C is the spectral dimension, defined as the number of spectral bands, of the input hyperspectral data. You can set this property by using wavelength input argument.

`Metadata` — Metadata of hyperspectral data
structure array

This property is read-only.

Metadata of hyperspectral data, stored as a structure array with these fields as defaults.

Field	Description
`Height`	Height of the image or number of rows in the data cube, specified as a positive integer
`Width`	Width of the image or number of columns in the data cube, specified as a positive integer
`Bands`	Number of spectral bands comprising the data cube, specified as a positive integer
`DataType`	Data type of data, specified as any of these values: `"single"` `"double"` `"uint8"` `"uint16"` `"int16"` `"uint32"` `"int32"` `"uint64"` `"int64"`
`Interleave`	Data interleave, specified as any 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, specified 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, specified as the string `"ieee-le"` for little endian or `"ieee-be"` for big endian.
`WavelengthUnits`	Units for the wavelengths of spectral bands, stored as one of these strings. `"Nanometers"` — If all wavelengths are in nanometers (greater than 200 and less than 100000) `"Micrometers"` — If all wavelengths are in micrometers (greater than 0.2 and less than 100) `""` — If all the wavelengths are neither in nanometers, nor in micrometers.

Note

The Metadata property of hypercube object can have one or more additional fields depending on the parameter values stored in the header file of the input hyperspectral data. You can modify the parameters values of the Metadata property or add new Metadata to the hypercube object by specifying the input argument metadata.

Data Types: struct

`BlockSize` — Size of data blocks
2-element vector of positive integers

Size of the data blocks, stored as a 2-element vector of positive integers. The 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 the execution time at the cost of increased memory usage.

You can set this property using the blockSize name-value argument.

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

Data Types: double

Object Functions

`assignData`	Assign new data to hyperspectral data cube
`cropData`	Crop regions-of-interest
`enviwrite`	Write hyperspectral data to ENVI file format
`selectBands`	Select most informative bands
`removeBands`	Remove spectral bands from data cube
`colorize`	Estimate color image of hyperspectral data

Examples

collapse all

Read and Visualize Hyperspectral Data from ENVI File

This example uses:

Hyperspectral Imaging Library for Image Processing Toolbox Hyperspectral Imaging Library for Image Processing Toolbox

Open Live Script

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

hcube = hypercube('paviaU.dat','paviaU.hdr');

Display the properties of the hypercube object.

hcube

hcube = 
  hypercube with properties:

      DataCube: "[610x340x103 double]"
    Wavelength: [103x1 double]
      Metadata: [1x1 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.

Inspect the metadata of the hypercube object.

hcube.Metadata

ans = struct with fields:
             Filename: "/mathworks/devel/bat/filer/batfs2566-0/Bdoc24b.2725827/build/runnable/matlab/toolbox/images/supportpackages/hyperspectral/hyperdata/mavendata/paviaU.hdr"
          FileModDate: "21-Jun-2024 16:13:21"
             FileSize: 654
               Format: "HDR"
        FormatVersion: ''
           SensorType: [0x0 string]
          Description: [0x0 string]
      AcquisitionTime: [0x0 string]
         RasterFormat: "ENVI"
               Height: 610
                Width: 340
                Bands: 103
             DataType: "double"
           Interleave: "bsq"
         HeaderOffset: 0
            ByteOrder: "ieee-le"
            BandNames: [0x0 string]
                 FWHM: []
                 Gain: []
               Offset: []
      ReflectanceGain: []
    ReflectanceOffset: []
             BadBands: []
           CloudCover: []
           SunAzimuth: []
         SunElevation: []
      SolarIrradiance: []
     EarthSunDistance: []
      WavelengthUnits: "Nanometers"

Read Data from ENVI File and Replace Wavelength Values

This example uses:

Hyperspectral Imaging Library for Image Processing Toolbox Hyperspectral Imaging Library for Image Processing Toolbox

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 = hypercube('paviaU.hdr');

Display the properties of the hypercube object.

hcube

hcube = 
  hypercube with properties:

      DataCube: "[610x340x103 double]"
    Wavelength: [103x1 double]
      Metadata: [1x1 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. Each wavelength value must be unique values.

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

Create a new hypercube object with the new wavelength values.

newhcube = hypercube('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.

Create Data Cube from Numeric Inputs

This example uses:

Hyperspectral Imaging Library for Image Processing Toolbox Hyperspectral Imaging Library for Image Processing Toolbox

Open Live Script

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

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 = hypercube(image,wavelength)

hcube = 
  hypercube with properties:

      DataCube: "[384x512x3 uint8]"
    Wavelength: [3x1 double]
      Metadata: [1x1 struct]
     BlockSize: [384 512]

Modify Metadata Property

This example uses:

Hyperspectral Imaging Library for Image Processing Toolbox Hyperspectral Imaging Library for Image Processing Toolbox

Open Live Script

Read a hyperspectral data into the workspace and inspect its properties.

hcube = hypercube('paviaU.dat');

Inspect the Metadata property of the hypercube object.

hcube.Metadata

ans = struct with fields:
             Filename: "/mathworks/devel/bat/filer/batfs2566-0/Bdoc24b.2725827/build/runnable/matlab/toolbox/images/supportpackages/hyperspectral/hyperdata/mavendata/paviaU.hdr"
          FileModDate: "21-Jun-2024 16:13:21"
             FileSize: 654
               Format: "HDR"
        FormatVersion: ''
           SensorType: [0x0 string]
          Description: [0x0 string]
      AcquisitionTime: [0x0 string]
         RasterFormat: "ENVI"
               Height: 610
                Width: 340
                Bands: 103
             DataType: "double"
           Interleave: "bsq"
         HeaderOffset: 0
            ByteOrder: "ieee-le"
            BandNames: [0x0 string]
                 FWHM: []
                 Gain: []
               Offset: []
      ReflectanceGain: []
    ReflectanceOffset: []
             BadBands: []
           CloudCover: []
           SunAzimuth: []
         SunElevation: []
      SolarIrradiance: []
     EarthSunDistance: []
      WavelengthUnits: "Nanometers"

Find and remove the empty fields from the metadata.

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

Set the value for the AcquistionTime field to current date.

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

Create a hypercube object with the new metadata. The DataCube and Wavelength properties of the new hypercube object is same as that of the input data.

nhcube = hypercube(hcube.DataCube,hcube.Wavelength,newMetadata);

Inspect the Metadata property of the new hypercube object.

nhcube.Metadata

ans = struct with fields:
             Height: 610
              Width: 340
              Bands: 103
           DataType: "double"
         Interleave: "bsq"
       HeaderOffset: 0
          ByteOrder: "ieee-le"
     AcquistionTime: "2024-09-05"
    WavelengthUnits: "Nanometers"

More About

expand all

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 then 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. You can crop the data cube to the desired region, and then work with the cropped data cube. You can also remove undesired bands from 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)

For an example on processing large hyperspectral images, see Process Large Hyperspectral Images.

Version History

Introduced in R2020a

expand all

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.

hypercube

Description

Creation

Syntax

Description

Input Arguments

`filename` — Input filename
character vector | string scalar

`img` — Image filename
character vector | string scalar

`hdr` — Header filename
character vector | string scalar

`wavelength` — Center wavelength values
C-element vector

`tifFile` — TIFF file name
character vector | string scalar

`image` — Input hyperspectral data
3-D numeric array

`metadata` — Metadata of hyperspectral data
structure array

`blockSize` — Size of data blocks
`[1024 1024]` (default) | 2-element vector of positive integers

Properties

`DataCube` — Hyperspectral data cube
3-D numeric array

`Wavelength` — Center wavelength values
C-element vector

`Metadata` — Metadata of hyperspectral data
structure array

`BlockSize` — Size of data blocks
2-element vector of positive integers

Object Functions

Examples

Read and Visualize Hyperspectral Data from ENVI File

Read Data from ENVI File and Replace Wavelength Values

Create Data Cube from Numeric Inputs

Modify Metadata Property

More About

Read Small Regions of Large Hyperspectral Image

Version History

R2024b: Specify block size for loading hyperspectral data cube

R2024a: Read small regions of large hyperspectral images

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

R2023a: Support for hyperspectral data from the AVIRIS sensor

See Also

Topics

hypercube

Description

Creation

Syntax

Description

Input Arguments

filename — Input filename character vector | string scalar

img — Image filename character vector | string scalar

hdr — Header filename character vector | string scalar

wavelength — Center wavelength values C-element vector

tifFile — TIFF file name character vector | string scalar

image — Input hyperspectral data 3-D numeric array

metadata — Metadata of hyperspectral data structure array

blockSize — Size of data blocks [1024 1024] (default) | 2-element vector of positive integers

Properties

DataCube — Hyperspectral data cube 3-D numeric array

Wavelength — Center wavelength values C-element vector

Metadata — Metadata of hyperspectral data structure array

BlockSize — Size of data blocks 2-element vector of positive integers

Object Functions

Examples

Read and Visualize Hyperspectral Data from ENVI File

Read Data from ENVI File and Replace Wavelength Values

Create Data Cube from Numeric Inputs

Modify Metadata Property

More About

Read Small Regions of Large Hyperspectral Image

Version History

R2024b: Specify block size for loading hyperspectral data cube

R2024a: Read small regions of large hyperspectral images

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

R2023a: Support for hyperspectral data from the AVIRIS sensor

See Also

Topics

`filename` — Input filename
character vector | string scalar

`img` — Image filename
character vector | string scalar

`hdr` — Header filename
character vector | string scalar

`wavelength` — Center wavelength values
C-element vector

`tifFile` — TIFF file name
character vector | string scalar

`image` — Input hyperspectral data
3-D numeric array

`metadata` — Metadata of hyperspectral data
structure array

`blockSize` — Size of data blocks
`[1024 1024]` (default) | 2-element vector of positive integers

`DataCube` — Hyperspectral data cube
3-D numeric array

`Wavelength` — Center wavelength values
C-element vector

`Metadata` — Metadata of hyperspectral data
structure array

`BlockSize` — Size of data blocks
2-element vector of positive integers