modules.writers 模块帮助

本章节包含 modules.writers 包中常用「数据写入 / 导出」模块的使用说明和示例，例如：

写入 GDIM 表格、文件服务器或本地文件的模块
更新 GDIM「项目信息」应用（项目元数据与坐标系统）的模块
导出 Word / Excel 报告的模块
导出 KCAD 出图用 .gsc 文件的模块

DocDataWriter

模块简介与适用场景

DocDataWriter 将 SingleResult / TableData / TableCollection / 文件路径等输入转换为 DocData``（端口：``OutputDocData），供 :class:`gdisdk.modules.writers.DocPrinter`（Word）或 :class:`gdisdk.modules.writers.ExcelPrinter`（Excel）基于模板渲染输出。

Hint

DocData``（``data / doc_keys_struct）结构与导出方法说明，见 DocData：报告打印的数据容器（模板 keys 与渲染数据）。

端口说明

输入端口 - InputData：输入数据（SingleResult / TableData / TableCollection / FilePath / FilesPath）
输出端口 - OutputDocData：输出文档数据（DocData，可直接用于 DocPrinter / ExcelPrinter 渲染）

快速上手示例：将 GDIM 表格转换为 DocData，并导出模板变量结构

from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.writers import DocDataWriter
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="GenerateDocKeys", app_title="导出模板变量结构示例")
pipeline.workspace = "test"

read_table = GdimTableReader(mname="ReadTable")
read_table.table_fields = ["钻孔一览表"]

doc_data = DocDataWriter(mname="DocData")
doc_data.precision = 2  # 所有数值保留 2 位小数

links = read_table.OutputTables >> doc_data.InputData
pipeline.add_links(links)
pipeline.run()

# 导出模板变量结构（用于模板中 {{key}} / 表格循环等配置）
doc_data.OutputDocData.data.export_keys_to_json("bore_table_doc_keys.json")

# （可选）导出打印数据（用于检查最终会写进报告的内容）
doc_data.OutputDocData.data.export_data_to_json("bore_table_doc_data.json")

参数说明

DocDataWriter 参数一览
参数名	类型	默认值	说明
`precision`	`int \| dict[str, int \| None] \| None`	`None`	数值格式化小数位数；支持统一 `int` 或按 “字段名/字段标题（SingleResult 也支持 result 名/标题）” 分别配置。
`datetime_format`	`str \| dict[str, str \| None] \| None`	`None`	日期时间格式化（strftime）；支持统一 `str` 或按字段分别配置。
`merge_strategy`	`"auto" \| "none" \| "explicit"`	`"auto"`	仅对 `TableCollection` 生效：是否按主子表关系合并（`auto`）、完全不合并（`none`）、或按 `explicit_merges` 指定合并规则（`explicit`）。
`explicit_merges`	`list[dict[str, str \| list[str]]] \| None`	`None`	仅 `merge_strategy="explicit"` 时生效；指定 main/subs/group_by 等合并规则。
`table_doc_key_name`	`str \| None`	`None`	仅对 `TableData` 或 “只含 1 张表的 TableCollection” 生效：表格在 `DocData` 中的 key；未设置时默认使用 ``TableData.name``（若 name 为空会报错）。
`table_doc_key_title`	`str \| None`	`None`	仅对 `TableData` 或 “只含 1 张表的 TableCollection”生效：表格在 doc keys 中展示的标题；未设置时默认使用 `TableData.title`。
`joiner`	`str`	`,`	仅对 `SingleResult` 生效：当某个 result 的值是 list 时，使用 joiner 拼接为字符串。
`files_path_to_list`	`str \| None`	`None`	仅对文件列表输入生效，控制多个文件如何写入 `DocData`。非 `None` 时，将整个列表合并写入一个 key（值为路径列表，`DocPrinter` 按 `ImagesPath` / `FilesPath` 批量插入图片或子文档）；为 `None` 时，每个文件各自占一个 key（key 取自文件名 stem，`-` 转为 `_`），适合在模板中分别引用。
`files_path`	`list[str] \| list[Path] \| list[dict] \| None`	`None`	若设置则忽略 `InputData`，直接将 `files_path` 作为文件列表输入（常用于将若干图片或子文档合并/插入到主模板数据中）。`list[dict]` 用于 GDIM 平台上传后的文件对象；`list[str]` / `list[Path]` 用于本地路径。写入方式见 `files_path_to_list`。
`latex_to_unicode_keys`	`str \| list[str] \| dict[str, str \| list[str]] \| None`	`None`	将指定 key 的字符串值从 LaTeX 转为 Unicode（例如 `\\alpha→α` ， `H_{2}O→H₂O` ），便于直接打印模型公式等；支持根级 key、表格列 key 以及混合模式（`"__root__"`）。

files_path 用法示例

doc = DocDataWriter(mname="SubDocWriter")

# files_path_to_list 非 None：合并为一个 key（适合模板中批量插入子文档）
doc.files_path = ["appendix/report_a.docx", "appendix/report_b.docx"]
doc.files_path_to_list = "appendix_docs"

doc.execute()
print(doc.OutputDocData.data)

doc = DocDataWriter(mname="ImageDoc")

# files_path_to_list 为 None（默认）：每个文件各自一个 key（key 为文件名 stem）
doc.files_path = ["images/plot_a.png", "images/plot_b.png"]

doc.execute()
print(doc.OutputDocData.data)

latex_to_unicode_keys 用法示例

# 1) 根级 key（单个 / 多个）
doc = DocDataWriter(mname="Doc")
doc.latex_to_unicode_keys = "model_expression"
# 或
doc.latex_to_unicode_keys = ["model_expression", "formula"]

# 2) 表格列 key（dict 模式）
doc.latex_to_unicode_keys = {"table1": "column1"}
# 或
doc.latex_to_unicode_keys = {"table1": ["col1", "col2"]}

# 3) 混合模式（dict + "__root__"）
doc.latex_to_unicode_keys = {"__root__": ["key1"], "table1": ["col1"]}

说明：

key 支持使用 字段名 或 **字段标题**（会按 doc keys 结构自动映射）
仅对 字符串值 生效，非字符串值保持不变
支持常见 LaTeX 语法（希腊字母、分数、根号、上下标、无穷大等）

上传 GDIM 前检查

是否需要特别处理：当 files_path 中的图片或子文档需要由 GDIM 前端上传、选择或在平台运行时提供时，是。
必须检查：
- 不要再依赖本机绝对路径或仅本地存在的相对路径；上传后的推荐方式是由前端传入 GDIM 文件描述（list[dict]），并绑定到 pipeline attribute 赋给 files_path；
- 建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``list[dict]``） 提供，这是上传后的推荐方式。
建议检查：
- 配合 files_path_to_list 指定写入 DocData 的 key，便于后续 DocPrinter 在模板中引用；
若遗漏，常见现象：
- 本地调试可正常读取固定路径文件，但上传 GDIM 后报“文件不存在”。

在 pipeline 中的使用方式：组合多个 DocDataWriter 并合并

当报告需要同时写入多份数据（例如：指标结果 + 图像 + 多张表格），常见做法是 “多个 DocDataWriter + MergeDocData 合并后再打印”：

from gdisdk.modules.writers import DocDataWriter, MergeDocData

data_doc = DocDataWriter(mname="DataDoc")   # 例如：TableCollection / TableData
image_doc = DocDataWriter(mname="ImageDoc") # 例如：图片路径（OutputImageFile）

merge_doc = MergeDocData(mname="MergeDoc")
merge_doc.add_dynamic_ports_in("InputDataDocData")
merge_doc.add_dynamic_ports_in("InputImageDocData")

links = data_doc.OutputDocData >> merge_doc.InputDataDocData | image_doc.OutputDocData >> merge_doc.InputImageDocData

