modules.geoDataProcess 模块帮助

本章节包含 modules.geoDataProcess 中与地质 / 钻孔 / 剖面数据处理相关的模块说明，例如：

按剖切线从地形点插值生成三维及二维地形线（SliceTerrain）
按钻孔与剖切线导出 CAD 用地质剖面（ExportGeoSectionsByBores）
为地质剖面钻孔补充柱状图信息（AddBoreLogForGeoSections）
地层编号补齐、按地层编号排序
按孔口高程补全分层表的层厚、层顶/层底深度和高程（CompleteLayerTable）
按参考规范计算标准贯入表或动力触探表的修正击数（CalculateCorrectedBlowCount）
钻孔类型 KCAD 映射等

MapBoreTypeToKCAD

模块简介与适用场景

MapBoreTypeToKCAD 将钻孔一览表中的「钻孔类型」字段值映射为 KCAD（AutoCAD/中望CAD出图插件）所使用的标准钻孔类型名称。
映射关系并非写死在代码里，而是通过 GDIM API 按当前 项目 ID 拉取；项目在 GDIM 中维护对照表时，Pipeline 可自动同步为最新映射。
对照表未覆盖的取值会**保留原单元格内容**，并通过 GDIDataQualityWarning 提示（详见后文「行为与错误说明」），便于在 GDIM 中核对后再补全项目映射或修正源数据。
典型适用场景： 钻孔布置图、平面图等下游 KCAD / CAD 绘图流程要求钻孔类型枚举与标准一致。

端口说明

输入端口 - InputTables：TableCollection 或 TableData``（单表时整张表即为钻孔一览表）。 - ``InputToken：Token；Pipeline 已配置 GDIM 运行上下文时可不连接。
输出端口 - OutputTables：拷贝并写回映射结果后的数据，类型与输入一致；InputTables 为空或无法解析 token 时为 None。

快速上手示例：单表映射

from gdisdk.modules import MapBoreTypeToKCAD

mapper = MapBoreTypeToKCAD(mname="MapBoreTypes")
mapper.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
mapper.bore_type_field = "bore_type"  # 列内部名或字段标题均可
mapper.InputTables = your_bore_table_data  # TableData

mapper.execute()
out = mapper.OutputTables.data

快速上手示例：表集合中指定钻孔表

from gdisdk.modules import MapBoreTypeToKCAD

mapper = MapBoreTypeToKCAD(mname="MapBoreTypes")
mapper.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
mapper.bore_table_name = "bore_table"   # 集合内表名或表标题，与 get_table 约定一致
mapper.bore_type_field = "bore_type"    # 或字段标题（与列元数据 title 一致）
mapper.InputTables = your_table_collection

mapper.execute()
out_tables = mapper.OutputTables.data

参数说明

MapBoreTypeToKCAD 参数一览
参数名	类型	默认值	说明
`tables`	`TableCollection \| TableData \| None`	`None`	构造时可直接赋给 `InputTables`；若为 `None` 则须在后续连接端口或属性赋值传入。
`bore_table_name`	`str`	`"bore_table"`	仅 ``TableCollection`` 输入时有效：集合内钻孔表名称或标题。单 `TableData` 输入时忽略。
`bore_type_field`	`str`	`"bore_type"`	待映射列的字段内部名或字段标题，未找到时抛出 `ValueError`，并列出可用字段名与标题。
`token` / `proj_id` / `host`	`str \| None` 等	`None`	鉴权与平台地址。构造器若设置 `proj_id` 写入 `self.proj_id`，其优先级高于 `InputToken` 与 Pipeline 上的项目 ID。

行为与错误说明

模块按 GDIM 项目「钻孔类型映射」对照表（get_bore_type_mapping）对钻孔类型列做 Series.replace：对照表中存在的 源类型名称 会被替换为对应的 KCAD 标准名称。
对照表中**没有**的取值不会被清空或改为缺失值，保留输入时的原字符串；若列中仍存在无法映射为 KCAD 标准钻孔类型的取值，会发出 ``GDIDataQualityWarning``（可在 GDIM 界面查看），并在消息中列出未映射的类型，便于补全项目对照表或修正钻孔一览表数据。
若项目在 GDIM 中尚未配置任何钻孔类型映射，get_bore_type_mapping 会返回空对照表并输出控制台提示，此时整列保持原样。
TableCollection 中找不到 bore_table_name，或表中无法按内部名/标题解析 bore_type_field 时，抛出 ValueError 并给出可用表、字段名与字段标题等线索。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules import MapBoreTypeToKCAD

pipe = PipeLine(app_name="BoreCadPrep", app_title="钻孔类型映射示例")
pipe.update_gdim_state(token="...", proj_id="...", host=None)

mapper = MapBoreTypeToKCAD("MapKcadBoreTypes")
# bore_reader.OutputTables >> mapper.InputTables
pipe.add_module(mapper)
pipe.run()

更多信息

API 参考 - modules 包

AddLayerNumberByStdLayerTable

模块简介与适用场景

AddLayerNumberByStdLayerTable 在 ``layer_table``（地层表）缺少 ``layer_number``（地层编号）时，依据 ``standard_layer_table``（标准地层表）回填该列。
模块会从 GDIM 模板（pipeline.gdim_template 或通过 token 拉取）中读取 standard_layer_update.define_layer_fields，据此确定 join 字段；输入须同时包含 layer_table 与 ``standard_layer_table``（详见后文「行为与错误说明」）。
典型适用场景： 下游流程要求地层表含编号列，或 GDIM 标准地层配置为 “autoGeneration”（自动确定地层字段）时需自动补齐 layer_number。

端口说明

