Page tree

The license could not be verified: License Certificate has expired!

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

Hdf button
Target/display/HDF5/Introduction+to+HDF5+--+PDF
LinkTextDownload PDF

...

There are two groups in the HDF5 file depicted above: Vis and Viz and SimOut. Under the Viz group are a variety of images and a table that is shared with the SimOut group. The SimOut group contains a 3-dimensional array, a 2-dimensional array and a link to a 2-dimensional array in another HDF5 file.

...

Attributes can optionally be associated with HDF5 objects. They have two parts: a name and a value. Attributes are accessed by opening the object that they are attached to so are not independent objects. Typically an attribute is small in size and contains user metadata about the object that it is attached to.

...

To introduce the programming model, examples in Python and C are included below. The Python examples use the HDF5 Python APIs (h5py) are included for their simplicity of use. However, they were not created and are not maintained by The HDF Group. See the Examples from "Learning the Basics" page for complete examples that can be downloaded and run for C, FORTRAN, C++, Java and Python.

The general paradigm for working with objects in HDF5 is to:

  • Open the object.
  • Access the object.
  • Close the object.

The library imposes an order on the operations by argument dependencies. For example, a file must be opened before a dataset because the dataset open call requires a file handle as an argument. Objects can be closed in any order. However, once an object is closed it no longer can be accessed.

...

FORTRAN:       Add “USE HDF5" and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN  interface

 

Steps to create a file:

To create an HDF5 file you must:

  1. Specify property lists (or use the defaults).
  2. Create the file.
  3. Close the file (and property lists if needed).

Example:

This example creates The following Python and C examples create a file, file.h5, and then closes itclose it. The resulting HDF5 file will only contain a root group:

 

...

Image Added

 

Python:

Calling h5py.File with ‘w’ for the file access flag will create a new HDF5 file and overwrite an existing file with the same name.  “file” is the file handle returned from opening the file.  When finished with the file, it must be closed. When not specifying property lists, the default property lists are used:

import h5py

file = h5py.File (‘file.h5’, ‘w’)

file.close ()

C:

The H5Fcreate function creates an HDF5 file.   H5F_ACC_TRUNC is the file access flag to create a new file and overwrite an existing file with the same name, and H5P_DEFAULT is the value specified to use a default property list.

#include “hdf5.h”

int main() {

    hid_t       file_id;

    herr_t      status;

 

    file_id = H5Fcreate ("file.h5", H5F_ACC_TRUNC,

...

H5P_DEFAULT, H5P_DEFAULT);   

    status = H5Fclose (file_id);

}

Steps to create a dataset:

As described previously, an HDF5 dataset consists of the raw data, as well as the metadata that describes the data (datatype, spatial information, and properties). To create a dataset you must:

  1. Define the dataset characteristics (datatype, dataspace, properties).
  2. Decide which group to attach the dataset to.
  3. Create the dataset.

...

  1. Close the dataset handle from step 3.

Example:

The code excerpts below show the calls that need to be made to create a 4 x 6 integer dataset “dset” dset in a file “dset.h5”:               dset.h5. The dataset will be located in the root group:

            Image Added  

Python:

With Python, the creation of the dataspace is included as a parameter in the dataset creation method.  Just one call will create a 4 x 6 integer dataset “dset” dset. A pre-defined Big Endian 32-bit integer datatype is specified. The create_dataset method creates the dataset in the root group (the file object).  The dataset is close by the Python interface.

 dataset = file.create_dataset("dset",(4, 6), h5py.h5t.STD_I32BE)

 

C:

To create the same dataset in C, you must specify the dataspace with the H5Screate_simple function, create the dataset by calling H5Dcreate, and then close the dataspace and dataset with calls to H5Dclose and H5Sclose. H5P_DEFAULT is specified to use a default property list. Note that the file identifier (file_id) is passed in as the first parameter to H5Dcreate, which creates the dataset in the root group.

   /* Create the dataspace for the dataset. */

   dims[0] = 4;

   dims[1] = 6;

   dataspace_id = H5Screate_simple(2, dims, NULL);

 

   /* Create the dataset. */

   dataset_id = H5Dcreate (file_id, "/dset", H5T_STD_I32BE,

...

dataspace_id, H5P_DEFAULT, H5P_DEFAULT,

...

H5P_DEFAULT);

 

   /* Close the dataset and dataspace */

   status = H5Dclose(dataset_id);

   status = H5Sclose(dataspace_id);

  

