hdfread

Read data from HDF4 or HDF-EOS2 file

Syntax

data = hdfread(filename,SDDatasetName)

data = hdfread(filename,VDatasetName)

data = hdfread(filename,gridDatasetName,Fields=fields)

data = hdfread(filename,pointDatasetName,Fields=fields,Level=level)

data = hdfread(filename,swathDatasetName,Fields=fields)

data = hdfread(S)

data = hdfread(___,Name=Value)

data = hdfread(filename,IDatasetName24Bit)

[data,map] = hdfread(filename,IDatasetName8Bit)

Description

Note

The hdfread function reads HDF4 data from HDF4 files or HDF-EOS2 files. To read data from HDF5 files, use the h5read function.

data = hdfread(filename,SDDatasetName) returns all the data in the specified HDF Scientific Data (SD) dataset from the specified file.

data = hdfread(filename,VDatasetName) returns all the data in the specified HDF Vertex (V) dataset.

data = hdfread(filename,gridDatasetName,Fields=fields) returns all the data in the specified field of the specified HDF-EOS Grid dataset.

data = hdfread(filename,pointDatasetName,Fields=fields,Level=level) returns all the data in the specified fields and at the specified level of the specified HDF-EOS Point dataset.

data = hdfread(filename,swathDatasetName,Fields=fields) returns all the data in the specified field of the specified HDF-EOS Swath dataset.

data = hdfread(S) returns all the data in the dataset specified by the structure S. Use the hdfinfo function to generate the structure. If the generated structure contains more than one dataset, indicate which dataset you want the hdfread function to read by specifying the field in the S structure that relates to a particular type of dataset and using indexing.

