第1章: Gmsh概述与C++ SDK配置

1.1 学习目标

理解 Gmsh 的定位：它是一个怎样的工具，在 CAE 前处理流程中扮演什么角色
掌握 Gmsh 的四模块架构（Geometry / Mesh / Solver / Post），理解各模块职责
能够在 Windows 和 Linux 上配置 Gmsh C++ SDK，正确编译和链接项目
能写出一个 initialize / finalize 骨架程序并成功运行
熟悉本章涉及的 Gmsh C++ API 核心函数

1.2 什么是 Gmsh

Gmsh 是一个开源的三维有限元网格生成器（open source 3D finite element mesh generator），内置 CAD 引擎和后处理器（post-processor）。它由 Christophe Geuzaine 和 Jean-Francois Remacle 开发，使用 GNU General Public License (GPL) 发布，当前稳定版本为 4.15.2（2026 年 3 月）。

Gmsh 的设计目标是提供一个快速、轻量且用户友好的网格划分工具，支持参数化输入和灵活的可视化能力。它围绕四个核心模块构建，并且提供了多种接口：

图形用户界面 (GUI)：交互式建模、网格划分和结果查看
命令行接口 (CLI)：批处理和脚本化工作流
脚本语言：.geo 文件格式，Gmsh 自有的领域特定语言
多语言 API：C++、C、Python、Julia 和 Fortran

对于 CAE 前处理软件开发人员来说，C++ API 是最强大的接口方式——它可以将 Gmsh 作为网格生成引擎直接嵌入到自己的 CAE 软件中，实现几何建模、网格划分、后处理功能的深度集成。

1.3 四模块架构

Gmsh 的功能由四个相对独立但紧密协作的模块组成：

+---------------------------------------------------------------+
|                        Gmsh 架构                              |
|                                                               |
|  +----------+  +----------+  +----------+  +--------------+   |
|  | Geometry |  |   Mesh   |  |  Solver  |  | Post-        |   |
|  |  Module  |  |  Module  |  |  Module  |  | Processing   |   |
|  |          |  |          |  |          |  | Module       |   |
|  +----+-----+  +----+-----+  +----+-----+  +------+-------+   |
|       |              |              |               |          |
|       +--------------+--------------+---------------+          |
|                      |                                        |
|              Gmsh C++ API (gmsh.h)                            |
|              动态链接库 (libgmsh.dll / libgmsh.so)            |
+---------------------------------------------------------------+

1.3.1 Geometry（几何建模）模块

负责创建和编辑几何模型。Gmsh 支持两种几何内核：

内置内核 (built-in kernel)：通过 gmsh::model::geo 命名空间访问，适合程序化构造简单到中等复杂度的几何。操作原语包括点 (Point)、线 (Line / Spline / BSpline)、面 (Plane Surface / Ruled Surface) 和体 (Volume)。
OpenCASCADE 内核：通过 gmsh::model::occ 命名空间访问，基于开源 CAD 内核 OpenCASCADE Technology (OCCT)，支持完整的边界表示法 (B-rep)，可以导入和操作 STEP、IGES 等标准 CAD 格式。

1.3.2 Mesh（网格划分）模块

负责在几何模型上生成有限元网格。核心功能包括：

控制网格尺寸的多种方式：全局参数、逐点指定、尺寸场 (Size Field)、背景网格 (Background Mesh)
支持一维、二维和三维网格的增量生成
结构网格 (Transfinite / Recombined) 和非结构网格
单元类型支持三角形/四边形（2D）、四面体/六面体/棱柱/金字塔（3D）
网格导出格式：MSH（原生）、UNV、STL、VTK 等

1.3.3 Solver（求解器接口）模块

提供与外部有限元求解器的交互接口。Gmsh 自身不完全实现一个通用求解器，而是提供了参数化描述物理问题、定义边界条件、关联解数据的能力。通过 gmsh::model::mesh::getIntegrationData() 等函数可以访问积分点信息，供外部求解器使用。

1.3.4 Post-Processing（后处理）模块

负责计算结果的可视化和分析。支持：

标量场、矢量场和张量场的渲染
剖切面显示、等值面、流线图
支持 ONELAB 框架下的多模型交互式分析
通过 gmsh::view 和 gmsh::plugin 命名空间控制后处理

1.4 Gmsh 在 CAE 前处理中的定位

在典型的 CAE 仿真流程中：

[CAD模型] --> [几何清理/修复] --> [网格划分] --> [求解器] --> [后处理]
   |--------------- 前处理 (Pre-processing) ------------|
              |--------------- Gmsh 核心覆盖 ---------------|

Gmsh 覆盖了从几何建模到后处理的完整链路。作为前处理引擎嵌入 CAE 软件时，其主要用法是：

