modules.writers 模块帮助

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

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

DocDataWriter

模块简介与适用场景

DocDataWriter 将 SingleResult / ResultModel / 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 / ResultModel / TableData / TableCollection / FilePath / FilesPath）。ResultModel 与 SingleResult 一样按字段展开为模板变量（字段名作 key）。
输出端口 - 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` / `ResultModel` 用字段名或字段标题。
`datetime_format`	`str \| dict[str, str \| None] \| None`	`None`	日期时间格式化（strftime）；支持统一 `str` 或按字段分别配置。键的含义与 `precision` 相同。
`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` 与 `ResultModel` 生效：字段值为 list 时，用该分隔符拼成字符串。
`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` 或 `proj_name`。
`token`	`str \| None`	`None`	GDIM 用户 token；通常更推荐通过 `pipeline.update_gdim_state(...)` 统一设置。
`proj_id`	`int \| str \| None`	`None`	GDIM 项目 ID；可通过 `InputToken` 或 `pipeline.gdim_state` 提供。设置后忽略 `proj_name`。
`proj_name`	`str \| None`	`None`	仅 `save_to_gdim=True` 且 `proj_id` 为空时，按精确名称定位上传目标，并覆盖 Pipeline 上的项目。不搜索已归档项目。空间规则见用项目名称定位。
`personal_space`	`bool`	`False`	`proj_name` 是否在个人空间中查找。
`space_name`	`str \| None`	`None`	`proj_name` 所在空间的精确名称。`None` 使用当前空间。
`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` 或 `proj_name`。
`proj_name`	`str \| None`	`None`	用于读取表关系、坐标系，以及 `save_to_gdim=True` 时确定上传目标。`proj_id` 为空时按精确名称定位，并覆盖 Pipeline 上的项目。不搜索已归档项目。空间规则见用项目名称定位。
`personal_space`	`bool`	`False`	`proj_name` 是否在个人空间中查找。
`space_name`	`str \| None`	`None`	`proj_name` 所在空间的精确名称。`None` 使用当前空间。
`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 项目的业务表。
同一张表可以同时包含插入、更新、删除行。**按 id 删除整行**的行不会进入字段校验；**作为部分更新提交**的墓碑行会正常校验。
墓碑行是否调用 delete_table_data 删整行，取决于写入列是否覆盖 GDIM 模板全部字段，以及参数 delete_tombstone_rows``（默认 ``True）；规则见「墓碑行：删除 vs 部分更新」。
Pipeline 中含 GdimTableWriter 时，运行前会与其它读表模块一样预取 GDIM 项目模板，避免 write_table_data 重复请求模板结构。
普通应用运行时立即写库，保持默认 auto_run=True。若 Pipeline 用于 GDIM 「自定义数据更新配置」/「表格数据更新」，平台只做预览、由前端确认后写入，保存的 .pipe 不能连接 writer（平台恢复时会把所有模块 auto_run 设为 True），见 GDIM数据更新 (Data Update)。

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

插入：没有 ``gdim_id``（或值为空）的行，调用 GDIM 接口新增数据。
更新：gdim_id 有值，且**除 gdim_id 外**至少还有一个业务字段非空（None / NaN 视为空）的行。只改写入表里出现的列；GDIM 上该记录**未出现在写入表中的列**保持原值。
墓碑行：gdim_id 有值，且写入表里**所有业务列**均为空（None / NaN）。空字符串不算空，仍视为更新。

墓碑行：删除 vs 部分更新

写入数据中的列集合会与 GDIM 模板字段比较（字段映射 / 按标题自动重命名之后）：