输入端口 - InputTables：TableCollection；须含 layer_table 与 standard_layer_table。 - InputToken：Token；Pipeline 已配置 GDIM 运行上下文时可不连接。
输出端口 - OutputTables：补齐 layer_number 后的 TableCollection；InputTables 为空或无法解析 GDIM 模板时为 None。

快速上手示例：补齐 TableCollection 中的地层编号

from gdisdk.modules.geoDataProcess import AddLayerNumberByStdLayerTable

add_layer_num = AddLayerNumberByStdLayerTable(mname="AddLayerNum")
add_layer_num.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
add_layer_num.InputTables = your_table_collection  # 须含 layer_table 与 standard_layer_table

add_layer_num.execute()
out_tables = add_layer_num.OutputTables.data

参数说明

AddLayerNumberByStdLayerTable 参数一览
参数名	类型	默认值	说明
`tables`	`TableCollection \| None`	`None`	构造时可直接赋给 `InputTables`；若为 `None` 则须在后续连接端口或属性赋值传入。
`layer_table_name`	`str`	`"layer_table"`	地层表在集合内的名称或标题。
`layer_number_name`	`str`	`"layer_number"`	新增地层编号列的字段内部名。
`layer_number_title`	`str`	`"地层编号"`	新增地层编号列的字段标题。
`token / proj_id / host`	`str \| int \| str \| str \| None`	`None`	鉴权与项目定位信息；若未显式传入，模块会尝试从 pipeline 获取，也可通过 `InputToken` 传入。

行为与错误说明

模块按 define_layer_fields 与 layer_table 的 公共字段名 做 left join，从 standard_layer_table 取 layer_number 写回 layer_table。
layer_table 已含 layer_number_name 或 layer_number_title 对应列时，发出 warnings.warn 并原样返回输入集合。
GDIM 模板中 standard_layer_update.update_method 不是 "autoGeneration" 时，发出 warnings.warn 并原样返回输入集合。
layer_table 或 standard_layer_table 缺失/为空、模板缺少 standard_layer_update 或 define_layer_fields、define_layer_fields 与 layer_table 无公共字段、standard_layer_table 缺少 layer_number 列时，抛出 ValueError。
join 后存在缺失的 layer_number``（NaN）时，抛出 ``ValueError 并指出第一条缺失的组合键值。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.geoDataProcess import AddLayerNumberByStdLayerTable

pipe = PipeLine(app_name="AddLayerNumberDemo", app_title="补齐地层编号示例")
pipe.update_gdim_state(token="你的GDIM Token", proj_id="你的GDIM项目ID")

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["layer_table", "standard_layer_table"]

add_layer_num = AddLayerNumberByStdLayerTable("AddLayerNum")

links = read_tables.OutputTables >> add_layer_num.InputTables
pipe.add_links(links)
pipe.run()

out_tables = add_layer_num.OutputTables.data

更多信息

CompleteLayerTable

模块简介与适用场景

CompleteLayerTable 读取 TableCollection 中的钻孔表与地层表，把地层表补成同时包含 layer_thickness、layer_bottom_depth、layer_top_elevation、layer_bottom_elevation、layer_top_depth 五列。
bore_table_name 与 layer_table_name 用表名或表标题指定钻孔表和地层表，默认是 bore_table、layer_table。
bore_table 需要字段名 bore_number 与 bore_top。layer_table 需要字段名 bore_number，以及 reference_column 指定的参考列。参考列只能是 layer_bottom_depth``（默认）、``layer_thickness 或 layer_bottom_elevation。layer_top_depth 和 layer_top_elevation 由参考列算出，不能作为参考列。列只按字段名匹配。
参考列是唯一依据，其余四个层位列按它重算，因此与参考列矛盾的原值会被覆盖。参考列不能有空值，地层表中的钻孔也必须在钻孔表中有孔口高程，否则抛出中文 ValueError。默认按地层表当前行序视为从上到下。order_by_reference=True 时，层底深度按从小到大、层底高程按从大到小排序后再计算，结果仍写回原行；层厚没有上下方向，仍按当前行序。深度与高程用孔口高程互换。首层顶面深度按 0 计。
典型适用场景： 分层表只录入了层底深度或层厚，下游统计、剖面或出图需要层顶、层底的深度和高程同时存在。

端口说明

输入端口 - InputTables：TableCollection，须含钻孔表与地层表。默认表名或表标题为 bore_table、layer_table。
输出端口 - OutputTables：补全层位列后的 TableCollection。InputTables 为空时为 None。

快速上手示例：由层底深度补全层位

from gdisdk.dataclass.tables import TableCollection, TableData
from gdisdk.modules.geoDataProcess import CompleteLayerTable

bore_table = TableData(
    {"bore_number": ["BH1"], "bore_top": [20.0]},
    name="bore_table",
)
layer_table = TableData(
    {"bore_number": ["BH1", "BH1"], "layer_bottom_depth": [2.0, 5.0]},
    name="layer_table",
)
tables = TableCollection()
tables.add_table(bore_table)
tables.add_table(layer_table)

complete = CompleteLayerTable(mname="CompleteLayers", reference_column="layer_bottom_depth")
complete.InputTables = tables

complete.execute()
out = complete.OutputTables.data
layers = out.get_table("layer_table")

参数说明

CompleteLayerTable 参数一览
参数名	类型	默认值	说明
`tables`	`TableCollection \| None`	`None`	构造时可直接赋给 `InputTables`；若为 `None` 则须在后续连接端口或属性赋值传入。
`bore_table_name`	`str`	`"bore_table"`	钻孔表的表名或表标题。
`layer_table_name`	`str`	`"layer_table"`	地层表的表名或表标题。
`reference_column`	`str`	`"layer_bottom_depth"`	作为计算依据的层位字段名。只能是 `layer_thickness`、`layer_bottom_depth`、`layer_bottom_elevation`。地层表中必须有这一列，且不能有空值。
`order_by_reference`	`bool`	`False`	为 `True` 时，按参考列把每个钻孔的地层从上到下排序后再计算。层底深度从小到大，层底高程从大到小。层厚仍按当前行序。结果写回原行。

