modules.converters 模块帮助

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

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

ConvertToMaterialTable

模块简介与适用场景

ConvertToMaterialTable 将 TableData 或 TableCollection 中的标准地层/岩性表转换为 MaterialTable，供地质计算、剖面生成、CAD 出图等模块使用。
输入为 TableCollection 时，可按 table_name 选取目标表；未指定时会依次尝试 standard_layer_table、标准地层表，再回退到集合中的第一张表。
典型场景：GDIM 读入 standard_layer_table 后，需转为 MaterialTable 再接入 ConvertToMultiProfile1D、ExportGeoSectionsByBores 等下游模块。
GProps.LayerNumber 列会被强制转为字符串；列名映射与自动匹配规则见后文说明。

端口说明

输入端口 - InputTable：输入表格（TableData）或表集合（TableCollection）。为 None 或空集合时，输出为 None。
输出端口 - OutputMaterialTable：输出 MaterialTable；无法解析输入时为 None。

快速上手示例

from gdisdk.dataclass.terminologies import GeoMaterialProps as GProps
from gdisdk.modules.converters import ConvertToMaterialTable

conv = ConvertToMaterialTable(mname="ConvertToMaterialTable")
conv.column_name_map = {
    "地层编号": GProps.LayerNumber,
    "岩土名称": GProps.MaterialName,
}
conv.sort_by_layer_number = True
conv.reset_material_id = True
# conv.InputTable = ...

conv.execute()
material_table = conv.OutputMaterialTable.data
print(material_table)

参数说明

ConvertToMaterialTable 参数一览
参数名	类型	默认值	说明
`column_name_map`	`dict[str, GProps] \| None`	`None`	表格列与 `GeoMaterialProps` 的映射。键为字段名或字段标题（自动解析）；值为目标材料属性。未配置的列会按字段名或标题自动匹配 `GeoMaterialProps`；详见「列名映射说明」。
`sort_by_layer_number`	`bool`	`True`	是否按 `LayerNumber` 排序；排序后 `material_id` 从 0 起编。若输出中无 `LayerNumber` 列，会发出警告且不排序。
`reset_material_id`	`bool`	`True`	排序后是否将 `material_id` 重置为与 `LayerNumber` 升序一致的 0..N-1；仅当 `sort_by_layer_number=True` 时生效。
`table_name`	`str \| None`	`None`	输入为 `TableCollection` 时，用于指定目标表的 `name` 或 `title`。为 `None` 时依次尝试 `standard_layer_table`、`标准地层表`，均不存在则取集合中第一张表。指定名称不存在时抛出 `ValueError`。

列名映射说明

列与 GeoMaterialProps 的对应关系按以下优先级解析：

**显式映射**（column_name_map）：键先按字段名匹配，再按字段标题匹配（与 TableData.resolve_columns_map 一致）。
自动匹配：未在映射中出现的列，先尝试字段名是否为 GeoMaterialProps 成员名，再尝试字段标题是否与 GeoMaterialProps 标题一致。
MaterialID：映射或原表中存在 MaterialID 列则保留；否则自动生成 0..N-1。
LayerNumber：匹配成功后强制转为字符串类型。

在 pipeline 中的使用方式

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

pipeline = PipeLine(app_name="MaterialTableDemo", app_title="标准地层表转MaterialTable")
pipeline.update_gdim_state(token="你的GDIM Token", proj_id="你的GDIM项目ID")

reader = GdimTableReader(mname="ReadTables")
reader.table_fields = ["standard_layer_table"]

conv = ConvertToMaterialTable(mname="ConvertMaterial")
conv.sort_by_layer_number = True

links = reader.OutputTables >> conv.InputTable
pipeline.add_links(links)
pipeline.run()

material_table = conv.OutputMaterialTable.data
print(material_table)

更多信息

API 参考 - modules 包
完整类定义与参数说明（converters）
下游 MultiProfile1D 转换见本章 ConvertToMultiProfile1D；剖面导出示例见 modules.geoDataProcess 模块帮助中的 ExportGeoSectionsByBores 章节。

ConvertToMultiProfile1D

模块简介与适用场景

ConvertToMultiProfile1D 将 TableCollection 中的 钻孔一览表 与 地层表，结合 MaterialTable，组装为 MultiProfile1D，供剖切线生成、地形切片、地质剖面出图等下游模块使用。
输入表集合须同时包含钻孔表与地层表；表名与列名可按中英文标准字段自动解析，也可通过参数显式指定。
典型场景：GDIM 读入 bore_table / layer_table``（或中文标题 ``钻孔一览表 / 地层表）及 standard_layer_table 转成的 MaterialTable 后，接入 CreatePolyLines、ExportGeoSectionsByBores 等模块。
地层编号会通过 MaterialTable.get_material_id 解析为 materials_id；若某层编号在材料表中不存在，执行时会抛出异常。