更多信息

TextWriter

模块简介与适用场景

TextWriter 用于将纯文本字符串、JSON 对象或 ResultModel 写入本地文本文件。
适合将 Markdown、提示词、LLM 输出、结构化结果模型、配置 JSON、调试文本等结果落盘，便于下载、归档或继续传给下游系统。

端口说明

输入端口 - InputText：输入文本、JSON 对象或 ResultModel``（会通过 ``to_plain_text 转为纯文本后再写入） - InputToken：鉴权与项目定位信息 (token, proj_id, host)；若未提供则可从 pipeline.gdim_state 获取
输出端口 - OutputFile：输出文件（本地保存时为 FilePath，上传 GDIM 时为 GdimFile）

快速上手示例：写出 Markdown 文件

from gdisdk.modules.writers import TextWriter

writer = TextWriter(mname="TextWriter")
writer.text = "# 结果摘要\n\n- 项目：示例项目\n- 结论：可行"
writer.output_dir = "workspace"
writer.output_name = "summary"
writer.suffix = "md"

writer.execute()
print(writer.OutputFile.data)

快速上手示例：写出 JSON 文件

from gdisdk.modules.writers import TextWriter

writer = TextWriter(mname="TextWriter")
writer.text = {"project": "Demo", "score": 95, "passed": True}
writer.output_name = "result"
writer.suffix = "json"
writer.json_indent = 2

writer.execute()
print(writer.OutputFile.data)

参数说明

TextWriter 参数一览
参数名	类型	默认值	说明
`result_model_keys`	`list[str] \| None`	`None`	当 `InputText` 为 `ResultModel` 时，仅按给定顺序写出这些字段（字段名或展示标题）；为 `None` 时写出模块逻辑允许的各字段（定义顺序）。
`result_model_value_separator`	`str`	`"\n\n"`	当 `InputText` 为 `ResultModel` 时，用于连接字段值序列中的条目以及相邻字段渲染结果（参见 `ResultModel.to_plain_text`）。
`output_dir`	`str \| None`	`None`	输出目录；若 pipeline 设置了 `workspace`，则优先使用 workspace；两者都为空时使用当前工作目录。
`output_name`	`str`	`"output"`	输出文件名（不含扩展名）。
`suffix`	`str`	`"txt"`	输出文件后缀名（不含前导点），例如 `"md"`、`"json"`、`"csv"`。
`encoding`	`str`	`"utf-8"`	写文件时使用的文本编码。
`save_to_gdim`	`bool`	`False`	是否将文件同时上传到 GDIM 文件服务器；为 `True` 时需要可用的 token/proj_id/host。
`token`	`str \| None`	`None`	GDIM 用户 token；通常更推荐通过 `pipeline.update_gdim_state(...)` 统一设置。
`proj_id`	`int \| str \| None`	`None`	GDIM 项目 ID；可通过 `InputToken` 或 `pipeline.gdim_state` 提供。
`host`	`str \| None`	`None`	GDIM 平台地址；通常沿用 pipeline 中的 GDIM 状态即可。
`json_indent`	`int \| None`	`2`	当输入为 `dict` / `list` 时，序列化为 JSON 字符串的缩进；为 `None` 时输出紧凑 JSON。当输入为 `ResultModel` 时，传给 `to_plain_text`，亦用于字段内嵌 `dict` 等值的 JSON 格式化。

上传 GDIM 前检查

是否需要特别处理：当文本文件需要在 GDIM 中留存、回传或提供给后续节点下载时，是。
必须检查：
- 将 save_to_gdim 设为 True，否则结果只会保存在本地路径。
建议检查：
- suffix 设为明确的业务格式，如 md、json、csv，方便下游识。
若遗漏，常见现象：
- 本地运行能生成文件，但上传 GDIM 后拿不到期望的 GdimFile 输出；
- 下游系统拿到文件后无法按预期格式解析，例如把 Markdown 当成普通 txt。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import TableToMarkdown
from gdisdk.modules.writers import TextWriter

pipeline = PipeLine(app_name="WriteMarkdownDemo", app_title="写出Markdown文件")
pipeline.workspace = "workspace"

to_md = TableToMarkdown(mname="ToMarkdown")
writer = TextWriter(mname="WriteMarkdown")
writer.output_name = "table_result"
writer.suffix = "md"

# links = upstream.OutputTable >> to_md.InputTable | to_md.OutputMarkdown >> writer.InputText
# pipeline.add_links(links)
# pipeline.run()

更多信息

ExportGdimTables

模块简介与适用场景

ExportGdimTables 将 GDIM 表格数据导出为 .gtb 或 .xlsx 文件（端口：OutputFile），适合读出项目表格后打包给外部系统、人工下载或二次导入。
导出格式（gtb / xlsx）见参数 format；导出文件会同时保留表/字段的 title 与 name 信息：
- 每张表的 CSV 文件名 / Excel 工作表名优先使用表标题，元数据中同时记录内部名、标题和工作表名；
- 每张表的第 1 行写字段标题，第 2 行写字段内部名，第 3 行写字段单位（input / number 类型字段可带单位；无单位时填 -），数据从第 4 行开始；
- 当 export_fields_description=True 时，第 4 行写入字段描述（数据类型及格式提示），数据从第 5 行开始。
metadata 中还包含：
- tableRelations：主表 / 子表关系（需提供有效 token 时从 GDIM 模板结构获取）；
- coordinateSystem：项目坐标系统设置（需提供有效 token 时从项目信息获取）；
- templateInstruction：表头布局说明。

端口说明

输入端口 - InputTables：待导出的表格数据（TableCollection 或 TableData） - InputTemplateId：项目资料中的模板信息（ResultModel，需包含 dataTemplateId） - InputToken：鉴权与项目定位信息 (token, proj_id, host)；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取
输出端口 - OutputFile：导出结果；本地保存时为 FilePath，上传 GDIM 时为 GdimFile

快速上手示例：导出 GDIM 表格为 Excel

from gdisdk.connectors import log_in
from gdisdk.modules.readers import GdimAppProjectInfoReader, GdimTableReader
from gdisdk.modules.writers import ExportGdimTables
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="ExportGdimTablesDemo", app_title="导出GDIM表格示例")
pipeline.workspace = "test"
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_tables = GdimTableReader(mname="ReadTables")
read_tables.table_fields = ["钻孔一览表", "地层信息表"]

read_project_info = GdimAppProjectInfoReader(mname="ReadProjectInfo")

export_tables = ExportGdimTables(mname="ExportTables")
export_tables.format = "xlsx"
export_tables.output_name = "项目表格导出"
export_tables.export_fields_description = True  # 可选：导出字段描述行

links = (
    read_tables.OutputTables >> export_tables.InputTables
    | read_project_info.OutputProjectInfo >> export_tables.InputTemplateId
)
pipeline.add_links(links)

pipeline.run()
print(export_tables.OutputFile.data)

参数说明

ExportGdimTables 参数一览
参数名	类型	默认值	说明
`format`	`"gtb" \| "xlsx"`	`"gtb"`	导出格式。`gtb` 适合 GDIM 兼容交换；`xlsx` 适合人工查看和通用 Excel 流程。
`output_dir`	`str \| None`	`None`	输出目录；若 pipeline 设置了 `workspace`，则优先使用 workspace。
`output_name`	`str`	`"gdim_tables"`	导出文件名（不含扩展名）。
`save_to_gdim`	`bool`	`False`	是否将导出结果上传到 GDIM 文件服务器；为 `True` 时需要可用的 token/proj_id/host（可从 pipeline 获取）。
`export_fields_description`	`bool`	`False`	是否在每张表第 4 行写入字段描述（数据类型及格式提示）；开启后数据从第 5 行开始。

