modules.converters 模块帮助

本章节包含 modules.converters 包中常用「数据结构转换」模块的使用说明和示例，例如：

表格数据转换为地质材料表、剖面数据结构等
不同内部数据结构之间的相互转换

PdfToImages

模块简介与适用场景

PdfToImages 用于将一个或多个 PDF 文件按页转换为图片文件（PNG/JPG/JPEG）。
适合在 pipeline 中将 PDF 扫描件/报表等转为图片，供后续识别、标注、可视化或归档。
该模块主要通过 pdf_configs``（表格化配置）指定多个 PDF 的路径与转换参数，输出图片路径列表到 ``OutputImages。

端口说明

输入端口 - （无）：该模块主要通过初始化参数 pdf_configs / output_dir / dpi / format 提供输入配置
输出端口 - OutputImages：输出图片文件路径列表（list[str]，图片格式由 format 决定）

快速上手示例

from gdisdk.modules.converters import PdfToImages

pdf2img = PdfToImages(
    pdf_configs=[
        {
            "file_path": "doc1.pdf",
            "image_prefix": "doc1",
            "first_page": 1,
            "last_page": 3,
        },
        {"file_path": "doc2.pdf"},  # 仅指定文件路径，其余使用默认值
    ],
    dpi=200,
    format="png",
    output_dir="output/pdf_images",
)
image_paths = pdf2img.execute()
print(image_paths)

参数说明

PdfToImages 参数一览
参数名	类型	默认值	说明
`pdf_configs`	`list[dict]`	`[]`	PDF 转换配置列表。每一项至少包含 `file_path`，可选键包括： `image_prefix`：输出图片前缀（为空/不填时自动从文件名生成；同名会自动加后缀区分） `first_page`：起始页（1-based，默认 1） `last_page`：终止页（1-based，含终止页；默认 None 表示到最后一页） `width` / `height`：输出图片宽高（像素，默认 None，按 DPI 缩放）
`output_dir`	`str \| Path \| None`	`None`	输出目录。若 pipeline 设置了 `pipeline.workspace`，其优先级高于 `output_dir`；若两者都为空，则默认使用第一个 PDF 所在目录。
`dpi`	`int`	`200`	转换 DPI（越大图片越清晰但更大）。
`format`	`Literal["png","jpg","jpeg"]`	`"png"`	输出图片格式。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import PdfToImages

pipeline = PipeLine(app_name="PdfToImagesDemo", app_title="PDF转图片示例")
pipeline.workspace = "workspace"  # 优先于 PdfToImages.output_dir

pdf2img = PdfToImages(
    pdf_configs=[{"file_path": "doc1.pdf", "first_page": 1, "last_page": 2}],
    dpi=200,
    format="png",
)
pipeline.add_module(pdf2img)

pipeline.run()
print(pdf2img.OutputImages.data)

更多信息

TableToMarkdown

模块简介与适用场景

TableToMarkdown 用于将 TableData 或 TableSeries 转换为 GitHub Flavored Markdown 表格文本。
适合将结构化表格数据直接提供给 LLM、前端 Markdown 渲染器、报告拼装模块或文本文件写出模块。
支持按字段名/标题筛选列、数字列输出精度（与 DocDataWriter / TableData.export_doc_context 语义一致）、是否附带字段单位、是否输出表标题、对含 LaTeX 的字符串按需包上 $...$``（见 ``latex_math），以及是否把结果同时封装为 ResultModel。

端口说明

输入端口 - InputTable：输入表格（TableData 或 TableSeries）
输出端口 - OutputMarkdown：输出 Markdown 文本（str） - OutputResultModel：输出结果模型（ResultModel，包含 1 个字符串字段，其值为 Markdown 文本）

快速上手示例

from gdisdk.modules.converters import TableToMarkdown

to_md = TableToMarkdown(
    columns=["孔号", "深度", "地层"],
    use_titles=True,
    include_units=True,
    include_table_title=True,
    show_index=False,
)
# to_md.InputTable = ...
markdown_text = to_md.execute()
print(markdown_text)
print(to_md.OutputResultModel.data)

参数说明