仅含 ``gdim_id`` 一列：整张表跳过写入，并 UserWarning 提示；不会删除也不会更新。
**列集合是模板字段的真子集**（例如只改 a、b，模板还有 c、d）：墓碑行**不会**删除整行，而是按**更新**处理，只清空写入表里出现的那些列。适用于表格数据更新等 Pipeline 只输出部分字段的场景。
**列集合包含模板中的全部字段**（完整 schema，MergeGdimTables 墓碑行即此类）：
- ``delete_tombstone_rows=True``（默认）：先**按 id 从 GDIM 删除整行**，再从写入批次中移除该行；其余行继续插入/更新。
- delete_tombstone_rows=False：不删除，墓碑行按更新处理（只清空写入表中的业务列，记录仍保留）。
经 MergeGdimTables 产出的删除用墓碑行应为**完整 GDIM schema**（gdim_id + 全部业务列，值均为 None），见 modules.mergers 模块帮助。
若**只完成了删除、没有剩余插入/更新行**，只要删除成功，该表视为写入成功，不会报「没有可写入 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 / proj_name、InputToken、pipeline gdim_state 都没有可用项目）时返回 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`，保持严格校验行为。
`delete_tombstone_rows`	`bool`	`True`	当写入表包含该表在 GDIM 模板中的全部字段时，墓碑行是否按 id 删除整行。`False` 时改为按更新清空字段、不删记录。写入表只是部分列时本参数无效，墓碑行始终按更新处理。详见上文「墓碑行：删除 vs 部分更新」。
`token`	`str \| None`	`None`	GDIM 用户 token。一般更推荐通过 `pipeline.update_gdim_state(...)` 统一设置。
`proj_id`	`str \| None`	`None`	GDIM 项目 ID。若构造函数中显式设置，该值优先级高于 `InputToken` 或 `pipeline.gdim_state.proj_id`，并忽略 `proj_name`。
`proj_name`	`str \| None`	`None`	项目的精确名称。`proj_id` 为空时用来定位写入目标，并覆盖 Pipeline 上的项目。不搜索已归档项目。空间规则见用项目名称定位。
`personal_space`	`bool`	`False`	`proj_name` 是否在个人空间中查找。
`space_name`	`str \| None`	`None`	`proj_name` 所在空间的精确名称。`None` 使用当前空间。
`host`	`str \| None`	`None`	GDIM 平台地址；通常沿用 pipeline 中的 GDIM 状态即可。

上传 GDIM 前检查

是否需要特别处理：当 pipeline 要在 GDIM 平台中运行，并直接把结果写回项目表时，是。用于 GDIM 「表格数据更新」/「数据更新」/「自定义数据更新配置」时，**尤其需要**把写入时机和预览端口分开，完整约定见 GDIM数据更新 (Data Update)。
必须检查：
- 若 pipeline 用于 GDIM 「表格数据更新」/「数据更新」/「自定义数据更新配置」，保存的 .pipe 不能连接 GdimTableWriter``（平台只做预览，前端确认后再写入）。平台恢复 Pipeline 时会把所有模块 ``auto_run 设为 True，因此 auto_run=False 挡不住写入。本地测试可在 save_pipeline() 之后再接线，但不要把 writer 写进 .pipe；
- 上述场景下 return_results_config 必须指向预览表端口（通常是 MergeGdimTables.OutputTables）。GdimTableWriter 没有面向用户的输出端口，不能当作预览结果；
- 若目标是更新已有记录而非新增，必须确保写入数据里保留了 gdim_id；
- 若目标是替换子表整组（MergeGdimTables 1:N overwrite）或删除未匹配键（delete_unmatched=True），必须把**完整 schema** 墓碑行原样交给 writer（gdim_id + 全部业务列为空），不要在写入前丢掉这些行；并保持默认 delete_tombstone_rows=True；
- 若 Pipeline 只输出部分列（自定义数据更新预览），不要指望墓碑行删除整行；未出现在写入表中的 GDIM 列不会被清空；
建议检查：
- 对日期时间类字段较多的数据，优先保持 strict_datetime_validation=True 和 validation_level="full"，先保证数据质量再考虑提速；
- 若数据来自 Excel、CSV 等外部来源且类型与 GDIM 字段不完全一致，可尝试 auto_convert=True 以减少类型校验失败；
若遗漏，常见现象：
- 看起来模块运行成功，但数据没有写入预期的 GDIM 表；
- 原本希望覆盖旧记录，结果在表中新增了重复记录；
- 子表整组替换时旧行仍在，通常是墓碑行未送到 writer，或 gdim_id 丢失后全部变成插入；
- 期望删整行但记录仍在，通常是写入表只有部分列（墓碑行被当作部分更新），或 delete_tombstone_rows=False；

更多信息

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` 或 `proj_name`。
`proj_name`	`str \| None`	`None`	仅 `save_to_gdim=True` 且 `proj_id` 为空时，按精确名称定位上传目标，并覆盖 Pipeline 上的项目。不搜索已归档项目。空间规则见用项目名称定位。
`personal_space`	`bool`	`False`	`proj_name` 是否在个人空间中查找。
`space_name`	`str \| None`	`None`	`proj_name` 所在空间的精确名称。`None` 使用当前空间。

