HDF数据使用指南.pdf

1、 国家卫星气象中心（NSMC） H D F 5.0 使用简介 HDF5.0 使用简介 国家卫星气象中心（NSMC） H D F 5.0 使用简介 目 录 1、介绍（Introduction）.1 2、HDF5 文件组织（File Organization）1 3、HDF5 应用程序接口（API）2 4、创建 HDF5 文件（Creating an HDF5 File）.3 4.1 什么是 HDF5 文件?.3 4.2 程序例子（Programming Example）4 4.2.1 描述（Description）4 4.2.2 备注（Remarks）5 4.2.3 文件内容（File Cont

2、ents）6 4.2.4 DDL 中的文件定义（File Definition in DDL） 7 5、创建数据集（Creating a Dataset）.7 5.1 什么是数据集（What is a Dataset）7 5.2 数据类型（Datatypes）7 5.3 数据集和数据空间（Datasets and Dataspaces） 9 5.4 数据集创建特性列表（Dataset Creation Property Lists） 9 5.2 程序例子（Programming Example）10 5.2.1 描述（Description）10 5.2.2 备注（Remarks）11 5.2

3、.3 文件内容（File Contents）12 5.2.4 DDL 中的数据集定义（Dataset Definition in DDL） 13 6、创建一个群组（Creating a Group）.14 6.1 什么是群组（What is a Group）?14 6.2 程序例子（Programming Example）15 6.2.1 描述（Description）15 6.2.2 备注（Remarks）15 6.2.3 文件内容（File Contents）16 7、创建属性（Creating an Attribute）.17 国家卫星气象中心（NSMC） H D F 5.0 使用简介

4、7.1 什么是属性（Attribute）?17 7.1.1 创建一个属性（Creating an attribute）17 7.1.2 读/写属性（Reading/Writing an attribute） 18 7.2 编程例子（Programming Example）18 7.2.1 描述（Description）18 7.2.2 备注（Remarks）19 7.2.3 文件内容（File Contents）21 7.2.4 DDL 中的属性定义（Attribute Definition in DDL） 22 8、读出和写入数据集（Reading from and Writing to a

5、 Dataset） .22 8.1 读出和写入数据集（Reading from and Writing to a Dataset） 22 8.2 编程例子（Programming Example）23 8.2.1 描述（Description）23 8.2.2 备注（Remarks）24 8.2.3 文件内容（File Contents）27 9、复合数据类型（Compound Datatypes）.28 9.1 创建复合数据类型（Creating Compound Datatypes） 28 9.2 程序例子（Programming Example）29 9.2.1 描述（Descripti

6、on）29 9.2.2 备注（Remarks）29 9.2.3 文件内容（File Contents）30 国家卫星气象中心（NSMC） H D F 5.0 使用简介 说明: 本教材不包含编译例程所需的软件。 Introductory Topics Advanced Topics Parallel HDF5 High Level APIs Introduction Property Lists Design Overview HDF5 File Organization Compound Datatypes Parallel Programming The HDF5 API Hyperslab

7、 Selection Create/Access File Create an HDF5 File Point Selection Create/Access Dataset Other Create Dataset References to Objects Write/Read Hyperslabs Tutorial Examples Dataset Read/Write References to Regions - by Contiguous Hyperslab Utilities: h5ls/h5dump Create Attribute Extendible Datasets -

8、by Regularly Spaced Data References Create Group Mounting Files - by Pattern Create Group - Abs/Rel Group Iteration - by Chunk Create Dataset in Group Questions Answers 国家卫星气象中心（NSMC） H D F 5.0 使用简介 - 1 - 1、介绍（INTRODUCTION） 欢迎使用由 HDF 用户支持组提供的 HDF5 使用教材 HDF5 是用于存储科学数据的一种文件格式和库文件。它被设计并实现满足科学数据存 储不断增加和

9、数据处理不断变化的需求，为了充分利用当今计算机系统的能力和特点，克服 HDF4.x 的不足。HDF5 有一个强大和灵活的数据模块，支持管理的文件大于 2 GB（HDF4.x 管理文件的极限），并且还支持并行 I/O。设计时考虑了安全线程并将在不久的将来实现此 功能。为了便于简单了解 HDF5 的数据模式、库函数和工具，请参看存放于 URL 地址 （http:/hdf.ncsa.uiuc.edu/HDF5/papers/HDF5_overview/index.htm）里的幻灯片。 本使用教材涵盖了基本的 HDF5 数据对象和文件结构，HDF5 程序模块、创建和修改数 据对象的 API 功能。还将

10、介绍用于存取 HDF5 文件的一些有用的工具。 本教材使用的程序例子以及编译它们的 Makefile 在 ./examples/子目录里。为了使用 Makefile 文件,用户也许不得不编辑和更新编译器和编译器选项，以及发布的 HDF5的目录 路径。Java程序例子在./examples/ 目录下的名为 java/子目录里。Java/目录有一个 Makefile 文件和运行 java 程序的脚本文件（shell scripts）。 对于其它 HDF5 程序的程序例子，请参看 References 里的指示标记。 希望这个程序例子和用法说明入门能帮助用户很方便地使用 HDF5。 任何意见和建议直