应用程序通过 C++ API 调用 Gmsh 的几何模块构建模型
调用网格模块生成网格
从 Gmsh 数据结构中提取节点坐标、单元拓扑信息
将提取的数据转换为目标求解器的输入格式
（可选）求解完毕后，调用后处理模块可视化结果

这种方式免去了开发人员自行实现网格生成算法的巨大工作量，同时又保持了程序对前处理流程的完全控制。

1.5 C++ SDK 配置

Gmsh C++ API 的核心文件：

文件	说明
`gmsh.h`	C++ API 头文件，包含所有 API 函数的声明和文档
`gmsh.h_cwrap`	C++ 对 C API 的包装层，用于 ABI 不兼容时的替代方案
`libgmsh.dll/.so/.dylib`	动态链接库 (dynamic library)，包含核心实现

1.5.1 获取 SDK

方式一：下载预编译二进制 SDK

从 https://gmsh.info/bin/ 下载对应平台的 SDK 压缩包（名称形如 gmsh-*-sdk.*），解压后目录结构如下：

gmsh-*-sdk/
  include/
    gmsh.h           # C++ API 头文件
    gmsh.h_cwrap     # C API 包装（ABI 兼容备选）
  lib/
    gmsh.lib         # Windows 导入库
    gmsh.dll         # Windows 动态库
    libgmsh.so       # Linux 共享库
    libgmsh.dylib    # macOS 动态库
  share/doc/gmsh/tutorials/c++/   # C++ 教程源码

方式二：从源码编译

cd gmsh-4.15.2-source
mkdir build && cd build
cmake -DENABLE_BUILD_DYNAMIC=1 ..
make
make install

编译完成后，gmsh.h 位于源码顶层目录的 api/ 子目录下，动态库在构建目录中。

1.5.2 Windows 配置

MSVC + Visual Studio (命令行)

在 Visual Studio Developer Command Prompt 中：

:: 如果编译器 ABI 与 SDK 不兼容，使用 gmsh.h_cwrap 代替 gmsh.h
:: 先将 gmsh.h_cwrap 重命名为 gmsh.h（备份原 gmsh.h）

cl /EHsc /I<SDK根目录>\include t1.cpp <SDK根目录>\lib\gmsh.lib /Fe:t1.exe

将 <SDK根目录> 替换为 SDK 的实际解压路径。运行时需确保 gmsh.dll 在 PATH 中或与可执行文件同目录。

CMakeLists.txt (Windows)

cmake_minimum_required(VERSION 3.14)
project(MyGmshApp LANGUAGES CXX)

# 设置 Gmsh SDK 路径
set(GMSH_SDK_DIR "C:/gmsh-4.15.2-Windows64-sdk" CACHE PATH "Gmsh SDK root")

# 头文件路径
include_directories(${GMSH_SDK_DIR}/include)

# 链接目录和库
link_directories(${GMSH_SDK_DIR}/lib)

add_executable(my_app main.cpp)
target_link_libraries(my_app gmsh)

# 将 DLL 复制到可执行文件目录
add_custom_command(TARGET my_app POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
    "${GMSH_SDK_DIR}/lib/gmsh.dll"
    $<TARGET_FILE_DIR:my_app>)

1.5.3 Linux 配置

直接使用 g++ 编译

# 使用预编译 SDK
g++ -o my_app main.cpp -I<SDK根目录>/include -L<SDK根目录>/lib -lgmsh

# 使用源码编译后安装的库
g++ -o my_app main.cpp -lgmsh

运行时需要确保动态库可被找到：

export LD_LIBRARY_PATH=<SDK根目录>/lib:$LD_LIBRARY_PATH
./my_app

CMakeLists.txt (Linux)

cmake_minimum_required(VERSION 3.14)
project(MyGmshApp LANGUAGES CXX)

# 如果 SDK 不在系统路径中
set(GMSH_SDK_DIR "/path/to/gmsh-sdk" CACHE PATH "Gmsh SDK root")

find_path(GMSH_INCLUDE_DIR gmsh.h
    HINTS ${GMSH_SDK_DIR}/include /usr/local/include)
find_library(GMSH_LIBRARY gmsh
    HINTS ${GMSH_SDK_DIR}/lib /usr/local/lib)

add_executable(my_app main.cpp)
target_include_directories(my_app PRIVATE ${GMSH_INCLUDE_DIR})
target_link_libraries(my_app ${GMSH_LIBRARY})

1.5.4 ABI 兼容性说明

如果编译器的 C++ ABI 与 SDK 构建时使用的编译器不兼容（最常见于 Windows 上 MSVC 与 MinGW 之间），应使用 gmsh.h_cwrap 代替 gmsh.h。

gmsh.h_cwrap 通过 C API 间接调用 Gmsh，会有轻微的性能开销（额外的数据拷贝），但功能完全一致。使用方法：