端口说明

输入端口 - InputTables：输入表集合（TableCollection）。须含钻孔表与地层表；为 None 时输出为 None。 - InputMaterialTable：岩性/标准地层表（MaterialTable），用于将地层编号映射为 materials_id；为 None 时输出为 None。
输出端口 - OutputMultiProfile1D：输出 MultiProfile1D，内含 profiles_table``（钻孔属性）与 ``layers_table``（分层与 ``materials_id）；任一必填输入缺失时为 None。

快速上手示例

from gdisdk.modules.converters import ConvertToMultiProfile1D

conv = ConvertToMultiProfile1D(mname="ConvertToMultiProfile1D")
# conv.InputTables = table_collection   # 含钻孔一览表与地层表
# conv.InputMaterialTable = material_table
# conv.selected_bores = ["ZK1", "ZK2"]  # 可选：仅保留指定钻孔
# conv.sort_layers_table = True         # 可选：按钻孔号、层底深度排序

conv.execute()
multi_profile = conv.OutputMultiProfile1D.data
print(multi_profile.profiles_table)
print(multi_profile.layers_table)

参数说明

ConvertToMultiProfile1D 参数一览
参数名	类型	默认值	说明
`bore_table_name`	`str \| None`	`None`	钻孔一览表在集合中的 `name` 或 `title`。为 `None` 时依次尝试 `bore_table`、`钻孔一览表`；均不存在时抛出 `ValueError`。
`bore_table_field_names`	`list[str] \| None`	`None`	钻孔表五列标识（字段名或字段标题），顺序为：钻孔编号、孔口高程、X、Y、稳定水位埋深。为 `None` 时按标准中英文字段自动匹配；详见「表与字段解析说明」。
`layer_table_name`	`str \| None`	`None`	地层表在集合中的 `name` 或 `title`。为 `None` 时依次尝试 `layer_table`、`地层表`。
`layer_table_field_names`	`list[str] \| None`	`None`	地层表三列标识：钻孔编号、层底深度、地层编号。为 `None` 时按标准中英文字段自动匹配。
`selected_bores`	`list[str] \| None`	`None`	若设置，仅保留列表中的钻孔编号（与钻孔表「钻孔编号」列取值一致）；`profiles_table` 与 `layers_table` 同步过滤。
`sort_layers_table`	`bool`	`False`	为 `False` 时保持地层表原始行序；为 `True` 时先按钻孔编号升序、再按层底深度升序排序后再组装 `layers_table`。

表与字段解析说明

钻孔一览表**（``bore_table_field_names`` 未指定时，按顺序匹配字段 **name 或 title）：

钻孔表标准字段
顺序	字段 name	字段 title
1	`bore_number`	`钻孔编号`
2	`bore_top`	`孔口高程`
3	`x_coordinate`	`X坐标`
4	`y_coordinate`	`Y坐标`
5	`steady_ground_water_depth`	`稳定水位埋深`

**地层表**（layer_table_field_names 未指定时）：

地层表标准字段
顺序	字段 name	字段 title
1	`bore_number`	`钻孔编号`
2	`layer_bottom_depth`	`层底深度`
3	`layer_number`	`地层编号`

组装后的 MultiProfile1D 内部列名：

profiles_table：pnum、top、x_coord、y_coord、gwt_depth
layers_table：pnum、layers_depth、materials_id

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.converters import ConvertToMaterialTable, ConvertToMultiProfile1D
from gdisdk.modules.gisOperators import CreatePolyLines

pipeline = PipeLine(app_name="MultiProfileDemo", app_title="钻孔表转MultiProfile1D")
pipeline.update_gdim_state(token="你的GDIM Token", proj_id="你的GDIM项目ID")

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

convert_material = ConvertToMaterialTable(mname="ConvertMaterial")
convert_material.sort_by_layer_number = True

convert_bores = ConvertToMultiProfile1D(mname="ConvertBores")
create_lines = CreatePolyLines(mname="CreatePolyLines")

links = (
    reader.OutputTables >> convert_material.InputTable
    | reader.OutputTables >> convert_bores.InputTables
    | convert_material.OutputMaterialTable >> convert_bores.InputMaterialTable
    | convert_bores.OutputMultiProfile1D >> create_lines.InputMultiProfile1D
)
pipeline.add_links(links)
pipeline.run()

multi_profile = convert_bores.OutputMultiProfile1D.data
print(multi_profile)

更多信息

