gctl_mesh/README.md

![logo](GCTL_logo.jpg)

# GCTL Mesh Library

GCTL Mesh是地球物理计算工具库(Geophysical Computational Tools & Library)的网格处理模块，提供了多种类型的网格实现和操作功能。

## 功能特点

- 支持多种网格类型的创建和操作
- 提供2D和3D网格的实现
- 包含规则网格和非规则网格的处理
- 支持球面网格的处理
- 支持网格数据的导入导出（包括Gmsh格式和二进制格式）
- 支持标量、矢量和张量数据的处理

## 文档

### 基础类
- [`mesh.h`](doc/mesh.md): 网格基类，定义了基本的网格接口和功能
- [`meshdata.h`](doc/meshdata.md): 网格数据结构的定义和处理

### 规则网格
- [`regular_grid.h`](doc/regular_grid.md): 通用规则网格实现，支持2D和3D
- [`regular_mesh_2d.h`](doc/regular_mesh_2d.md): 二维规则网格，专注于2D结构化网格
- [`regular_mesh_3d.h`](doc/regular_mesh_3d.md): 三维规则网格，专注于3D结构化网格
- [`regular_mesh_sph_3d.h`](doc/regular_mesh_sph_3d.md): 三维球面规则网格，适用于地球物理建模

### 线性网格
- [`linear_mesh_2d.h`](doc/linear_mesh_2d.md): 二维线性网格，用于表示2D空间中的线段
- [`linear_mesh_3d.h`](doc/linear_mesh_3d.md): 三维线性网格，用于表示3D空间中的曲线

### 非规则网格
- [`tri_mesh.h`](doc/tri_mesh.md): 三角形网格，用于复杂2D区域的离散化
- [`tet_mesh.h`](doc/tet_mesh.md): 四面体网格，用于复杂3D区域的离散化

## 核心功能

### 网格数据管理
- 支持在顶点或单元上定义数据
- 支持三种数据类型：
  - 标量数据 (Scalar)
  - 矢量数据 (Vector)
  - 张量数据 (Tensor)
- 数据操作功能：
  - 添加/删除数据
  - 数据导入导出
  - 数据统计分析

### 网格操作
- 网格初始化和清理
- 网格信息查询（节点数、单元数等）
- 网格文件导入导出
  - 支持Gmsh格式
  - 支持二进制格式
  - 支持NetCDF格式（部分网格类型）
- 网格数据可视化输出

### 网格类型
支持的网格维度：
- 0D网格 (MESH_0D)
- 2D网格 (MESH_2D)
- 3D网格 (MESH_3D)

支持的网格类别：
- 规则网格 (REGULAR_MESH)
- 线性网格 (LINEAR_MESH)
- 三角形/四面体网格 (TRI_TET_MESH)
- 球面规则网格 (REGULAR_MESH_SPH)
- 球面线性网格 (LINEAR_MESH_SPH)
- 球面三角形/四面体网格 (TRI_TET_MESH_SPH)
- 规则网格 (REGULAR_GRID)

## 应用场景

- **规则网格**：适用于简单几何形状的离散化，如矩形/立方体区域
- **线性网格**：
  - 2D：用于表示边界、裂缝等线性特征
  - 3D：用于表示输电线路、管道系统、裂缝网络等
- **三角形网格**：适用于复杂2D区域的有限元分析、流体动力学等
- **四面体网格**：适用于复杂3D区域的有限元分析、计算流体力学等
- **球面网格**：特别适用于地球物理学、大气科学等全球尺度的模拟

## API示例

详细的API使用示例请参考各个网格类型的文档。基本使用模式如下：

```cpp
// 创建网格对象
gctl::regular_grid rgd;
rgd.init("grid-1", "test grid", 4, 4, 0.0, 0.0, 1.0, 1.0);

// 添加数据
rgd.add_data(gctl::NodeData, gctl::Scalar, "temperature", 25.0);
rgd.add_data(gctl::ElemData, gctl::Vector, "velocity", velocity_array);

// 保存网格
rgd.save_gmsh("output.msh", gctl::OverWrite);
```

## 许可证

该项目采用双重许可证方案：
1. GNU Lesser General Public License v2或更高版本
2. 商业许可证（需单独申请）

## 联系方式

作者：Yi Zhang (yizhang-geo@zju.edu.cn)

## 版权声明

Copyright (c) 2023 Yi Zhang

## 使用示例

库提供了多个完整的示例程序，展示了不同功能的使用方法：

### 基础网格操作
```cpp
// mesh_ex1.cpp - 基础网格创建和数据操作
gctl::regular_grid rgd;
rgd.init("grid-1", "null", 4, 4, 0.0, 0.0, 1.0, 1.0);  // 创建4x4网格
rgd.add_data(gctl::NodeData, gctl::Scalar, "data-1", 2.5);  // 添加节点数据
rgd.add_data(gctl::ElemData, gctl::Scalar, "data-2", 1.2);  // 添加单元数据
```

### 文件导入导出
```cpp
// mesh_ex5.cpp - NetCDF格式文件操作
gctl::regular_grid rgd;
rgd.load_netcdf_grid("data/input.nc", gctl::ElemData, "x", "y");  // 读取网格
rgd.save_netcdf_grid("data/output.nc", "example");  // 保存网格
```

### 球面网格处理
```cpp
// mesh_ex10.cpp - 3D球面网格创建
gctl::regular_mesh_sph_3d rm_3ds;
rm_3ds.init("mesh-1", "null", 30.25, 30.25, 2005, 0.5, 0.5, 10, 40, 40, 50);
rm_3ds.add_data(gctl::ElemData, gctl::Scalar, "data-1", 2.5);
rm_3ds.save_gmsh("mesh_sample10", gctl::OverWrite, gctl::NotPacked);
```

更多示例可以在`example`目录下找到：
- `mesh_ex1.cpp`: 基础网格创建和数据操作
- `mesh_ex2.cpp`: 网格数据的导入导出
- `mesh_ex3.cpp`: 网格变换和操作
- `mesh_ex4.cpp`: 非结构化网格处理
- `mesh_ex5.cpp`: NetCDF格式文件操作
- `mesh_ex6.cpp`: 网格数据插值
- `mesh_ex7.cpp`: 网格数据统计分析
- `mesh_ex8.cpp`: 二维规则网格操作
- `mesh_ex9.cpp`: 三维规则网格操作
- `mesh_ex10.cpp`: 球面网格处理