字段 description 为图片/子文档路径时，None、空字符串、空列表不会尝试打开文件：单值类型插入空内容（""），列表类型按空列表处理，避免模板把 None 打出来或在 {% for %} 中报错。

上传 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.pipeline.portTypes import PortType
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", ptype=PortType.TableCollection)
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`。
`output_dir`	`str \| Path \| None`	`None`	输出目录；若 pipeline 设置了 `workspace`，则优先使用 workspace。
`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` 或 `proj_name`。
`proj_name`	`str \| None`	`None`	仅 `save_to_gdim=True` 且 `proj_id` 为空时，按精确名称定位上传目标，并覆盖 Pipeline 上的项目。不搜索已归档项目。空间规则见用项目名称定位。
`personal_space`	`bool`	`False`	`proj_name` 是否在个人空间中查找。
`space_name`	`str \| None`	`None`	`proj_name` 所在空间的精确名称。`None` 使用当前空间。

上传 GDIM 前检查

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

更多信息

CreateGdimProject

模块简介与适用场景

CreateGdimProject 在当前登录空间中按一个数字模型创建一个 GDIM 项目，并只写入该模型的项目信息表。
项目名称必填。数字模型用模板 ID 或精确名称指定；两者都填时使用模板 ID。名称在当前空间对应多个数字模型时会失败，需要改用模板 ID。
项目名称以外的必填项随数字模型变化，创建前会读取该模型的项目信息表。这些值通过 fields 提供，键可以是字段名或字段标题。
输出为新建项目的 SingleResult，其中包含项目 ID。其它业务表要等拿到该 ID 之后再写，不在本次创建中处理。
Token 里的项目 ID 不参与创建。未提供 token，或项目名称与数字模型都未设置时，OutputProjectInfo 为 None。

端口说明

输入端口 - InputToken：鉴权信息 (token, proj_id, host)。proj_id 可为空。若 pipeline 已通过 update_gdim_state(token=...) 配置 gdim_state，可从 pipeline 取得 token，该端口可不连接。
输出端口 - OutputProjectInfo：新建项目信息（SingleResult）。缺少 token 或创建条件不足时为 None。

快速上手示例：按模板名称创建一个项目

from gdisdk.connectors import log_in
from gdisdk.modules.writers import CreateGdimProject

creator = CreateGdimProject(mname="CreateProject")
creator.InputToken = (log_in(user_name="你的GDIM用户名", password="你的GDIM密码"), None, None)
creator.project_name = "示例项目"
creator.template_name = "场地工程勘察"
creator.fields = {
    "项目编号": "PRJ-001",
    "projectAddressProvince": "广东省",
    "projectAddressCity": "广州市",
}

creator.execute()
print(creator.OutputProjectInfo.data)

快速上手示例：在 pipeline 中创建项目

from gdisdk.connectors import log_in
from gdisdk.modules.writers import CreateGdimProject
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="CreateProjectDemo", app_title="创建GDIM项目示例")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
)

creator = CreateGdimProject(mname="CreateProject")
creator.project_name = "示例项目"
creator.template_id = "数字模型ID"
creator.fields = {"项目编号": "PRJ-001"}
pipeline.add_module(creator)
pipeline.run()

print(creator.OutputProjectInfo.data)

参数说明

CreateGdimProject 参数一览
参数名	类型	默认值	说明
`project_name`	`str \| None`	`None`	新建项目的名称。非空时优先于 `fields` 中的 `projectName` 或「项目名称」。
`template_id`	`str \| None`	`None`	数字模型 ID。与 `template_name` 至少提供一项；非空时优先于模板名称，也优先于 `fields` 中的模板 ID。
`template_name`	`str \| None`	`None`	数字模型的精确名称。`template_id` 为空时使用。当前空间中同名模型多于一个时创建失败。
`fields`	`dict[str, Any] \| None`	`None`	其它项目信息。键为字段名或字段标题；同一字段两者都给出时使用字段名。必填项随数字模型变化。
`token`	`str \| None`	`None`	GDIM 用户 token。独立运行或 pipeline 中更推荐通过 `InputToken` 或 `pipeline.update_gdim_state(...)` 提供。
`host`	`str \| None`	`None`	GDIM 平台地址。为空时沿用 pipeline 的 GDIM 状态；仍为空时使用项目 `.env` 的 `GDIM_HOST`。

字段与必填说明

项目名称始终必填。数字模型 ID 与名称至少提供一项。
fields 中未出现在该项目信息表里的键会被忽略，并给出 warning。
以下字段即使在表结构里标为必填，创建时也不检查、也不提交：createdDisplay 为 false 的字段、分割线（divider）、流水号（serialNumber）、dataTemplateId、dataTemplateGroupId。后两项由所选数字模型写入请求顶层。
值为空包括 None、空字符串、只含空格的字符串、空对象和空数组。0 和 False 不是空。地址对象的每一层都空时，该地址才算空。
必填且为空时抛出 请输入 {字段标题}。模板名称重复时抛出中文错误，提示改用模板 ID。
项目地址可写在 projectAddress 对象中，也可以使用以下平铺键：
- projectAddressProvince：省
- projectAddressCity：市
- projectAddressDistrict：区/县
- projectAddressDetail：详细地址
- projectAddressCenter：地图中心，格式为经度,纬度
未分组的数字模型，创建请求中的分组 ID 为 "0"。

上传 GDIM 前检查

是否需要特别处理：当 pipeline 在 GDIM 上运行、并由当前登录用户创建项目时，是。
必须检查：
- 不要在脚本中写死只在本机有效的 token；上传后由 update_gdim_state 或平台注入的登录状态提供 token。
- template_name 在运行时所在空间必须唯一。可能重名时改用 template_id。
- fields 覆盖该数字模型项目信息表中、除项目名称以外的必填字段。不同空间、不同模型的必填项不同。
若遗漏，常见现象：
- 本地用固定模板名称可以创建，上传后因同名数字模型多于一个而失败；
- 创建请求在提交前报 请输入 {字段标题}。

更多信息

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` 提供。设置后忽略 `proj_name`。
`proj_name`	`str \| None`	`None`	项目的精确名称。`proj_id` 为空时用来定位要更新的项目，并覆盖 Pipeline 上的项目。不搜索已归档项目。空间规则见用项目名称定位。
`personal_space`	`bool`	`False`	`proj_name` 是否在个人空间中查找。
`space_name`	`str \| None`	`None`	`proj_name` 所在空间的精确名称。`None` 使用当前空间。
`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 文件。
典型场景：从 GDIM 读取勘察表格与项目元数据，生成可在 AutoCAD / 中望 CAD 中通过 KCAD 插件绘制钻孔平面图的 GSC 数据包；需要在平面图中一并绘制剖面线时，可连接 ``InputSectionLines``（常见上游为 GdimCrossSectionReader）。
.gsc 内的字段名与 GDIM 保留字段名 对齐；输入 TableCollection 已使用保留表名/字段名时，name_maps 可省略。
可选入端口 InputSectionLines 用于接入 GDIM「地质剖面图」应用中的剖面线定义；未连接时仍可从 InputTables 内的 section_lines_table 读取剖面线（见后文「剖面线输入说明」）。
若钻孔类型字段尚未映射为 KCAD 标准名称，可在上游接入 modules.geoDataProcess 模块帮助中的 MapBoreTypeToKCAD``（无法映射的取值会保留原值并发出 ``GDIDataQualityWarning）；非标准表名/字段名时再配置 name_maps 与 ``bore_types_map``（详见后文）。

端口说明

输入端口 - InputTables：钻孔与剖面线相关表格（TableCollection）；缺少 InputTables、InputProjectInfo 或 InputCoordinateSystem 时输出 None。 - InputSectionLines``（可选）：剖面信息表（``TableData），通常来自 GdimCrossSectionReader 的 OutputTable。模块读取每行的 section_number、define_by、section_lines 并转换为 SectionLine 写入 bore_plan.json；section_2d / section_3d 不参与平面图剖面线绘制。未连接或表为空时不影响其余输入；与 section_lines_table 合并规则见「剖面线输入说明」。 - 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.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)

快速上手示例：从地质剖面图应用读取剖面线

当剖面线已在 GDIM「地质剖面图」应用中维护、而项目数字模型中未单独建 section_lines_table 时，用 GdimCrossSectionReader 读入并连到 InputSectionLines：

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

pipeline = PipeLine(app_name="boreholePlanWithSections", app_title="平面图含地质剖面线")
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")
read_cross_sections = GdimCrossSectionReader(mname="ReadCrossSections")

bore_plan_writer = BorePlanDrawWriter(mname="BorePlanDrawWriter")
bore_plan_writer.gsc_file_name = "Gdim平面图数据.gsc"

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
    | read_cross_sections.OutputTable >> bore_plan_writer.InputSectionLines
)
pipeline.add_links(links)
pipeline.run()

输入表格与字段说明

name_maps 用于在输入表 未使用 GDIM 保留名时，将保留表名/字段名映射到实际的表名/表标题与字段名/字段标题（table_names / field_names 两个子字典）。输入已为标准保留名时保持 None 即可。

BorePlanDrawWriter 默认输入表与字段（GDIM 保留名）
保留表名	常见 GDIM 表标题	主要保留字段	说明
`bore_table`	钻孔一览表	`bore_number`、`x_coordinate`、`y_coordinate`、`bore_type`、`bore_top`、`steady_ground_water_depth` 等	钻孔编号、平面坐标、孔型、孔口高程、稳定水位等
`section_lines_table`	剖面线表	`section_number`、`bore_numbers`	可选；剖面编号及关联钻孔编号（字符串可用逗号/分号分隔）

写入 bore_plan.json 的 SectionBore / SectionLine 字段名与上表保留字段一致（参见 SectionBore、SectionLine）。

剖面线输入说明

平面图 GSC 中的剖面线（BoreForPlanDraw.section_lines）可来自以下来源，模块会在 execute 时合并：

**InputTables 中的 section_lines_table``**（可选）：保留字段 ``section_number、bore_numbers；bore_numbers 可为逗号/分号分隔的钻孔编号字符串，或编号列表。
**InputSectionLines``**（可选）：列名须为 ``section_number、define_by、section_lines``（与 :ref:`GdimCrossSectionReader <modules_help_gdim_cross_section_reader>` 输出一致）。``define_by 为 "points" 时 section_lines 为含 x、y 的坐标点列表；为 "bores" 时为钻孔编号列表。单元格可为 JSON 字符串，模块会尝试解析。

合并规则：两类来源先分别转换为 SectionLine 列表再合并；section_number 相同时，``InputSectionLines`` 中的定义优先，会覆盖 section_lines_table 中同编号的剖面线。无 section_number 的条目会保留在结果末尾。

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` 或 `proj_name`。
`proj_name`	`str \| None`	`None`	仅 `save_to_gdim=True` 且 `proj_id` 为空时，按精确名称定位上传目标，并覆盖 Pipeline 上的项目。不搜索已归档项目。空间规则见用项目名称定位。
`personal_space`	`bool`	`False`	`proj_name` 是否在个人空间中查找。
`space_name`	`str \| None`	`None`	`proj_name` 所在空间的精确名称。`None` 使用当前空间。