TableToMarkdown 参数一览
参数名	类型	默认值	说明
`columns`	`list[str] \| str \| None`	`None`	需要输出的列，可使用字段名或字段标题；传入列表时也会按该顺序重排列。仅当输入为 `TableData` 时生效。
`use_titles`	`bool`	`True`	是否使用字段标题作为 Markdown 表头；为 `False` 时使用字段名。
`include_units`	`bool`	`True`	是否在表头后追加单位，例如 `深度 (m)`；无单位时自动忽略。
`include_table_title`	`bool`	`True`	是否在表格前输出表标题。默认使用 Markdown 二级标题 `## 标题`。
`center_title`	`bool`	`False`	是否将表标题输出为居中的 HTML 标题 `<h2 align="center">...</h2>`；仅当 `include_table_title=True` 时有效。
`show_index`	`bool`	`False`	是否把 DataFrame 行索引作为第一列输出。对 LLM 输入场景通常建议保持 `False`。
`precision`	`int \| dict[str, int \\| None] \| None`	`None`	数值列写入 Markdown 时的小数位数。`int` 表示所有数值列统一精度；`dict` 可按列字段名或字段标题指定位数，值为 `None` 表示该列不做格式化。
`latex_math`	`bool \| set[Literal["table_title", "field_titles", "cells"]]`	`False`	是否在含 LaTeX 命令或上下标的字符串外包裹 $...$``（面向支持公式的渲染器）。``False 不包裹；`True` 对表标题、表头字符串单元格按需包裹；也可用集合指定作用范围。
`result_key_name`	`str \| None`	`None`	`OutputResultModel` 中字段的 name；为空时优先使用表的 `name`，再回退到 `"markdown_table"`。
`result_key_title`	`str \| None`	`None`	`OutputResultModel` 中字段的 title；为空时优先使用表的 `title`，再回退到 `result_key_name`。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.filters import TableSelector
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.converters import TableToMarkdown

pipeline = PipeLine(app_name="TableToMarkdownDemo", app_title="表格转Markdown")

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["钻孔一览表"]

pick = TableSelector("PickTable")
pick.table_name = "钻孔一览表"

to_md = TableToMarkdown("ToMarkdown", include_units=True, show_index=False)

pipeline.add_links(
    read_tables.OutputTables >> pick.InputTables
    | pick.OutputTable >> to_md.InputTable
)
pipeline.run()

print(to_md.OutputMarkdown.data)

更多信息

TablesToMarkdown

模块简介与适用场景

TablesToMarkdown 用于将 TableCollection 转换为一个或多个 Markdown 表格文本块。
当表格集合定义了主子表关系且 combine_related=True 时，模块会按主键将主表与子表合并后输出，更适合展示钻孔主表 + 分层子表之类的数据。
合并后的表块可通过 related_tables_title 选用主标题、子标题，或拼接为 "{主表标题} - {子表标题}"。
支持两种合并展示模式：markdown 模式更适合 LLM；html 模式会输出带 rowspan 的 HTML 表格，更适合前端展示。
支持全局或多表分项的数值精度设置，以及与 TableToMarkdown 相同的 latex_math 行为（作用于集合内的每个表块）。

端口说明

输入端口 - InputTables：输入表格集合（TableCollection）
输出端口 - OutputMarkdown：输出完整 Markdown 文本（str，多个表块使用 separator 拼接） - OutputResultModel：输出结果模型（ResultModel，包含 1 个字符串字段，其值为完整 Markdown 文本）

快速上手示例

from gdisdk.modules.converters import TablesToMarkdown

to_md = TablesToMarkdown(
    combine_related=True,
    merge_mode="markdown",
    use_titles=True,
    include_units=True,
    separator="\n\n---\n\n",
)
# to_md.InputTables = ...
markdown_text = to_md.execute()
print(markdown_text)
print(to_md.OutputResultModel.data)

参数说明

