geohypercube

R2026b

Read hyperspectral image with geospatial information

Since R2025a

collapse all in page

    Syntax

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

    Description

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

    hcube = geohypercube(file) reads hyperspectral image data with geospatial information from the specified file file and stores the geospatial information in the Metadata property of the hypercube object.

    example

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

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

    hcube = geohypercube(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.

    hcube = geohypercube(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 = geohypercube(___,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

    This function requires a Mapping Toolbox™ license.

    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 with geospatial data into the workspace.

    hcube = geohypercube("LC08_L1TP_097070_20201101_20201101_01_cropped.dat");

    Extract the geospatial information in the metadata of the hypercube object. For more information about geospatial information, see the Reference Objects section of Georeferenced Raster Data (Mapping Toolbox). 

    R = hcube.Metadata.RasterReference
    R = 
  MapCellsReference with properties:

            XWorldLimits: [796770 827880]
            YWorldLimits: [-1603770 -1573470]
              RasterSize: [1010 1037]
    RasterInterpretation: 'cells'
        ColumnsStartFrom: 'north'
           RowsStartFrom: 'west'
      CellExtentInWorldX: 30
      CellExtentInWorldY: 30
    RasterExtentInWorldX: 31110
    RasterExtentInWorldY: 30300
        XIntrinsicLimits: [0.5 1037.5]
        YIntrinsicLimits: [0.5 1010.5]
      TransformationType: 'rectilinear'
    CoordinateSystemType: 'planar'
            ProjectedCRS: [1×1 projcrs]

    Estimate and visualize the RGB image of the hyperspectral data.

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

    Figure contains an axes object. The hidden axes object contains an object of type image.

    Create a polygonal region of interest in geographic coordinates.

    xlimits = R.XWorldLimits;
ylimits = R.YWorldLimits;
dataRegion = mappolyshape(xlimits([1 1 2 2 1]),ylimits([1 2 2 1 1]));
dataRegion.ProjectedCRS = R.ProjectedCRS;

    Plot the polygonal region of interest using satellite imagery.

    figure
geoplot(dataRegion, ...
  LineWidth=2, ...
  EdgeColor="yellow", ...
  FaceColor="red", ...
  FaceAlpha=0.2)
hold on
geobasemap satellite

    Figure contains an axes object with type geoaxes. The geoaxes object contains an object of type polygon.

    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.

    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: "hyperspectralData.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\hyperspectralData.tif"

    Example: "\imgDir\hyperspectralData.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/hyperspectralData.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 Locationscheme_name
    Amazon S3™s3
    Windows Azure® Blob Storagewasb, wasbs
    HDFS™hdfs

    For more information, see Work with Remote Data.

    Example: "s3://my_bucket/my_path/hyperspectralData.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

    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

    Hyperspectral image data cube, 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.

    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. To include geospatial information in the hypercube object, the metadata structure must contain the geospatial information in the field RasterReference.

    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 with geospatial information, returned as a hypercube object.

    Version History

    Introduced in R2025a

    expand all

    See Also

    | | | |

    Topics