hdfread

Read data from HDF4 or HDF-EOS file

collapse all in page

Syntax

data = hdfread(filename, datasetname)
data = hdfread(hinfo)
data = hdfread(...,param,value,...)
data = hdfread(filename,EOSname,param,value,...)
[data,map] = hdfread(...)

Description

data = hdfread(filename, datasetname) returns all the data in the data set specified by datasetname from the HDF4 or HDF-EOS file specified by filename. To determine the name of a data set in an HDF4 file, use the hdfinfo function.

Note

hdfread can be used on Version 4.x HDF files or Version 2.x HDF-EOS files. To read data from an HDF5 file, use h5read.

data = hdfread(hinfo) returns all the data in the data set specified by the structurehinfo, returned by the hdfinfo function. Specify the field in the hinfo structure that relates to a particular type of data set, and use indexing to specify which data set, when there are more than one. See Specify data set to read for more information.

data = hdfread(...,param,value,...) returns subsets of the data according to the specified parameter and value pairs. See the tables below to find the valid parameters and values for different types of data sets.

data = hdfread(filename,EOSname,param,value,...) subsets the data field from the HDF-EOS point, grid, or swath specified by EOSname.

[data,map] = hdfread(...) returns the image data and the colormap map for an 8-bit raster image.

Subsetting Parameters

The following tables show the subsetting parameters that can be used with the hdfread function for certain types of HDF4 data. These data types are

Note the following:

  • If a parameter requires multiple values, use a cell array to store the values. For example, the 'Index' parameter requires three values: start, stride, and edge. Enclose these values in curly braces as a cell array.

    hdfread(..., 'Index', {start,stride,edge})

  • All values that are indices are 1-based.


Subsetting Parameters for HDF Scientific Data (SD) Data Sets

When you are working with HDF SD files, hdfread supports the parameters listed in this table.

Parameter

Description

'Index'

Three-element cell array, {start,stride,edge}, specifying the location, range, and values to be read from the data set

  • start — A 1-based array specifying the position in the file to begin reading

    Default: 1, start at the first element of each dimension. The values specified must not exceed the size of any dimension of the data set.

  • stride — A 1-based array specifying the interval between the values to read

    Default: 1, read every element of the data set.

  • edge — A 1-based array specifying the length of each dimension to read

    Default: An array containing the lengths of the corresponding dimensions

For example, this code reads the data set Example SDS from the HDF file example.hdf. The 'Index' parameter specifies that hdfread start reading data at the beginning of each dimension, read until the end of each dimension, but only read every other data value in the first dimension. 

data = hdfread('example.hdf','Example SDS','Index',{[],[2 1],[]})

Subsetting Parameters for HDF Vdata Sets

When you are working with HDF Vdata files, hdfread supports these parameters.

Parameter

Description

'Fields'

Character vector or string scalar specifying the name of the field to be read. When specifying multiple field names, use a cell array of character vectors or a string array.

'FirstRecord'

1-based number specifying the record from which to begin reading

'NumRecords'

Number specifying the total number of records to read

For example, this code reads the Vdata set Example Vdata from the HDF file example.hdf. 

data = hdfread('example.hdf','Example Vdata','FirstRecord', 2,'NumRecords', 5)

Subsetting Parameters for HDF-EOS Grid Data