11、接发给：hdfhelpncsa.uiuc.edu. 2、HDF5文件组织（FILE ORGANIZATION） 一个 HDF5 文件就是一个由两种基本数据对象（groups and datasets）存放多种科学数 据的容器： HDF5 group: 包含 0 个或多个 HDF5 对象以及支持元数据（metadata）的一个群组结 构。 HDF5 dataset: 数据元素的一个多维数组以及支持元数据（metadata） 任何 HDF5 的群组或数据集或许都有一个对应的属性列表。HDF5 属性是一个用户自定义的 HDF5 结构，能为 HDF5 对象提供附加信息。 国家卫星气象中心（NSMC）

12、H D F 5.0 使用简介 - 2 - 使用群组和数据集时在许多方面类似于使用 UNIX 的目录和文件。HDF5 文件里的对象经常通 过它的绝对路径来引用。 / signifies the root group. /foo signifies a member of the root group called foo. /foo/zoo signifies a member of the group foo, which in turn is a member of the root group. 3、HDF5应用程序接口（API） HDF5 函数库提供几个应用程序接口（API）。这些 AP

13、I 提供用于创建、存取、处理 HDF5 文件和对象的例程。 库函数本身是由 C 程序实现的。为了便于 FORTRAN90和 Java程序员的工作，HDF5 包装 的外壳函数也已经用这些语言开发出来了。到写此用户教材时，用 C+包装的外壳函数正在 开发中。本教材只涉及 C 和FORTRAN的外壳包装函数。 HDF5 库中所有 C 的例程都有一个前缀形式 H5*开始，这里的*是一个或两个大写字母， 表明有关函数操作对象的类型。 而 FORTRAN 外壳包装是以子程序由 h5 开始和_f 结束的。 API 列表如下： API 描述 H5 库函数：H5 函数的通用目的 H5A 注解(Annotatio

14、n)接口：属性存取(access)和操作例程 H5D 数据集接口：数据集存取和操作接口 H5E 错误接口：错误处理例程 H5F 文件接口：文件存取例程 H5G 群组接口：群组创建和运行例程 H5I 标识号接口：标识号例程 H5P 特性（Property）列表接口：对象特性列表操作例程 H5R 引用接口：引用例程 H5S 数据大小接口：数据大小定义和存取例程 H5T 数据类型接口：数据类型创建和操作例程 H5Z 压缩接口：压缩例程 国家卫星气象中心（NSMC） H D F 5.0 使用简介 - 3 - 4、创建HDF5文件（CREATING AN HDF5 FILE） 4.1 什么是 HDF5

15、文件? HDF5 是一个含有科学数据和支持元数据的二进制文件。 HDF5文件存储对象的基本类型， 即群组和数据集，将在本教材的其它章节讨论。 要创建一个文件，应用程序必须指定一个文件名、文件存取模式、文件创建特性列表、 和文件存取特性列表。 文件存取模式（File access mode） ：: 当创建一个文件时，假如此文件已经存在，文件存取模式就会指定要发生的动作： o H5F_ACC_TRUNC 说明如果此文件已经存在， 当前的内容将被删除以便应用程 序可以用新数据重新写此文件。 o H5F_ACC_EXCL 说明如果此文件存在，打开则会失败。 o 如果此文件不存在，则文件的存取参数被忽略

16、。 o 在所有情况下，对于一个成功创建的文件，应用程序都可以对这个文件进行 读写存取。 注意对于打开已经存在的文件有两种不同的存取模式： o H5F_ACC_RDONLY 说明应用程序只有读取而没有写入任何数据的权利。 o H5F_ACC_RDWR 说明应用程序有读写的权利。 更详细的信息请参见HDF 用户指南里的The File Interface (H5F)小节和HDF5 参考手册中的 H5F: File Interface 小节。 文件创建特性列表（File creation property list） ： 文件创建特性列表常被用于控制文件的元数据。文件的元数据包含有关用户块的大 小、

17、HDF5 库使用的不同文件数据结构大小等。此教材中，缺省的文件创建特性列表 是 H5P_DEFAULT。 用户块（user-block）是被 HDF5 库忽略的位于文件开始的固定长度的数据块。用户 块可以用于存放任何数据或对应用有用的信息。 更详细的内容请参见HDF 用户指南中的 The File Interface (H5F) 小节。 文件存取特性列表（File access property list） ： 国家卫星气象中心（NSMC） H D F 5.0 使用简介 - 4 - 文件存取特性列表通常被用来控制对文件 I/O 表现采取不同的方法。本教材使用的 缺省文件存取特性列表是 H5P_