行为与错误说明

新增列的字段标题取自 GeoResults：层厚「地层厚度」、层底深度「层底深度」、层顶高程「层顶高程」、层底高程「层底高程」、层顶深度「层顶深度」，单位为 m。
换算关系：layer_top_elevation = bore_top - layer_top_depth，layer_bottom_elevation = bore_top - layer_bottom_depth，layer_thickness = layer_bottom_depth - layer_top_depth。除参考列外，这些结果会覆盖原值。
同一钻孔内，上一层的层底即下一层的层顶。默认按当前行序从上到下。order_by_reference 为 True 时，层底深度按从小到大排序，层底高程按从大到小排序，然后再推算。结果仍写回原行。首层顶面深度按 0 计。
先确认钻孔表和地层表存在，并检查必要字段，再深拷贝整个 TableCollection 后写入地层表。输入集合不会被修改。
找不到 bore_table_name 或 layer_table_name、两个参数指向同一张表、缺少 bore_number 或 bore_top、reference_column 不是 layer_thickness、layer_bottom_depth、layer_bottom_elevation 之一，或地层表没有该参考列时，抛出 ValueError。参考列存在空值时，抛出中文 ValueError。
钻孔表中钻孔编号为空或重复时，抛出中文 ValueError。地层表中钻孔编号为空、钻孔在钻孔表中不存在，或对应孔口高程为空时，同样抛出中文 ValueError，不输出结果。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.geoDataProcess import CompleteLayerTable

pipe = PipeLine(app_name="CompleteLayerDemo", app_title="补全地层层位示例")
pipe.update_gdim_state(token="你的GDIM Token", proj_id="你的GDIM项目ID")

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["bore_table", "layer_table"]

complete_layers = CompleteLayerTable("CompleteLayers")

links = read_tables.OutputTables >> complete_layers.InputTables
pipe.add_links(links)
pipe.run()

out_tables = complete_layers.OutputTables.data

更多信息

SortByLayerNumber

模块简介与适用场景

SortByLayerNumber 按地层编号对 TableData 或 TableCollection 中的 layer 表排序，使用 sort_layer_numbers 自然排序规则（如 1-3 排在 10-1 前），可容忍部分非标准编号值。
输入为 TableCollection 时，仅对 layer_table_name 指定的表排序，集合内其余表原样保留。
典型适用场景： 绘图、剖面、汇总或导出前统一层序顺序。

端口说明

输入端口 - InputTable：TableData 或 TableCollection。
输出端口 - OutputTable：排序后的数据，类型与输入一致；InputTable 为空、空表或空集合时为 None。

快速上手示例：排序单张 layer 表

from gdisdk.dataclass.tables import TableData
from gdisdk.modules.geoDataProcess import SortByLayerNumber

table = TableData({"layer_number": ["2-1", "10-1", "1-3"], "v": [1, 2, 3]})

sort_mod = SortByLayerNumber(mname="Sort")
sort_mod.InputTable = table
sort_mod.order = "ascending"

sort_mod.execute()
out = sort_mod.OutputTable.data

快速上手示例：排序 TableCollection 中的 layer 表

from gdisdk.modules.geoDataProcess import SortByLayerNumber

sort_mod = SortByLayerNumber(mname="SortLayer")
sort_mod.layer_table_name = "layer_table"
sort_mod.layer_number_column = "layer_number"
sort_mod.order = "ascending"
sort_mod.InputTable = your_table_collection

sort_mod.execute()
out = sort_mod.OutputTable.data

参数说明

SortByLayerNumber 参数一览
参数名	类型	默认值	说明
`table`	`TableCollection \| TableData \| None`	`None`	构造时可直接赋给 `InputTable`；若为 `None` 则须在后续连接端口或属性赋值传入。
`order`	`Literal["ascending", "descending"]`	`"ascending"`	升序/降序；GDIM 界面通过 `update_ui_schema` 暴露为「地层编号排序」。
`layer_table_name`	`str`	`"layer_table"`	当输入为 `TableCollection` 时，指定要排序的表名或表标题。
`layer_number_column`	`str`	`"layer_number"`	地层编号列的字段内部名或字段标题。

行为与错误说明

排序基于 sort_layer_numbers(..., raise_on_invalid=False)；同一地层编号的多行保持相对顺序，再按编号整体重排。
layer_number_column 支持字段内部名、字段标题，或通过 title_to_name 解析的别名。
找不到地层编号列时，发出 warnings.warn 并返回原表副本（不修改上游数据）。
TableCollection 中找不到 layer_table_name 对应表或该表为空时，发出 warnings.warn 并返回集合副本（其余表不变）。
输出始终为新副本，不会就地修改 InputTable 中的对象。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.geoDataProcess import SortByLayerNumber

pipe = PipeLine(app_name="SortLayerDemo", app_title="地层编号排序示例")
pipe.update_gdim_state(token="你的GDIM Token", proj_id="你的GDIM项目ID")

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["layer_table", "bore_table"]

sort_layer = SortByLayerNumber("SortLayer")
sort_layer.order = "ascending"

links = read_tables.OutputTables >> sort_layer.InputTable
pipe.add_links(links)
pipe.run()

out_tables = sort_layer.OutputTable.data

更多信息

SliceTerrain

模块简介与适用场景

