hdf images hdf images

This web site is no longer updated (but will remain online).
Please see The HDF Group's new Support Portal for the latest information.

HDF5 Tutorial: Command-line Tools for Converting

Contents:


Output HDF5 Dataset into an ASCII File (to Import into Excel and Other Applications)

The h5dump utility can be used to convert an HDF5 dataset into an ASCII file, which can then be imported into Excel and other applications. The following options are used:

Options Description
 -d D, --dataset=D
Display dataset D
 -o F, --output=F 
Output raw data into file F
 -y, --noindex
Suppress printing of array indices with the data
 -w N, --width=N
Set N number of columns of output. A value of 0
sets the number to 65535 (the maximum)

As an example, h5_crtdat.c from the Creating a Dataset HDF5 Tutorial topic, creates the file dset.h5 with a dataset /dset that is a 4 x 6 integer array. The following is displayed when viewing dset.h5 with h5dump:

$ h5dump dset.h5
HDF5 "dset.h5" {
GROUP "/" {
   DATASET "dset" {
      DATATYPE  H5T_STD_I32BE
      DATASPACE  SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
      DATA {
      (0,0): 1, 2, 3, 4, 5, 6,
      (1,0): 7, 8, 9, 10, 11, 12,
      (2,0): 13, 14, 15, 16, 17, 18,
      (3,0): 19, 20, 21, 22, 23, 24
      }
   }
}
} 

The following command will output the values of the /dset dataset to the ASCII file dset.asci:

In particular, note that:

In addition to creating the ASCII file dset.asci, the above command outputs the metadata of the specified dataset:

HDF5 "dset.h5" {
DATASET "/dset" {
   DATATYPE  H5T_STD_I32BE
   DATASPACE  SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
   DATA {
   }
}
}

The dset.asci file will contain the values for the dataset:

      1, 2, 3, 4, 5, 6,
      7, 8, 9, 10, 11, 12,
      13, 14, 15, 16, 17, 18,
      19, 20, 21, 22, 23, 24


Output HDF5 Dataset into Binary File

The h5dump utility can be used to convert an HDF5 dataset to a binary file with the following options:

Options Description
 -d D, --dataset=D
Display dataset D
 -o F, --output=F 
Output raw data into file F
 -b B, --binary=B
Binary file output of form B.
Valid values are: LE, BE, NATIVE, FILE

As an example, h5_crtdat.c from the Creating a Dataset HDF5 Tutorial topic, creates the file dset.h5 with a dataset /dset that is a 4 x 6 integer array. The following is displayed when viewing dset.h5 with h5dump:

$ h5dump -d /dset/ dset.h5
HDF5 "dset.h5" {
DATASET "/dset/" {
   DATATYPE  H5T_STD_I32BE
   DATASPACE  SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
   DATA {
   (0,0): 1, 2, 3, 4, 5, 6,
   (1,0): 7, 8, 9, 10, 11, 12,
   (2,0): 13, 14, 15, 16, 17, 18,
   (3,0): 19, 20, 21, 22, 23, 24
   }
}
}

As specified by the -d and -o options, the following h5dump command will output the values of the dataset /dset to a file called dset.bin. The -b option specifies that the output will be binary in Little Endian format (LE).

This command outputs the metadata for the dataset, as well as creating the binary file dset.bin:

HDF5 "dset.h5" {
DATASET "/dset" {
   DATATYPE  H5T_STD_I32BE
   DATASPACE  SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
   DATA {
   }
}
}

If you look at the resulting dset.bin file with a binary editor, you will see that it contains the dataset's values. For example (on Linux) you will see:

$ od -t d dset.bin
0000000           1           2           3           4
0000020           5           6           7           8
0000040           9          10          11          12
0000060          13          14          15          16
0000100          17          18          19          20
0000120          21          22          23          24
0000140


Export from h5dump and Import into HDF5

The h5import utility can use the output of h5dump as input to create a dataset or file.

The h5dump utility must first create two files:

The DDL file must be generated with the h5dump -p option, to generate properties.

The raw data file that can be imported into HDF5 using this method may contain either numeric or string data with the following restrictions:

Two examples follow: the first imports a dataset with a numeric datatype. Note that numeric data requires the use of the h5dump -b option to produce a binary data file. The example program (h5_crtdat.c) that creates this file is included with the HDF5 Introductory tutorial and can be obtained from the HDF5 Introductory Examples page:

The output before and after running these commands is shown below:

$  h5dump dset.h5
HDF5 "dset.h5" {
GROUP "/" {
   DATASET "dset" {
      DATATYPE  H5T_STD_I32BE
      DATASPACE  SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
      DATA {
      (0,0): 1, 2, 3, 4, 5, 6,
      (1,0): 7, 8, 9, 10, 11, 12,
      (2,0): 13, 14, 15, 16, 17, 18,
      (3,0): 19, 20, 21, 22, 23, 24
      }
   }
}
}
$ h5dump -p -d "/dset" --ddl=dsetbin.dmp -o dset.bin -b dset.h5

$ h5import dset.bin -c dsetbin.dmp -o new-dset.h5

$ h5dump new-dset.h5
HDF5 "new-dset.h5" {
GROUP "/" {
   DATASET "dset" {
      DATATYPE  H5T_STD_I32BE
      DATASPACE  SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
      DATA {
      (0,0): 1, 2, 3, 4, 5, 6,
      (1,0): 7, 8, 9, 10, 11, 12,
      (2,0): 13, 14, 15, 16, 17, 18,
      (3,0): 19, 20, 21, 22, 23, 24
      }
   }
}
}

The second example imports string data. The example program that creates this file can be downloaded from the C Examples by API page.

Note that string data requires use of the h5dump -y option to exclude indexes and the h5dump --width=1 option to generate a single column of strings. The -o option outputs the data into an ASCII file.

The output before and after running these commands is shown below:

$ h5dump h5ex_t_vlstring.h5
HDF5 "h5ex_t_vlstring.h5" {
GROUP "/" {
   DATASET "DS1" {
      DATATYPE  H5T_STRING {
         STRSIZE H5T_VARIABLE;
         STRPAD H5T_STR_SPACEPAD;
         CSET H5T_CSET_ASCII;
         CTYPE H5T_C_S1;
      }
      DATASPACE  SIMPLE { ( 4 ) / ( 4 ) }
      DATA {
      (0): "Parting", "is such", "sweet", "sorrow."
      }
   }
}
}

$ h5dump -p -d "/DS1" -O vlstring.dmp -o vlstring.ascii -y --width=1 h5ex_t_vlstring.h5

$ h5import vlstring.ascii -c vlstring.dmp -o new-vlstring.h5

$ h5dump new-vlstring.h5
HDF5 "new-vlstring.h5" {
GROUP "/" {
   DATASET "DS1" {
      DATATYPE  H5T_STRING {
         STRSIZE H5T_VARIABLE;
         STRPAD H5T_STR_NULLTERM;
         CSET H5T_CSET_ASCII;
         CTYPE H5T_C_S1;
      }
      DATASPACE  SIMPLE { ( 4 ) / ( 4 ) }
      DATA {
      (0): "Parting", "is such", "sweet", "sorrow."
      }
   }
}
}


- - Last modified: 21 December 2016