上传 GDIM 前检查

是否需要特别处理：当导出的表格文件需要在 GDIM 中回传、下载或被后续流程消费时，是。
必须检查：
- 将 save_to_gdim 设为 True，否则结果只会保存在本地路径；
建议检查：
- output_name 设为清晰稳定的文件名，便于在 GDIM 文件列表中识别。
若遗漏，常见现象：
- 本地运行能生成文件，但上传 GDIM 后拿不到期望的 GdimFile 输出；

更多信息

GdimTableWriter

模块简介与适用场景

GdimTableWriter 将 ResultModel、TableData、TableCollection、GeneralTable 或 NumberTable 写入 GDIM 项目的业务表。
同一张表可以同时包含插入、更新、删除行。删除先于插入/更新执行，墓碑行不会进入字段校验。

写入行为（如何理解 ``gdim_id``）

插入：没有 ``gdim_id``（或值为空）的行，调用 GDIM 接口新增数据。
更新：gdim_id 有值、且至少还有一个业务字段非空的行，写入时做部分更新，未出现的列保持原值。
删除：gdim_id 有值、且其余列全部为空（None / NaN）的行视为墓碑行。写入前先调用 GDIM 接口删除 id 相同的行，再写入剩余行。
墓碑行必须与插入/更新行共用**完整 GDIM schema**（只把业务列留空），不能做成只有 gdim_id 一列。
这类墓碑行通常由 MergeGdimTables 的 1:N overwrite 产出；模块本身不负责生成墓碑行。
若删除墓碑行后没有剩余数据，只要删除成功，该表视为写入成功，不会报「没有可写入 GDIM 的数据」。

Hint

需要更新或删除已有记录时：

从 GDIM 读取时将 GdimTableReader.keep_gdim_id 设为 True；
新数据与旧数据混合回写时，用 MergeGdimTables 生成 gdim_id / 墓碑行；
GdimTableWriter 按上一节规则自动插入、更新或删除。

端口说明

输入端口 - InputData：待写入的数据（ResultModel / TableData / TableCollection / GeneralTable / NumberTable） - InputToken：鉴权与项目定位信息 (token, proj_id, host)。若 pipeline 已通过 update_gdim_state(token=..., proj_id=...) 配置 gdim_state，可从pipeline自动取得 token，该端口可不连接；否则需提供 token。若构造函数里已经设置 proj_id，则该值优先级高于 InputToken 或 pipeline.gdim_state 中的项目 ID。
输出端口 - 无专门输出端口；execute 在全部写入成功（write_table_data 返回空错误字典）时返回 True。缺少 token、InputData 为空、或无法取得项目 ID（构造参数 proj_id、InputToken、pipeline gdim_state 均无有效 proj_id）时返回 None。raise_error=True 时，校验失败或接口错误通常直接抛错；raise_error=False 时失败信息以 warning 形式汇总，若仍有部分数据成功写入则可能返回 True，全部失败则可能返回 None。若某表仅因空表导致“没有可写入 GDIM 的数据”而失败，提示类型由 empty_warning_type 控制；其他校验或写入失败则始终以 GDIDataQualityWarning 提示。

快速上手示例：将表格数据写入 GDIM 指定表

from gdisdk.connectors import log_in
from gdisdk.dataclass import TableData
from gdisdk.modules.writers import GdimTableWriter
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="GdimTableWriterDemo", app_title="写入GDIM表示例")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

table = TableData(
    data={
        "钻孔编号": ["ZK-001", "ZK-002"],
        "孔口高程": [12.35, 14.10],
    },
    name="borehole_summary",
    title="钻孔一览表",
)

writer = GdimTableWriter(mname="WriteTable")
writer.InputData = table
writer.table_names = "钻孔一览表"

pipeline.add_module(writer)
pipeline.run()

快速上手示例：更新 GDIM 中已有记录

from gdisdk.connectors import log_in
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.writers import GdimTableWriter
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="UpdateGdimTableDemo", app_title="更新GDIM记录示例")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_table = GdimTableReader(mname="ReadTable")
read_table.table_fields = ["钻孔一览表"]
read_table.keep_gdim_id = True

writer = GdimTableWriter(mname="WriteBack")
writer.table_names = "钻孔一览表"

# 实际使用时，通常会在两者之间插入清洗、计算或合并模块
links = read_table.OutputTableData >> writer.InputData
pipeline.add_links(links)

pipeline.run()

快速上手示例：写入 MergeGdimTables 的 1:N 替换结果（先删后插）

from gdisdk.modules.mergers import MergeGdimTables
from gdisdk.modules.writers import GdimTableWriter

merge = MergeGdimTables(mname="ReplaceByBore")
merge.how = "overwrite"
merge.join_key = "bore_number"
# merge.InputTables = new_rows
# merge.InputGdimTables = existing_gdim_rows  # keep_gdim_id=True
merge.execute()

writer = GdimTableWriter(mname="WriteRockCoreRate")
writer.table_names = "rock_core_rate_table"
writer.InputData = merge.OutputTables.data
writer.execute()
# 墓碑行先按 id 删除，其余行作为新记录插入

参数说明

GdimTableWriter 参数一览
参数名	类型	默认值	说明
`table_names`	`str \| list[str] \| None`	`None`	目标表名或表标题（会先按表名匹配，再按表标题）。为 `None` 时，`TableData` / `TableCollection` 使用数据对象自带的表名/标识；非 `None` 时，对 `TableData` / `TableCollection` 会忽略数据内部自带的表名，以本参数为准。若传入 `list`，要求输入为 `TableCollection` 且与集合长度一一对应。
`fields_mapping`	`dict[str, str] \| dict[str, dict[str, str]] \| None`	`None`	源字段到 GDIM 字段的映射。`dict[str, str]` 时，键可为源列名或字段标题，值可为 GDIM 字段名或字段标题；`dict[str, dict[str, str]]` 时，外层键为表名或表标题，内层为对应字段映射。未定义的字段沿用原列名或标题匹配。为 `None` 时不做显式映射。示例：`{"source_col": "target_field"}`、`{"源标题": "目标标题"}`、`{"钻孔一览表": {"孔口高程": "elevation"}}`。
`raise_error`	`bool`	`True`	写入失败时的严格程度。`True` 时，任一张表写入失败即中止，仅当全部表都成功时模块才视为执行成功。`False` 时，失败信息以 warning 形式记录并继续写后续表；只要至少有一张表写入成功，模块仍可视为执行成功。
`empty_warning_type`	`"warning" \| "gdi_warning"`	`"warning"`	某表没有可写入 GDIM 的行时的提示方式。`"warning"`：仅在控制台输出 `UserWarning`；`"gdi_warning"`：抛出 `GDIDataQualityWarning`，在 GDIM 界面可见。
`strict_datetime_validation`	`bool`	`True`	时间类字段校验策略。`True`：正则结合日期时间解析（较慢、更准确）；`False`：仅用正则（较快、略宽松）。
`validation_level`	`"fast" \| "full"`	`"full"`	写入前的数据校验级别。`"fast"`：仅向量化运算与基础类型检查（最快）；`"full"`：完整校验，含复杂结构检查（较慢、最准确）。
`auto_convert`	`bool`	`False`	是否在校验前按 GDIM 控件类型自动转换列值。`True` 时会做安全转换，例如数值转文本、日期时间转格式化字符串、数字字符串转数值。默认 `False`，保持严格校验行为。
`token`	`str \| None`	`None`	GDIM 用户 token。一般更推荐通过 `pipeline.update_gdim_state(...)` 统一设置。
`proj_id`	`int \| str \| None`	`None`	GDIM 项目 ID。若构造函数中显式设置，该值优先级高于 `InputToken` 或 `pipeline.gdim_state.proj_id`。
`host`	`str \| None`	`None`	GDIM 平台地址；通常沿用 pipeline 中的 GDIM 状态即可。

