LoopStructural 是一个用于构建三维地质模型的 Python 库，采用约束隐式建模方法。其核心思想是用连续的地质标量场表示地质界面：标量值标记界面位置，但该值本身并不自动代表年龄、实测深度或高程。使用时应记录坐标参考系统（CRS）、共享的 XYZ 单位、正 Z 约定、特征顺序以及每个标量层级的含义。
主要能力
该技能支持从构造地质数据构建三维地质模型，包括隐式曲面、断层、褶皱和地层约束。资料中重点展示了受约束的平面模型：通过标量观测和梯度约束同时锚定层级和方向，单个点无法定义地质表面。模型支持 FDI 和 PLI 插值器，可创建并添加叶理（foliation），并支持世界坐标评估。
使用方式
基本流程包括：定义模型范围（origin 和 maximum），准备包含 X、Y、Z、feature_name、val 以及梯度或法向量约束的数据框，创建 GeologicalModel 实例，添加叶理特征，更新模型，然后评估特征值。示例代码展示了如何用米制坐标和非零原点构建非对称盒子，标量场为 Z - 3030 + 0.1*(X - 1050) - 0.05*(Y - 2100)，并验证查询点的期望值约为 -10、+10 和 0。评估时需传入世界坐标，默认 scale=True；直接特征评估使用不同的局部坐标约定。GeologicalModel 1.8 接受两个边界作为位置参数，不应假设旧示例中的 origin= 和 maximum= 关键字仍然有效。
VTK 网格评估与导出
模型可通过 regular_grid 生成 N×3 数组，需禁用洗牌（shuffle=False）并使用 Fortran 排序以匹配 VTK 的 x 最快点顺序。随后可创建 StructuredGrid，设置点、维度，将标量值写入点数据，再通过 contour 提取等值面。导出时使用 grid.save('model.vtk') 或 surface.save('strat.vtk')。渲染的表面是离散化的水平集，解释小尺度结构前应检查约束残差和网格收敛性。
CSV 辅助脚本与条件模型
模型构建器支持受约束的 FDI/PLI 叶理以及网格/等值面导出。它会验证有限坐标、完整约束和正的三维范围，并在导出失败或为空时以非零退出状态报告。对于平面或零跨度输入几何，应提供显式边界，而不是凭空创造范围。命令行示例：python scripts/build_model.py constraints.csv --grid --output model.vtk --origin 1000 2000 3000 --maximum 1100 2200 3060 --nsteps 9 7 5。命令应相对于已安装的技能目录解析。辅助脚本要求 X、Y、Z、feature_name，以及 val 和/或完整的 gx、gy、gz 或 nx、ny、nz 约束；每个特征需要一个标量层级锚点。缺失的向量行应全部为 NaN，而不是零向量。
适用场景与限制
该技能适用于需要根据观测数据约束连续地质标量场的场景，例如地层界面重建、三维网格评估与可视化。断层、褶皱框架和不确定性集合需要显式的运动学/数据以及单独配置的模型，不能仅通过 CSV 列或该叶理辅助脚本创建。验证范围限于 LoopStructural 1.8.0 与 loop-interpolation 0.0.2 的平面模型、世界坐标评估、非对称网格排序、等值面与 VTK 回读，以及错误输入和 CLI 失败处理；不涵盖断层网络反演、褶皱地质、不确定性估计或稀疏场约束的地质充分性。官方模型源已于 2026-09-14 对照安装的 1.8.0 API 进行检查。