TablesToMarkdown 参数一览
参数名	类型	默认值	说明
`tables`	`TableCollection \| None`	`None`	输入表格集合；也可通过端口 `InputTables` 传入（端口优先）。
`combine_related`	`bool`	`True`	当表格集合中存在主子表关系且配置了主键时，是否按关系合并展示；为 `False` 时每张表独立渲染。
`related_tables_title`	`Literal["combined","main","sub"]`	`"sub"`	仅对合并后的主子表块生效。`combined`：标题为 `"{主表标题} - {子表标题}"`；`main` / `sub`：分别仅使用主表或子表的表标题（一方缺失时可回退到另一方）。
`columns`	`dict[str, list[str] \| str] \| None`	`None`	按表配置列筛选。key 可为表的 `name` 或 `title`，value 为字段名/标题或其列表；列表顺序即输出顺序。`combine_related=True` 时，主键列会自动放在最前面。
`merge_mode`	`Literal["markdown","html"]`	`"markdown"`	合并主子表时的展示模式。`markdown` 用空白单元格表示重复主表值；`html` 使用带 `rowspan` 的 HTML 表格。
`use_titles`	`bool`	`True`	是否使用字段标题作为表头；为 `False` 时使用字段名。
`include_units`	`bool`	`True`	是否在表头后追加字段单位。
`include_table_title`	`bool`	`True`	是否在每个表块前输出标题。
`center_title`	`bool`	`False`	是否将标题渲染为居中的 HTML 标题，而不是普通 `##` 标题。
`show_index`	`bool`	`False`	是否输出行索引。仅在“独立渲染每张表”时生效，对合并块无效。
`separator`	`str`	`"\\n\\n---\\n\\n"`	多个表块之间的分隔文本。
`precision`	`int \| dict[str, int \\| None] \\| dict[str, dict[str, int \\| None]] \\| None`	`None`	数值列小数位数。可与 `TableToMarkdown` 相同地使用 `int` 或扁平 `dict[str, int \\| None]` 作用于全部表；也可使用嵌套字典 `{ <表名或表标题>: { <列名或列标题>: n } }` 按表分别指定。
`latex_math`	`bool \| set[Literal["table_title", "field_titles", "cells"]]`	`False`	与 `TableToMarkdown` 相同：对含 LaTeX 的内容按需包裹 $...$ ，作用于集合中每个表块。
`result_key_name`	`str \| None`	`None`	`OutputResultModel` 中字段的 name；为空时优先使用集合 `name`，再回退到 `"markdown_tables"`。
`result_key_title`	`str \| None`	`None`	`OutputResultModel` 中字段的 title；为空时优先使用集合 `title`，再回退到 `result_key_name`。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.converters import TablesToMarkdown

pipeline = PipeLine(app_name="TablesToMarkdownDemo", app_title="表格集合转Markdown")

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

to_md = TablesToMarkdown(
    "ToMarkdown",
    combine_related=True,
    merge_mode="html",
)

pipeline.add_links(read_tables.OutputTables >> to_md.InputTables)
pipeline.run()

print(to_md.OutputMarkdown.data)

更多信息

DocxToMarkdown

模块简介与适用场景

DocxToMarkdown 用于将 Word 文档（.docx）或 RTF 文档（.rtf）转换为 Markdown 文本。
默认输出 ``gfm``（GitHub Flavored Markdown），并默认提取图片、关闭自动换行，适合 LLM / 多模态模型后续处理。
输入既可以是本地文件路径，也可以是 GDIM MinIO 文件信息字典；模块会自动下载后再转换。
本模块支持将 Markdown 中的图片 URL 改写为**相对路径**，便于连同 .md 与图片目录一并拷贝或上传。详见下文 images_dir / images_dir_relative_to_input / relative_image_link。

端口说明

输入端口 - InputDocxFile：输入文档路径（.docx / .rtf）
输出端口 - OutputMarkdown：输出 Markdown 文本内容 - OutputResultModel：结构化结果（ResultModel，仅包含 1 个字符串字段，字段值为 Markdown 文本）

快速上手示例

from gdisdk.modules.converters import DocxToMarkdown

conv = DocxToMarkdown(
    input_file="report.docx",
    result_key_name="report_markdown",
    result_key_title="报告 Markdown",
    markdown_format="gfm",
    extract_images=True,
    images_dir="images",
    wrap_text=False,
)

md_text = conv.execute()
print(md_text)

result = conv.OutputResultModel.data
print(result.report_markdown)

参数说明