上传 GDIM 前检查

是否需要特别处理：当 pipeline 要在 GDIM 平台中运行，并直接把结果写回项目表时，是。
必须检查：
- 若目标是更新已有记录而非新增，必须确保写入数据里保留了 gdim_id；
- 若目标是替换子表整组（MergeGdimTables 1:N overwrite），必须把墓碑行原样交给 writer（gdim_id + 其余列为空），不要在写入前丢掉这些行；
建议检查：
- 对日期时间类字段较多的数据，优先保持 strict_datetime_validation=True 和 validation_level="full"，先保证数据质量再考虑提速；
- 若数据来自 Excel、CSV 等外部来源且类型与 GDIM 字段不完全一致，可尝试 auto_convert=True 以减少类型校验失败；
若遗漏，常见现象：
- 看起来模块运行成功，但数据没有写入预期的 GDIM 表；
- 原本希望覆盖旧记录，结果在表中新增了重复记录；
- 子表整组替换时旧行仍在，通常是墓碑行未送到 writer，或 gdim_id 丢失后全部变成插入；

更多信息

MergeDocData

模块简介与适用场景

MergeDocData 将多个 DocData 合并为一个 DocData``（端口：``OutputDocData）。
合并时若出现重复 key，会自动在后续重复项上追加 _1、_2 等后缀，并给出 warning，避免覆盖已有数据。

Hint

合并后的 DocData 同样可以通过 export_keys_to_json / export_data_to_json 导出查看（见 DocData：报告打印的数据容器（模板 keys 与渲染数据）），便于排查 “合并后 key 是否冲突 / 数据是否符合预期”。

端口说明

输入端口 - 动态输入端口：通过 add_dynamic_ports_in("InputXXX") 添加；每个动态端口的数据类型均为 DocData``（通常接 ``DocDataWriter.OutputDocData）
输出端口 - OutputDocData：输出合并后的文档数据（DocData）

快速上手示例：合并两份 DocData

from gdisdk.modules.writers import DocDataWriter, MergeDocData

doc_a = DocDataWriter(mname="DocA")
doc_b = DocDataWriter(mname="DocB")

merge_doc = MergeDocData(mname="MergeDoc")
merge_doc.add_dynamic_ports_in("InputA")
merge_doc.add_dynamic_ports_in("InputB")

links = doc_a.OutputDocData >> merge_doc.InputA | doc_b.OutputDocData >> merge_doc.InputB

参数说明

MergeDocData 参数一览
参数名	类型	默认值	说明
`all_ports_required`	`bool`	`True`	为 True 时：只有当所有动态输入端口都有数据（不为 None）时才输出合并结果；任一端口为 None 则输出 None（常用于阻塞式等待所有分支完成）。

Hint

DocDataWriter 在输入数据 “为空但不为 None” （例如空表/空结果）时，会输出一个空的 DocData(data={}, doc_keys_struct={})，这通常有助于在 all_ports_required=True 时避免因为 “空数据” 而阻塞合并。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.writers import DocDataWriter, MergeDocData, DocPrinter

pipeline = PipeLine(app_name="MergeDocDataDemo", app_title="合并文档数据示例")
pipeline.workspace = "test"

doc1 = DocDataWriter(mname="Doc1")
doc2 = DocDataWriter(mname="Doc2")

merge_doc = MergeDocData(mname="MergeDoc")
merge_doc.add_dynamic_ports_in("InputDoc1")
merge_doc.add_dynamic_ports_in("InputDoc2")

printer = DocPrinter(mname="PrintDoc")
printer.template = "test/template.docx"
printer.output_name = "merged.docx"

links = (
    doc1.OutputDocData >> merge_doc.InputDoc1
    | doc2.OutputDocData >> merge_doc.InputDoc2
    | merge_doc.OutputDocData >> printer.InputDocData
)
pipeline.add_links(links)
pipeline.run()

更多信息

DocPrinter

模块简介与适用场景

DocPrinter 将 DocData 渲染为 .docx 文档（端口：OutputFile），常用于基于 Word 模板生成自动报告。

端口说明

输入端口 - InputDocData：输入文档数据（DocData） - InputToken：鉴权与项目定位信息 (token, proj_id, host)；仅当 save_to_gdim=True 时需要；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取
输出端口 - OutputFile：输出文件（本地保存时为 FilePath/FilesPath；上传 GDIM 时为 GdimFile/GdimFiles）

快速上手示例：打印 Word 报告

from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.writers import DocDataWriter, DocPrinter
from gdisdk.pipeline import PipeLine
from gdisdk.connectors import log_in

pipeline = PipeLine(app_name="GenerateDoc", app_title="生成报告示例")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)
pipeline.workspace = "test"

read_table = GdimTableReader(mname="ReadTable")
read_table.table_fields = ["钻孔一览表"]

doc_data = DocDataWriter(mname="DocData")
doc_data.precision = 2

print_doc = DocPrinter(mname="PrintDoc")
print_doc.template = "test/钻孔一览表模板.docx"
print_doc.output_name = "钻孔一览表.docx"

links = (
    read_table.OutputTables >> doc_data.InputData
    | doc_data.OutputDocData >> print_doc.InputDocData
)
pipeline.add_links(links)
pipeline.run()

print(print_doc.OutputFile.data)

参数说明

DocPrinter 参数一览
参数名	类型	默认值	说明
`template`	`str \| Path \| dict \| list[str \| Path \| dict] \| None`	`None`	Word 模板（单个或多个）；为 `None` 时模块不执行并输出 `None`。
`output_name`	`str \| list[str] \| None`	`None`	输出文件名；为 `None` 时默认使用 `{template_stem}_printed.docx`。
`output_dir`	`str \| Path \| None`	`None`	输出目录；若 pipeline 设置了 `workspace`，则优先使用 workspace。
`image_size_type`	`"width" \| "height" \| dict[str, "width" \| "height"]`	`"width"`	图片缩放按宽或按高；也可按 key 分别配置。
`image_size`	`float \| int \| dict[str, float \| int] \| dict[str, list[float \| int]] \| None`	`None`	图片大小（mm）；可统一、按 key 配置，或按 key 为 “图片列表” 逐张配置。
`save_to_gdim`	`bool`	`False`	是否将生成的文档上传到 GDIM 文件服务器；为 `True` 时需要可用的 token/proj_id/host（可从 pipeline 获取）。

上传 GDIM 前检查

是否需要特别处理：当该模块的输出文件需要在 GDIM 中留存、回传或被后续流程消费时，是。
必须检查：
- 将 save_to_gdim 设为 True，否则结果通常只会保存在本地路径；
- 不要依赖模块里单独写死的运行时 GDIM 参数；
- 模板建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``dict``） 提供，这是上传后的推荐方式。
建议检查：
- output_name 设为清晰、稳定的文件名，便于结果识别；
- 若仍保留本地模板路径写法，应明确这是本地调试用配置；上传时以前端传入的文件描述为准。
若遗漏，常见现象：
- 本地运行能生成 .docx 文件，但上传 GDIM 后，拿不到期望的 GdimFile / GdimFiles 输出。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.writers import DocDataWriter, DocPrinter

pipe = PipeLine(app_name="DocPrinterDemo", app_title="打印 Word 示例")
# pipe.update_gdim_state(token="...", proj_id="...")
pipe.workspace = "test"

doc_data = DocDataWriter(mname="DocData")
printer = DocPrinter(mname="PrintDoc")
printer.template = "test/template.docx"
printer.output_name = "output.docx"
# printer.save_to_gdim = True