API 参考 - modules 包
完整类定义与参数说明（converters）
上游材料表转换见本章 ConvertToMaterialTable；剖切线与剖面出图见 modules.geoDataProcess 模块帮助中的 SliceTerrain、ExportGeoSectionsByBores 章节。

PdfToImages

模块简介与适用场景

PdfToImages 用于将一个或多个 PDF 文件按页转换为图片文件（PNG/JPG/JPEG）。
适合在 pipeline 中将 PDF 扫描件/报表等转为图片，供后续识别、标注、可视化或归档。

端口说明

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

快速上手示例

from gdisdk.modules.converters import PdfToImages

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

pdf2img.execute()
print(pdf2img.OutputImages.data)

参数说明

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(mname="PdfToImages")
pdf2img.pdf_configs = [{"file_path": "doc1.pdf", "first_page": 1, "last_page": 2}]
pdf2img.dpi = 200
pdf2img.format = "png"
pipeline.add_module(pdf2img)

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

更多信息

TableToMarkdown

模块简介与适用场景

TableToMarkdown 用于将 TableData 或 TableSeries 转换为 GitHub Flavored Markdown 表格文本。
适合将结构化表格数据直接提供给 LLM、前端 Markdown 渲染器、报告拼装模块或文本文件写出模块。
可选将结果同时封装为 ResultModel 输出到 OutputResultModel。

端口说明

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

快速上手示例

from gdisdk.modules.converters import TableToMarkdown

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

to_md.execute()
print(to_md.OutputMarkdown.data)
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(mname="ReadTables")
read_tables.table_fields = ["钻孔一览表"]

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

to_md = TableToMarkdown(mname="ToMarkdown")
to_md.include_units = True
to_md.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 表格文本块。
当集合存在主子表关系时，可自动合并展示（更适合钻孔主表 + 分层子表等场景）；merge_mode 可在 LLM 友好的 Markdown 与带 rowspan 的 HTML 表格之间切换。
列筛选、精度、LaTeX 等行为与 TableToMarkdown 一致。

端口说明

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

快速上手示例

from gdisdk.modules.converters import TablesToMarkdown

to_md = TablesToMarkdown(mname="TablesToMarkdown")
to_md.combine_related = True
to_md.merge_mode = "markdown"
to_md.use_titles = True
to_md.include_units = True
to_md.separator = "\n\n---\n\n"
# to_md.InputTables = ...

to_md.execute()
print(to_md.OutputMarkdown.data)
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(mname="ReadTables")
read_tables.table_fields = ["钻孔一览表", "地层信息表"]

to_md = TablesToMarkdown(mname="ToMarkdown")
to_md.combine_related = True
to_md.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 文本。
适合 LLM / 多模态模型后续处理；输入既可以是本地文件路径，也可以是 GDIM MinIO 文件信息字典（模块会自动下载后再转换）。
提取图片时可将 Markdown 中的图片链接改写为相对路径，便于连同 .md 与图片目录一并拷贝或上传（详见 images_dir 等参数）。

端口说明

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

快速上手示例

from gdisdk.modules.converters import DocxToMarkdown

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

conv.execute()
print(conv.OutputMarkdown.data)

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(mname="DocxToMarkdown")
conv.input_file = "report.docx"
conv.result_key_name = "report_markdown"
conv.extract_images = True
conv.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(mname="TableToDataFrame")
conv.use_titles_as_columns = True
conv.preserve_index = True
# conv.InputTable = ...

conv.execute()
df = conv.OutputGeneralTable.data
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(mname="ReadTables")
read_tables.table_fields = ["某表"]

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

to_df = TableToDataFrame(mname="ToDF")
to_df.use_titles_as_columns = True

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

df = to_df.OutputGeneralTable.data
print(df)

更多信息

TableToJson

模块简介与适用场景

TableToJson 用于将 TableData / TableSeries 通过其 serialize() 方法转换为 JSON 对象（dict）。
同时会输出一份 JSON 字符串 到 OutputResultModel，便于直接喂给 LLM 做表格内容分析。

端口说明

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

快速上手示例

from gdisdk.modules.converters import TableToJson

to_json = TableToJson(mname="TableToJson")
to_json.columns = ["字段A", "字段B"]  # 可用字段 name 或 title；仅对 TableData 生效
to_json.indent = 2
to_json.result_key_name = "table_json"
to_json.result_key_title = "表格JSON"
# to_json.InputTable = ...

to_json.execute()
print(to_json.OutputJsonObject.data)  # 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(mname="ReadTables")
read_tables.table_fields = ["某表"]

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

to_json = TableToJson(mname="ToJson")
to_json.columns = None
to_json.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。

端口说明

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