上传 GDIM 前检查

是否需要特别处理：当生成的 GSC 需要在 GDIM 中下载、回传或被 KCAD 流程消费时，是。
必须检查：
- 将 save_to_gdim 设为 True，否则结果只会保存在本地路径。
建议检查：
- 若钻孔类型非 KCAD 标准值，在 BorePlanDrawWriter 上游接入 MapBoreTypeToKCAD，并在 GDIM 项目钻孔类型映射表中维护完整对照；
- 输入表未使用 GDIM 保留名时再配置 name_maps；标准 bore_table / section_lines_table 可省略；
- 剖面线来自「地质剖面图」应用时，确认已连接 GdimCrossSectionReader.OutputTable → InputSectionLines，且项目中剖面信息表有有效 section_lines；
- gsc_file_name 设为清晰、稳定的文件名，便于在 GDIM 文件列表中识别。
若遗漏，常见现象：
- 本地运行能生成 .gsc，但上传 GDIM 后 OutputFile 为 None 或拿不到 GdimFile。
- Pipeline 运行出现钻孔类型相关的 GDIDataQualityWarning，说明 MapBoreTypeToKCAD 未能将部分取值映射为 KCAD 标准名称（原值已保留）；需在 GDIM 补全映射或修正源表。
- KCAD 打开 GSC 后钻孔位置、类型或剖面线缺失，多为 name_maps 或坐标系统未正确映射；平面图无剖面线但钻孔正常，多为未连接 InputSectionLines 且 section_lines_table 为空或未读入。