18、DEFAULT。 详情见HDF用户指南中的 The File Interface (H5F) 小节。 创建和关闭一个 HDF5 文件的步骤如下： 1. 如果需要，指定文件创建和存取特性列表。 2. 创建文件。 3. 如需要，关闭文件和关闭特性列表 要创建一个 HDF5 文件，调用程序必须包含调用创建和关闭文件。如下例： C: file_id = H5Fcreate (filename, access_mode, create_id, access_id); status = H5Fclose (file_id); FORTRAN: CALL h5fcreate_f (filename, acc

19、ess_mode, file_id, hdferr, status = H5Sclose (space_id ); FORTRAN: CALL h5screate_simple_f (rank, dims, space_id, hdferr, maxdims=max_dims) or CALL h5screate_simple_f (rank, dims, space_id, hdferr) CALL h5sclose_f (space_id, hdferr) 要创建一个简单的数据集，调用程序必须调用创建和关闭此数据集。见如下例程： C: dset_id = H5Dcreate (hid_t

20、loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t creation_prp); status = H5Dclose (dset_id); FORTRAN: CALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, & hdferr, creation_prp=creat_plist_id) or CALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, hdferr) CALL h5dclose_

21、f (dset_id, hdferr) 假如在 FORTRAN 中要使用预定义的数据类型， 必须调用对这个预定义的数据类型的初始 化和终止访问： CALL h5open_f (hdferr) CALL h5close_f (hdferr) h5open_f 必须在调用其它 HDF5 子程序库函数之前调用； h5close_f 则必须在调用其它 HDF5 子程序库函数之后调用。参见下面程序例子对这些调用的说明。 5.2 程序例子（Programming Example） 5.2.1 描述（Description） 下面例子表示怎样创建一个空的数据集。 它用 C创建了一个名为的 dset.h5 （

22、用FORTRAN 则为 dsetf.h5)，定义了数据集的数据空间，创建了一个 4 x 6 整型数组的数据集，然后关 闭数据空间、数据集和文件。 国家卫星气象中心（NSMC） H D F 5.0 使用简介 - 11 - C Example - h5_crtdat.c Fortran Example - dsetexample.f90 NOTE: To download a tar file of the examples, including a Makefile, please go to the References page of this tutorial. 5.2.2 备注（Rema

23、rks） H5Screate_simple/h5screate_simple_f 创建一个新的简单数据空间并返回一个数 据空间标识号。 C: hid_t H5Screate_simple (int rank, const hsize_t * dims, const hsize_t * maxdims) FORTRAN: h5screate_simple_f (rank, dims, space_id, hdferr, maxdims) rank INTEGER dims(*) INTEGER(HSIZE_T) space_id INTEGER(HID_T) hdferr INTEGER (Va

24、lid values: 0 on success and -1 on failure) maxdims(*) INTEGER(HSIZE_T), OPTIONAL o rank 参数指定秩（rank） ，即数据集维数的个数。 o dims 参数指定数据集的大小。 o The maxdims 参数指定数据集大小的上限。如果在 C 里此参数为 NULL（或 在 FORTRAN没有被指定） ，上限与由 dim 参数指定的维数大小相同。 o 假如成功，在 C 中此函数返回数据空间标识号；否则返回一个负数。对于 FORTRAN，数据空间标识号（dataspace identifier）由 space_i

25、d 参数返回。 如果调用成功则在hdferr 中返回0，否则返回-1。 H5Dcreate/h5dcreate_f 在指定位置创建一个数据集并返回数据集标识号 （dataset identifier） 。 C: hid_t H5Dcreate (hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t creation_prp) FORTRAN: h5dcreate_f (loc_id, name, type_id, space_id, dset_id, & hdferr, creation_prp) loc_id

26、 INTEGER(HID_T) name CHARACTER(LEN=*) 国家卫星气象中心（NSMC） H D F 5.0 使用简介 - 12 - type_id INTEGER(HID_T) space_id INTEGER(HID_T) dset_id INTEGER(HID_T) hdferr INTEGER (Valid values: 0 on success and -1 on failure) creation_prp INTEGER(HID_T), OPTIONAL o loc_id 参数是位置标识号（location identifier） 。 o name 参数是要创建的

27、数据集名。 o type_id 参数指定的数据类型标识号（datatype identifier） 。 o space_id 参数是数据空间标识号（dataspace identifier） 。 o creation_prp 参数指定数据集创建属性列表。H5P_DEFAULT（C）和 H5P_DEFAULT_F （FORTRAN）指定缺省的数据集创建属性列表。在 FORTRAN 这个参数是可选项； 如果省略了， 那么缺省的数据集创建属性列表 （default dataset creation property list）就被使用。 o 如果成功，C函数返回数据集标识号（dataset iden

28、tifier）否则返回一个 负数。FORTRAN 在 dset_id 中调用返回的数据集标识号。如成功在 hdferr 返回0，否则返回-1。 H5Dcreate/h5dcreate_f 创建一个空的数组并把数据初始化为 0。 当数据集不再被程序存取，When a dataset is no longer accessed by a program, H5Dclose/h5dclose_f 必须被调用来释放由此数据集占用的资源。这种调用是强制 性的。 C: hid_t H5Dclose (hid_t dset_id) FORTRAN: h5dclose_f (dset_id, hdferr) dset_id INTEGER(HID_T) hdferr INTEGER (Valid values: 0 on success and -1 on failure) 5.2.3 文件内容（File Contents） 文件 dset.h5 的内容(dsetf.h5 for FORTRAN) 如图 a 5.4 and 图5.5a and 5.5b. Figure 5.4 Contents of dset.h5 ( dsetf.h5)