MuPDF Table Hunt Options 完全指南：vertically-collapse-bordered-cells 参数解析与源码级原理-开发者社区

图形学
图像处理

【免费下载链接】mupdf

mupdf mirror

项目地址：https://gitcode.com/gh_mirrors/mu/mupdf

Table Hunt 是 MuPDF 结构化文本提取管线中的实验性功能，用于在已提取的 stext 页面（structured text page）上自动识别表格、重建表格结构，并将识别结果写回文档结构树。本文以docs/reference/common/table-hunt-options.md为骨架，完整讲解 Table Hunt 唯一可控参数vertically-collapse-bordered-cells的语义、选项字符串书写语法、C API 与命令行（mutool draw）用法，并结合仓库源码深入其底层实现逻辑。读完本文，你将能够准确地在文本提取任务中配置该参数，理解它在行合并（row merging）阶段如何改变表格结构判定结果。

参数一览：唯一选项及其默认值

Table Hunt Options 的全部配置项只有一个，且为布尔类型：

选项键	类型	默认值	说明
`vertically-collapse-bordered-cells`	布尔	`false`	为 true 时，任何完全带边框的单元格（cell）的内容将被视为适合纵向折叠（vertically collapsing）

该选项当前标注为experimental（实验性），其行为可能在后续版本中不经通知即发生变更（"subject to change without notice"）。这一点在头文件注释、官方 man 手册与文档中均有明确提示。

选项字符串语法：三种书写形式

Table Hunt Options 通过选项字符串（option string）以 key-value 键值对的形式指定。完整语法规则见 docs/reference/common/option-strings.md，MuPDF 支持以下三种等价语法。

1. 逗号分隔键值对（经典语法）

vertically-collapse-bordered-cells=true

多个选项用逗号分隔；值中如需嵌入逗号或等号，可用双引号包裹，双引号本身写作两个连续的双引号。

2. URL 查询字符串语法

以?开头的字符串将按 URL query string 解析：

?vertically-collapse-bordered-cells=true

特殊字符用%HH十六进制转义。

3. JSON 子集语法

也可以直接写一个仅含布尔值、数字、字符串与数字数组的 JSON 对象：

{"vertically-collapse-bordered-cells":true}

布尔值的等价写法

布尔值支持多种等价表示（源码is_yes_option/is_no_option逻辑位于 source/fitz/options.c）：

真值：true、yes、on、enable、1
假值：false、no、off、disable、0
空值（如vertically-collapse-bordered-cells不带=value）等价于true

在结构化文本选项中的位置：table-hunt 开关

Table Hunt Options 本身不独立启用表格识别，它只是细调Table Hunt 行为的参数集。真正的开关是结构化文本选项（Structured Text Options）中的table-hunt标志，见 docs/reference/common/stext-options.md：

table-hunt : Hunt for tables within a (segmented) page

官方文档明确说明：Structured Text Options 中可以一并包含 Table Hunt Options 集合中的选项（"Also, options from the Table Hunt Options set can be included here"）。也就是说，你可以在同一条选项字符串里同时写table-hunt=true与vertically-collapse-bordered-cells=true，前者决定"要不要找表格"，后者决定"找到后如何对待完全带边框的单元格"。

源码级剖析：选项如何被解析与生效

数据结构与枚举

Table Hunt 选项在 C 层面对应结构体fz_table_hunt_options，定义于 include/mupdf/fitz/structured-text.h：

typedef struct { int vertically_collapse_bordered_cells; } fz_table_hunt_options; enum { /* Never collapse the contents of bordered cells vertically. */ FZ_TABLE_HUNT_VERTICAL_COLLAPSE_NO = 0, /* Always collapse the contents of bordered cells vertically. */ FZ_TABLE_HUNT_VERTICAL_COLLAPSE_YES = 1 };

该结构体会被内嵌进fz_stext_options（include/mupdf/fitz/structured-text.h中fz_stext_options的table_hunt_options字段），因此它可以随结构化文本设备一起使用。

解析链路：fz_parse_table_hunt_options

选项字符串的实际解析发生在 source/fitz/stext-table.c：

void fz_init_table_hunt_options(fz_context *ctx, fz_table_hunt_options *opts) { memset(opts, 0, sizeof *opts); } fz_table_hunt_options * fz_parse_table_hunt_options(fz_context *ctx, fz_table_hunt_options *opts, const char *args) { fz_options *options = fz_new_options(ctx, args); fz_try(ctx) { fz_init_table_hunt_options(ctx, opts); fz_apply_table_hunt_options(ctx, opts, options); fz_throw_on_unused_options(ctx, options, "table hunt"); } fz_always(ctx) fz_drop_options(ctx, options); fz_catch(ctx) fz_rethrow(ctx); return opts; }