# links = doc_data.OutputDocData >> printer.InputDocData
# pipe.add_links(links)
# pipe.run()

更多信息

ExcelPrinter

模块简介与适用场景

ExcelPrinter 将 DocData 渲染为 .xlsx 文档（端口：OutputFile），常用于按固定 Excel 模板导出业务表格或第三方格式（如 GEO5三维地质建模）。

端口说明

输入端口 - InputDocData：输入文档数据（DocData） - InputToken：鉴权与项目定位信息 (token, proj_id, host)；仅当 save_to_gdim=True 时需要；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取
输出端口 - OutputFile：输出文件（本地保存时为 FilePath/FilesPath；上传 GDIM 时为 GdimFile/GdimFiles）

快速上手示例：按模板导出 Excel（GEO5 示例）

from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.widgets import PythonCoder
from gdisdk.modules.writers import DocDataWriter, ExcelPrinter
from gdisdk.pipeline import PipeLine
from gdisdk.connectors import log_in

pipeline = PipeLine(app_name="GenerateGeo5Tables", app_title="导出GEO5格式Excel")
pipeline.workspace = "test"
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)
pipeline.local_functions_path = "pipelineImages/gdim/appDataExchange/GenerateGeo5Tables.py"

reader = GdimTableReader(mname="Reader")
reader.table_fields = ["bore_table", "layer_table"]

generate_geo5_tables = PythonCoder(mname="GenerateGeo5Tables")
generate_geo5_tables.add_dynamic_ports_in("InputTables")
generate_geo5_tables.add_dynamic_ports_out("OutputTables")
generate_geo5_tables.local_function_name = "GenerateGeo5Tables"

excel_writer = DocDataWriter(mname="ExcelWriter")

print_excel = ExcelPrinter(mname="PrintExcel")
print_excel.template = "test/GEO5三维地质建模模板.xlsx"
print_excel.output_name = "导出GEO5.xlsx"

links = (
    reader.OutputTables >> generate_geo5_tables.InputTables
    | generate_geo5_tables.OutputTables >> excel_writer.InputData
    | excel_writer.OutputDocData >> print_excel.InputDocData
)
pipeline.add_links(links)

pipeline.run()
print(print_excel.OutputFile.data)

参数说明

ExcelPrinter 参数一览
参数名	类型	默认值	说明
`template`	`str \| Path \| dict \| list[str \| Path \| dict] \| None`	`None`	Excel 模板（单个或多个）；为 `None` 时模块不执行并输出 `None`。
`output_name`	`str \| list[str] \| None`	`None`	输出文件名；为 `None` 时默认使用 `{template_stem}_printed.xlsx`。
`process_sheets`	`str \| list[str] \| "active" \| "all"`	`"all"`	指定处理哪些 sheet：`"all"` 处理全部；`"active"` 仅处理活动 sheet；也可指定 sheet 名或列表。
`include_table_titles`	`bool`	`False`	为 `True` 时会从 `doc_keys_struct` 自动生成表头；为 `False` 时假设模板中已包含表头。
`apply_table_borders`	`bool`	`False`	是否为表格区域应用外边框。
`border_style`	`str`	`"thin"`	边框样式（如 `thin/medium/thick/double/dashed` 等，具体取值依赖 Excel 边框样式集合）。
`image_size_type`	`"width" \| "height" \| dict[str, "width" \| "height"]`	`"width"`	图片缩放按宽或按高；也可按 key 分别配置（保持纵横比）。
`image_size`	`dict[str, float] \| dict[str, list[float]] \| None`	`None`	图片大小（单位：mm）；可按 key 配置单张或多张图片的目标尺寸（保持纵横比）。
`save_to_gdim`	`bool`	`False`	是否上传到 GDIM 文件服务器；为 `True` 时需要可用的 token/proj_id/host（可从 pipeline 获取）。

上传 GDIM 前检查

是否需要特别处理：当导出的 Excel 文件需要在 GDIM 中留存、回传或交给后续环节下载时，是。
必须检查：
- 将 save_to_gdim 设为 True，否则结果通常只会保存在本地路径；
- 不要依赖模块里单独写死的运行时 GDIM 参数；
- 模板建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``dict``） 提供，这是上传后的推荐方式。
建议检查：
- output_name 设为稳定、可识别的导出文件名；
- 若仍保留本地模板路径写法，应明确这是本地调试用配置；上传时以前端传入的文件描述为准。
- 若使用 PythonCoder 等前置模块生成 DocData，一并确认这些模块本身也满足上传 GDIM 的脚本序列化要求。
若遗漏，常见现象：
- 本地运行能生成 .xlsx 文件，但上传 GDIM 后，拿不到期望的 GdimFile / GdimFiles 输出。

更多信息

UpdateGdimAppProjectInfo

模块简介与适用场景

UpdateGdimAppProjectInfo 更新 GDIM「项目信息」应用的数据（项目信息与坐标系统）；与 GdimAppProjectInfoReader 互为读写。
典型场景：从 GTB/MDB/Excel 等外部数据源同步工程名称、地址或自定义字段；导入表格时一并恢复项目坐标系统。

Hint

输入数据支持三种形式：

SingleResult / ResultModel：按字段名或字段标题提供待更新值，支持局部更新；
CoordinateSystem：直接更新整个坐标系统（例如来自 ReadGtbFile.OutputCoordinateSystem），此时不会修改项目名称、地址等非坐标字段。

端口说明

输入端口 - InputToken：鉴权与项目定位信息 (token, proj_id, host)。若 pipeline 已通过 update_gdim_state(token=..., proj_id=...) 配置 gdim_state，可从 pipeline 自动取得 token，该端口可不连接。 - InputResultModel：待更新的项目信息（SingleResult / ResultModel），或坐标系对象（CoordinateSystem，例如 ReadGtbFile.OutputCoordinateSystem 或 GdimAppProjectInfoReader.OutputCoordinateSystem）。
输出端口 - OutputResultModel：更新后的项目信息（ResultModel）；缺少 token 或输入数据时输出 None。

快速上手示例：局部更新项目名称与地址

from gdisdk.dataclass.results import ResultModel
from gdisdk.modules.writers import UpdateGdimAppProjectInfo

update_data = ResultModel.from_dict(
    {
        "projectName": "示例工程项目",
        "projectAddressProvince": "四川省",
        "projectAddressCity": "成都市",
    },
)

updater = UpdateGdimAppProjectInfo(mname="UpdateProjectInfo")
updater.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
updater.InputResultModel = update_data

updater.execute()
print(updater.OutputResultModel.data)

快速上手示例：在 pipeline 中更新项目信息

from gdisdk.connectors import log_in
from gdisdk.dataclass.results import ResultModel
from gdisdk.modules.writers import UpdateGdimAppProjectInfo
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="UpdateProjectInfoDemo", app_title="更新项目信息示例")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

update_data = ResultModel.from_dict(
    {
        "projectName": "示例工程项目",
        "projectAddressProvince": "四川省",
        "projectAddressCity": "成都市",
    },
)

updater = UpdateGdimAppProjectInfo(mname="UpdateProjectInfo")
updater.InputResultModel = update_data
pipeline.add_module(updater)
pipeline.run()

print(updater.OutputResultModel.data)

快速上手示例：从 GTB 文件恢复坐标系统

from gdisdk.connectors import log_in
from gdisdk.modules import ReadGtbFile, UpdateGdimAppProjectInfo
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="RestoreCoordinateSystem", app_title="恢复坐标系统示例")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_gtb = ReadGtbFile(mname="ReadGtbFile")
read_gtb.file = "export/gdim_tables.gtb"  # 本地测试路径；上传 GDIM 时由前端上传

update_proj_info = UpdateGdimAppProjectInfo(mname="UpdateProjectInfo")

