HDF5文件

掌握HDF5文件：先理解核心结构（打基础），再学C#读写库（搭环境），最后实战读写操作（练手）。

全程结合代码示例，确保新手能跟上。

阶段1：先搞懂HDF5文件的核心结构（必须先理解！）

HDF5（Hierarchical Data Format 5）是一种分层结构的二进制文件格式，专门用于存储和管理大规模、复杂的科学数据。可以把它想象成“计算机里的文件柜”，结构逻辑和我们日常整理文件的方式高度一致。

1.1 核心概念：3个“抽屉”和“文件”

HDF5的结构由3个核心对象组成，用“文件柜”类比理解：

HDF5对象	类比（文件柜）	核心作用	举例（数据采集场景）
File（文件）	整个文件柜	最顶层容器，所有数据都放在一个.h5文件里，是读写操作的入口。	sensor_data.h5（存储所有传感器的采集数据）
Group（组）	文件柜里的“文件夹”	用于分类管理数据，支持嵌套（像文件夹里套文件夹），实现数据的分层组织。	/Device1/Channel1（设备1的1号通道数据文件夹）
Dataset（数据集）	文件夹里的“表格/文件”	真正存储数据的地方，类似数组（支持1维、2维、N维），还包含数据的元信息。	temperature（存储温度数据的1维数组）

HDF5 的结构是一个严格的树状层次结构，其中只有 Group 节点可以分支，而 Dataset 节点永远是叶子节点。

HDF5文件根节点下面可以直接的Group或Dataset；
Group可以嵌套group；
Dataset（数据集） 是 数据对象。它的作用是存储一个多维数组及其相关的元数据（如数据类型、维度信息）。它是数据的最终载体，不能包含任何其他 HDF5 对象（不能包含其他 Dataset，也不能包含 Group）；

1.2 关键补充：Metadata（元数据）

数据集（Dataset）不仅存数据，还绑定“元数据”——描述数据的附加信息，比如：

• 数据类型（int32、float64）
• 数据维度（1000个点→1维，100×200像素→2维）
• 单位（温度：℃，时间：ms）
• 采集时间（2024-05-01 10:00:00）

元数据是HDF5的灵魂，能让数据“自描述”，别人拿到文件也能看懂数据含义。

在 HDF5 中，根节点、Group（组）、Dataset（数据集）都可以拥有自己的元数据（Metadata），这是 HDF5 格式灵活性的重要体现。

元数据以 “属性（Attribute）” 的形式存在，可以为任何 HDF5 对象（包括根节点、Group、Dataset）添加描述性信息。

Attribute = 贴在抽屉、文件夹或文件上的便利贴（元数据）。便利贴很小，但提供了至关重要的上下文信息。

1、元数据的本质是 “属性（Attribute）”

HDF5 中没有单独的 “元数据对象”，元数据通过 “属性” 绑定到其他对象上，属性本身也是一种 HDF5 对象（有自己的 ID，需要手动关闭）。

2、添加元数据的通用流程

无论给哪种对象添加元数据，步骤都相同：
创建属性数据空间（H5S）→ 创建属性（H5A.create）→ 写入属性值（H5A.write）→ 关闭属性（H5A.close）

3、元数据的类型

元数据支持所有 HDF5 基础类型（整数、浮点数、布尔等），也支持复合类型（如结构体）。

4、根节点的特殊性

根节点没有单独的 “创建” 方法（文件创建时自动生成），其 ID 就是文件的 ID（fileId），因此给根节点添加属性时，objectId参数直接传fileId即可。

阶段2：C#操作HDF5的“工具”——选择合适的库

C#本身不自带HDF5读写API，需要借助第三方库。新手优先推荐HDF.PInvoke（底层封装，灵活）或MathNet.Numerics（结合科学计算，简化API），这里我们用最通用的HDF.PInvoke（支持.NET Framework/.NET Core/.NET 5+）。

2.1 环境搭建（3步搞定）

1. 安装NuGet包：
   在Visual Studio的“解决方案资源管理器”中，右键项目→“管理NuGet程序包”，搜索并安装 HDF.PInvoke（选择最新稳定版）。

2. 引用命名空间：
   所有操作都需要这2个命名空间：

   using System;
   using HDF.PInvoke; // 核心API都在这里
   

3. 核心原则：
   HDF5的API是C风格的非托管代码，必须严格遵守“打开→操作→关闭”的流程（类似文件流），否则会导致内存泄漏或文件损坏！

阶段3：实战！C#读写HDF5文件（从简单到复杂）

我们以“存储传感器数据”为例，先写后读，覆盖90%的基础场景。

3.1 基础：写HDF5文件（创建Group+Dataset+元数据）

需求：创建sensor_data.h5，在/Device1/Channel1组下，存储1000个温度数据（float类型），并添加“单位”“采集时间”元数据。