When you are working with HDF-EOS grid data, hdfread supports three types of parameters:

  • Required parameters

  • Optional parameters

  • Mutually exclusive parameters — You can only specify one of these parameters in a call to hdfread, and you cannot use these parameters in combination with any optional parameter.

    Parameter

    Description

    Required Parameter

    'Fields'

    Character vector or string scalar specifying the field to be read. You can specify only one field name for a Grid data set.

    Mutually Exclusive Optional Parameters

    'Index'

    Three-element cell array, {start,stride,edge}, specifying the location, range, and values to be read from the data set

    start — An array specifying the position in the file to begin reading

    Default: 1, start at the first element of each dimension. The values must not exceed the size of any dimension of the data set.

    stride — An array specifying the interval between the values to read

    Default: 1, read every element of the data set.

    edge — An array specifying the length of each dimension to read

    Default: An array containing the lengths of the corresponding dimensions

    'Interpolate'

    Two-element cell array, {longitude,latitude}, specifying the longitude and latitude points that define a region for bilinear interpolation. Each element is an N-length vector specifying longitude and latitude coordinates.

    'Pixels'

    Two-element cell array, {longitude,latitude}, specifying the longitude and latitude coordinates that define a region. Each element is an N-length vector specifying longitude and latitude coordinates. This region is converted into pixel rows and columns with the origin in the upper left corner of the grid.

    Note: This is the pixel equivalent of reading a 'Box' region.

    'Tile'

    Vector specifying the coordinates of the tile to read, for HDF-EOS Grid files that support tiles

    Optional Parameters

    'Box'

    Two-element cell array, {longitude,latitude}, specifying the longitude and latitude coordinates that define a region. longitude and latitude are each two-element vectors specifying longitude and latitude coordinates.

    'Time'

    Two-element cell array, [start stop], where start and stop are numbers that specify the start and end-point for a period of time

    'Vertical'

    Two-element cell array, {dimension, range}

    dimension — Character vector or string scalar specifying the name of the data set field to be read from. You can specify only one field name for a Grid data set.

    range — Two-element array specifying the minimum and maximum range for the subset. If dimension is a dimension name, then range specifies the range of elements to extract. If dimension is a field name, then range specifies the range of values to extract.

    'Vertical' subsetting can be used alone or in conjunction with 'Box' or 'Time'. To subset a region along multiple dimensions, vertical subsetting can be used up to eight times in one call to hdfread.

For example,

data = hdfread('grid.hdf','PolarGrid','Fields','ice_temp','Index', {[5 10],[],[15 20]})

Subsetting Parameters for HDF-EOS Point Data

When you are working with HDF-EOS Point data, hdfread has two required parameters and three optional parameters.

Parameter

Description

Required Parameters

'Fields'

Character vector or string scalar containing the name of the data set field to be read. For multiple field names, use a cell array of character vectors or a string array.

'Level'

1-based number specifying which level to read from in an HDF-EOS Point data set

Mutually Exclusive Optional Parameters

'Box'

Two-element cell array, {longitude,latitude}, specifying the longitude and latitude coordinates that define a region. longitude and latitude are each two-element vectors specifying longitude and latitude coordinates.

'RecordNumbers'

Vector specifying the record numbers to read

'Time'

Two-element cell array, [start stop], where start and stop are numbers that specify the start and endpoint for a period of time

For example, 

hdfread(...,'Fields',{field1, field2},...
            'Level',level,'RecordNumbers',[1:50, 200:250])

Subsetting Parameters for HDF-EOS Swath Data

When you are working with HDF-EOS Swath data, hdfread supports three types of parameters:

  • Required parameters

  • Optional parameters

  • Mutually exclusive

You can only use one of the mutually exclusive parameters in a call to hdfread, and you cannot use these parameters in combination with any optional parameter.

Parameter

Description

Required Parameter

'Fields'

Character vector or string scalar containing the name of the data set field to be read. You can specify only one field name for a Swath data set.

Mutually Exclusive Optional Parameters

'Index'

Three-element cell array, {start,stride,edge}, specifying the location, range, and values to be read from the data set

  • start — An array specifying the position in the file to begin reading

    Default: 1, start at the first element of each dimension. The values must not exceed the size of any dimension of the data set.

  • stride — An array specifying the interval between the values to read

    Default: 1, read every element of the data set.

  • edge — An array specifying the length of each dimension to read

    Default: An array containing the lengths of the corresponding dimensions

'Time'

Three-element cell array, {start, stop, mode}, where start and stop specify the beginning and the endpoint for a period of time, and mode is a character vector or string scalar which defines the criterion for the inclusion of a cross track in a region. The cross track is within a region if any of these conditions is met:

  • Its midpoint is within the box (mode='midpoint').

  • Either endpoint is within the box (mode='endpoint').

Optional Parameters

'Box'