SliceTerrain 按 InputPolyLines 定义的剖切线，从 InputTerrainPoints 地形点插值生成 三维地形线 与 **二维地形线**（桩号 + 高程）。
典型适用场景：
- 地质剖面、地形剖面出图前，将散点地形与剖面线结合，得到沿剖迹的高程采样线；
- 与 CreatePolyLines、GdimTerrainDataReader 联用：前者提供剖切线顶点，后者或上游模块提供地形点。
常见下游模块：ExportGeoSectionsByBores``（通过 ``InputTerrainLines 接收三维地形线输出）。

端口说明

输入端口 - InputTerrainPoints：地形点表（TableData）。须含 x_coordinate、y_coordinate、z_coordinate``（或等价字段名/列标题）；有效点至少 **3** 个。 - ``InputPolyLines：剖切线顶点表（TableData）。须含 name、x_coordinate、y_coordinate；可选 z_coordinate、bore_number。结构遵循 PolyLinesTable。
输出端口 - OutputTerrainLines：三维地形线（TableData）。列包括 name、x_coordinate、y_coordinate、z_coordinate、slice_point；输入剖切线含 bore_number 时输出保留该列（仅 slice_point=True 的行写入钻孔编号）。 - Output2DTerrainLines：二维地形线（TableData）。列包括 name、chainage、z_coordinate、slice_point；bore_number 规则同上。

快速上手示例：按剖切线切地形

import pandas as pd

from gdisdk.dataclass.tables import TableData
from gdisdk.modules.geoDataProcess import SliceTerrain

terrain = TableData(
    pd.DataFrame(
        {
            "x_coordinate": [0.0, 100.0, 0.0, 100.0],
            "y_coordinate": [0.0, 0.0, 100.0, 100.0],
            "z_coordinate": [0.0, 100.0, 100.0, 200.0],
        }
    ),
    name="terrain_points",
    title="地形点",
)

poly_lines = TableData(
    pd.DataFrame(
        {
            "name": ["剖面1-1", "剖面1-1"],
            "x_coordinate": [0.0, 100.0],
            "y_coordinate": [0.0, 0.0],
            "bore_number": ["ZK1", "ZK2"],
        }
    ),
    name="poly_lines",
    title="剖切线",
)

mod = SliceTerrain(mname="SliceTerrain")
mod.max_segment_length = 25.0
mod.InputTerrainPoints = terrain
mod.InputPolyLines = poly_lines

mod.execute()
terrain_3d = mod.OutputTerrainLines.data
terrain_2d = mod.Output2DTerrainLines.data

快速上手示例：自定义地形点列名

import pandas as pd

from gdisdk.dataclass.tables import TableData
from gdisdk.modules.geoDataProcess import SliceTerrain

terrain = TableData(
    pd.DataFrame(
        {
            "east": [0.0, 100.0, 0.0, 100.0],
            "north": [0.0, 0.0, 100.0, 100.0],
            "elev": [0.0, 100.0, 100.0, 200.0],
        }
    )
)

poly_lines = TableData(
    pd.DataFrame(
        {
            "name": ["A-A", "A-A"],
            "x_coordinate": [0.0, 100.0],
            "y_coordinate": [0.0, 0.0],
        }
    )
)

mod = SliceTerrain(mname="SliceTerrainByColumns")
mod.terrain_columns = ["east", "north", "elev"]
mod.max_segment_length = 0.0  # 不细分剖切线段
mod.InputTerrainPoints = terrain
mod.InputPolyLines = poly_lines

mod.execute()
terrain_3d = mod.OutputTerrainLines.data

参数说明

SliceTerrain 参数一览
参数名	类型	默认值	说明
`terrain_points`	`TableData \| None`	`None`	构造时可直接赋给 `InputTerrainPoints`；若为 `None` 则须在执行前连接端口或属性赋值。
`poly_lines`	`TableData \| None`	`None`	构造时可直接赋给 `InputPolyLines`；若为 `None` 则须在执行前连接端口或属性赋值。
`terrain_columns`	`list[str] \| None`	`None`	地形点 x/y/z 列标识（字段名或列标题），顺序为 x、y、z。为 `None` 时按 `GeneralProps` 默认字段名或标题（如 `x_coordinate` / `X坐标`）自动识别。
`max_segment_length`	`float`	`10.0`	剖切线相邻采样点的最大水平间距（米）。较长线段会先细分再插值高程；设为 `<= 0` 表示不细分，仅在剖切线顶点处采样。

Note

若 InputTerrainPoints 或 InputPolyLines 为 None，则两个输出端口均为 None。
地形点表为空、有效点不足 3 个，或 terrain_columns 长度不为 3 时，抛出 ValueError。
slice_point 为 True 的行对应剖切线 原始顶点；细分产生的中间采样点为 False。
输入剖切线未含 bore_number 列时，输出不含该列。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import ConvertToMultiProfile1D
from gdisdk.modules.geoDataProcess import ExportGeoSectionsByBores, SliceTerrain
from gdisdk.modules.gisOperators import CreatePolyLines
from gdisdk.modules.readers import GdimTableReader, GdimTerrainDataReader

pipe = PipeLine(app_name="SliceTerrainDemo", app_title="地形面切剖示例")

reader = GdimTableReader("ReadTables")
convert_bores = ConvertToMultiProfile1D("ConvertBores")
create_lines = CreatePolyLines("CreatePolyLines")
terrain_reader = GdimTerrainDataReader("TerrainReader")
terrain_reader.query_mode = "nearest_line"
slice_terrain = SliceTerrain("SliceTerrain")
export_sections = ExportGeoSectionsByBores("ExportSections")

links = (
    reader.OutputTables >> convert_bores.InputTables
    | convert_bores.OutputMultiProfile1D >> create_lines.InputMultiProfile1D
    | create_lines.OutputPolyLines >> terrain_reader.InputPolyLines
    | create_lines.OutputPolyLines >> slice_terrain.InputPolyLines
    | terrain_reader.OutputTerrainPoints >> slice_terrain.InputTerrainPoints
    | slice_terrain.OutputTerrainLines >> export_sections.InputTerrainLines
    | create_lines.OutputPolyLines >> export_sections.InputPolyLines
)
pipe.add_links(links)