links = read_gtb.OutputCoordinateSystem >> update_proj_info.InputResultModel
pipeline.add_links(links)
pipeline.run()

参数说明

UpdateGdimAppProjectInfo 参数一览
参数名	类型	默认值	说明
`update_data`	`SingleResult \| ResultModel \| CoordinateSystem \| None`	`None`	待更新的项目信息；仅在构造函数中传入时会写入 `InputResultModel` 端口。独立运行或 pipeline 中更推荐通过 `InputResultModel` 赋值。未出现在数据中的字段保持原值不变。
`token`	`str \| None`	`None`	GDIM 用户 token；一般更推荐通过 `pipeline.update_gdim_state(...)` 统一设置。
`proj_id`	`int \| str \| None`	`None`	GDIM 项目 ID；可通过 `InputToken` 或 `pipeline.gdim_state` 提供。
`host`	`str \| None`	`None`	GDIM 平台地址；通常沿用 pipeline 中的 GDIM 状态即可。

支持的字段说明

**项目地址**（SingleResult / ResultModel 中使用以下 key）：
- projectAddressProvince：省
- projectAddressCity：市
- projectAddressDistrict：区/县
- projectAddressDetail：详细地址
**坐标系统**（可单独字段更新，也可整体传入 CoordinateSystem）：
- coordinateSystem、zoneMethod、zoneNumber、centralMeridian
- refPointLongitude、refPointLatitude、refPointX、refPointY
- elevationDatum、yAxisDirection
自定义字段：字段名或字段标题均可识别；不在项目信息结构中的字段会被跳过并给出 warning。

在 pipeline 中的使用方式

与 GdimTableWriter 配合，在导入 GTB/XLSX 时同时回写表格与坐标系统：

from gdisdk.connectors import log_in
from gdisdk.modules import GdimTableWriter, ReadGtbFile, UpdateGdimAppProjectInfo
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="ImportAllTableData", app_title="导入所有表数据")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_gtb = ReadGtbFile(mname="ReadGtbFile")
write_tables = GdimTableWriter(mname="WriteGdimTables")
update_proj_info = UpdateGdimAppProjectInfo(mname="UpdateProjectInfo")

links = (
    read_gtb.OutputTables >> write_tables.InputData
    | read_gtb.OutputCoordinateSystem >> update_proj_info.InputResultModel
)
pipeline.add_links(links)
pipeline.run()

更多信息

API 参考 - modules 包
完整类定义与参数说明（writers）
读取项目信息见 modules.readers 模块帮助中的 GdimAppProjectInfoReader 章节

BorePlanDrawWriter

模块简介与适用场景

BorePlanDrawWriter 将钻孔与剖面线等表格数据，连同项目信息与坐标系统，打包为 KCAD 钻孔平面图出图用的 .gsc 文件（端口：OutputFile）。
典型场景：从 GDIM 读取勘察表格与项目元数据，生成可在 AutoCAD / 中望 CAD 中通过 KCAD 插件绘制钻孔平面图的 GSC 数据包。
若钻孔类型字段尚未映射为 KCAD 标准名称，可在上游接入 modules.geoDataProcess 模块帮助中的 MapBoreTypeToKCAD；name_maps 与 bore_types_map 的详细规则见后文说明。

端口说明

输入端口 - InputTables：钻孔与剖面线相关表格（TableCollection）；缺少 InputTables、InputProjectInfo 或 InputCoordinateSystem 时输出 None。 - InputProjectInfo：项目信息（ResultModel），通常来自 GdimAppProjectInfoReader.OutputProjectInfo。 - InputCoordinateSystem：项目坐标系统（CoordinateSystem），通常来自 GdimAppProjectInfoReader.OutputCoordinateSystem；模块会读取 yAxisDirection 并转换为 KCAD 所需的 N / E 方向。 - InputToken：鉴权与项目定位信息 (token, proj_id, host)；仅当 save_to_gdim=True 时需要；若 pipeline 已通过 update_gdim_state(token=..., proj_id=...) 配置 gdim_state，可从 pipeline 自动取得 token，该端口可不连接。
输出端口 - OutputFile：生成的 .gsc 文件；本地保存时为 FilePath，上传 GDIM 时为 GdimFile。

快速上手示例：在 pipeline 中生成 KCAD 钻孔平面图 GSC

from gdisdk.connectors import log_in
from gdisdk.modules import MapBoreTypeToKCAD
from gdisdk.modules.readers import GdimAppProjectInfoReader, GdimTableReader
from gdisdk.modules.writers import BorePlanDrawWriter
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="boreholePlan", app_title="生成KCAD钻孔平面图GSC文件")
pipeline.workspace = "test"
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_tables = GdimTableReader(mname="ReadTables")
read_tables.table_fields = {
    "bore_table": [
        "bore_number",
        "bore_type",
        "x_coordinate",
        "y_coordinate",
        "bore_top",
        "steady_ground_water_depth",
    ],
}

map_bore_types = MapBoreTypeToKCAD(mname="MapBoreTypes")
map_bore_types.bore_table_name = "bore_table"
map_bore_types.bore_type_field = "bore_type"

read_project_info = GdimAppProjectInfoReader(mname="ReadProjectInfo")

bore_plan_writer = BorePlanDrawWriter(mname="BorePlanDrawWriter")
bore_plan_writer.name_maps = {
    "table_names": {"bore_table": "bore_table"},
    "field_names": {
        "bore_table": {
            "bore_num": "bore_number",
            "x": "x_coordinate",
            "y": "y_coordinate",
            "bore_type": "bore_type",
            "top": "bore_top",
            "steady_water_depth": "steady_ground_water_depth",
        },
    },
}
bore_plan_writer.proj_info_name_map = {
    "company_name": "project_contractor",
    "project_name": "projectName",
    "project_number": "project_number",
}
bore_plan_writer.gsc_file_name = "Gdim平面图数据.gsc"
bore_plan_writer.save_to_gdim = True

links = (
    read_tables.OutputTables >> map_bore_types.InputTables
    | map_bore_types.OutputTables >> bore_plan_writer.InputTables
    | read_project_info.OutputProjectInfo >> bore_plan_writer.InputProjectInfo
    | read_project_info.OutputCoordinateSystem >> bore_plan_writer.InputCoordinateSystem
)
pipeline.add_links(links)
pipeline.run()

print(bore_plan_writer.OutputFile.data)

输入表格与字段说明

name_maps 用于将 GSC 内部逻辑名映射到实际 TableCollection 中的表名/表标题与字段名/字段标题。未配置时，模块默认查找以下逻辑表名与字段名：

BorePlanDrawWriter 默认输入表与字段
逻辑表名	常见 GDIM 表标题	逻辑字段	说明
`bore_table`	钻孔一览表	`bore_num`、`x`、`y`、`bore_type`、`top`、`steady_water_depth`	钻孔编号、平面坐标、孔型、孔口高程、稳定水位等
`section_line_table`	剖面线表	`name`、`bores`	可选；剖面线名称及关联钻孔编号（字符串可用逗号/分号分隔）

bore_types_map 可将钻孔类型字符串映射为 BoreTypes 枚举；未提供时会自动按枚举的 value / title 匹配。proj_info_name_map 的键为 ProjectInfo 字段名，值为 ResultModel 中的字段名或字段标题；未映射的字段会尝试按同名自动匹配。

参数说明

