MATLAB Function Reference |
|
hdfread
Extract data from an HDF or HDF-EOS file
Syntax
data = hdfread(filename, dataset)
data = hdfread(hinfo)
data = hdfread(...,param1,value1,param2,value2,...)
[data,map] = hdfread(...)
Description
data = hdfread(filename, dataset)
returns all the data in the specified data set dataset
from the HDF or HDF-EOS file filename
. To determine the names of the data sets in an HDF file, use the hdfinfo
function. The information returned by hdfinfo
contains structures describing the data sets contained in the file. You can extract one of these structures and pass it directly to hdfread
.
Note
hdfread can be used on Version 4.x HDF files or Version 2.x HDF-EOS files.
|
data = hdfread(hinfo)
returns all the data in the data set specified in the structure hinfo
. The hinfo
structure can be extracted from the data returned by the hdfinfo
function.
data = hdfread(...,param1,value1,param2,value2,...)
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,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 HDF data. These data types are
Note the following:
- If a parameter requires multiple values, the values must be stored in a cell array. For example, the
'Index'
parameter requires three values: start
, stride
, and edge
. Enclose these values in curly braces as a cell array.
hdfread(dataset_name, '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
stride -- A 1-based array specifying the interval between the values to read
edge -- A 1-based array specifying the length of each dimension to read
|
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.
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'
|
Text string specifying the name of the data set field to be read from. When specifying multiple field names, use a comma-separated list.
|
'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
.
hdfread('example.hdf', 'Example Vdata', 'FirstRecord', 400,
'NumRecords', 50)
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'
|
String naming the data set 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
stride -- An array specifying the interval between the values to read
edge -- An array specifying the length of each dimension to read
|
'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 -- String 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,
hdfread(grid_dataset, 'Fields', fieldname, ...
'Vertical', {dimension, [min, max]})
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'
|
String naming the data set field to be read. For multiple field names, use a comma-separated list.
|
'Level'
|
1-based number specifying which level to read from in an HDF-EOS Point data set
|
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(point_dataset, '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'
|
String naming 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
stride -- An array specifying the interval between the values to read
edge -- An array specifying the length of each dimension to read
|
'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 string defining 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' ).
|
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 string defining 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' ).
|
'ExtMode'
|
String specifying whether geolocation fields and data fields must be in the same swath (mode='internal' ), or can be in different swaths (mode='external' )
Note: mode is only used when extracting a time period or a region.
|
'Vertical'
|
Two-element cell array, {dimension, range}
dimension is a string 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('example.hdf',swath_dataset, 'Fields', fieldname, ...
'Time', {start, stop, 'midpoint'})
Examples
Importing a Data Set by Name
When you know the name of the data set, you can refer to the data set by name in the hdfread
command. To read a data set named 'Example SDS'
, use
Importing a Data Set Using the Hinfo Structure
When you don't know the name of the data set, follow this procedure.
- Use
hdfinfo
first to retrieve information on the data set.
- Extract the structure containing information about the particular data set you want to import from
fileinfo
.
- Pass this structure to
hdfread
to import the data in the data set.
Importing a Subset of a Data Set
You can check the size of the information returned as follows.
Using hdfread
parameter/value pairs, you can read a subset of the data in the data set. 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(sds_info, 'Index', {[3 3],[],[10 2]});
data(:,1)
ans =
7
8
9
10
11
12
13
14
15
16
data(:,2)
ans =
8
9
10
11
12
13
14
15
16
17
Importing Fields from a Vdata Set
This example retrieves information from example.hdf
first, and then reads two fields of the data, Idx
and Temp
.
info = hdfinfo('example.hdf');
data = hdfread(info.Vdata,...
'Fields',{'Idx','Temp'})
data =
[1x10 int16]
[1x10 int16]
index = data{1,1};
temp = data{2,1};
temp(1:6)
ans =
0 12 3 5 10 -1
See Also
hdfinfo
, hdf
| hdfinfo | | hdftool | |
© 1994-2005 The MathWorks, Inc.