pipe.add_attribute(
    attr_name="max_segment_length",
    module_name="SliceTerrain",
    param_name="max_segment_length",
    attr_title="剖切线最大段长",
)

pipe.run()

更多信息

API 参考 - modules 包
完整类定义与参数说明（geoDataProcess）
多段线表结构约定
GIS 数据操作中的 CreatePolyLines``（``InputPolyLines 来源）
地形数据读取中的 GdimTerrainDataReader

ExportGeoSectionsByBores

模块简介与适用场景

ExportGeoSectionsByBores 根据 InputPolyLines 定义的剖切线，将 InputMultiProfile1D 钻孔数据与 InputMaterialTable 岩性表合成为 **CAD 出图用地质剖面**（SectionForCadDraw 列表），并可同步输出三维剖面（Section3D 列表）。输出的 SectionBore / SectionMaterial 字段名与 GDIM 保留字段名一致（v0.3.4+），经 GeoSectionsWriter 写入 .gsc 时不再使用旧的缩写逻辑名。
剖切线支持两种定义方式（由 InputPolyLines 中 bore_number 列是否齐全决定，详见后文「剖切线定义方式说明」）：
- 钻孔定义：剖面线顶点即钻孔位置，按钻孔顺序生成剖面；
- 坐标点定义：剖面线为 XY 折线，需指定投影钻孔及可选的自定义投影坐标。
若 terrain_lines_required=True``（默认），须连接 ``InputTerrainLines``（通常来自 ``SliceTerrain）；地形线与剖切线顶点 XY 须对齐。
典型适用场景：GDIM / KCAD 地质剖面出图前，将钻孔、岩性、剖切线、地形线整合为 .gsc 或下游 AddBoreLogForGeoSections、GeoSectionsWriter 可消费的结构化剖面数据。

端口说明

输入端口 - InputMultiProfile1D：竖向钻孔数据（MultiProfile1D）。须含非空 profiles_table 与 layers_table。 - InputMaterialTable：CAD 绘图用岩性表（MaterialTable）。 - InputPolyLines：剖切线顶点表（TableData）。须含 name、x_coordinate、y_coordinate；可选 bore_number。结构遵循 PolyLinesTable。 - InputTerrainLines：沿剖切线的三维地形线（TableData），通常来自 SliceTerrain.OutputTerrainLines。terrain_lines_required=True 时为必填；须含 name、x_coordinate、y_coordinate、slice_point 等列（见 TerrainLinesTable）。
输出端口 - OutputGeoSections：SectionForCadDraw 对象列表；任一必填输入缺失或处理失败时为 None。 - OutputGeoSections3D：Section3D 对象列表；output_3d_sections=False 或 OutputGeoSections 为 None 时为 None。

剖切线定义方式说明

InputPolyLines 的解析模式由 PolyLinesTable.define_mode 自动判定：

剖切线定义方式对照
模式	判定条件	主要参数	说明
``bores``（钻孔定义）	每行 `bore_number` 均非空	`terrain_lines_required`、`use_layer_num` 等	剖面线顶点顺序即钻孔顺序；考虑地形时，地形线与钻孔重合处高程以钻孔孔口为准。
``points``（坐标点定义）	无 `bore_number` 列，或存在空值	`projected_bores`、`user_defined_projections`、`terrain_bores_alignment`	须连接非空 `InputTerrainLines`；将指定钻孔投影到剖切线后生成剖面。

快速上手示例：在 pipeline 中生成剖面

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import ConvertToMaterialTable, ConvertToMultiProfile1D
from gdisdk.modules.geoDataProcess import (
    AddLayerNumberByStdLayerTable,
    ExportGeoSectionsByBores,
    SliceTerrain,
)
from gdisdk.modules.gisOperators import CreatePolyLines
from gdisdk.modules.readers import GdimTableReader, GdimTerrainDataReader

pipe = PipeLine(app_name="ExportSectionsDemo", app_title="导出地质剖面示例")
pipe.update_gdim_state(token="你的GDIM Token", proj_id="你的GDIM项目ID")

reader = GdimTableReader("ReadTables")
reader.table_fields = ["layer_table", "standard_layer_table", "bore_table"]

add_layer_num = AddLayerNumberByStdLayerTable("AddLayerNum")
convert_material = ConvertToMaterialTable("ConvertMaterial")
convert_bores = ConvertToMultiProfile1D("ConvertBores")
create_lines = CreatePolyLines("CreatePolyLines")
terrain_reader = GdimTerrainDataReader("TerrainReader")
terrain_reader.query_mode = "nearest_line"
slice_terrain = SliceTerrain("SliceTerrain")
export_sections = ExportGeoSectionsByBores("ExportSections")

links = (
    reader.OutputTables >> add_layer_num.InputTables
    | add_layer_num.OutputTables >> convert_material.InputTable
    | add_layer_num.OutputTables >> convert_bores.InputTables
    | convert_material.OutputMaterialTable >> convert_bores.InputMaterialTable
    | convert_bores.OutputMultiProfile1D >> create_lines.InputMultiProfile1D
    | create_lines.OutputPolyLines >> terrain_reader.InputPolyLines
    | create_lines.OutputPolyLines >> slice_terrain.InputPolyLines
    | terrain_reader.OutputTable >> slice_terrain.InputTerrainPoints
    | convert_bores.OutputMultiProfile1D >> export_sections.InputMultiProfile1D
    | convert_material.OutputMaterialTable >> export_sections.InputMaterialTable
    | create_lines.OutputPolyLines >> export_sections.InputPolyLines
    | slice_terrain.OutputTerrainLines >> export_sections.InputTerrainLines
)
pipe.add_links(links)