DocxToMarkdown 参数一览
参数名	类型	默认值	说明
`input_file`	`FilePath \| dict \| None`	`None`	输入文档路径；也可通过端口 `InputDocxFile` 传入（端口优先）。若为 `dict`，会按 GDIM MinIO 文件信息处理并自动下载。
`result_key_name`	`str \| None`	`None`	`OutputResultModel` 中唯一字段的 name。为空时优先使用输入文件名的 stem；若不可用则回退到 `"markdown_content"`。
`result_key_title`	`str \| None`	`None`	`OutputResultModel` 中唯一字段的 title。为空时默认与 `result_key_name` 相同。
`markdown_format`	`Literal["gfm","markdown","commonmark","markdown_strict","markdown_phpextra","markdown_mmd"]`	`"gfm"`	Markdown 格式。`gfm` 对 LLM 通常更友好；`markdown_mmd` 适合学术写作。
`extract_images`	`bool`	`True`	是否提取图片到目录并在 Markdown 中引用（默认会做相对路径改写，便于打包移动；见 `images_dir` 等参数）。
`images_dir`	`str \| Path \| None`	`None`	图片输出目录。为 `None` 且 `extract_images=True` 时，目录名为 `{input_stem}_images`；具体落在「输入文件所在目录」还是「进程当前工作目录」，由 `images_dir_relative_to_input` 决定。传入绝对路径时不再按 `images_dir_relative_to_input` 改根目录。
`images_dir_relative_to_input`	`bool`	`True`	当 `images_dir` 为 `None` 或相对路径时生效。`True`：以输入文件所在目录为根，即 `Path(input).parent / …`；`False`：以当前工作目录 `Path.cwd()` 为根（默认文件夹名 `{stem}_images` 也同样根在该处）。便于与「相对路径依赖 CWD」的 CLI 习惯对齐。
`relative_image_link`	`bool`	`False`	仅当 `images_dir` 为绝对路径时使用。True``（默认）：将 Markdown 中的本地图片 URL 改写为相对 ``Path(images_dir).parent 的路径（例如图片在 `…/bundle/images/…` 时，应把 `.md` 保存在 `…/bundle` 下，引用形如 `images/media/...`）。`False`：保留 Pandoc 原始输出（常为绝对路径）。当 `images_dir` 非绝对时，本参数无作用（模块会按根目录规则自动做相对路径改写）。
`embed_images`	`bool`	`False`	是否将图片以 base64 data URI 形式嵌入 Markdown（会覆盖 `extract_images` / `images_dir` 设置）。
`wrap_text`	`bool`	`False`	是否对输出文本自动换行。默认会附加 `--wrap=none`，更适合 LLM 处理；若为 `True` 则不主动添加该参数。
`extra_args`	`list[str] \| None`	`None`	额外传给 Pandoc 的命令行参数（高级用法）。例如 `["--toc"]`、`["--standalone"]`。

图片与 Markdown 保存位置（简要约定）

images_dir_relative_to_input=True、且 images_dir 为默认或相对路径：建议将导出的 .md 与输入文档放在**同一目录**（或与所选根目录一致），使 Markdown 图片语法与 HTML <img> 中 src 的相对路径能解析到 images``（或 ``{stem}_images）下的文件。
images_dir 为绝对路径且 relative_image_link=True：将 .md 保存在 **Path(images_dir).parent``**（即图片文件夹的上一级），与 ``relative_image_link 的语义一致。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import DocxToMarkdown

pipeline = PipeLine(app_name="DocxToMarkdownDemo", app_title="Docx转Markdown")

conv = DocxToMarkdown(
    input_file="report.docx",
    result_key_name="report_markdown",
    extract_images=True,
    markdown_format="gfm",
)
pipeline.add_module(conv)

pipeline.run()
print(conv.OutputMarkdown.data)
print(conv.OutputResultModel.data)

Note

当一个 pipeline 中有多个 DocxToMarkdown，且后续模块需要按字段名读取 Markdown 内容时，建议为每个模块设置不同的 result_key_name，避免动态字段名冲突。

上传 GDIM 前检查

是否需要特别处理：当该模块在 GDIM 平台运行，且输入文档来自前端上传文件时，是。
必须检查：
- 不要依赖仅本地存在的固定路径；上传到 GDIM 后，推荐由前端传入 GDIM 文件描述 dict，并直接赋给 input_file；
- 文件建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``dict``） 提供，这是上传后的推荐方式。
建议检查：
- 如需提取图片：优先使用默认 images_dir``（``None）并保持 images_dir_relative_to_input=True，使图片目录与下载后的输入文件在同一父目录下；
- extra_args 中避免依赖仅在本地机器有效的路径或系统资源，尽量只使用与 Pandoc 转换本身相关的参数；
若遗漏，常见现象：
- 本地调试时能读取 D:\\...\\report.docx，上传 GDIM 后因服务器看不到该路径而失败；
- 指定了不可写或不存在的 images_dir，导致图片提取失败或 Markdown 中图片引用异常；

更多信息

TableToDataFrame

模块简介与适用场景

TableToDataFrame 将 TableData``（带字段元信息：title/unit/description 等）转换为纯 ``pandas.DataFrame。
适合把 pipeline 的表格数据接到只接受 DataFrame 的第三方库/自定义脚本中。

端口说明

输入端口 - InputTable：输入表格（TableData）
输出端口 - OutputGeneralTable：输出 ``pandas.DataFrame``（纯 DataFrame，不含字段元信息）

