Using the HDF4 Command-Line Interface :: Data Import and Export (Programming)

Programming

Using the HDF4 Command-Line Interface

This section describes how to use MATLAB functions to access the HDF4 Application Programming Interfaces (APIs). These APIs are libraries of C routines that you can use to import data from an HDF4 file. For a complete list of the HDF APIs supported by MATLAB and the functions you use to access each one, see the hdf reference page.

Topics covered include

Note You can also use the HDF Import Tool to get information about the contents of an HDF4 file. See Using the HDF Import Tool for more information.

Understanding the HDF4 to MATLAB Syntax Mapping

Each HDF4 API includes many individual routines that you use to read data from files, write data to files, and perform other related functions. For example, the HDF Scientific Data (SD) API includes separate C routines to open (SDopen), close (SDend), and read data (SDreaddata).

Instead of supporting each routine in the HDF APIs, MATLAB provides a single function that serves as a gateway to all the routines in a particular HDF API. For example, the HDF Scientific Data (SD) API includes the C routine SDend to close an HDF file:

```
status = SDend(sd_id); /* C code */
```

To call this routine from MATLAB, use the MATLAB function associated with the SD API, hdfsd. You must specify the name of the routine, minus the API acronym, as the first argument and pass any other required arguments to the routine in the order they are expected. For example,

status = hdfsd('end',sd_id); % MATLAB code

Handling HDF Routines with Output Arguments. Some HDF API routines use output arguments to return data. Because MATLAB does not support output arguments, you must specify these arguments as return values.

For example, the SDfileinfo routine returns data about an HDF file in two output arguments, ndatasets and nglobal_atts:

status = SDfileinfo(sd_id, ndatasets, nglobal_atts); /* C code */

To call this routine from MATLAB, change the output arguments into return values:

[ndatasets, nglobal_atts, status] = hdfsd('fileinfo',sd_id);

Specify the return values in the same order as they appear as output arguments. The function status return value is always specified as the last return value.

Example: Using the HDF4 SD API to Import Data

To illustrate using HDF4 API routines in MATLAB, this section describes how to import HDF4 Scientific Data (SD) into the MATLAB workspace. The following gives an overview of the steps required by the SD API to import data from and HDF file. The following sections walk you through a detailed example.

Note The following sections, when referring to specific routines in the HDF SD API, use the C library name rather than the MATLAB function name. The MATLAB syntax is used in all examples.

Step 1: Opening the HDF4 File. To import an HDF SD data set, you must first open the file using the SD API routine SDstart. In MATLAB, you use the hdfsd function, specifying as arguments:

Name of the SD API routine, start in this case.
Name of the file you want to open.
Mode in which you want to open it. The following table lists the file access modes supported by the SDstart routine. In MATLAB, you specify these modes as text strings. You can specify the full HDF mode name or one of the abbreviated forms listed in the table.

HDF File Creation Mode
HDF Mode Name
MATLAB String

Create a new file
'DFACC_CREATE'
'create'

Read access
'DFACC_RDONLY'
'read' or
'rdonly'

Read and write access
'DFACC_RDWR'
'rdwr' or
'write'

HDF File Creation Mode	HDF Mode Name	MATLAB String
Create a new file	`'DFACC_CREATE'`	`'create'`
Read access	`'DFACC_RDONLY'`	`'read'` or `'rdonly'`
Read and write access	`'DFACC_RDWR'`	`'rdwr'` or `'write'`

For example, this code opens the file mydata.hdf for read access:

sd_id = hdfsd('start','mydata.hdf','read');

If SDstart can find and open the file specified, it returns an HDF SD file identifier, named sd_id in the example. Otherwise, it returns -1.

Step 2: Retrieving Information About the HDF File. To get information about an HDF4 file, you must use the SD API routine SDfileinfo. This function returns the number of data sets in the file and the number of global attributes in the file, if any. (For more information about global attributes, see Exporting MATLAB Data to an HDF4 File.) In MATLAB, you use the hdfsd function, specifying the following arguments:

Name of the SD API routine, fileinfo in this case
SD file identifier, sd_id, returned by SDstart

In this example, the HDF4 file contains three data sets and one global attribute.

[ndatasets, nglobal_atts, stat] = hdfsd('fileinfo',sd_id)

ndatasets =
    3

nglobal_atts =
    1

status =
    0

Step 3: Retrieving Attributes from an HDF File (Optional). HDF files can optionally include information, called attributes, that describes the data the file contains. Attributes associated with an entire HDF file are called global attributes. Attributes associated with a data set are called local attributes. (You can also associate attributes with files or dimensions. For more information, see Step 4: Writing Metadata to an HDF File.)

To retrieve attributes from an HDF file, use the HDF4 API routine SDreadattr. In MATLAB, use the hdfsd function, specifying as arguments:

