# GCTL Linear Mesh 3D 文档

## 简介

`linear_mesh_3d.h` 定义了GCTL网格库中的三维线性网格类 `linear_mesh_3d`，用于创建和管理三维空间中的非结构化线性网格。该类支持不规则分布的网格点，适用于复杂三维几何结构中的线性特征离散化。

## 类继承

`linear_mesh_3d` 继承自 `base_mesh` 基类，实现了所有虚函数，并添加了三维线性网格特有的功能。

## 主要API

### 初始化
```cpp
// 初始化三维线性网格
void init(std::string name,                // 网格名称
          std::string info,                // 网格信息
          const array<point3dc> &nodes,    // 节点坐标数组
          const array<int2> &elements);    // 单元连接关系数组
```

### 网格信息
```cpp
// 获取节点坐标
void get_node_coord(int node_idx,          // 节点索引
                   double &x, double &y, double &z) const;

// 获取单元节点索引
void get_elem_nodes(int elem_idx,          // 单元索引
                   int &n1, int &n2) const;

// 获取单元中心坐标
void get_elem_center(int elem_idx,         // 单元索引
                    double &x, double &y, double &z) const;

// 获取单元长度
double get_elem_length(int elem_idx) const;

// 获取单元方向向量
void get_elem_direction(int elem_idx,      // 单元索引
                       double &dx, double &dy, double &dz) const;
```

### 网格查询
```cpp
// 查找最近的单元
bool find_nearest_element(double x, double y, double z,  // 目标点坐标
                         int &elem_idx,                  // 返回单元索引
                         double &distance) const;        // 返回最短距离

// 获取节点相邻的单元
array<int> get_node_elements(int node_idx) const;

// 获取单元相邻的单元
array<int> get_elem_neighbors(int elem_idx) 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
// 创建节点坐标数组
array<point3dc> nodes;
nodes.push_back(point3dc(0.0, 0.0, 0.0));
nodes.push_back(point3dc(1.0, 0.0, 0.0));
nodes.push_back(point3dc(1.0, 1.0, 1.0));
nodes.push_back(point3dc(0.0, 1.0, 1.0));

// 创建单元连接关系
array<int2> elements;
elements.push_back(int2(0, 1));  // 第一条边
elements.push_back(int2(1, 2));  // 第二条边
elements.push_back(int2(2, 3));  // 第三条边

// 创建线性网格
gctl::linear_mesh_3d mesh3d;
mesh3d.init("curve3d", "3D curve mesh", nodes, elements);

// 获取单元信息
double length = mesh3d.get_elem_length(0);  // 获取第一条边的长度

// 获取单元方向
double dx, dy, dz;
mesh3d.get_elem_direction(0, dx, dy, dz);  // 获取第一条边的方向向量

// 查找最近的单元
int elem_idx;
double distance;
if (mesh3d.find_nearest_element(0.5, 0.5, 0.5, elem_idx, distance)) {
    // 找到距离点(0.5,0.5,0.5)最近的单元
}

// 添加数据并保存
mesh3d.add_data(gctl::NodeData, gctl::Vector, "displacement", 
                array<point3dc>(nodes.size(), point3dc(0,0,0)));
mesh3d.save_gmsh("curve3d.msh", gctl::Packed);
```

## 注意事项

1. 线性网格主要用于表示一维结构（如曲线、管线）在三维空间中的分布
2. 每个单元由两个节点定义，表示一条空间线段
3. 节点和单元的编号从0开始
4. 支持不规则分布的节点，适合复杂三维曲线的离散化
5. 提供了网格拓扑关系查询功能
6. 支持计算单元的方向向量，便于处理定向问题
7. 查找最近单元功能适用于路径规划和碰撞检测
8. 支持Gmsh和二进制格式的文件操作
9. 适用于输电线路、管道系统、裂缝网络等模拟