更多信息

API 参考 - modules 包
完整类定义与参数说明（writers）
钻孔类型 KCAD 映射见 modules.geoDataProcess 模块帮助中的 MapBoreTypeToKCAD 章节
读取项目信息与坐标系统见 modules.readers 模块帮助中的 GdimAppProjectInfoReader 章节
读取地质剖面图剖面信息表见 GdimCrossSectionReader <modules_help_gdim_cross_section_reader>`（``InputSectionLines` 常用上游）
.gsc JSON 字段定义见 dataclass.geoProfiles`（``BoreForPlanDraw`、SectionBore 等）

BoreLogDrawWriter

模块简介与适用场景

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

端口说明

输入端口 - InputTables：钻孔柱状图相关表格（TableCollection）；可含 proposed_geotechnical_parameters_table``（岩土参数建议值，缺失时跳过）；缺少 ``InputTables 或 InputProjectInfo 时输出 None。 - 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.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",
    "sampling_log_table",
    "sonic_logging_table",
    "proposed_geotechnical_parameters_table",
]

add_layer_number = AddLayerNumberByStdLayerTable(mname="AddLayerNumber")

read_project_info = GdimAppProjectInfoReader(mname="ReadProjectInfo")

bore_log_writer = BoreLogDrawWriter(mname="BoreLogDrawWriter")
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_project_info.OutputProjectInfo >> bore_log_writer.InputProjectInfo
)
pipeline.add_links(links)
pipeline.run()