Three-element cell array, {longitude, latitude, mode} specifying the longitude and latitude coordinates that define a region. longitude and latitude are two-element vectors that specify longitude and latitude coordinates. mode is a character vector or string scalar which defines the criterion for the inclusion of a cross track in a region. The cross track is within a region if any of these conditions is met:

  • Its midpoint is within the box (mode='midpoint').

  • Either endpoint is within the box (mode='endpoint').

  • Any point is within the box (mode='anypoint').

'Vertical'

Two-element cell array, {dimension, range}

  • dimension is a character vector or string scalar specifying either a dimension name or field name to subset the data by.

  • range is a two-element vector specifying the minimum and maximum range for the subset. If dimension is a dimension name, then range specifies the range of elements to extract. If dimension is a field name, then range specifies the range of values to extract.

    'Vertical' subsetting can be used alone or in conjunction with 'Box' or 'Time'. To subset a region along multiple dimensions, vertical subsetting can be used up to eight times in one call to hdfread.

For example, 

hdfread('swath.hdf', 'Example Swath', 'Fields', 'Temperature', ...
         'Time', {5000, 6000, 'midpoint'})

Examples

collapse all

Open Live Script

Specify the name of the HDF file and the name of the data set. This example reads a data set named temperature from a sample HDF file.

data = hdfread('sd.hdf','temperature');
Open Live Script

Call hdfinfo to retrieve information about the contents of the HDF file.

fileinfo = hdfinfo('sd.hdf')
fileinfo = struct with fields:
      Filename: '/mathworks/devel/bat/BR2020bd/build/matlab/toolbox/matlab/imagesci/sd.hdf'
    Attributes: [1x1 struct]
           SDS: [1x2 struct]
         Vdata: [1x1 struct]

Extract the structure containing information about the particular data set you want to import from the data returned by hdfinfo. This example uses the structure in the SDS field to retrieve a scientific data set.

sds_info = fileinfo.SDS(2)
sds_info = struct with fields:
       Filename: '/mathworks/devel/bat/BR2020bd/build/matlab/toolbox/matlab/imagesci/sd.hdf'
           Type: 'Scientific Data Set'
           Name: 'temperature'
           Rank: 2
       DataType: 'double'
     Attributes: [1x11 struct]
           Dims: [2x1 struct]
          Label: {}
    Description: {}
          Index: 1

Pass this structure to hdfread to import the data in the data set. 

data = hdfread(sds_info);
Open Live Script

Read data from the HDF-EOS global grid field, TbOceanRain, in the example file, example.hdf.

data1 = hdfread('example.hdf','MonthlyRain','Fields','TbOceanRain');

Read data for the northern hemisphere for the same field. Use the Box parameter to specify the longitude and latitude coordinates for that region.

data2 = hdfread('example.hdf','MonthlyRain', ...
'Fields','TbOceanRain', ...
'Box', {[0 360],[0 90]});
Open Live Script

Retrieve info about the example file, example.hdf.

fileinfo = hdfinfo('example.hdf');

Retrieve information about Scientific Data Set in example.hdf.

data_set_info = fileinfo.SDS;

Check the size of the data set.

data_set_info.Dims.Size
ans = 16

ans = 5

Read a subset of the data in the data set using the 'index' parameter with hdfread. This example specifies a starting index of [3 3], an interval of 1 between values ([] meaning the default value of 1), and a length of 10 rows and 2 columns.

data = hdfread(data_set_info,'Index',{[3 3],[],[10 2]});
data(:,1)
ans = 10x1 int16 column vector

    7
    8
    9
   10
   11
   12
   13
   14
   15
   16


data(:,2)
ans = 10x1 int16 column vector

    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
Open Live Script

Use the Vdata field from the information returned by hdfinfo to read three fields of the data, Idx, Temp, and Dewpt.

s = hdfinfo('example.hdf'); 
data = hdfread(s.Vdata(1),'Fields',{'Idx','Temp','Dewpt'})
data=3×1 cell array
    {1x10 int16}
    {1x10 int16}
    {1x10 int16}

See Also

Introduced before R2006a

MATLAB Documentation

Support