:: Windows
ren include\gmsh.h gmsh.h_original
ren include\gmsh.h_cwrap gmsh.h

# Linux / macOS
cp include/gmsh.h include/gmsh.h_original
cp include/gmsh.h_cwrap include/gmsh.h

1.6 最小的可运行程序

下面是一个最基本的 Gmsh C++ 程序骨架，它演示了 API 使用的完整生命周期：

// min_gmsh.cpp — Gmsh C++ API 最小骨架程序
#include <gmsh.h>

int main(int argc, char **argv)
{
    // 第1步：初始化 Gmsh（必须在调用任何 API 函数之前执行）
    gmsh::initialize();

    // 第2步：创建一个新模型（可选；如果不调用，Gmsh 会自动创建一个无名默认模型）
    gmsh::model::add("my_first_model");

    // 第3步：在此处进行几何建模、网格划分等操作
    // （本章暂不涉及具体操作，后续章节逐步展开）

    // 第4步：结束 Gmsh 会话（释放所有资源）
    gmsh::finalize();

    return 0;
}

代码解释：

gmsh::initialize() —— 初始化 Gmsh 内部状态。这是强制性调用，必须在所有其他 API 调用之前执行。它负责初始化图形后端（FLTK）、命令行参数解析等底层基础设施。
gmsh::model::add("my_first_model") —— 创建一个名为 "my_first_model" 的模型。Gmsh 支持同时管理多个模型，每个模型拥有独立的几何和网格数据。tag 会从 0 开始自动递增分配，也可以通过返回值获取。
gmsh::finalize() —— 释放 Gmsh 分配的所有资源，关闭 GUI 子系统。这是强制性调用，应在程序结束前执行。不调用的后果包括内存泄漏和未刷新的文件缓冲区。

运行验证：

# Linux
g++ -o min_gmsh min_gmsh.cpp -lgmsh
./min_gmsh

# Windows (MSVC)
cl /EHsc /I<SDK>\include min_gmsh.cpp <SDK>\lib\gmsh.lib /Fe:min_gmsh.exe
min_gmsh.exe

如果程序静默退出（无输出、无崩溃），说明 Gmsh SDK 配置正确。

1.7 关键 API 速查表

本章介绍的所有 API 函数汇总如下。这些函数都定义在 gmsh.h 头文件中。

函数	命名空间	说明
`initialize()`	`gmsh`	初始化 Gmsh，必须在所有 API 调用前执行
`finalize()`	`gmsh`	释放 Gmsh 资源，程序结束前必须执行
`add(name)`	`gmsh::model`	创建新模型，参数为模型名称字符串。返回模型 tag
`setCurrent(tag)`	`gmsh::model`	切换到指定 tag 的模型（多模型管理场景）
`list(models)`	`gmsh::model`	获取当前所有已创建模型的名称和 tag 列表
`isInitialized()`	`gmsh`	查询 Gmsh 是否已完成初始化
`open(file)`	`gmsh`	打开并载入一个 `.geo` 脚本文件或 `.msh` 网格文件
`write(file)`	`gmsh`	将当前模型（网格）保存到文件，格式由扩展名确定
`option::setNumber(name, val)`	`gmsh`	设置数值型全局选项（如 `"Mesh.SaveAll"`）

命名空间体系简图：

gmsh                               # 顶层：初始化、文件 I/O、全局选项
├── model                          # 模型管理：增删模型、物理组、域属性
│   ├── geo                        # 内置几何内核：点、线、面、体操作
│   ├── occ                        # OpenCASCADE 几何内核
│   └── mesh                       # 网格生成与数据访问
├── view                           # 后处理视图管理
│   └── option                     # 视图级选项
├── plugin                        # 后处理插件（切片、等值面、统计等）
├── fltk                          # GUI 控制（仅当 FLTK 编译进库中时可用）
└── logger                        # 日志输出控制

1.8 本章小结

Gmsh 是一个完整的网格生成平台，四模块架构使其职责分明：几何建模 (Geometry)、网格划分 (Mesh)、求解器接口 (Solver)、后处理 (Post-Processing)。
C++ API 通过 gmsh.h 头文件和动态链接库提供服务，可将 Gmsh 作为前处理引擎直接嵌入 CAE 软件。
SDK 获取方式包含预编译二进制下载和源码编译两种途径，配置要点是头文件路径和链接库路径的正确设置。
每个 Gmsh C++ 程序必须以 gmsh::initialize() 开头、以 gmsh::finalize() 结尾。
ABI 不兼容时可用 gmsh.h_cwrap 替代 gmsh.h，功能等价但略增拷贝开销。

下一章将基于内置几何内核，从点、线、面等基本几何实体（elementary entity）入手，逐步构建完整的几何模型。