export_sections.terrain_lines_required = True
export_sections.use_layer_num = True

pipe.run()

sections_2d = export_sections.OutputGeoSections.data
sections_3d = export_sections.OutputGeoSections3D.data

快速上手示例：坐标点定义剖面的投影参数

当 CreatePolyLines.define_poly_lines_by="points" 时，须在 ExportGeoSectionsByBores 上配置投影钻孔；user_defined_projections 可覆盖自动投影坐标。

from gdisdk.modules.geoDataProcess import ExportGeoSectionsByBores

export_sections = ExportGeoSectionsByBores("ExportSections")
export_sections.terrain_lines_required = True
export_sections.projected_bores = {
    "1-1": ["ZK1", "ZK2", "ZK3"],
    "2-2": ["ZK4", "ZK5"],
}
export_sections.user_defined_projections = {
    "1-1": {"ZK1": (100.0, 50.0)},
}
export_sections.terrain_bores_alignment = True

# 连接 InputMultiProfile1D、InputMaterialTable、InputPolyLines、InputTerrainLines 后：
export_sections.execute()
sections = export_sections.OutputGeoSections.data

参数说明

ExportGeoSectionsByBores 参数一览
参数名	类型	默认值	说明
`bores` / `material_table` / `poly_lines` / `terrain_lines`	各端口对应类型或 `None`	`None`	构造时可直接赋给对应输入端口；若为 `None` 则须在执行前连接端口或属性赋值。
`use_layer_num`	`bool`	`True`	是否使用地层编号；`False` 时按材质名自动生成编号。
`terrain_lines_required`	`bool`	`True`	是否考虑地形线。`True` 时 `InputTerrainLines` 必填，且与 `InputPolyLines` 顶点 XY 对齐；`False` 时忽略地形参与剖面生成。
`projected_bores`	`dict[str, list[str]] \| None`	`None`	仅坐标点定义模式：剖面编号到待投影钻孔编号列表的映射。
`user_defined_projections`	`dict[str, dict[str, tuple[float, float]]] \| None`	`None`	仅坐标点定义模式：剖面编号到「钻孔编号 → (X, Y) 投影坐标」的映射；与 `projected_bores` 中同孔同剖面时覆盖自动投影。
`terrain_bores_alignment`	`bool`	`False`	仅坐标点定义模式：是否将投影钻孔孔口高程与地形线对齐；`False` 时输出钻孔线仍基于原始孔口，地层线基于对齐后数据计算。
`output_3d_sections`	`bool`	`True`	是否生成 `OutputGeoSections3D`。
`pinch_type`	`int`	`1`	尖灭类型；当前仅支持 ``1``（孔上尖灭）。
`merge_interfaces`	`bool`	`True`	是否合并相邻且 `geo_id` 相同的地层界面线。
`precision_grid_size`	`float`	`0.001`	闭合区域计算用的网格步长。
`snap_tolerance`	`float`	`0.001`	闭合区域计算用的捕捉容差。

Note

InputMultiProfile1D、InputMaterialTable 或 InputPolyLines 为 None，或 profiles_table / layers_table 缺失时，两个输出均为 None。
terrain_lines_required=True 且 InputTerrainLines 为 None 时，两个输出均为 None。
坐标点定义模式下 InputTerrainLines 为空时，两个输出均为 None。
InputPolyLines 为空或缺少必填列、同一条线顶点少于 2 个时，抛出 ValueError。
projected_bores、user_defined_projections、terrain_bores_alignment 在 GDIM 界面上仅于坐标点定义模式可见（见 update_ui_schema）。

在 pipeline 中的使用方式

与「快速上手示例：在 pipeline 中生成剖面」相同；常见做法是暴露 terrain_lines_required、projected_bores 等属性供 GDIM 界面编辑：

pipe.add_attribute(
    attr_name="terrain_lines_required",
    module_name="ExportGeoSectionsByBores",
    param_name="terrain_lines_required",
    attr_title="考虑地形",
)
pipe.add_attribute(
    attr_name="projected_bores",
    module_name="ExportGeoSectionsByBores",
    param_name="projected_bores",
    attr_title="投影钻孔",
)

更多信息

API 参考 - modules 包
完整类定义与参数说明（geoDataProcess）
多段线表结构约定
上游：GIS 数据操作中的 CreatePolyLines、本文 SliceTerrain
下游：AddBoreLogForGeoSections``（补充柱状图信息）、``GeoSectionsWriter``（写出 ``.gsc）

AddBoreLogForGeoSections

模块简介与适用场景

AddBoreLogForGeoSections 从 InputTables 读取钻孔、地层、原位测试、取样等表格数据，将 柱状图出图字段 合并进 ExportGeoSectionsByBores 已生成的 SectionBore 对象中。
表格到 SectionBore 的转换逻辑与 BoreLogDrawWriter 相同（保留表名/字段名与 v0.3.4+ .gsc JSON 一致）；模块仅按剖面中出现的 bore_number 筛选并转换对应钻孔。
ExportGeoSectionsByBores 已写入的剖面几何字段（bore_mileage、bore_top、layer_bottom_elevation、layer_bottom_depth、material_id、layer_number、offset_distance）在合并时 不会被表格数据覆盖。
典型适用场景： KCAD 地质剖面 .gsc 出图前，在剖面钻孔上叠加标贯、动探、静探、取样、岩土参数等柱状图信息，再经 GeoSectionsWriter 写出文件。

端口说明