Writing to or reading from a dataset:

Once you have created or opened a dataset you can write to it:

Python:  

data = np.zeros((4,6))

...

for i in range(4):

...

  for j in range(6):

...

     data[i][j]= i*6+j+1

...

 dataset[...] = data  

...

        <-- Write data to dataset

...

data_read = dataset[...]

...

  <-- Read data from dataset

C:

H5S_ALL is passed in for the memory and file dataspace parameters to indicate that the entire dataspace of the dataset is specified. These two parameters can be modified to allow subsetting of a dataset. The native predefined datatype, H5T_NATIVE_INT, is used for reading and writing so that HDF5 will do any necessary integer conversions:  

status = H5Dwrite (dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL,

...

H5P_DEFAULT, dset_data);

 

...

status = H5Dread (dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL,

...

  

...

H5P_DEFAULT, dset_data);

 

Steps to create a group:

An HDF5 group is a structure containing zero or more HDF5 objects. Before you can create a group you must obtain the location identifier of where the group is to be created. Following are the steps that are required:

  1. Decide where to put the group – in the “root group” (or file identifier) or in another group. Open the group if it is not already open.
  2. Define properties or use the default.
  3. Create the group.
  4. Close the group.

 

Example:


This example illustrates how to create a group MyGroup that is attached to the root group. If the file identifier is specified for the location of the group it will be created in the root group. 

Image Added

Python:

The code below opens the dataset dset.h5 with read/write permission and creates a group MyGroup in the root group. Properties are not specified so the defaults are used:

import h5py

file = h5py.File('dset.h5', 'r+')  

group = file.create_group ('MyGroup')

file.close()

 

C:

 

To

...

create

...

the

...

group

...

MyGroup

...

in

...

the

...

root

...

group,

...

you

...

must

...

call

...

H5Gcreate,

...

passing

...

in

...

the

...

file

...

identifier

...

returned

...

from

...

opening

...

or

...

creating

...

the

...

file.

...

The

...

default

...

property

...

lists

...

are

...

specified

...

with

...

H5P_DEFAULT.

...

The

...

group

...

is

...

then

...

closed:

...


...

group_id = H5Gcreate (file_id, "MyGroup", H5P_DEFAULT, H5P_DEFAULT,

...

H5P_DEFAULT);

...

status = H5Gclose (group_id);

 

Steps to create and write to an attribute:

To create an attribute you must open the object that you wish to attach the attribute to. Then you can create, access, and close the attribute as needed:

  1. Open the object that you wish to add an attribute to.
  2. Write to Create the attribute.Create
  3. Write to the attribute.
  4. Close the attribute and the object it is attached to.        

The example below creates attributes that are attached to the dataset dset:

Image Added      

Python:

The dataspace, datatype, and data are specified in the call to create an attribute in Python:

...

To create an integer attribute in C, you must create the dataspace, create the attribute, write to it and then close it in separate steps:

hid_t       attribute_id, dataspace_id;  /* identifiers */

hsize_t     dims;

int         attr_data[2];

herr_t      status;

   ...

/* Initialize the attribute data. */

attr_data[0] = 100;

attr_data[1] = 200;

 

/* Create the data space for the attribute. */

...

dataspace_id = H5Screate_simple(1, &dims, NULL);

 

/* Create a dataset attribute. */

attribute_id = H5Acreate2 (dataset_id, "Units", H5T_STD_I32BE,

                           dataspace_id, H5P_DEFAULT, H5P_DEFAULT);

 

/* Write the attribute data. */

status = H5Awrite(attribute_id, H5T_NATIVE_INT, attr_data);

 

/* Close the attribute. */

status = H5Aclose(attribute_id);

 

/* Close the dataspace. */

status = H5Sclose(dataspace_id);