Name of the SD API routine, readattr in this case.
File identifier (sd_id) returned by SDstart, for global attributes, or the data set identifier for local attributes. (See Step 4: Selecting the Data Sets to Import to learn how to get a data set identifier.)
Index identifying the attribute you want to view. HDF uses zero-based indexing. If you know the name of an attribute but not its index, use the SDfindattr routine to determine the index value associated with the attribute.

For example, this code returns the contents of the first global attribute, which is the character string my global attribute:

attr_idx = 0;
[attr, status] = hdfsd('readattr', sd_id, attr_idx); 

attr =
    my global attribute

Step 4: Selecting the Data Sets to Import. To select a data set, use the SD API routine SDselect. In MATLAB, you use the hdfsd function, specifying as arguments:

Name of the SD API routine, select in this case
HDF SD file identifier (sd_id) returned by SDstart

If SDselect finds the specified data set in the file, it returns an HDF SD data set identifier, called sds_id in the example. If it cannot find the data set, it returns -1.

Note Do not confuse HDF SD file identifiers, named sd_id in the examples, with HDF SD data set identifiers, named sds_id in the examples.

```
sds_id = hdfsd('select',sd_id,1)
```

Step 5: Getting Information About a Data Set. To read a data set, you must get information about the data set, such as its name, size, and data type. In the HDF SD API, you use the SDgetinfo routine to gather this information. In MATLAB, use the hdfsd function, specifying as arguments:

Name of the SD API routine, getinfo in this case
HDF SD data set identifier (sds_id) returned by SDselect

This code retrieves information about the data set identified by sds_id:

[dsname, dsndims, dsdims, dstype, dsatts, stat] =
              hdfsd('getinfo',sds_id)
dsname =
      A

dsndims =
      2

dsdims =
      5     3

dstype =
      double

dsatts =
      0

stat =
      0

Step 6: Reading Data from the HDF File. To read data from an HDF4 file, you must use the SDreaddata routine. In MATLAB, use the hdfsd function, specifying as arguments:

Name of the SD API function, readdata in this case.
HDF SD data set identifier (sds_id) returned by SDselect.
Location in the data set where you want to start reading data, specified as a vector of index values, called the start vector. To read from the beginning of a data set, specify zero for each element of the start vector. Use SDgetinfo to determine the dimensions of the data set.
Number of elements along each dimension to skip between each read operation, specified as a vector of scalar values, called the stride vector. To read every element of a data set, specify 1 as the value for each element of the vector or specify an empty array ([]).
Total number of elements to read along each dimension, specified as a vector of scalar values, called the edges vector. To read every element of a data set, set each element of the edges vector to the size of each dimension of the data set. Use SDgetinfo to determine these sizes.

Note SDgetinfo returns dimension values in row-major order, the ordering used by HDF. Because MATLAB stores data in column-major order, you must specify the dimensions in column-major order, that is, [columns,rows]. In addition, you must use zero-based indexing in these arguments.

For example, to read the entire contents of a data set, use this code:

[ds_name, ds_ndims, ds_dims, ds_type, ds_atts, stat] =
                              hdfsd('getinfo',sds_id);

ds_start = zeros(1,ds_ndims); % Creates the vector [0 0]
ds_stride = []; 
ds_edges = ds_dims; 

[ds_data, status] =
           hdfsd('readdata',sds_id,ds_start,ds_stride,ds_edges)
;

disp(ds_data)
    1    2    3    4    5
    6    7    8    9    10
   11   12   13   14    15

To read less than the entire data set, use the start, stride, and edges vectors to specify where you want to start reading data and how much data you want to read. For example, this code reads the entire second row of the sample data set:

ds_start = [0 1] % Start reading at the first column, second row
ds_stride = []; % Read each element
ds_edges = [5 1]; % Read a 1-by-5 vector of data 

[ds_data, status] =
           hdfsd('readdata',sds_id,ds_start,ds_stride,ds_edges)
;

Step 7: Closing the HDF4 Data Set. After writing data to a data set in an HDF file, you must close access to the data set. In the HDF SD API, you use the SDendaccess routine to close a data set. In MATLAB, use the hdfsd function, specifying as arguments:

Name of the SD API routine, endaccess in this case
HDF SD data set identifier (sds_id) returned by SDselect

For example, this code closes the data set:

```
stat = hdfsd('endaccess',sds_id);
```

You must close access to all the data sets in an HDF file before closing it.

Step 8: Closing the HDF File. After writing data to a data set and closing the data set, you must also close the HDF file. In the HDF SD API, you use the SDend routine. In MATLAB, use the hdfsd function, specifying as arguments:

Name of the SD API routine, end in this case
HDF SD file identifier (sd_id) returned by SDstart

For example, this code closes the data set:

```
stat = hdfsd('end',sd_id);
```

Using the MATLAB hdfread Function Exporting MATLAB Data to an HDF4 File