注意其实现要点：

fz_init_table_hunt_options用memset将结构体清零，即所有字段默认取FZ_TABLE_HUNT_VERTICAL_COLLAPSE_NO（0）——这正是文档所述"默认 false"的代码来源；
解析完成后调用fz_throw_on_unused_options，任何拼写错误或未知的选项键都会触发报错，可有效防止拼写失误被静默忽略。

选项键映射：fz_apply_table_hunt_options

真正的键名映射在 source/fitz/stext-table.c：

void fz_apply_table_hunt_options(fz_context *ctx, fz_table_hunt_options *opts, fz_options *args) { fz_lookup_option_boolean(ctx, args, "vertically-collapse-bordered-cells", &opts->vertically_collapse_bordered_cells); fz_validate_options(ctx, args, "table hunt"); }

fz_lookup_option_boolean（定义于 source/fitz/options.c）负责把前文列出的各种布尔写法归一化为 0/1。当用户未提供该键时，lookup_option返回 0，字段保持初始化后的默认值 0（即false）。

与 stext 选项的联动

fz_apply_stext_options（source/fitz/stext-device.c）在处理table-hunt标志后，会调用fz_apply_table_hunt_options将字符串中剩余的 Table Hunt 键一并应用；同时fz_init_stext_options（同文件 L2125-L2132）在初始化时也会先初始化内嵌的table_hunt_options。因此 Table Hunt 参数可以无缝嵌入 stext 选项字符串。

该参数究竟改变了什么：行合并（merge_rows）逻辑

vertically-collapse-bordered-cells的作用点位于表格网格（grid）构建后的行合并阶段。相关实现见 source/fitz/stext-table.c 的merge_rows函数。

网格由横竖线（h_line/v_line）与"跨越线"（h_crossed/v_crossed）标记出一个个cell_t单元格。默认（FZ_TABLE_HUNT_VERTICAL_COLLAPSE_NO）情况下，两行能否合并取决于：

行是否为空且竖线分布一致；
上方/下方单元格是否为空；
两行单元格的竖线"线度"是否一致；
两行都非空时，是否被横线分隔、是否"跨越"、行距是否足够近（a->content.y1 + fs/2 >= b->content.y0，其中fs取两行字号最大值）。

而当vertically_collapse_bordered_cells != FZ_TABLE_HUNT_VERTICAL_COLLAPSE_NO时，会额外启用一条合并路径：

if (opts != NULL && opts->vertically_collapse_bordered_cells != FZ_TABLE_HUNT_VERTICAL_COLLAPSE_NO) { /* If every cell in a row is plausibly bounded, and none have a horizontal * line under them, we can merge. */ for (x = 0; x < gd->cells->w-1; x++) { cell_t *b = get_cell(gd->cells, x, y+1); if (!plausibly_bordered_spanned_cell(gd->cells, x, y) || b->h_line) break; } if (x == gd->cells->w-1) goto merge_row; }

即：只要一行中每个单元格都"看起来带完整边框"（plausibly_bordered_spanned_cell），且其正下方没有横线（h_line），这两行就可以被纵向合并。这正是文档所述"完全带边框的单元格内容适合纵向折叠"的实现语义。

"看起来带完整边框"如何判定

辅助函数plausibly_bordered_spanned_cell（source/fitz/stext-table.c）的判定流程为：

从单元格(x,y)出发，向左、向右、向上、向下扫描，分别找到包围它的竖线（v_line）与横线（h_line），从而确定一个候选的"大单元格"（super-cell，允许跨行跨列）；
检查大单元格的上下左右四边是否每条边都确实存在边框线（内部扫描时对每一列检查顶/底h_line，对每一行检查左/右v_line）；
再确认大单元格内部没有多余的横线或竖线（cell->h_line || cell->v_line必须全部为假）；
全部通过才返回 1，判定该单元格是"完全带边框"的。

也就是说，该选项只会影响那些四边框线完整、内部无分割线的单元格——这类单元格在视觉上更像一个合并后的整体，纵向折叠（把相邻行的内容并入同一行）在语义上更合理。

何时会真正触发：Table Hunt 的调用路径