BorePlanDrawWriter 参数一览
参数名	类型	默认值	说明
`name_maps`	`dict[str, dict[str, str]] \| None`	`None`	表名与字段名映射，含 `table_names` 与 `field_names` 两个子字典；详见上文「输入表格与字段说明」。
`bore_types_map`	`dict[str, BoreTypes] \| None`	`None`	钻孔类型字符串到 `BoreTypes` 的显式映射；可与上游 `MapBoreTypeToKCAD` 配合使用。
`proj_info_name_map`	`dict[str, str] \| None`	`None`	`ProjectInfo` 字段与 `ResultModel` 字段/标题的映射。
`output_dir`	`str \| Path \| None`	`None`	输出目录；若 pipeline 设置了 `workspace`，则优先使用 workspace。
`gsc_file_name`	`str`	`"bore_plan_for_cad_draw.gsc"`	输出 `.gsc` 文件名。
`save_to_gdim`	`bool`	`False`	是否将生成的 `.gsc` 上传到 GDIM 文件服务器；为 `True` 时需要可用的 token/proj_id/host（可从 pipeline 获取）。

上传 GDIM 前检查

是否需要特别处理：当生成的 GSC 需要在 GDIM 中下载、回传或被 KCAD 流程消费时，是。
必须检查：
- 将 save_to_gdim 设为 True，否则结果只会保存在本地路径。
建议检查：
- 若钻孔类型非 KCAD 标准值，在 BorePlanDrawWriter 上游接入 MapBoreTypeToKCAD；
- 按项目模板配置 name_maps，确保钻孔、剖面线表字段正确映射；
- gsc_file_name 设为清晰、稳定的文件名，便于在 GDIM 文件列表中识别。
若遗漏，常见现象：
- 本地运行能生成 .gsc，但上传 GDIM 后 OutputFile 为 None 或拿不到 GdimFile。
- KCAD 打开 GSC 后钻孔位置、类型或剖面线缺失，多为 name_maps 或坐标系统未正确映射。

更多信息

API 参考 - modules 包
完整类定义与参数说明（writers）
钻孔类型 KCAD 映射见 modules.geoDataProcess 模块帮助中的 MapBoreTypeToKCAD 章节
读取项目信息与坐标系统见 modules.readers 模块帮助中的 GdimAppProjectInfoReader 章节

BoreLogDrawWriter

模块简介与适用场景

BoreLogDrawWriter 将钻孔、地层、原位测试、取样与岩土参数等表格数据，连同项目信息，打包为 KCAD 钻孔柱状图出图用的 .gsc 文件（ZIP，内含 bores_log.json；端口：OutputFile）。
典型场景：从 GDIM 读取勘察表格与项目元数据，生成可在 AutoCAD / 中望 CAD 中通过 KCAD 插件绘制钻孔柱状图的 GSC 数据包。
若 layer_table 缺少 layer_number``（地层编号），建议在模块上游接入 :doc:`modules_help.geoDataProcess` 中的 ``AddLayerNumberByStdLayerTable；name_maps、drawing_scales 与 sample_types_map 的详细规则见后文说明。

端口说明

输入端口 - InputTables：钻孔柱状图相关表格（TableCollection）；缺少 InputTables 或 InputProjectInfo 时输出 None。 - InputGeoParamsTable：岩土参数建议值表（TableData，可选）；用于为标准地层补充承载力、侧摩阻力等参数；也可通过 TableSelector 从 InputTables 中拆分后接入。 - InputProjectInfo：项目信息（ResultModel），通常来自 GdimAppProjectInfoReader.OutputProjectInfo。 - InputToken：鉴权与项目定位信息 (token, proj_id, host)；仅当 save_to_gdim=True 时需要；若 pipeline 已通过 update_gdim_state(token=..., proj_id=...) 配置 gdim_state，可从 pipeline 自动取得 token，该端口可不连接。
输出端口 - OutputFile：生成的 .gsc 文件；本地保存时为 FilePath，上传 GDIM 时为 GdimFile。

快速上手示例：在 pipeline 中生成 KCAD 钻孔柱状图 GSC

from gdisdk.connectors import log_in
from gdisdk.modules.filters import TableSelector
from gdisdk.modules.geoDataProcess import AddLayerNumberByStdLayerTable
from gdisdk.modules.readers import GdimAppProjectInfoReader, GdimTableReader
from gdisdk.modules.writers import BoreLogDrawWriter
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="boreholeLog", app_title="生成KCAD钻孔柱状图GSC文件")
pipeline.workspace = "test"
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_tables = GdimTableReader(mname="ReadTables")
read_tables.table_fields = [
    "bore_table",
    "standard_layer_table",
    "layer_table",
    "spt_table",
    "cpt_table",
    "proposed_geotechnical_parameters_table",
]

add_layer_number = AddLayerNumberByStdLayerTable(mname="AddLayerNumber")
select_geo_params = TableSelector(mname="SelectGeoParams")
select_geo_params.table_name = "proposed_geotechnical_parameters_table"

read_project_info = GdimAppProjectInfoReader(mname="ReadProjectInfo")

bore_log_writer = BoreLogDrawWriter(mname="BoreLogDrawWriter")
bore_log_writer.name_maps = {
    "table_names": {
        "bore_table": "bore_table",
        "materials_table": "standard_layer_table",
        "layer_table": "layer_table",
        "spt_table": "spt_table",
        "cpt_table": "cpt_table",
        "geo_parameters_table": "proposed_geotechnical_parameters_table",
    },
    "field_names": {
        "bore_table": {
            "bore_num": "bore_number",
            "x": "x_coordinate",
            "y": "y_coordinate",
            "top": "bore_top",
        },
        "layer_table": {
            "bore_num": "bore_number",
            "layer_number": "layer_number",
            "depths": "layer_bottom_depth",
        },
        "materials_table": {
            "material_name": "material_name",
            "layer_number": "layer_number",
        },
    },
}
bore_log_writer.proj_info_name_map = {
    "company_name": "project_contractor",
    "project_name": "projectName",
    "project_number": "project_number",
}
bore_log_writer.sample_types_map = {
    "厚壁原状": 0,
    "薄壁原状": 0,
    "扰动样": 1,
    "岩石样": 2,
    "水样": 3,
}
bore_log_writer.gsc_file_name = "Gdim柱状图数据.gsc"
bore_log_writer.save_to_gdim = True

links = (
    read_tables.OutputTables >> add_layer_number.InputTables
    | add_layer_number.OutputTables >> bore_log_writer.InputTables
    | read_tables.OutputTables >> select_geo_params.InputTables
    | select_geo_params.OutputTable >> bore_log_writer.InputGeoParamsTable
    | read_project_info.OutputProjectInfo >> bore_log_writer.InputProjectInfo
)
pipeline.add_links(links)
pipeline.run()

print(bore_log_writer.OutputFile.data)

输入表格与字段说明

name_maps 用于将 GSC 内部逻辑名映射到实际 TableCollection 中的表名/表标题与字段名/字段标题。未配置时，模块默认查找以下逻辑表名与字段名：

BoreLogDrawWriter 默认输入表与字段
逻辑表名	常见 GDIM 表标题	主要逻辑字段	说明
`bore_table`	钻孔一览表	`bore_num`、`x`、`y`、`top`、`steady_water_depth`、`drawing_scale` 等	钻孔编号、坐标、孔口高程、稳定水位、柱状图比例等
`layer_table`	地层表	`bore_num`、`depths`、`layer_number`	各地层底深与地层编号；`layer_number` 缺失时需上游补齐
`materials_table`	标准地层表	`material_name`、`layer_number`、`texture`、`layer_description` 等	标准地层属性；承载力/侧摩阻力也可来自 `geo_parameters_table`
`spt_table` / `cpt_table` / `dpt_table` / `wave_table`	标贯表 / 双桥静探表 / 动探表 / 波速表	各表 `bore_num` 及对应测试深度、读数等字段	可选；用于柱状图原位测试曲线
`samples_table` / `soils_test_table`	取样表 / 常规试验表	`bore_num`、`sample_num`、`sample_depths`、`sample_types` 等	可选；取样与室内试验标注
`geo_parameters_table`	岩土参数建议值表	`layer_number`、`bearing_capacity`、`pile_side_friction`	可选；经 `InputGeoParamsTable` 接入，或写入 `InputTables` 后由 `name_maps` 映射