快速上手示例

from gdisdk.modules.converters import JsonToTable

to_table = JsonToTable(mname="JsonToTable")
to_table.single_column_as = "auto"

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

参数说明

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(mname="ToJson")
to_json.indent = None
to_table = JsonToTable(mname="ToTable")
to_table.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(mname="TableToSingleResult")
conv.axis = "row"
conv.row_index = 0
conv.result_mode = "multiple"
# conv.InputTable = ...

conv.execute()
print(conv.OutputSingleResult.data)

参数说明

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(mname="ToSingleResult")
conv.axis = "column"
conv.column_index = "某指标"
conv.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(mname="TableToResultModel")
conv.row_index = 0
conv.model_name = "ProjectSummaryModel"
# conv.InputTable = ...

conv.execute()
print(conv.OutputResultModel.data)

参数说明

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(mname="ReadTables")
read_tables.table_fields = ["项目基本信息表"]

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

to_result_model = TableToResultModel(mname="ToResultModel")
to_result_model.row_index = 0
to_result_model.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 按模板格式化为文本。
适合生成报告段落、结论描述、日志输出等。

端口说明

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

快速上手示例

from gdisdk.modules.converters import SingleResultToText

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

to_text.execute()
print(to_text.OutputText.data)

参数说明

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(mname="ToText")
to_text.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(mname="SingleResultToTable")
conv.table_name = "single_result"
conv.table_title = "结果表"
conv.joiner = ","
# conv.InputSingleResult = ...

conv.execute()
print(conv.OutputTable.data)

参数说明

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(mname="ToTable")
conv.table_name = "R"
conv.table_title = "结果表"
# links = upstream.OutputSingleResult >> conv.InputSingleResult
# pipeline.add_links(links)
# pipeline.run()

更多信息

ResultModelToTable

模块简介与适用场景

ResultModelToTable 将 ResultModel``（或其子类）转为只有一行的 ``TableData：每个模型字段对应一列，字段的 title 与 unit 会写入 FieldMetadata。
与 SingleResultToTable 类似，都用于把结构化结果回写为表格；区别在于本模块面向 ResultModel 类型化字段，而非 SingleResult 中的 UnitResult 列表。
典型场景：上游模块输出 ResultModel``（如 ``GdimAppProjectInfoReader 的项目信息），需转为 TableData 再写入 GDIM/MDB 或并入 TableCollection。

端口说明

输入端口 - InputResultModel：输入结构化结果（ResultModel 或其子类）。为 None 时，输出为 None。
输出端口 - OutputTable：输出单行表格（TableData，每个模型字段对应一列）

快速上手示例

from gdisdk.modules.converters import ResultModelToTable

conv = ResultModelToTable(mname="ResultModelToTable")
conv.table_name = "app_project_information"
conv.table_title = "项目信息表"
conv.joiner = ","
# conv.InputResultModel = ...

conv.execute()
print(conv.OutputTable.data)

参数说明

ResultModelToTable 参数一览
参数名	类型	默认值	说明
`table_name`	`str \| None`	`None`	输出表 `name`；不为 `None` 时覆盖 `ResultModel.convert_to_table_data` 生成的默认 `"result"`。
`table_title`	`str \| None`	`None`	输出表 `title`；不为 `None` 时覆盖转换结果中的默认 title。
`joiner`	`str`	`,`	当某个字段值为 list 时，使用该连接符拼接为单个字符串写入表格单元。

在 pipeline 中的使用方式

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

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

conv = ResultModelToTable(mname="ToTable")
conv.table_name = "app_project_information"
conv.table_title = "项目信息表"
# links = upstream.OutputResultModel >> conv.InputResultModel
# pipeline.add_links(links)
# pipeline.run()

更多信息

TableToString

模块简介与适用场景

TableToString 用字符串模板把 TableData 按行描述成文本，并将一个或多个模板的结果汇总为 ResultModel 输出。

Note

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

端口说明

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

快速上手示例

from gdisdk.modules.converters import TableToString

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

conv.execute()
print(conv.OutputResultModel.data)

参数说明

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(mname="TableToString")
converter.templates = {
    "layer_overview": "{geological_age}（{geological_age_symbol}^{{{geological_origin_symbol}}}）"
}
converter.separator = "、"
converter.include_empty_rows = False  # 跳过所有字段都为空的行
converter.InputTable = table
converter.execute()
result = converter.OutputResultModel.data

# 输出：第四系（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(mname="ToString")
conv.templates = {"desc": "{字段A}={字段B}"}
conv.separator = "; "
# links = upstream.OutputTable >> conv.InputTable
# pipeline.add_links(links)
# pipeline.run()

更多信息