modules.geoDataProcess 模块帮助

本章节包含 modules.geoDataProcess 中与地质 / 钻孔数据处理相关的模块说明，例如地层编号补齐、按地层编号排序、钻孔类型 KCAD 映射等。

MapBoreTypeToKCAD

模块简介与适用场景

MapBoreTypeToKCAD 将钻孔一览表中的「钻孔类型」字段值映射为 KCAD（AutoCAD/中望CAD出图插件）所使用的标准钻孔类型名称。
映射关系并非写死在代码里，而是通过 GDIM API 按当前 项目 ID 拉取：键一般为业务表中原有的钻孔类型，值为平台返回的 KCAD 选项名称（若某名称在映射中不存在，pandas Series.map 会得到缺失值）。
**输入形态**可以是：
- TableCollection：在集合中按配置的表名查找钻孔表（默认内部表名 bore_table），只改写该表中指定列；
- 单张 TableData：整张表即为钻孔一览表，按列名改写 bore_type_field。
典型适用场景：
- 钻孔布置图、平面图等下游 KCAD / CAD 绘图流程要求钻孔类型枚举与标准一致；
- 项目在 GDIM 中维护了钻孔类型对照表，希望在 Pipeline 中自动同步为最新映射。

端口说明

输入端口 - InputTables：TableCollection``（须包含配置的钻孔表）或带钻孔类型列的 ``TableData。 - InputToken：(token, proj_id, host)。若 Pipeline 已通过 pipeline.update_gdim_state(token=..., proj_id=..., host=...) 配置运行上下文，可不连接此端口，模块会从 Pipeline 自动取 token 与项目信息。
输出端口 - OutputTables：与输入同类；为 拷贝后 写回映射结果后的 TableCollection 或 TableData。

当 InputTables 为空、或无法解析有效 token 时，OutputTables 为 None。

快速上手示例：单表映射

from gdisdk.modules import MapBoreTypeToKCAD

mapper = MapBoreTypeToKCAD(
    mname="MapBoreTypes",
    token="你的GDIM Token",
    proj_id="你的GDIM项目ID",
    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",
    token="你的GDIM Token",
    proj_id="你的GDIM项目ID",
    bore_table_name="bore_table",   # 集合内表名或表标题，与 get_table 约定一致
    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。

行为与错误说明

钻孔类型列的值经 Series.map(mapping_dict) 替换；映射表中没有的键会变成 pandas 中的缺失标记，请结合业务决定是否在前游清洗或使用 fillna。
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 是 GDIM 相关模块：当 layer_table (地层表) 中没有 layer_number (地层编号) 字段时，依据 standard_layer_table (标准地层表) 的 layer_number 数据为 layer_table 补充 layer_number 列。
模块会从 GDIM 模板（pipeline.gdim_template 或通过 token 拉取）中读取 standard_layer_update.define_layer_fields，据此寻找 layer_table 与 standard_layer_table 的公共字段并进行 join。
典型适用场景：
- 业务流程要求 layer_table 必须包含 layer_number 字段，但项目数据缺失该列；
- 标准地层配置使用 “autoGeneration” 自动确定地层字段时，需要为 layer_table 回填 layer_number。

端口说明

输入端口 - InputTables：输入表集合（TableCollection，需包含 layer_table 与 standard_layer_table） - InputToken：GDIM 访问 token 信息（Token；仅当 pipeline 未提供 gdim_template/token 时需要）
输出端口 - OutputTables：输出表集合（TableCollection，其中 layer_table 将新增 layer_number 列）

快速上手示例：在 pipeline 中从 GDIM 读取并补齐地层编号

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="补齐地层编号示例")

# 建议在 pipeline 上设置 token/proj_id（模块内部 get_token 会优先取 pipeline 的值）
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

参数说明

AddLayerNumberByStdLayerTable 参数一览
参数名	类型	默认值	说明
`layer_table_name`	`str \| None`	`None`	layer 表名/标题；不传则默认 `"layer_table"`。
`layer_number_name`	`str \| None`	`None`	新增的地层编号字段 name；不传则默认 `"layer_number"`。
`layer_number_title`	`str \| None`	`None`	新增字段 title；不传则默认 `"地层编号"`。
`token / proj_id / host`	`str \| int\|str \| str \| None`	`None`	鉴权与项目定位信息；若未显式传入，模块会尝试从 pipeline 获取，也可通过输入端口 `InputToken` 传入。

Note

输入集合必须包含 standard_layer_table，且其中必须有 layer_number 列。
若 join 后存在缺失的 layer_number``（NaN），模块会抛出 ``ValueError 指出第一条缺失的组合值。

更多信息

SortByLayerNumber

模块简介与适用场景

SortByLayerNumber 用于按 “地层编号” 对表格进行排序，支持两类输入：
- TableData：直接对该表排序；
- TableCollection：对集合中指定的 layer 表排序（默认 layer_table），并输出排序后的集合。
排序使用内部的 sort_layer_numbers 逻辑，支持常见地层编号的自然排序规则（并可容忍部分非标准值）。
典型适用场景：
- 绘图/剖面/汇总前需要确保 layer 表按地层编号有序；
- 数据导出前统一层序顺序。

端口说明

输入端口 - InputTable：输入数据（TableData 或 TableCollection）
输出端口 - OutputTable：排序后的数据（TableData 或 TableCollection；与输入类型一致）

快速上手示例：排序单张 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("Sort")
sort_mod.InputTable = table
sort_mod.order = "ascending"
out = sort_mod.execute()

参数说明

SortByLayerNumber 参数一览
参数名	类型	默认值	说明
`order`	`Literal["ascending", "descending"]`	`"ascending"`	升序/降序。
`layer_table_name`	`str \| None`	`None`	当输入为 `TableCollection` 时，指定要排序的表名/标题；不传默认 `"layer_table"`。
`layer_number_column`	`str \| None`	`None`	地层编号列名/标题；不传默认 `"layer_number"`。

Note

当找不到地层编号列时，模块会发出 warning 并返回原表（不强制报错）。

在 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="地层编号排序示例")

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

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

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

更多信息