快速上手示例

from gdisdk.modules.converters import TableToDataFrame

conv = TableToDataFrame(use_titles_as_columns=True, preserve_index=True)
# conv.InputTable = ...
df = conv.execute()
print(df)

参数说明

TableToDataFrame 参数一览
参数名	类型	默认值	说明
`use_titles_as_columns`	`bool`	`False`	是否使用字段标题（title）作为 DataFrame 列名；否则使用字段名（name）。
`preserve_index`	`bool`	`True`	是否保留原始索引；为 `False` 时会重置为 0..N 的默认索引。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.filters import TableSelector
from gdisdk.modules.converters import TableToDataFrame

pipeline = PipeLine(app_name="ToDFDemo", app_title="TableData转DataFrame")

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["某表"]

pick = TableSelector("PickTable")
pick.table_name = "某表"

to_df = TableToDataFrame("ToDF", use_titles_as_columns=True)

links = (
    read_tables.OutputTables >> pick.InputTables
    | pick.OutputTable >> to_df.InputTable
)
pipeline.add_links(links)
pipeline.run(return_results={"ToDF": ["OutputGeneralTable"]})

df = to_df.OutputGeneralTable.data
print(df)

更多信息

TableToJson

模块简介与适用场景

TableToJson 用于将 TableData / TableSeries 通过其 serialize() 方法转换为 JSON 对象（dict）。
同时会输出一份 JSON 字符串 到 OutputResultModel，便于直接喂给 LLM 做表格内容分析。
支持对 TableData 按列过滤（columns），并可通过 indent 控制 JSON 文本缩进美化。

端口说明

输入端口 - InputTable：输入表格（TableData）或单列序列（TableSeries）
输出端口 - OutputJsonObject：JSON 对象（dict） - OutputResultModel：结构化结果（ResultModel，仅包含 1 个字段，其值为 JSON 字符串）

快速上手示例

from gdisdk.modules.converters import TableToJson

to_json = TableToJson(
    columns=["字段A", "字段B"],  # 可用字段 name 或 title；仅对 TableData 生效
    indent=2,
    result_key_name="table_json",
    result_key_title="表格JSON",
)
# to_json.InputTable = ...
json_obj = to_json.execute()
print(json_obj)  # dict
print(to_json.OutputResultModel.data)  # ResultModel（字段值是 JSON 字符串）

参数说明

TableToJson 参数一览
参数名	类型	默认值	说明
`columns`	`list[str] \| str \| None`	`None`	需要转换的列名（可为字段 name 或 title）。为空表示全部列。仅当输入为 TableData 时生效；输入为 TableSeries 时忽略该参数。
`result_key_name`	`str \| None`	`None`	`OutputResultModel` 中字段 name 的值。为空时优先使用表/序列的 name；若也为空则使用 `"json_object"`。
`result_key_title`	`str \| None`	`None`	`OutputResultModel` 中字段 title 的值。为空时优先使用表/序列的 title；若也为空则回退到 `result_key_name`。
`indent`	`int \| None`	`None`	JSON 文本缩进。为空时输出紧凑格式；设为 2/4 可读性更好（文本更长）。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.filters import TableSelector
from gdisdk.modules.converters import TableToJson

pipeline = PipeLine(app_name="TableToJsonDemo", app_title="表格转JSON示例")

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["某表"]

pick = TableSelector("PickTable")
pick.table_name = "某表"

to_json = TableToJson("ToJson", columns=None, indent=2)

links = (
    read_tables.OutputTables >> pick.InputTables
    | pick.OutputTable >> to_json.InputTable
)
pipeline.add_links(links)
pipeline.run()

print(to_json.OutputJsonObject.data)
print(to_json.OutputResultModel.data)

更多信息

JsonToTable

模块简介与适用场景

JsonToTable 用于将 JSON 对象（dict）或 JSON 字符串（str）转换为 TableData 或 TableSeries。
会自动判断 JSON 格式并优先走 TableSeries.deserialize / TableData.deserialize；若不是内部序列化格式，会回退尝试 pandas.DataFrame(json_object) 再封装为 TableData。
通过 single_column_as 控制 “单列数据” 最终输出为 TableData 还是 TableSeries。

端口说明

输入端口 - InputJsonObject：输入 JSON（dict 或 JSON 字符串）
输出端口 - OutputTable：输出表格（TableData 或 TableSeries）

快速上手示例

from gdisdk.modules.converters import JsonToTable