proj_info_name_map 的键为 ProjectInfo 字段名，值为 ResultModel 中的字段名或字段标题；未映射的字段会尝试按同名自动匹配。sample_types_map 将取样类型字符串映射为 KCAD 整数编码；未提供时按原始字符串写入。

参数说明

BoreLogDrawWriter 参数一览
参数名	类型	默认值	说明
`name_maps`	`dict[str, dict[str, str]] \| None`	`None`	表名与字段名映射，含 `table_names` 与 `field_names` 两个子字典；详见上文「输入表格与字段说明」。
`selected_bores`	`list[str] \| None`	`None`	要导出的钻孔编号列表；`None` 表示导出全部钻孔。
`drawing_scales`	`dict[str, int] \| list[dict[str, str \| int]] \| int \| None`	`None`	柱状图比例；`int` 表示全部钻孔统一比例，`dict` 按钻孔编号分别设置，`list` 格式为 `[{"bore_num": "...", "drawing_scales": 200}, ...]`。
`proj_info_name_map`	`dict[str, str] \| None`	`None`	`ProjectInfo` 字段与 `ResultModel` 字段/标题的映射。
`sample_types_map`	`dict[str, int] \| None`	`None`	取样类型字符串到 KCAD 整数编码的映射，例如 `{"厚壁原状": 0, "扰动样": 1}`。
`output_dir`	`str \| Path \| None`	`None`	输出目录；若 pipeline 设置了 `workspace`，则优先使用 workspace。
`gsc_file_name`	`str`	`"bore_for_cad_draw.gsc"`	输出 `.gsc` 文件名。
`save_to_gdim`	`bool`	`False`	是否将生成的 `.gsc` 上传到 GDIM 文件服务器；为 `True` 时需要可用的 token/proj_id/host（可从 pipeline 获取）。

上传 GDIM 前检查

是否需要特别处理：当生成的 GSC 需要在 GDIM 中下载、回传或被 KCAD 流程消费时，是。
必须检查：
- 将 save_to_gdim 设为 True，否则结果只会保存在本地路径。
建议检查：
- 确认 layer_table 已含 layer_number，必要时在上游接入 AddLayerNumberByStdLayerTable；
- 按项目模板配置 name_maps，确保钻孔、地层与测试表字段正确映射；
- gsc_file_name 设为清晰、稳定的文件名，便于在 GDIM 文件列表中识别。
若遗漏，常见现象：
- 本地运行能生成 .gsc，但上传 GDIM 后 OutputFile 为 None 或拿不到 GdimFile。
- KCAD 打开 GSC 后地层、测试曲线或取样标注缺失，多为 name_maps 未正确映射或 layer_number 未补齐。

更多信息

API 参考 - modules 包
完整类定义与参数说明（writers）
补齐地层编号见 modules.geoDataProcess 模块帮助中的 AddLayerNumberByStdLayerTable 章节
读取项目信息见 modules.readers 模块帮助中的 GdimAppProjectInfoReader 章节

GeoSectionsWriter

模块简介与适用场景

GeoSectionsWriter 将 GeoSections``（``SectionForCadDraw 列表）序列化为 KCAD 地质剖面出图用的 .gsc 文件（ZIP，每条剖面一个 JSON；端口：OutputFile）。
剖面数据通常由 modules.geoDataProcess 模块帮助中的 ExportGeoSectionsByBores 生成；若需在剖面钻孔上叠加标贯、动探、静探、取样等柱状图信息，可先经同文档中的 AddBoreLogForGeoSections 再接入本模块。
典型场景：GDIM / KCAD 地质剖面出图流程的最后一步，将已整理好的剖面结构化数据打包为可在 AutoCAD / 中望 CAD 中通过 KCAD 插件绘制的 GSC 数据包。

端口说明

输入端口 - InputGeoSections：地质剖面列表（GeoSections，即 SectionForCadDraw 对象列表）；为空或缺失时 OutputFile 为 None。 - InputToken：鉴权与项目定位信息 (token, proj_id, host)；仅当 save_to_gdim=True 时需要；若 pipeline 已通过 update_gdim_state(token=..., proj_id=...) 配置 gdim_state，可从 pipeline 自动取得 token，该端口可不连接。
输出端口 - OutputFile：生成的 .gsc 文件；本地保存时为 FilePath，上传 GDIM 时为 GdimFile。

输出文件结构说明

.gsc 为 ZIP 压缩包，内部每条剖面对应一个 JSON 文件，内容为 SectionForCadDraw.model_dump_json()。
ZIP 内条目名优先取 section_num``（经非法文件名字符替换与 Windows 保留名过滤）；``section_num 为空或无效时使用随机 UUID 文件名。
多条剖面 section_num 相同时，后续条目自动追加 _2、_3 等后缀以避免重名。

快速上手示例：在 pipeline 中生成 KCAD 地质剖面 GSC

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

pipeline = PipeLine(app_name="geoSections", app_title="生成KCAD地质剖面GSC文件")
pipeline.workspace = "test"
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

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

export_sections = ExportGeoSectionsByBores(mname="ExportGeoSections")
add_bore_log = AddBoreLogForGeoSections(mname="AddBoreLog")
add_bore_log.name_maps = {
    "table_names": {"bore_table": "bore_table", "layer_table": "layer_table"},
    "field_names": {
        "bore_table": {"bore_num": "bore_number"},
        "layer_table": {"bore_num": "bore_number", "layer_num": "layer_number"},
    },
}

write_gsc = GeoSectionsWriter(mname="GeoSectionsWriter")
write_gsc.gsc_file_name = "Gdim剖面图数据.gsc"
write_gsc.save_to_gdim = True

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

print(write_gsc.OutputFile.data)

Note

上例省略 ExportGeoSectionsByBores 的上游 InputMultiProfile1D、InputMaterialTable、InputPolyLines 等连接；完整剖面生成链路见 modules.geoDataProcess 模块帮助中的 ExportGeoSectionsByBores 章节。若不需要柱状图叠加，可将 export_sections.OutputGeoSections 直接连至 write_gsc.InputGeoSections。

参数说明

GeoSectionsWriter 参数一览
参数名	类型	默认值	说明
`output_dir`	`str \| Path \| None`	`None`	输出目录；若 pipeline 设置了 `workspace`，则优先使用 workspace。
`gsc_file_name`	`str`	`"geo_sections.gsc"`	输出 `.gsc` 文件名；可在 GDIM 界面通过 `update_ui_schema` 暴露为「GSC文件名」。
`save_to_gdim`	`bool`	`False`	是否将生成的 `.gsc` 上传到 GDIM 文件服务器；为 `True` 时需要可用的 token/proj_id/host（可从 pipeline 获取）。

上传 GDIM 前检查

是否需要特别处理：当生成的 GSC 需要在 GDIM 中下载、回传或被 KCAD 流程消费时，是。
必须检查：
- 将 save_to_gdim 设为 True，否则结果只会保存在本地路径。
若遗漏，常见现象：
- 本地运行能生成 .gsc，但上传 GDIM 后 OutputFile 为 None 或拿不到 GdimFile。

更多信息

API 参考 - modules 包
完整类定义与参数说明（writers）
上游剖面生成与柱状图叠加见 modules.geoDataProcess 模块帮助中的 ExportGeoSectionsByBores、AddBoreLogForGeoSections 章节
完整 pipeline 脚本参考仓库 pipelineApps/gdim/cadDrawing/createGeoSectionsPipeline.py