简介这份资源面向在 Windows 64 位环境下从事科学计算、流体力学或工程仿真的 C 开发者提供 CGNS 库的预编译静态版本省去自行编译 CGNS、HDF5、ZLIB 与 SZIP 的繁琐过程。CGNS 作为开放源代码的网格数据存储格式支持三维、多时间步复杂网格数据交换而 HDF5、ZLIB、SZIP 分别承担数据组织、无损压缩与高压缩比存储静态库形式让依赖全部打包部署时无需额外动态链接。压缩包共 6 个文件包含 4 个 lib 静态库与 2 个头文件整体约 2.55MB头文件提供函数声明与数据结构定义可直接在 C 项目中引用。目前已有 921 人学习下载适合希望跳过 CMake 配置与依赖排错、快速集成 CGNS 读写能力的开发者参考使用。1. Windows 下 CGNS 静态库 64 位一个头文件就能跑通的 CFD 数据读写方案如果你在 Windows 上写过 CFD 后处理或者网格转换工具大概率被 CGNS 的编译折腾过。CGNS 本身是 ANSI C 写的跨平台没问题但它的依赖链——HDF5、zlib、szip——在 Windows 上凑齐一套能用的 64 位静态库比在 Linux 上apt install麻烦得多。这个资源就是把这套东西提前编好了CGNS 静态库、libhdf5、libzlib、libszip 全部 64 位头文件也一并打包解压后配好路径就能直接#include使用。适合做气动数据管理、CFD 结果归档、网格格式互转的 C 工程师尤其是那些不想在依赖编译上耗时间、只想把 CGNS 当黑匣子调 API 的人。下面从库的构成、工程配置、API 调用到踩坑排查一步步拆开讲。2. 静态库构成与工程配置从目录结构到链接参数2.1 包里到底有什么四个库的分工拿到压缩包先别急着往工程里塞花两分钟看清楚每个库的角色后面链接出问题才知道该查谁。CGNS 的核心是cgnslib它提供cg_open、cg_close、cg_goto、cg_array_read这些 API负责把网格坐标、流场变量、边界条件按 ADF 或 HDF5 后端组织起来。这个包里用的是 HDF5 后端所以libhdf5是必须的——CGNS 的节点树最终落在 HDF5 的 group/dataset 结构上。libzlib负责 HDF5 内部的 DEFLATE 压缩没有它 HDF5 编译时就会报找不到zlib.h。libszip则是另一种压缩滤波器HDF5 用它做 szip 压缩虽然日常写 CGNS 文件不一定触发但链接时如果 HDF5 编译时启用了 szip缺这个库就会报一堆unresolved external symbol。目录结构常见做法是cgns_static_x64/ ├── include/ │ ├── cgnslib.h │ ├── cgns_io.h │ ├── hdf5.h │ ├── H5*.h │ ├── zlib.h │ ├── zconf.h │ └── szlib.h └── lib/ ├── cgns.lib ├── hdf5.lib ├── zlib.lib └── szip.lib头文件全在include下库文件全在lib下。注意cgnslib.h里会#include cgns_io.h所以这两个必须放在同一目录否则编译期就报找不到头文件。2.2 Visual Studio 工程配置三个必须改的地方在 VS 里新建一个 C 控制台工程平台选 x64。配置分三步缺一不可。第一步头文件路径。右键工程 → 属性 → C/C → 常规 → 附加包含目录把cgns_static_x64\include加进去。这里有个细节如果你同时装了别的 HDF5 版本系统环境变量里有HDF5_DIR之类的VS 可能会优先找到那个版本的头文件导致版本不匹配。稳妥做法是把附加包含目录放在最前面或者干脆把系统里的 HDF5 环境变量临时清掉。第二步库文件路径。链接器 → 常规 → 附加库目录加上cgns_static_x64\lib。第三步附加依赖项。链接器 → 输入 → 附加依赖项按顺序写cgns.lib hdf5.lib zlib.lib szip.lib顺序有讲究。MSVC 的链接器从左到右解析符号cgns.lib引用了 HDF5 的符号所以hdf5.lib必须排在它后面hdf5.lib又引用了 zlib 和 szip 的符号所以这两个排在最后。如果顺序反了会出现LNK2019找不到H5Fopen之类的错误。还有一个容易漏的点CGNS 静态库在 Windows 下编译时如果用了CGNSDLL宏做导出声明静态链接时需要确保没有定义CGNSDLL。检查cgnslib.h里有没有#ifdef CGNSDLL的分支如果有在工程属性 → C/C → 预处理器 → 预处理器定义里确认没有定义CGNSDLL。这个宏是给动态库用的静态库场景下定义了反而会让函数声明变成__declspec(dllimport)链接时报错。2.3 用 CMake 管理比手动配 VS 更省事如果你用 CMake配置更干净。在CMakeLists.txt里这样写cmake_minimum_required(VERSION 3.15) project(cgns_demo CXX) set(CGNS_ROOT ${CMAKE_SOURCE_DIR}/cgns_static_x64) add_executable(cgns_demo main.cpp) target_include_directories(cgns_demo PRIVATE ${CGNS_ROOT}/include ) target_link_directories(cgns_demo PRIVATE ${CGNS_ROOT}/lib ) target_link_libraries(cgns_demo PRIVATE cgns hdf5 zlib szip )target_link_libraries里的顺序同样重要CMake 会按写的顺序传给链接器。另外如果 CMake 在配置阶段报找不到 HDF5可以在命令行加-DHDF5_ROOT${CGNS_ROOT}把查找路径指过来避免它去系统目录里翻。提示静态链接时如果运行时报LNK4098默认库冲突检查工程是不是同时链接了libcmt和msvcrt。静态库通常用/MT编译你的主工程也要用/MT在 C/C → 代码生成 → 运行库里改成多线程 (/MT)。3. CGNS 核心 API 调用打开、读网格、写流场3.1 打开文件与节点定位CGNS 的 API 是 C 风格用cg_open打开文件cg_goto定位到某个节点然后读或写。下面这段代码打开一个 CGNS 文件定位到第一区的网格坐标节点读出顶点数。#include cgnslib.h #include vector #include iostream int main() { int fn; // 文件索引 int base, zone; // base 和 zone 索引 int coord; // 坐标数组索引 char basename[33], zonename[33]; cgsize_t size[3]; // 存储顶点数 // 以只读方式打开 CGNS 文件 if (cg_open(demo.cgns, CG_MODE_READ, fn) ! CG_OK) { std::cerr cg_open failed: cg_get_error() std::endl; return 1; } // 定位到第一个 base 的第一个 zone if (cg_goto(fn, 1, Zone_t, 1, end) ! CG_OK) { std::cerr cg_goto failed: cg_get_error() std::endl; cg_close(fn); return 1; } // 读取 CoordinateX 数组的大小 if (cg_array_size(fn, 1, CoordinateX, coord, size) ! CG_OK) { std::cerr cg_array_size failed: cg_get_error() std::endl; cg_close(fn); return 1; } std::cout Vertex count: size[0] std::endl; cg_close(fn); return 0; }cg_open的第三个参数是文件索引后续所有操作都用它。cg_goto的路径参数是成对的Zone_t, 1表示第一个 zone最后的end表示停在当前节点。cg_array_size返回数组的维度对于CoordinateX这种一维数组size[0]就是顶点数。3.2 读取坐标与流场变量定位到节点后用cg_array_read把数据读进std::vector。注意 CGNS 的坐标数组是cgsize_t类型在 64 位下通常是long long别用int接否则大网格会溢出。std::vectordouble x(size[0]); std::vectordouble y(size[0]); std::vectordouble z(size[0]); // 读取 X 坐标 if (cg_array_read(fn, 1, CoordinateX, x.data()) ! CG_OK) { std::cerr read CoordinateX failed: cg_get_error() std::endl; cg_close(fn); return 1; } // 读取 Y 坐标 if (cg_array_read(fn, 2, CoordinateY, y.data()) ! CG_OK) { std::cerr read CoordinateY failed: cg_get_error() std::endl; cg_close(fn); return 1; } // 读取 Z 坐标 if (cg_array_read(fn, 3, CoordinateZ, z.data()) ! CG_OK) { std::cerr read CoordinateZ failed: cg_get_error() std::endl; cg_close(fn); return 1; }cg_array_read的第二个参数是数组索引这个索引是在cg_goto定位的节点下按顺序排的。如果你不确定索引可以用cg_narrays先查数量再循环cg_array_info拿名字。流场变量的读法一样只是节点路径不同通常要先cg_goto到FlowSolution_t, 1再读Density、Pressure这些数组。3.3 写入 CGNS 文件从建 base 到写数组写文件比读多几步建 base、建 zone、写坐标、写解。下面是一个最小写入示例。int fn; int base, zone, coord; cgsize_t size[3] { 100, 1, 1 }; // 100 个顶点 double x[100], y[100], z[100]; // 初始化数组 for (int i 0; i 100; i) { x[i] i * 0.1; y[i] 0.0; z[i] 0.0; } // 创建新文件 if (cg_open(output.cgns, CG_MODE_WRITE, fn) ! CG_OK) { std::cerr cg_get_error() std::endl; return 1; } // 建 base if (cg_base_write(fn, Base, 3, 3, base) ! CG_OK) { std::cerr cg_get_error() std::endl; cg_close(fn); return 1; } // 建 zone类型是 Structured if (cg_zone_write(fn, base, Zone, size, CGNS_ENUMV(Structured), zone) ! CG_OK) { std::cerr cg_get_error() std::endl; cg_close(fn); return 1; } // 写坐标 if (cg_coord_write(fn, base, zone, CGNS_ENUMV(RealDouble), CoordinateX, x, coord) ! CG_OK) { std::cerr cg_get_error() std::endl; cg_close(fn); return 1; } // 同理写 CoordinateY 和 CoordinateZ cg_close(fn);cg_base_write的第三个参数是物理维度第四个是拓扑维度对三维网格都填 3。cg_zone_write的size数组对结构网格是顶点数对非结构网格是顶点数和单元数。CGNS_ENUMV(Structured)是枚举宏CGNS 3.x 之后用CGNS_ENUMV包一层直接写Structured在 C 里可能编译不过。注意写文件时如果目标文件已存在CG_MODE_WRITE会直接覆盖不会提示。调试阶段建议用CG_MODE_MODIFY或者先检查文件是否存在。4. 避坑与排查链接报错、版本冲突、运行时崩溃4.1 LNK2019 找不到 H5Fopen链接顺序或运行库不匹配现象编译通过链接时报unresolved external symbol H5Fopen referenced in function cg_open。原因有两种。一是附加依赖项里hdf5.lib排在cgns.lib前面链接器先解析 HDF5 的符号发现没人引用就跳过了等解析到cgns.lib时已经不再回头找。二是运行库不匹配cgns.lib是用/MT编的主工程用/MD符号修饰不一样链接器认不出来。解决把cgns.lib放在附加依赖项第一行hdf5.lib第二行。然后检查工程属性 → C/C → 代码生成 → 运行库改成多线程 (/MT)。如果还报错用dumpbin /symbols cgns.lib | findstr H5Fopen看看cgns.lib里到底有没有引用这个符号确认库没拿错。4.2 运行时崩溃在 cg_openHDF5 插件路径或环境变量干扰现象程序编译链接都过了一运行到cg_open就崩或者返回CG_ERROR但cg_get_error()只给一个笼统的错误。原因通常是系统里装了多个 HDF5运行时动态加载了错误的版本。虽然你链接的是静态库但如果主工程还依赖了别的动态库比如某些第三方库内部用了 HDF5运行时可能把那个版本的 HDF5 加载进来和静态链接的符号冲突。解决用where hdf5.dll查一下系统里有没有 HDF5 的动态库如果有把它的路径从PATH里临时移除再跑。另外CGNS 的 HDF5 后端在打开文件时会尝试加载压缩插件如果HDF5_PLUGIN_PATH环境变量指向了一个不存在的目录也会导致打开失败。检查这个环境变量没有就设成空。4.3 读大网格时数据错位cgsize_t 用了 int现象小网格读写正常换成百万级顶点的网格后读出来的坐标全是乱的或者程序直接访问越界崩溃。原因CGNS 的cgsize_t在 64 位编译下是 64 位整数但很多示例代码里用int接cg_array_size返回的 size或者用int做循环变量遍历顶点。当顶点数超过INT_MAX时int溢出后续的数组访问全部错位。解决所有和 CGNS 尺寸相关的变量都用cgsize_t循环变量用size_t或long long。std::vector的索引也用size_t。在 32 位工程里cgsize_t是 32 位但既然这个包是 64 位的就统一按 64 位处理。4.4 写文件后 HDF5 报 “unable to flush”文件句柄没关或磁盘满现象cg_close返回错误提示 HDF5 无法 flush 缓冲区。原因一是文件句柄泄漏前面cg_open打开的文件没关就打开了另一个HDF5 内部状态乱了。二是磁盘空间不足HDF5 写缓存刷不下去。三是文件被其他进程占用比如你一边用 ParaView 打开着这个文件一边程序往里写。解决确保每个cg_open都有对应的cg_close用 RAII 包一层或者goto清理。写文件前检查磁盘剩余空间。调试阶段关掉 ParaView 之类的查看器。4.5 头文件报红但编译通过IntelliSense 路径没配现象VS 里#include cgnslib.h下面有红色波浪线提示找不到头文件但按 F7 编译能过。原因IntelliSense 的包含路径和编译器的包含路径是分开配的。你改了 C/C → 常规 → 附加包含目录但 IntelliSense 可能还在用旧的缓存。解决关掉 VS删掉工程目录下的.vs隐藏文件夹重新打开。或者在工程属性 → C/C → 常规 → 附加包含目录里确认路径写的是绝对路径还是相对路径IntelliSense 对相对路径的解析有时和编译器不一致改成绝对路径最稳。5. 进阶技巧用 CGNS 做网格格式转换的批量处理把 CGNS 当中间格式做批量转换是我用得最多的场景。比如把几十个 Plot3D 文件转成 CGNS再统一读出来做统计。这里的关键不是 API 本身而是怎么组织循环和错误处理让一个文件出错不至于中断整批任务。我一般会写一个convert_one函数返回bool内部用cg_open打开源文件读坐标和单元再用cg_open打开目标文件写入。两个文件句柄分开管理用std::unique_ptr加自定义 deleter 包一层确保异常时也能关掉。struct CgFileCloser { void operator()(int* fn) const { if (fn *fn 0) { cg_close(*fn); } delete fn; } }; using CgFilePtr std::unique_ptrint, CgFileCloser; CgFilePtr open_cgns(const std::string path, int mode) { int* fn new int(-1); if (cg_open(path.c_str(), mode, fn) ! CG_OK) { std::cerr open path failed: cg_get_error() std::endl; delete fn; return CgFilePtr(nullptr); } return CgFilePtr(fn); }这样在convert_one里拿到CgFilePtr后不管中间哪一步返回错误函数退出时文件都会自动关闭。批量循环里对每个文件调convert_one返回false就记一条日志继续下一个最后统计成功失败数量。另一个技巧是读非结构网格时cg_nsections和cg_section_read配合用。非结构网格的单元类型四面体、六面体、棱柱是分开存的每个 section 一种类型。遍历 section 时先拿ElementType_t再根据类型决定每个单元的节点数最后用cg_elements_read一次性读出所有连接关系。这里容易翻车的地方是cg_elements_read的elements数组大小要按cg_section_read返回的nelems乘以节点数来分配少乘了就会缓冲区溢出。验证转换结果是否正确的办法用 ParaView 打开输出的 CGNS 文件看网格显示是否正常再用cg_get_error确认没有隐藏的错误。如果 ParaView 能正常渲染基本说明坐标和连接关系写对了。从那以后我每次批量转换完都会随机抽三个文件用 ParaView 过一遍确认没有坐标错位或者单元丢失。希望帮到你。本文还有配套的精品资源点击获取