输入端口 - InputGeoSections：GeoSections``（``SectionForCadDraw 列表）。通常来自 ExportGeoSectionsByBores.OutputGeoSections，其中 SectionBore 已含剖面坐标与地层几何。 - InputTables：TableCollection。须含钻孔、地层及所需测试/取样/岩土参数表；表结构为标准 GDIM 保留名时可省略 name_maps``（可选 ``sonic_logging_table、sampling_log_table、proposed_geotechnical_parameters_table 等，规则同 BoreLogDrawWriter）。
输出端口 - OutputGeoSections：合并柱状图信息后的 GeoSections；InputGeoSections 或 InputTables 为 None 时为 None。

快速上手示例：补充剖面钻孔柱状图信息

from gdisdk.modules.geoDataProcess import AddBoreLogForGeoSections

add_bore_log = AddBoreLogForGeoSections(mname="AddBoreLog")
add_bore_log.sample_types_map = {
    "厚壁原状": 0,
    "薄壁原状": 0,
    "扰动样": 1,
    "岩石样": 2,
    "水样": 3,
}
add_bore_log.InputGeoSections = geo_sections_from_export
add_bore_log.InputTables = your_table_collection

add_bore_log.execute()
enriched_sections = add_bore_log.OutputGeoSections.data

参数说明

AddBoreLogForGeoSections 参数一览
参数名	类型	默认值	说明
`geo_sections`	`GeoSections \| None`	`None`	构造时可直接赋给 `InputGeoSections`；示例中推荐初始化后通过 `InputGeoSections` 赋值。
`tables`	`TableCollection \| None`	`None`	构造时可直接赋给 `InputTables`；示例中推荐初始化后通过 `InputTables` 赋值。
`name_maps`	`dict[str, dict[str, str]] \| None`	``None``（空字典）	输入表未使用 GDIM 保留名时的表/字段映射（`table_names` / `field_names`）；结构与 BoreLogDrawWriter 一致，键均为保留名。
`sample_types_map`	`dict[str, int] \| None`	`None`	取样类型字符串到 KCAD 整数编码的映射，例如 `{"厚壁原状": 0, "扰动样": 1}`。

Note

剖面中未出现 bore_number 时，原样透传 InputGeoSections。
InputTables 中找不到某 bore_number 时，模块发出 warnings.warn，该 SectionBore 保持 ExportGeoSectionsByBores 输出不变。
name_maps 只需映射本模块要从表格读取的表与字段；剖面几何字段由上游 ExportGeoSectionsByBores 提供，无需在 name_maps 中重复配置。

在 pipeline 中的使用方式

典型链路：ExportGeoSectionsByBores → AddBoreLogForGeoSections → GeoSectionsWriter；InputTables 可与读表模块共用同一份 TableCollection。

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.geoDataProcess import (
    AddBoreLogForGeoSections,
    ExportGeoSectionsByBores,
)
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.writers import GeoSectionsWriter

pipe = PipeLine(app_name="GeoSectionsWithBoreLog", app_title="剖面柱状图补充示例")

reader = GdimTableReader("ReadTables")
export_sections = ExportGeoSectionsByBores("ExportSections")
add_bore_log = AddBoreLogForGeoSections("AddBoreLog")
write_gsc = GeoSectionsWriter("WriteGsc")
write_gsc.gsc_file_name = "geo_sections.gsc"

links = (
    reader.OutputTables >> add_bore_log.InputTables
    | export_sections.OutputGeoSections >> add_bore_log.InputGeoSections
    | add_bore_log.OutputGeoSections >> write_gsc.InputGeoSections
)
pipe.add_links(links)
pipe.run()

sections = add_bore_log.OutputGeoSections.data

更多信息

API 参考 - modules 包
完整类定义与参数说明（geoDataProcess）
上游：本文 ExportGeoSectionsByBores
表格/字段映射参考：writers 模块帮助中的 BoreLogDrawWriter
下游：writers 模块帮助中的 GeoSectionsWriter

CalculateCorrectedBlowCount

模块简介与适用场景

CalculateCorrectedBlowCount 按所选参考规范，为标准贯入表或动力触探表逐行计算修正击数，写入 ``corrected_blow_count``（修正击数）。
当前只实现《岩土工程勘察规范》GB 50021-2001（2009 年版）：标贯按钻杆长度取校正系数；重型动力触探按杆长与换算击数查表 B.0.1；轻型、超重型直接采用实测击数。系数表与跳过规则见后文「计算规则说明」。
模块用表的 name``（或 ``table_name）识别表种，只接受 spt_table、dpt_table。参与计算的列只按字段内部名读取。某一行缺少击数、缺少总杆长，或动探类型无法识别时，该行不写入新的修正击数，并发出 GDIWarning。
典型适用场景： 统计、承载力估算或报告引用修正击数之前，把实测击数换算后写回试验表。

端口说明

输入端口 - InputTable：TableData。表名须为 ``spt_table``（标准贯入表）或 ``dpt_table``（动力触探表）。
输出端口 - OutputTable：写入 corrected_blow_count 后的试验表。InputTable 为 None 或空表时为 None。

快速上手示例：计算标贯修正击数

from gdisdk.dataclass.tables import TableData
from gdisdk.modules.geoDataProcess import CalculateCorrectedBlowCount

spt = TableData(
    {
        "bore_number": ["ZK1"],
        "blow_count": [18],
        "penetration_depth": [0.30],
        "total_rod_length": [6.5],
    },
    name="spt_table",
)

calc = CalculateCorrectedBlowCount(mname="CorrectBlow")
calc.reference_standard = "gb50021"
calc.InputTable = spt

calc.execute()
out = calc.OutputTable.data

动力触探表同样接入 InputTable，表名设为 dpt_table，并提供 ``dpt_type``（动探类型）。

参数说明