print(bore_log_writer.OutputFile.data)

输入表格与字段说明

name_maps 仅在输入表未使用 GDIM 保留名时需要；默认可直接读取下列保留表（缺失的表跳过）：

BoreLogDrawWriter 默认输入表与字段（GDIM 保留名）
保留表名	常见 GDIM 表标题	主要保留字段	说明
`bore_table`	钻孔一览表	`bore_number`、`x_coordinate`、`y_coordinate`、`bore_top`、`steady_ground_water_depth`、`drawing_scale` 等	钻孔编号、坐标、孔口高程、稳定水位、柱状图比例等
`layer_table`	地层表	`bore_number`、`layer_bottom_depth`、`layer_number`	各地层底深与地层编号；`layer_number` 缺失时需上游补齐
`standard_layer_table`	标准地层表	`material_name`、`layer_number`、`texture`、`layer_description`、`fill_color` 等	标准地层属性
`spt_table` / `cpt_table` / `dpt_table`	标贯表 / 双桥静探表 / 动探表	`bore_number` 及 `test_point_top_depth`、`penetration_depth`、`blow_count` 等（各表字段见 `SptLog` 等）	可选；原位测试曲线
`sonic_logging_table`	声波测井表	`bore_number`、`test_point_depth`、`shear_wave_velocity`、`p_wave_velocity`	可选；波速曲线（公路工程仅纵波时 `shear_wave_velocity` 可为空）
`sampling_log_table`	取样表	`bore_number`、`sample_number`、`sample_top_depth`、`sample_length`、`sample_type`	可选；取样标注
`soil_test_table`	常规试验表	`bore_number`、`sample_number`、`collapsibility_coefficient`、`self_weight_collapsibility_coefficient` 等	场地工程勘察的湿陷记录从此表读取；湿陷系数与自重湿陷系数都为空的行跳过。若输入中仍有 `loess_collapsibility_table`，优先使用该表。缺 `sample_top_depth` / `sample_length` 时可按 `sample_number` 从 `sampling_log_table` 补全
`proposed_geotechnical_parameters_table`	岩土参数建议值表	`layer_number`、`soil_bearing_capacity_fak`、`skin_friction`	可选；写入 `InputTables` 即可；`soil_bearing_capacity_fak` 缺失时尝试 `soil_bearing_capacity_fa0`

