# GCTL Regular Mesh Spherical 3D 文档

## 简介

`regular_mesh_sph_3d.h` 定义了GCTL网格库中的三维球面规则网格类 `regular_mesh_sph_3d`，用于创建和管理球面坐标系下的三维规则网格。该类特别适用于地球物理学中的球面网格计算。

## 类继承

`regular_mesh_sph_3d` 继承自 `base_mesh` 基类，实现了所有虚函数，并添加了球面网格特有的功能。

## 主要API

### 初始化
```cpp
// 初始化三维球面规则网格
void init(std::string name,          // 网格名称
          std::string info,          // 网格信息
          double lat0,               // 起始纬度
          double lon0,               // 起始经度
          double r0,                 // 起始半径
          double dlat,               // 纬度间隔
          double dlon,               // 经度间隔
          double dr,                 // 半径间隔
          int nlat,                  // 纬度方向网格数
          int nlon,                  // 经度方向网格数
          int nr);                   // 径向网格数
```

### 网格信息
```cpp
// 获取网格点数
void get_mesh_num(int &nlat, int &nlon, int &nr) const;

// 获取网格范围
void get_mesh_range(double &lat0, double &lon0, double &r0,    // 起点
                   double &lat1, double &lon1, double &r1) const; // 终点

// 获取网格间距
void get_mesh_step(double &dlat, double &dlon, double &dr) const;
```

### 网格操作
```cpp
// 获取指定位置的网格点球面坐标
void get_node_coord_sph(int i, int j, int k,              // 节点索引
                       double &lat, double &lon, double &r) const;

// 获取指定位置的网格点笛卡尔坐标
void get_node_coord(int i, int j, int k,                  // 节点索引
                   double &x, double &y, double &z) const;

// 获取指定位置的单元中心球面坐标
void get_elem_center_sph(int i, int j, int k,            // 单元索引
                        double &lat, double &lon, double &r) const;

// 获取指定位置的单元中心笛卡尔坐标
void get_elem_center(int i, int j, int k,                // 单元索引
                    double &x, double &y, double &z) const;

// 获取指定球面坐标所在的网格单元索引
bool get_elem_index(double lat, double lon, double r,    // 球面坐标
                   int &i, int &j, int &k) const;        // 返回单元索引
```

### 文件操作
```cpp
// 保存为Gmsh格式
virtual void save_gmsh(std::string filename,
                      index_packed_e packed = Packed) override;

// 保存为二进制格式
virtual void save_binary(std::string filename) override;

// 读取二进制格式
virtual void load_binary(std::string filename) override;
```

## 使用示例

```cpp
// 创建三维球面规则网格
gctl::regular_mesh_sph_3d mesh_sph;
mesh_sph.init("earth_mesh", "Earth model mesh",
              -90.0, -180.0, 6371.0,     // 起始点：南极点，经度-180度，地球半径
              1.0, 1.0, 10.0,            // 间隔：1度纬度，1度经度，10km深度
              180, 360, 100);            // 网格数：180纬度，360经度，100层

// 获取网格信息
int nlat, nlon, nr;
mesh_sph.get_mesh_num(nlat, nlon, nr);

// 获取特定位置的坐标（球面坐标）
double lat, lon, r;
mesh_sph.get_node_coord_sph(90, 180, 0, lat, lon, r);  // 获取中心点坐标

// 获取特定位置的坐标（笛卡尔坐标）
double x, y, z;
mesh_sph.get_node_coord(90, 180, 0, x, y, z);

// 添加数据并保存
mesh_sph.add_data(gctl::NodeData, gctl::Scalar, "temperature", 0.0);
mesh_sph.save_gmsh("earth_model.msh", gctl::Packed);
```

## 注意事项

1. 坐标系采用地理坐标系约定：
   - 纬度范围：-90度（南极）到90度（北极）
   - 经度范围：-180度到180度
   - 半径：从地心开始计算
2. 提供了球面坐标和笛卡尔坐标的双重表示
3. 网格在极点附近可能出现变形，需要特别处理
4. 经度方向是周期性的，可以处理跨越180度经线的情况
5. 支持Gmsh和二进制格式的文件操作
6. 适用于地球物理建模、大气科学等领域