data = hdfread(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. For example, to read 20 records from an HDF V dataset, set NumRecords to 20. For a quick reference on the types of datasets and the name-value arguments they support, see Valid Argument Combinations.

data = hdfread(filename,IDatasetName24Bit) returns the image data for the specified 24-bit raster image.

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

Examples

Read Dataset in HDF File

Read a dataset named temperature from a sample HDF4 file.

data = hdfread("sd.hdf","temperature");

Check the size of the dataset. Then display the first five rows and columns of the dataset.

size(data)

ans = 1×2

    10    20

data(1:5,1:5)

ans = 5×5

     1     2     3     4     5
    21    22    23    24    25
    41    42    43    44    45
    61    62    63    64    65
    81    82    83    84    85

Specify Dataset Using Structure

Retrieve information about the contents of an HDF4 file by using the hdfinfo function. Then extract the structure containing information about the particular dataset that you want to import. This example uses a structure in the SDS field.

S = hdfinfo("sd.hdf");
sds_info = S.SDS(1);

Import the data using the hdfread function.

data = hdfread(sds_info)

data = 1×5

     1     2     3     4     5

Read Data from HDF-EOS Grid Field

Read data from the HDF-EOS grid field TbOceanRain from a sample file.

oceanRain = hdfread("example.hdf","MonthlyRain",Fields="TbOceanRain");

Read data for the northern hemisphere for the same field. Use the Box name-value argument to specify the longitude and latitude coordinates for the region.

oceanRainNorth = hdfread("example.hdf","MonthlyRain", ...
                         Fields="TbOceanRain",Box={[0 360] [0 90]});

Read Subset of Data in Dataset

Retrieve information about a Scientific Data dataset from a sample file.

S = hdfinfo("example.hdf");
sds_info = S.SDS;

Check the size of the dataset.

sds_info.Dims.Size

ans = 
16

ans = 
5

Read a subset of the data in the dataset using the Index name-value argument. Specify a starting index of [3 3], a stride of 1 for each dimension (by using [] for the second entry of Index), and a count of 10 rows and 2 columns.

data = hdfread(sds_info,Index={[3 3] [] [10 2]})

data = 10×2 int16 matrix

    7    8
    8    9
    9   10
   10   11
   11   12
   12   13
   13   14
   14   15
   15   16
   16   17

Read Data from HDF V Fields

Read the Idx, Temp, and Dewpt fields of an HDF V dataset. Use the Vdata field in the structure returned by hdfinfo.

S = hdfinfo("example.hdf");
data = hdfread(S.Vdata(1),Fields=["Idx" "Temp" "Dewpt"])

data=3×1 cell array
    {[  1 2 3 4 5 6 7 8 9 10]}
    {[0 12 3 5 10 -1 3 0 2 1]}
    {[5 5 7 11 7 10 4 14 4 8]}

Input Arguments

filename — Filename

string scalar | character vector

Filename of an existing HDF4 or HDF-EOS2 file, specified as a string scalar or character vector.

Depending on the location of your file, filename can take one of these forms.

Location	Form
Current folder or folder on the MATLAB® path	If the file is in the current folder or in a folder on the MATLAB path, then specify the name of the file in filename. Example: "myFile.hdf"
Other folders	If the file is neither in the current folder nor in a folder on the MATLAB path, then specify the full or relative path in filename. Example: "C:\myFolder\myFile.hdf" Example: "myFolder\myFile.hdf"

SDDatasetName — Name of HDF SD dataset

string scalar | character vector

Name of an HDF SD dataset, specified as a string scalar or character vector.

Example: "mySDDataset"

VDatasetName — Name of HDF V dataset

string scalar | character vector

Name of an HDF V dataset, specified as a string scalar or character vector.

Example: "myVDataset"

gridDatasetName — Name of HDF-EOS Grid dataset

string scalar | character vector

Name of an HDF-EOS Grid dataset, specified as a string scalar or character vector.

Example: "myGridDataset"

pointDatasetName — Name of HDF-EOS Point dataset

string scalar | character vector

Name of an HDF-EOS Point dataset, specified as a string scalar or character vector.

Example: "myPointDataset"

swathDatasetName — Name of HDF-EOS Swath dataset

string scalar | character vector

Name of an HDF-EOS Swath dataset, specified as a string scalar or character vector.

Example: "mySwathDataset"

S — Dataset to read

structure

Dataset to read, specified as a structure. You can use the hdfinfo function to generate a suitable S structure. If the generated structure contains more than one dataset, indicate which dataset you want the hdfread function to read by specifying the field that relates to a particular type of dataset and using indexing.

Example: S

Example: S.SDS(2)

IDatasetName24Bit — Name of 24-bit raster image

string scalar | character vector

Name of a 24-bit raster image, specified as a string scalar or character vector.

Example: "myIDataset24Bit"

IDatasetName8Bit — Name of 8-bit raster image

string scalar | character vector

Name of an 8-bit raster image, specified as a string scalar or character vector.

Example: "myIDataset8Bit"

fields — Names of HDF V or HDF-EOS fields to read

string array | character vector | cell array of character vectors

Names of the HDF V or HDF-EOS fields to read, specified as a string array, character vector, or cell array of character vectors.

• For HDF V and HDF-EOS Point datasets, you can specify one or more fields. Specify fields as a string scalar or character vector when reading only one field, and as a string array or cell array of character vectors when reading more than one field.

• For HDF-EOS Grid and Swath datasets, you can specify only one field. In these cases, specify fields as a string scalar or character vector.

Note

You must specify fields for HDF-EOS datasets. However, specifying fields is optional for HDF V datasets.

Example: "myGridField"

Example: ["myField1" "myField2"]

Example: {'myField1' 'myField2'}

level — Level from which to read HDF-EOS Point dataset

string scalar | character vector | positive integer

Level from which to read an HDF-EOS Point dataset, specified as a string scalar, character vector, or positive integer. You can specify the name of the level using a string scalar or character vector, or you can specify the index of the level using a positive integer.

Example: "myLevel"

Example: 1

Data Types: string | char | double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: hdfread("example.hdf","Example Vdata",FirstRecord=2,NumRecords=5) reads five records from the Example Vdata V dataset in the file example.hdf, beginning with the second record.

Note

For a quick reference on the types of datasets and the name-value arguments they support, see Valid Argument Combinations.

Index — Location, range, and values of SD, Grid, or Swath dataset to read

three-element cell vector of positive integer vectors

Location, range, and values of the SD, Grid, or Swath dataset to read, specified as a three-element cell vector of positive integer vectors. Specify Index using the form {start stride count}. Each of start, stride, and count must have type double.

• start — Positions in the dataset at which to begin reading at each dimension. Specify start as [] to read from the start of each dimension.

• stride — Interval between values to read for each dimension. Specify stride as [] to set a stride of 1 for each dimension.

• count — Number of entries to read for each dimension. Specify count as [] to read until the end of each dimension.

Each nonempty entry of Index must have a number of entries equal to the number of dimensions in the dataset to be read.

Note

If you specify Index for Grid data, then you cannot specify Interpolate, Pixels, or Tile.

If you specify Index for Swath data, then you cannot specify Time.

Example: {[1 10] [3 2] [2 4]}

Example: {[2 4 5] [] []}

FirstRecord — Index of first V record to read

positive integer

Index of the first V record to read, specified as a positive integer.

By default, the hdfread function starts at the first record.

Example: 2

Data Types: double

NumRecords — Number of V records to read

positive integer

Number of V records to read, specified as a positive integer.

By default, the hdfread function reads all the records.

Example: 10

Data Types: double

Interpolate — Region of Grid dataset to read for bilinear interpolation

two-element cell vector of numeric vectors

Region of the Grid dataset to read for bilinear interpolation, specified as a two-element cell vector of numeric vectors. Specify Interpolate using the form {lon lat}. Each of lon and lat must have type double.

• lon — Longitude coordinates.

• lat — Latitude coordinates.

The hdfread function performs bilinear interpolation on the region described by the lon and lat vectors.

Note

If you specify Interpolate, then you cannot specify Index, Pixels, or Tile.

Example: {-125:10:-65 25:2.5:50}

Pixels — Region of Grid dataset to read

two-element cell vector of numeric vectors

Region of the Grid dataset to read, specified as a two-element cell vector of numeric vectors. Specify Pixels using the form {lon lat}. Each of lon and lat must have type double.

• lon — Longitude coordinates.

• lat — Latitude coordinates.

The hdfread function reads data from the region described by the lon and lat vectors and converts this region into pixel rows and columns with the origin in the upper-left corner of the grid.

Note

If you specify Pixels, then you cannot specify Index, Interpolate, or Tile.

Example: {-125:10:-65 25:2.5:50}

Tile — Coordinates of one tile in Grid dataset to read

numeric vector

Coordinates of one tile in the Grid dataset to read, specified as a numeric vector.

Note

If you specify Tile, then you cannot specify Index, Interpolate, or Pixels.

Example: [1 1 9]

Data Types: double

Box — Region of Grid, Point, or Swath dataset to read

two- or three-element cell vector

Region of the Grid, Point, or Swath dataset to read, specified as a two- or three-element cell vector.

For Grid and Point datasets, specify Box using the form {[lonStart lonStop] [latStart latStop]}; for Swath datasets, specify Box using the form {[lonStart lonStop] [latStart latStop] mode}.

• lonStart — Minimum longitude of the region.

• lonStop — Maximum longitude of the region.

• latStart — Minimum latitude of the region.

• latStop — Maximum latitude of the region.

• mode — Mode for inclusion of a cross track in a region, specified as one of these values:

  • "midpoint" — Include the cross track in the region if its midpoint is within the box.

  • "endpoint" — Include the cross track in the region if either of its endpoints is within the box.

  • "anypoint" — Include the cross track in the region if any of its points is within the box.

Note

If you specify Box for Point data, then you cannot specify Time or RecordNumbers.

Example: {[-125 -65] [25 50]}

Example: {[-125 -65] [25 50] "anypoint"}

Time — Time box in Grid, Point, or Swath dataset to read

two- or three-element cell vector

Time box in the Grid, Point, or Swath dataset to read, specified as a two- or three-element cell vector.

For Grid and Point datasets, specify Time using the form {start stop}; for Swath datasets, specify Time using the form {start stop mode}.

• start — Minimum time.

• stop — Maximum time.

• mode — Mode for inclusion of a cross track in a region, specified as one of these values:

  • "midpoint" — Include the cross track in the region if its midpoint is within the box.

  • "endpoint" — Include the cross track in the region if either of its endpoints is within the box.

Note

If you specify Time for Point data, then you cannot specify Box or RecordNumbers.

If you specify Time for Swath data, then you cannot specify Index.

Example: {5 13}

Example: {5 13 "midpoint"}

Vertical — Portion of field or dimension of Grid or Swath dataset to read

two-element cell vector

Portion of the field or dimension of the Grid or Swath dataset to read, specified as a two-element cell vector. Specify Vertical using the form {name range}.

• name — Name of dataset field or dimension from which to read, specified as a string scalar or character vector.

• range — Portion of the data, specified as a two-element numeric vector.

  • If name specifies a dataset field, then range specifies the range of values to extract.

  • If name specifies a dataset dimension, then range specifies the range of elements to extract.

Note

You can specify Vertical alone or with Box or Time.

To subset a region along multiple dimensions, you can specify Vertical up to eight times in a single call to hdfread.

Example: {"myField" [1 5]}

Example: {"myDimension" [11 20]}

RecordNumbers — Record numbers of Point dataset to read

numeric vector

Record numbers of the Point dataset to read, specified as a numeric vector.

Note

If you specify RecordNumbers, then you cannot specify Box or Time.

Example: 10:20

Data Types: double

Output Arguments

data — Data from dataset

numeric array | text | cell array

Data from the dataset, returned as a numeric array, text, or cell array.

map — Colormap associated with 8-bit raster image data

three-column numeric matrix

Colormap associated with the 8-bit raster image data, returned as a three-column numeric matrix.

More About

Valid Argument Combinations

This table is a quick reference for valid argument combinations for the hdfread function.

Name-Value Argument	HDF SD	HDF V	HDF-EOS Grid	HDF-EOS Point	HDF-EOS Swath
Fields		✔	✔1	✔1	✔1
Level				✔1
Index	✔		✔2		✔2
FirstRecord		✔
NumRecords		✔
Interpolate			✔2
Pixels			✔2
Tile			✔2
Box			✔	✔2	✔
Time			✔	✔2	✔2
Vertical			✔		✔
RecordNumbers				✔2

¹ — These name-value arguments are required for their respective types of data.

² — These name-value arguments are mutually exclusive for their respective types of data.

Version History

Introduced before R2006a