to_table = JsonToTable(single_column_as="auto")

# 既支持 dict，也支持 JSON 字符串
to_table.InputJsonObject = '{"a":[1,2], "b":[3,4]}'
table = to_table.execute()
print(type(table), table)

参数说明

JsonToTable 参数一览
参数名	类型	默认值	说明
`json_object`	`JsonObject \| Text \| None`	`None`	输入 JSON；也可通过端口 `InputJsonObject` 传入（端口优先）。当为字符串时会先 `json.loads`，解析失败将抛出 `ValueError`。
`single_column_as`	`Literal["table_data","table_series","auto"]`	`"auto"`	单列数据输出策略： `"auto"`：保持反序列化结果原样（TableSeries JSON → TableSeries；TableData JSON → TableData） `"table_data"`：确保单列输出始终为 TableData（若解析为 TableSeries 则转为单列 TableData） `"table_series"`：确保单列输出始终为 TableSeries（若解析为单列 TableData 则转为 TableSeries）

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import TableToJson, JsonToTable

pipeline = PipeLine(app_name="JsonRoundTripDemo", app_title="JSON与表格互转示例")

to_json = TableToJson("ToJson", indent=None)
to_table = JsonToTable("ToTable", single_column_as="auto")

pipeline.add_links(
    to_json.OutputJsonObject >> to_table.InputJsonObject
)
pipeline.run()

print(to_table.OutputTable.data)

更多信息

TableToSingleResult

模块简介与适用场景

TableToSingleResult 用于从 TableData 中提取指定的**一行**或**一列**，并转换为 SingleResult。
适合把表格中的关键指标（某列/某行）抽成结果对象，供报告、文本模板、结果汇总等环节使用。

端口说明

输入端口 - InputTable：输入表格（TableData）
输出端口 - OutputSingleResult：输出结果（SingleResult，包含 1 个或多个 UnitResult，取决于 result_mode）

快速上手示例

from gdisdk.modules.converters import TableToSingleResult

# 从第 0 行提取：为每个列生成一个 UnitResult（默认 multiple）
conv = TableToSingleResult(axis="row", row_index=0, result_mode="multiple")
# conv.InputTable = ...
single_result = conv.execute()
print(single_result)

参数说明

TableToSingleResult 参数一览
参数名	类型	默认值	说明
`axis`	`Literal["row","column"]`	`"row"`	提取方向：按行或按列。
`row_index`	`str \| int`	`0`	当 `axis="row"` 时生效。字符串表示按表的索引值定位；整数表示按位置（iloc）定位。
`column_index`	`str \| int`	`0`	当 `axis="column"` 时生效。字符串可为字段名或字段标题；整数为列位置。
`result_mode`	`Literal["single","multiple"]`	`"multiple"`	`single`：把该行/列所有值组成一个 list 放到一个 UnitResult；`multiple`：生成多个 UnitResult（更常用）。
`single_result_name` / `single_result_title`	`str \| None`	`None`	仅在 `result_mode="single"` 时有效，用于指定单个 UnitResult 的 name/title。
`multiple_result_prefix`	`str`	`""`	仅在 `result_mode="multiple"` 时有效，为多个 UnitResult 的 name/title 增加前缀。
`use_row_index`	`bool`	`True`	仅当 `axis="column"` 且 `result_mode="multiple"` 时有效：是否使用行索引值命名结果（否则用 0,1,2…）。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import TableToSingleResult

pipeline = PipeLine(app_name="ToSingleResultDemo", app_title="表格转SingleResult")

conv = TableToSingleResult(axis="column", column_index="某指标", result_mode="single")
# links = upstream.OutputTable >> conv.InputTable
# pipeline.add_links(links)
# pipeline.run()

更多信息

TableToResultModel

模块简介与适用场景

TableToResultModel 用于把 TableData 的某一行转换为动态生成的 ResultModel。
输入表中的每一列都会变成结果模型中的一个字段，并自动继承原字段的 title、description 和 unit 元数据，同时根据 pandas dtype 推断 Python 类型。
适合把“单行表格”转换成结构化结果对象，供下游模块、模板渲染或接口返回直接使用。

端口说明

输入端口 - InputTable：输入表格（TableData）
输出端口 - OutputResultModel：输出结果模型（ResultModel）

快速上手示例

from gdisdk.modules.converters import TableToResultModel

conv = TableToResultModel(
    row_index=0,
    model_name="ProjectSummaryModel",
)
# conv.InputTable = ...
result_model = conv.execute()
print(result_model)