fz_table_hunt只是fz_table_hunt_within_bounds以无限矩形调用的一层封装（source/fitz/stext-table.c）：

void fz_table_hunt(fz_context *ctx, fz_stext_page *page, const fz_table_hunt_options *opts) { fz_table_hunt_within_bounds(ctx, page, fz_infinite_rect, opts); }

完整的调用关系为：

结构化文本设备结束一页时，若设置了FZ_STEXT_TABLE_HUNT标志，则调用fz_table_hunt(ctx, page, NULL)（source/fitz/stext-device.c）——注意此时传NULL，即使用默认选项；
若需自定义行为，应通过选项字符串设置vertically-collapse-bordered-cells，它会经由fz_apply_stext_options落入opts->table_hunt_options，最终在行合并阶段生效；
更细粒度的控制还有fz_table_hunt_within_bounds（限定矩形范围）、fz_find_table_within_bounds（把给定矩形内容解释为单个表格）、fz_find_table_within_grid（跳过网格检测阶段、直接使用给定网格）、fz_propose_table_within_bounds（只猜测网格结构、不写入页面），声明均位于 include/mupdf/fitz/structured-text.h。

实际用法：mutool draw 命令行

mutool draw支持通过-O选项传入通用选项字符串（source/tools/mudraw.c中case 'O': options_string = fz_optarg，随后fz_new_options(ctx, options_string)），文本提取时这些选项会应用到 stext 设备上（见source/tools/mudraw.c中fz_apply_stext_options(ctx, &stext_options, user_options)）。因此可以直接这样使用：

# 提取结构化文本（stext）为 XML，同时启用表格识别与纵向折叠 mutool draw -F stext -o out.xml -O "table-hunt=true,vertically-collapse-bordered-cells=true" input.pdf # 使用 JSON 语法 mutool draw -F stext -o out.xml -O '{"table-hunt":true,"vertically-collapse-bordered-cells":true}' input.pdf # 使用 URL 查询字符串语法 mutool draw -F stext -o out.xml -O "?table-hunt=true&vertically-collapse-bordered-cells=true" input.pdf

mutool draw支持的输出文本格式为 plain text、html 与结构化文本（xml 或 json，由-F指定，详见 docs/tools/mutool-draw.md）。man 手册 docs/man/mutool.1 对相关选项的描述为：

table-hunt：在（已分段的）页面中寻找表格；
vertically-collapse-bordered-cells（实验性）：为 true 时，将完全带边框的超级单元格（super-cells）的内容视为可纵向折叠。

C API 用法示例

对于直接使用 MuPDF C API 的开发者，可以通过fz_parse_table_hunt_options或fz_apply_table_hunt_options编程式配置：

fz_table_hunt_options opts; fz_parse_table_hunt_options(ctx, &opts, "vertically-collapse-bordered-cells=true"); /* 之后可将 opts 交给 fz_table_hunt / fz_table_hunt_within_bounds */ /* 若需手动初始化再逐键设置： */ fz_init_table_hunt_options(ctx, &opts); opts.vertically_collapse_bordered_cells = FZ_TABLE_HUNT_VERTICAL_COLLAPSE_YES;

需要强调的是，除非显式指定FZ_STEXT_TABLE_HUNT标志或直接调用fz_table_hunt系列函数，否则 Table Hunt 不会运行，vertically-collapse-bordered-cells也就不会产生任何效果。

注意事项与适用前提

实验性 API：fz_table_hunt、fz_segment_stext_page等接口在头文件中均被标注为实验性，可能在未来版本中变更甚至移除；vertically-collapse-bordered-cells亦不例外；
默认关闭：结构体经memset清零，默认值为FZ_TABLE_HUNT_VERTICAL_COLLAPSE_NO（false），需要时显式开启；
对输入的要求：该选项只在存在完整边框单元格的表格（如典型的全框线表格）上才有意义；对无线框或仅部分线框的表格，plausibly_bordered_spanned_cell的边框完整性检查会使其不满足折叠条件；
拼写敏感：选项键必须精确写作vertically-collapse-bordered-cells，未知键会被fz_throw_on_unused_options直接拒绝并报错；
与segment的关系：官方 man 手册将table-hunt描述为"hunt for tables within a (segmented) page"，即表格识别通常配合segment=true的分段分析使用（fz_segment_stext_page见 include/mupdf/fitz/structured-text.h），但二者是独立的 stext 标志，可按需单独开启。