写入 bores_log.json 的 SectionBore 及嵌套日志模型字段名与上表一致（参见 dataclass.geoProfiles 中 SectionBore、SamplingLog、SptLog 等）。

proj_info_name_map 的键为 ProjectInfo 字段名，值为 ResultModel 中的字段名或字段标题；未映射的字段会尝试按同名自动匹配。sample_types_map 为取样类型到 KCAD 整数编码的显式映射；未列出或未配置时按子串规则编码（「原状」→ 0、「扰动」→ 1、「岩」→ 2、「水」→ 3，否则 -1），原始名称写入 SamplingLog.sample_type_name。

参数说明

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_number": "...", "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` 或 `proj_name`。
`proj_name`	`str \| None`	`None`	仅 `save_to_gdim=True` 且 `proj_id` 为空时，按精确名称定位上传目标，并覆盖 Pipeline 上的项目。不搜索已归档项目。空间规则见用项目名称定位。
`personal_space`	`bool`	`False`	`proj_name` 是否在个人空间中查找。
`space_name`	`str \| None`	`None`	`proj_name` 所在空间的精确名称。`None` 使用当前空间。

上传 GDIM 前检查

是否需要特别处理：当生成的 GSC 需要在 GDIM 中下载、回传或被 KCAD 流程消费时，是。
必须检查：
- 将 save_to_gdim 设为 True，否则结果只会保存在本地路径。
建议检查：
- 确认 layer_table 已含 layer_number，必要时在上游接入 AddLayerNumberByStdLayerTable；
- 输入表未使用 GDIM 保留名时再配置 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 章节
.gsc JSON 字段定义见 dataclass.geoProfiles`（``BoreForCadDraw`、SectionBore、SamplingLog 等）

GeoSectionsWriter

模块简介与适用场景

GeoSectionsWriter 将 GeoSections``（``SectionForCadDraw 列表）序列化为 KCAD 地质剖面出图用的 .gsc 文件（ZIP，每条剖面一个 JSON；端口：OutputFile）。JSON 内 SectionBore、SectionMaterial 等字段名与 GDIM 保留字段名一致。
剖面数据通常由 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 内条目名优先取 ``SectionForCadDraw.section_number``（经非法文件名字符替换与 Windows 保留名过滤）；为空或无效时使用随机 UUID 文件名。
多条剖面 section_number 相同时，后续条目自动追加 _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")

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` 或 `proj_name`。
`proj_name`	`str \| None`	`None`	仅 `save_to_gdim=True` 且 `proj_id` 为空时，按精确名称定位上传目标，并覆盖 Pipeline 上的项目。不搜索已归档项目。空间规则见用项目名称定位。
`personal_space`	`bool`	`False`	`proj_name` 是否在个人空间中查找。
`space_name`	`str \| None`	`None`	`proj_name` 所在空间的精确名称。`None` 使用当前空间。

上传 GDIM 前检查

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

更多信息

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