完整代码（含注释）

using System;
using HDF.PInvoke;namespace HDF5Demo
{class Program{static void Main(string[] args){// 1. 定义文件路径和数据string hdf5Path = "sensor_data.h5";string groupPath = "/Device1/Channel1"; // 组路径（支持嵌套）string datasetName = "temperature";     // 数据集名称int dataCount = 1000;                   // 数据长度float[] temperatureData = new float[dataCount];// 生成模拟温度数据（0~50℃）Random rand = new Random();for (int i = 0; i < dataCount; i++){temperatureData[i] = (float)rand.NextDouble() * 50;}// 2. 打开/创建HDF5文件（核心：H5F.create）// 参数说明：路径、创建模式（TRUNC=覆盖已有文件）、默认属性、默认访问权限int fileId = H5F.create(hdf5Path, H5F.ACC_TRUNC, H5P.DEFAULT, H5P.DEFAULT);if (fileId < 0) // HDF5 API用负数表示错误{Console.WriteLine("创建文件失败！");return;}try{// 3. 创建Group（类似创建文件夹，H5G.create）int groupId = H5G.create(fileId, groupPath, H5P.DEFAULT, H5P.DEFAULT, H5P.DEFAULT);if (groupId < 0){Console.WriteLine("创建组失败！");return;}// 4. 定义Dataset的维度（H5S：数据空间）long[] dims = { dataCount }; // 1维数据，长度1000int spaceId = H5S.create_simple(1, dims, null); // 1=维度数，dims=各维度长度if (spaceId < 0){Console.WriteLine("创建数据空间失败！");return;}// 5. 创建Dataset（H5D.create）// 参数：组ID、数据集名称、数据类型（H5T.IEEE_F32LE=32位小端float）、数据空间ID、默认属性int datasetId = H5D.create(groupId, datasetName, H5T.IEEE_F32LE, spaceId, H5P.DEFAULT, H5P.DEFAULT, H5P.DEFAULT);if (datasetId < 0){Console.WriteLine("创建数据集失败！");return;}// 6. 向Dataset写入数据（H5D.write）// 参数：数据集ID、数据类型、内存空间（默认）、文件数据空间（默认）、传输属性（默认）、数据数组int writeStatus = H5D.write(datasetId, H5T.IEEE_F32LE, H5S.ALL, H5S.ALL, H5P.DEFAULT, temperatureData);if (writeStatus < 0){Console.WriteLine("写入数据失败！");return;}// 7. 给Dataset添加元数据（属性，H5A）// 7.1 添加“单位”属性（字符串类型）string unit = "℃";int unitAttrId = H5A.create(datasetId, "Unit", H5T.C_S1, H5S.create(H5S.class_t.SCALAR), H5P.DEFAULT, H5P.DEFAULT);H5A.write(unitAttrId, H5T.C_S1, unit);H5A.close(unitAttrId); // 写完属性立即关闭// 7.2 添加“采集时间”属性（字符串类型）string collectTime = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss");int timeAttrId = H5A.create(datasetId, "CollectTime", H5T.C_S1, H5S.create(H5S.class_t.SCALAR), H5P.DEFAULT, H5P.DEFAULT);H5A.write(timeAttrId, H5T.C_S1, collectTime);H5A.close(timeAttrId);Console.WriteLine("HDF5文件写入成功！");// 8. 关闭资源（顺序：先关子对象，再关父对象）H5D.close(datasetId);H5S.close(spaceId);H5G.close(groupId);}finally{// 最终必须关闭文件（即使中间出错）H5F.close(fileId);}}}
}

关键知识点拆解

• 文件创建模式：H5F.ACC_TRUNC（覆盖已有文件）、H5F.ACC_EXCL（若文件存在则报错）、H5F.ACC_RDWR（读写打开已有文件）。
• 数据类型对应：C#的float→H5T.IEEE_F32LE（32位小端浮点数），double→H5T.IEEE_F64LE，int→H5T.STD_I32LE。
• 资源关闭顺序：Dataset → DataSpace → Group → File（类似先关文件，再关文件夹，最后关文件柜）。

3.2 基础：读HDF5文件（读取Group+Dataset+元数据）

需求：读取上一步创建的sensor_data.h5，获取/Device1/Channel1/temperature的数据集数据和元数据。

完整代码（含注释）

using System;
using HDF.PInvoke;namespace HDF5Demo
{class Program{static void Main(string[] args){// 1. 定义文件路径和目标路径string hdf5Path = "sensor_data.h5";string datasetPath = "/Device1/Channel1/temperature"; // 数据集完整路径（组+数据集）// 2. 打开HDF5文件（只读模式：H5F.ACC_RDONLY）int fileId = H5F.open(hdf5Path, H5F.ACC_RDONLY, H5P.DEFAULT);if (fileId < 0){Console.WriteLine("打开文件失败！");return;}try{// 3. 打开Dataset（H5D.open）int datasetId = H5D.open(fileId, datasetPath, H5P.DEFAULT);if (datasetId < 0){Console.WriteLine("打开数据集失败！");return;}// 4. 获取Dataset的维度（确定数据长度）int spaceId = H5D.get_space(datasetId); // 获取数据空间int rank = H5S.get_simple_extent_ndims(spaceId); // 维度数（这里是1）long[] dims = new long[rank];H5S.get_simple_extent_dims(spaceId, dims, null); // 获取各维度长度int dataCount = (int)dims[0]; // 数据总长度// 5. 读取Dataset数据（H5D.read）float[] readData = new float[dataCount];int readStatus = H5D.read(datasetId, H5T.IEEE_F32LE, H5S.ALL, H5S.ALL, H5P.DEFAULT, readData);if (readStatus < 0){Console.WriteLine("读取数据失败！");return;}// 6. 读取Dataset的元数据（属性）// 6.1 读取“Unit”属性string unit = string.Empty;if (H5A.exists(datasetId, "Unit") > 0) // 先判断属性是否存在{int unitAttrId = H5A.open(datasetId, "Unit");unit = H5A.read<string>(unitAttrId); // 泛型读取，简化字符串处理H5A.close(unitAttrId);}// 6.2 读取“CollectTime”属性string collectTime = string.Empty;if (H5A.exists(datasetId, "CollectTime") > 0){int timeAttrId = H5A.open(datasetId, "CollectTime");collectTime = H5A.read<string>(timeAttrId);H5A.close(timeAttrId);}// 7. 打印读取结果（只打印前10个数据，避免输出过长）Console.WriteLine("=== HDF5文件读取结果 ===");Console.WriteLine($"采集时间：{collectTime}");Console.WriteLine($"数据单位：{unit}");Console.WriteLine($"数据长度：{dataCount}");Console.Write("前10个数据：");for (int i = 0; i < 10; i++){Console.Write($"{readData[i]:F2} ");}Console.WriteLine();// 8. 关闭资源H5D.close(datasetId);H5S.close(spaceId);}finally{H5F.close(fileId);}}}
}

运行结果示例

=== HDF5文件读取结果 ===
采集时间：2024-05-20 15:30:00
数据单位：℃
数据长度：1000
前10个数据：12.34 25.67 8.91 45.23 33.45 19.87 7.65 39.01 22.33 48.76 

3.3 进阶：读写2维数据（比如图像、矩阵）

如果要存储200×300的图像像素数据（2维数组），只需修改“数据空间”的维度定义：

写2维数据（核心代码片段）

// 2维数据：200行（高度）×300列（宽度）
int rows = 200;
int cols = 300;
float[,] imageData = new float[rows, cols]; // 2维数组// 定义2维数据空间
long[] dims = { rows, cols }; // 第1维=行，第2维=列
int spaceId = H5S.create_simple(2, dims, null); // 维度数改为2// 写入2维数据（直接传2维数组即可）
H5D.write(datasetId, H5T.IEEE_F32LE, H5S.ALL, H5S.ALL, H5P.DEFAULT, imageData);

读2维数据（核心代码片段）

// 获取2维维度
long[] dims = new long[2];
H5S.get_simple_extent_dims(spaceId, dims, null);
int rows = (int)dims[0];
int cols = (int)dims[1];// 读取2维数据
float[,] readImage = new float[rows, cols];
H5D.read(datasetId, H5T.IEEE_F32LE, H5S.ALL, H5S.ALL, H5P.DEFAULT, readImage);

阶段4：新手避坑指南（必看！）

1. 资源泄露：忘记关闭fileId/datasetId等，会导致文件被占用（删除不了），必须用try-finally确保关闭。
2. 数据类型不匹配：C#的int是32位，若写成H5T.STD_I64LE（64位），会读写出错，务必对应（参考下表）。
3. 路径错误：Group/Dataset路径必须以/开头（如/Device1，不能写Device1）。

C#与HDF5数据类型对应表

C#类型	HDF5类型常量	说明
byte	H5T.STD_U8LE	8位无符号整数
short	H5T.STD_I16LE	16位有符号整数
int	H5T.STD_I32LE	32位有符号整数
long	H5T.STD_I64LE	64位有符号整数
float	H5T.IEEE_F32LE	32位浮点数
double	H5T.IEEE_F64LE	64位浮点数
string	H5T.C_S1	C风格字符串（null结尾）

阶段5：扩展学习（进阶方向）

1. 更友好的库：如果觉得HDF.PInvoke太底层，可以试试 HDF5DotNet（封装更面向对象）或 MathNet.Numerics.Data.Hdf5（结合科学计算库）。