参数说明

TableToResultModel 参数一览
参数名	类型	默认值	说明
`row_index`	`str \| int`	`0`	要转换的行。传 `int` 时按位置（`iloc`）取第 N 行；传 `str` 时按索引标签（`loc`）取指定行。
`model_name`	`str`	`"DynamicResultModel"`	动态生成的 `ResultModel` 子类类名。

空表行为说明

当输入为 None 时，模块输出 None。
当表格没有任何列时，模块返回一个不含字段的空 ResultModel。
当表格有列但没有行时，模块仍会按列结构创建 ResultModel，只是所有字段值都为 None；这对“先保留 schema、后续再补值”的场景很有用。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.filters import TableSelector
from gdisdk.modules.converters import TableToResultModel

pipeline = PipeLine(app_name="TableToResultModelDemo", app_title="表格转ResultModel")

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["项目基本信息表"]

pick = TableSelector("PickTable")
pick.table_name = "项目基本信息表"

to_result_model = TableToResultModel(
    "ToResultModel",
    row_index=0,
    model_name="ProjectInfoModel",
)

links = (
    read_tables.OutputTables >> pick.InputTables
    | pick.OutputTable >> to_result_model.InputTable
)
pipeline.add_links(links)
pipeline.run()

result_model = to_result_model.OutputResultModel.data
print(result_model)

更多信息

SingleResultToText

模块简介与适用场景

SingleResultToText 将 SingleResult 按模板格式化为文本。
模板支持使用 UnitResult 的 name 或 title 作为占位符（{name} / {title}），并支持 Python 格式化语法（如 {value:.2f}）。
适合生成报告段落、结论描述、日志输出等。

端口说明

输入端口 - InputSingleResult：输入结果对象（SingleResult）
输出端口 - OutputText：输出格式化文本（str）

快速上手示例

from gdisdk.modules.converters import SingleResultToText

to_text = SingleResultToText(
    text_template="计算结果：{result_a}，精度={result_b:.3f}",
    joiner_for_list_value=", ",
)
# to_text.InputSingleResult = ...
text = to_text.execute()
print(text)

参数说明

SingleResultToText 参数一览
参数名	类型	默认值	说明
`text_template`	`str \| None`	`None`	文本模板。占位符来自 SingleResult 中 UnitResult 的 name / title；支持格式化（如 `{x:.2f}`）。
`joiner_for_list_value`	`str`	`,`	当某个 UnitResult 的 value 为 list 时，使用该连接符拼接成字符串再参与模板格式化。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import SingleResultToText

pipeline = PipeLine(app_name="SingleResultToTextDemo", app_title="结果转文本")

to_text = SingleResultToText(text_template="结论：{结论}")
# links = upstream.OutputSingleResult >> to_text.InputSingleResult
# pipeline.add_links(links)
# pipeline.run()

更多信息

SingleResultToTable

模块简介与适用场景

SingleResultToTable 将 SingleResult 转为只有一行的 TableData：每个 UnitResult 对应一列。
适合把结果对象回写为表格，以便保存、展示或进一步表格化处理。

端口说明

输入端口 - InputSingleResult：输入结果对象（SingleResult）
输出端口 - OutputTable：输出单行表格（TableData，每个 UnitResult 对应一列）

快速上手示例

from gdisdk.modules.converters import SingleResultToTable

conv = SingleResultToTable(table_name="single_result", table_title="结果表", joiner=",")
# conv.InputSingleResult = ...
table = conv.execute()
print(table)

参数说明

SingleResultToTable 参数一览
参数名	类型	默认值	说明
`table_name`	`str \| None`	`None`	输出表 name；为空时使用默认 `"single_result"`。
`table_title`	`str \| None`	`None`	输出表 title；为空时使用默认 `"single_result"`。
`joiner`	`str`	`,`	当某个 UnitResult 的 value 为 list 时，使用该连接符拼接为单个字符串写入表格单元。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import SingleResultToTable

pipeline = PipeLine(app_name="SingleResultToTableDemo", app_title="结果转表格")

conv = SingleResultToTable(table_name="R", table_title="结果表")
# links = upstream.OutputSingleResult >> conv.InputSingleResult
# pipeline.add_links(links)
# pipeline.run()

更多信息

TableToString

模块简介与适用场景