CalculateCorrectedBlowCount 参数一览
参数名	类型	默认值	说明
`table`	`TableData \| None`	`None`	构造时可直接赋给 `InputTable`；示例中推荐初始化后通过 `InputTable` 赋值。
`reference_standard`	`str`	`"gb50021"`	参考规范代码。GDIM 界面标题为「参考规范」，当前可选项只有 `gb50021`，显示名称为「《岩土工程勘察规范》GB 50021」。

输入字段

列名使用字段内部名。下表标题是 GDIM 保留字段的常见标题，模块不按标题匹配。

参与计算的字段
字段内部名	常见标题	适用表	作用
`blow_count`	击数	标贯、动探	实测击数。缺失时跳过该行。
`total_rod_length`	总杆长（m）	标贯、重型动探	钻杆长度。缺失、无法转为数字或小于 0 时跳过该行。轻型、超重型不使用。
`penetration_depth`	贯入深度	标贯、重型动探	实际贯入距离。缺失或非正时按标准贯入距离计。
`dpt_type`	动探类型	动探	区分轻型、重型、超重型。为空时按重型处理。
`corrected_blow_count`	修正击数	标贯、动探	结果列。表中没有该列时新增；跳过的行保留原值，新列中为空。

bore_number、spt_number、dpt_number、test_point_top_depth 只用于警告中的行标识，不参与计算。

计算规则说明

规范为 GB 50021-2001（2009 年版）。标贯与重型动力触探：

修正击数 = round(α × N', 2)
N' = 击数 × (标准贯入距离 / 实际贯入距离)

标贯标准贯入距离为 0.30 m，重型动力触探为 0.10 m。
penetration_depth 的数值大于 1 时按厘米换算为米（除以 100），否则按米。因此 30 与 0.30 都表示 0.30 m。空值、非数或小于等于 0 时，按上一条的标准贯入距离计，并发出 GDIWarning。

标贯校正系数 α 只随钻杆长度变化，相邻表列之间线性内插。杆长小于等于 3 m 时 α 为 1.00；大于 21 m 时按 21 m 取值，并在警告中说明。

标贯钻杆长度校正系数 α
钻杆长度 L (m)	≤3	6	9	12	15	18	21
α	1.00	0.92	0.86	0.81	0.77	0.73	0.70

重型动力触探的 α 取自规范表 B.0.1，按杆长与 N’ 双线性内插。杆长限制在 2–20 m，N’ 限制在 5–50；超出端点时用端点系数，不再另发警告。

GB 50021 表 B.0.1 重型动力触探杆长校正系数 α
杆长 L (m)	N’=5	10	15	20	25	30	35	40	50
2	1.00	1.00	1.00	1.00	1.00	1.00	1.00	1.00	1.00
4	0.96	0.95	0.93	0.92	0.90	0.89	0.87	0.86	0.84
6	0.93	0.90	0.88	0.85	0.83	0.81	0.79	0.78	0.75
8	0.90	0.86	0.83	0.80	0.77	0.75	0.73	0.71	0.67
10	0.88	0.83	0.79	0.75	0.72	0.69	0.67	0.64	0.61
12	0.85	0.79	0.75	0.70	0.67	0.64	0.61	0.59	0.55
14	0.82	0.76	0.71	0.66	0.62	0.58	0.56	0.53	0.50
16	0.79	0.73	0.67	0.62	0.57	0.54	0.51	0.48	0.45
18	0.77	0.70	0.63	0.57	0.53	0.49	0.46	0.43	0.40
20	0.75	0.67	0.59	0.53	0.48	0.44	0.41	0.39	0.36

动探类型按下面顺序识别：

含「轻型」或 N10：轻型。修正击数等于实测击数保留两位小数，不做贯入距离换算和杆长修正，并给出说明性警告。
含「超重型」或 N120：超重型。同样直接采用实测击数并保留两位小数，不发警告。
等于「重型动力触探」、含「重型」，或含 N63.5 / N63：重型，按表 B.0.1 修正。dpt_type 为空时也按重型处理。
其余取值：无法识别，跳过该行并警告。

因此 GDIM 中的「轻型动力触探」「重型动力触探」「超重型动力触探」分别对应轻型、重型、超重型。

行为与错误说明

输出是输入表的深拷贝，不修改 InputTable。
表名不是 spt_table 或 dpt_table 时，发出 GDIWarning 并返回副本，不计算、也不新增 corrected_blow_count。
reference_standard 不是已实现的规范时，同样警告并返回副本。
可计算的行写入两位小数的修正击数。跳过的行保留该列原值；列是本次新增时，这些单元格为空。
InputTable 为 None 或空表时，OutputTable 为 None。

在 pipeline 中的使用方式

先从 GDIM 表集合中取出 spt_table 或 dpt_table，再接入本模块。reference_standard 可暴露到 GDIM 界面。

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.filters import TableSelector
from gdisdk.modules.geoDataProcess import CalculateCorrectedBlowCount
from gdisdk.modules.readers import GdimTableReader

pipe = PipeLine(app_name="CorrectedBlowDemo", app_title="修正击数计算示例")
pipe.update_gdim_state(token="你的GDIM Token", proj_id="你的GDIM项目ID")

reader = GdimTableReader("ReadTables")
reader.table_fields = ["spt_table"]

pick = TableSelector("PickSpt")
pick.table_name = "spt_table"

calc = CalculateCorrectedBlowCount("CorrectBlow")

links = (
    reader.OutputTables >> pick.InputTables
    | pick.OutputTable >> calc.InputTable
)
pipe.add_links(links)
pipe.add_attribute(
    attr_name="reference_standard",
    module_name="CorrectBlow",
    param_name="reference_standard",
    attr_title="参考规范",
)
pipe.run()

out = calc.OutputTable.data

更多信息