TableToString 用字符串模板把 TableData 按行描述成文本，并将一个或多个模板的结果汇总为 ResultModel 输出。
每个模板 key 会生成 OutputResultModel 中的一个字段；字段值是把所有行描述按 separator 连接后的字符串。
占位符支持表字段名（name）与字段标题（title）。

Note

需要显式设置 templates；未设置时模块会直接输出 None。

端口说明

输入端口 - InputTable：输入表格（TableData）
输出端口 - OutputResultModel：输出结果（ResultModel，每个模板 key 生成一个字段，其值为拼接后的描述文本）

快速上手示例

from gdisdk.modules.converters import TableToString

conv = TableToString(
    templates={
        "simple": "{item} has {count}",
        "detail": "Item {item} count={count:.2f}",
    },
    result_titles={"simple": "简述", "detail": "详细描述"},
    separator="\n",
    prefix="Summary:\n",
    suffix="\n--END--",
    include_empty_rows=False,
)
# conv.InputTable = ...
result_model = conv.execute()
print(result_model)

参数说明

TableToString 参数一览
参数名	类型	默认值	说明
`templates`	`dict[str,str] \| None`	`None`	模板字典：key 作为 `OutputResultModel` 的字段名；value 为格式化模板字符串（可用字段名/标题占位符，支持格式化）。
`result_titles`	`dict[str,str] \| None`	`None`	模板结果标题映射：key 为模板 key，value 为输出字段的 title；为空则用 key 作为 title。
`separator`	`str`	``, ``	多行描述的连接符（如 `", "` 或 `"\\n"`）。
`prefix` / `suffix`	`str`	`""`	可选前后缀，添加到最终整段描述的开头/结尾。
`include_empty_rows`	`bool`	`True`	是否保留 “模板所有字段都为空值” 的行；为 `False` 时会跳过这些行。空值包括：`None`、`NaN`、空字符串 `""`、纯空格字符串。行为说明：仅当模板中的所有字段都为空值时，该行才会被跳过如果只有部分字段为空值，该行仍会保留，空值会被替换为空字符串 `""` 例如模板 `"{A}（{B}^{{{C}}}）"`：若只有 `C` 为空，输出为 `"value_A（value_B^{}）"`

模板语法说明

模板使用 Python 的 .format() 方法进行格式化，支持以下语法：

基本变量替换：使用 {变量名} 或 {字段标题} 作为占位符

templates = {
    "desc": "{geological_age}（{geological_age_symbol}）"
}
# 输出示例：第四系（Q）

格式化数字：使用 Python 格式化语法

templates = {
    "desc": "数值：{value:.2f}"
}
# 输出示例：数值：3.14

输出字面量花括号：使用双花括号 {{ 和 }}

templates = {
    "desc": "格式：{{literal_text}}"
}
# 输出：格式：{literal_text}

变量值包裹在花括号中：使用三花括号 {{{变量名}}}
```
templates = {
    "layer_overview": "{geological_age}（{geological_age_symbol}^{{{geological_origin_symbol}}}）"
}
# 假设 geological_origin_symbol = "apl"
# 输出示例：第四系（Q^{apl}）
```
Note
- {{{variable}}} 会先解析 {{ 为字面量 {，然后 {variable} 被替换为变量值，最后 }} 被解析为字面量 }
- 这样可以将变量的值包裹在花括号中输出

跳过包含空值的行：使用 include_empty_rows=False

# 表格数据（部分行有空值）
data = pd.DataFrame({
    "geological_age": ["第四系", "第三系", "第二系", "侏罗系", None],
    "geological_age_symbol": ["Q", "E", "N", "J", None],
    "geological_origin_symbol": ["apl", None, "", "m", None],
})

table = TableData(data)

converter = TableToString(
    templates={
        "layer_overview": "{geological_age}（{geological_age_symbol}^{{{geological_origin_symbol}}}）"
    },
    separator="、",
    include_empty_rows=False,  # 跳过所有字段都为空的行
)
converter.InputTable = table
result = converter.execute()

# 输出：第四系（Q^{apl}）、第三系（E^{}）、第二系（N^{}）、侏罗系（J^{m}）
# 注意：
# - 第1-4行保留（至少有一个非空字段），空值显示为空字符串
# - 第5行被跳过（所有字段都为 None）

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import TableToString

pipeline = PipeLine(app_name="TableToStringDemo", app_title="表格转描述文本")

conv = TableToString(
    templates={"desc": "{字段A}={字段B}"},
    separator="; ",
)
# links = upstream.OutputTable >> conv.InputTable
# pipeline.add_links(links)
# pipeline.run()

更多信息