docvortex 0.4.7__tar.gz → 0.4.8__tar.gz

{docvortex-0.4.7/src/docvortex.egg-info → docvortex-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.4.7
+Version: 0.4.8
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex

docvortex-0.4.8/docs/flash-spatial-layout-followup-2026-09-16.md

@@ -0,0 +1,48 @@
+# Flash 标题与段落成员补充修复验收
+
+## 结果
+
+本轮完成 9 组补充标注：fix P10 的附录 E 是完整的双行 `paragraph_title`；dual_caption P5、P10、P12、P15 指定的 7 处小字号粗体标题全部提升，P15 的双行标题保持一个块；dual_caption P10 的 `Prescribing` 完整、唯一地归于下一段，上一段止于 `day.`，两段行框和块框不再共享该行。
+
+同一规则还自然恢复了 9 个同类标题。两份原件共有 12 个变化页，均对照原文、修改前及修改后标框逐页接受。生产规则不使用文件名、页码、块号、论文原句或特定字体名称。
+
+- 逐页画廊：`output/pdf/flash-round3-followup/final/index.html`
+- 两份完整导出：`output/pdf/flash-round3-followup/exports/`（HTML、MiddleJson、图片、资产包）
+- 逐项裁决：`tests/fixtures/flash_round3_followup_review_decisions.json`
+
+## 实现与成因
+
+多行标题使用后继正文重复左右缘作为额外的局部居中参照。同一物理行的字体碎片先按基线聚合，首行和列表缩进不决定栏中心；保留原有未知字重和跨页重复排版要求。
+
+小字号标题单独使用相对字号、可靠字重、上下独立留白、后继正文和容器排除证据。已确认的标题行组通过内部 `title_band_id` 传递给语义行连接，避免分类后重新拆开。该字段不进入公共协议。
+
+段首恢复只对具有共同物理行身份、同字体、同栏和后继整行支持的连续文字放宽空格距离。空间合并复用统一成员合并函数，完整传递 `_text_lines`、内容和几何元数据，解决旧实现只合并内容及框、随后又从不完整成员重建内容造成的漏词。
+
+## 回归与裁决
+
+- **1480 项测试通过**，耗时 206.37 秒；包含新增的 35 项标题、成员守恒、数值列保护及真实样本检查。针对性检查单独运行 **200 项通过**。
+- 历史 **19 份／168 页**相对本次冻结基线零变化。
+- 第一轮 **8 份／118 页**相对本次冻结基线零变化；第二轮 **6 份／98 页**包含其中，不累计为额外独立覆盖量。
+- 首个候选曾把 nougat P17 小表格的标签和百分数列连入一组，造成两条比较记录合并。对照原页后拒绝此变化，通过排除数值列的宽空格放宽修复，并增加合成与原件反例；未更新旧基线。
+- 最终两份 41 页原件的非空白文本差异仅为恢复 `Prescribing`，未删除其他字符。另以源成员集合、唯一归属、行框和公共段落边界断言验证，避免仅比较旧输出遗漏已有缺字。
+- 公共 `parse → MiddleJson → HTML／资产包` 全链路通过，34 个资产均可解析，缺失图片和解析诊断为空。浏览器确认附录 E 和小标题的标题层级、完整双行标题，以及独立的 `Prescribing` 段落。
+- 21 个修改或新增 Python 文件通过 Ruff、格式检查，`git diff --check` 通过。
+
+## 冻结与重放
+
+冻结的是上一轮未提交源码及其输出，而非仅 Git HEAD。源码指纹 `1533f54963374b15a3cb18ff581f594a1a75fdc9eea47e88ee44cbddbf6988f8` 已与 `baseline-code/src` 逐文件核对；原输出保存在 `output/pdf/flash-round3-followup/baseline/`。本轮最终源码指纹为 `d9a40dab073789eafc52b25fd2fc5771ae0ccc930b44222735eac7c4310f774c`，画廊、历史重放和公共导出记录一致。
+
+```sh
+PY=/Users/myhloli/projects/20240809magic_pdf/Magic-PDF/.venv1/bin/python
+PYTHONPATH=src "$PY" tools/review_flash_round3.py --baseline output/pdf/flash-round3-followup/baseline/final --output output/pdf/flash-round3-followup/final
+PYTHONPATH=src "$PY" tools/review_flash_annotations.py --output output/pdf/flash-round3-followup/final-manual
+PYTHONPATH=src "$PY" tools/review_flash_regression.py --output output/pdf/flash-round3-followup/final-history --compare-to output/pdf/flash-round3-followup/baseline/accepted-history
+PYTHONPATH=src "$PY" tools/review_flash_round2.py --manifest tests/fixtures/flash_round3_annotations.json --output output/pdf/flash-round3-followup/exports
+PYTHONPATH=src "$PY" -m pytest tests/unittest/test_flash_pdf_*.py tests/unittest/test_flash_rule_generalization.py tests/unittest/test_flash_manual_annotations.py tests/unittest/test_flash_round2_annotations.py tests/unittest/test_flash_round3_annotations.py tests/unittest/test_flash_spatial_evidence.py tests/unittest/test_pdf_document.py tests/unittest/test_pdf_object_clipping.py tests/unittest/test_pdf_text_dedup.py tests/unittest/test_native_pdf_table*.py tests/unittest/test_pdf_visualization.py tests/unittest/test_pdf_text_styles.py tests/unittest/test_postprocess_paragraphs.py -q
+```
+
+仍位于 `codex/flash-spatial-layout-round3`，未提交或推送；结果为指定本地 macOS／Python／PDFium 运行时的验收，未运行远端 CI。本轮没有新增公共参数或输出类型。
+
+## 后续栏首及长标题补充
+
+P8 与 P11 的剩余两处标题已修复，详见 [栏首与近满栏小标题验收](flash-title-coverage-2026-09-16.md)。

docvortex-0.4.8/docs/flash-spatial-layout-round3-2026-09-16.md

@@ -0,0 +1,76 @@
+# Flash 原生 PDF 空间布局：第三轮修复与验收
+
+## 范围与证据
+
+基于 `a8511caa6615fcf479a2b861061b4633ae1eef5f`，开发分支为 `codex/flash-spatial-layout-round3`。两份原件共 41 页、25 个重点页、36 组人工标注。源文件和原始块锚点保存在 `tests/fixtures/flash_round3_annotations.json`，断言不依赖修复后的块编号。
+
+- `journal_dual_caption.pdf`：20 页；SHA256 `ae9ee7db89a1ff23f9be8ecdb4ae70596ad1e3eec78c1d370f562a4aad3aa5ec`。
+- `quantum_appendix_layout.pdf`：21 页；SHA256 `6f393579aacfb8119f92790e565d539856e21d901f683147d242daefd6d094bb`。
+- 原页／修改前／修改后画廊：`output/pdf/flash-round3/final/index.html`。
+- 公共接口导出：`output/pdf/flash-round3/final-exports/`，每份文档包含 HTML、MiddleJson、图片资产及 ZIP。
+- 修改前代码的完整源码指纹为 `e5ddd06fdb910bfcb83e316e42c36b58bfb8d51baac2682f68d919be183434c6`，已与独立的只读基准 checkout 核对。
+
+## 实现
+
+1. **参考文献和局部分栏**：使用连续编号的稳定左缘确定参考区域的横向和纵向范围，支持无 References 标题、齐平或悬挂续行。局部标题限定区域起点；只有具有独立留白的章节标题才能终止区域。作者年代式条目的年份不充当编号。混合栏页上方正文独立排序，避免上标的微小高度差让右栏先读。
+2. **标题和段落**：限制正文原型对满栏连续行的提升及标题邻行传播；多行未知字重标题增加居中对齐证据。首页独立标题带和出版日期带支持文档标题及编号机构识别。同行碎片依据同栏、基线、后继整行支持恢复；段内数学前缀按成员而非外接框认领。
+3. **公式**：在原有检测结束后补齐独立数学带及右侧／右下编号，只扩充不完整区域。完整公式沿用原有结果。短标记必须有包围结构，百分数及全角百分数不能作为编号；正文短句、栏沟及表格为屏障。保留既有行内数学回退成员，不因其已被正文认领而删除。
+4. **表注与图例**：以表内规则行的结束位置分离外框包住的表注，表格恢复和投影共用收缩后的表体范围。从紧邻图片的独立图编号恢复破碎说明，完整图注不再次扩展。图例先恢复药名—符号物理行，再按分类和重复栏左缘组织阅读顺序，统一归属图片的图注释。
+5. **公共转换**：临时参考条目起点及段界证据传入页面合并阶段；新编号和已确认段界禁止续接，跨栏／跨页参考续项可保留 `continues_prev`。临时字段在 PageInfo 对象化前移除，不新增公共参数或块类型。
+
+生产规则没有新增文件名、页码、块号、论文原句或特定字体名称判断。新增函数均有中文说明。
+
+## 回归裁决
+
+没有通过更新旧基线消除失败。下列候选变化均通过规则收紧解决，审阅过程的失败图像仍保留在输出目录：
+
+| 回归证据 | 裁决与处理 |
+| --- | --- |
+| `current-history/demo2/page-03-after.png`：短正文 `is given by` 被吸入公式 | 扩展短正文屏障，并把数学带恢复放在既有检测之后，完整公式不重建。 |
+| `current-history/caibao1/page-02-after.png`：并列图片的图注归属和顺序改变 | 图注恢复入口限定为独立编号及其尚未归组的说明带；已有完整图注沿用原流程。 |
+| 作者年代式参考文献被按年份重新分条；参考上下文侵入附录 | 编号模式与传统悬挂条目分组分开，仅对可靠编号区域提前保护；保留附录终止及脚注排除规则。 |
+| `refined2-history/中文论文4/page-02-after.png`：正文中的行内数学内容缺失 | 区分原先用于正文恢复的已认领成员和新公式补全成员，保留前者；增加全角百分数反例。 |
+| `frames_v1/v2` 附录数字列表吸入下方图说明 | 作者年代式跨页状态不激活数字参考模式；普通编号仍作为传统分组边界，保留原基线并增加四页反例。 |
+| `fix.pdf` 参考条目内部的斜体行被当成区域终点 | 终点必须具有独立留白；真实样本同时检查条目数、条目完整性和无假标题，不能只数编号。 |
+
+两个临时字段 `_reference_start`、`_paragraph_boundary` 不进入旧可见内容指纹；只排除这两个明确字段，没有放宽类型、内容、顺序或 bbox 校验。其行为由公共页面转换测试单独断言，包括跨页数字开头续项、新编号不续接、图例归属和私有字段清理。
+
+## 重放
+
+使用用户指定的 `.venv1`，在仓库根目录执行：
+
+```sh
+PY=/Users/myhloli/projects/20240809magic_pdf/Magic-PDF/.venv1/bin/python
+PYTHONPATH=src "$PY" tools/review_flash_round3.py
+PYTHONPATH=src "$PY" tools/review_flash_round2.py --manifest tests/fixtures/flash_round3_annotations.json --output output/pdf/flash-round3/final-exports
+PYTHONPATH=src "$PY" tools/review_flash_regression.py --output output/pdf/flash-round3/accepted-history --compare-to output/pdf/flash-round3/baseline-history
+PYTHONPATH=src "$PY" tools/review_flash_annotations.py --output output/pdf/flash-round3/accepted-manual
+PYTHONPATH=src "$PY" -m pytest tests/unittest/test_flash_pdf_*.py tests/unittest/test_flash_rule_generalization.py tests/unittest/test_flash_manual_annotations.py tests/unittest/test_flash_round2_annotations.py tests/unittest/test_flash_round3_annotations.py tests/unittest/test_flash_spatial_evidence.py tests/unittest/test_pdf_document.py tests/unittest/test_pdf_object_clipping.py tests/unittest/test_pdf_text_dedup.py tests/unittest/test_native_pdf_table*.py tests/unittest/test_pdf_visualization.py tests/unittest/test_pdf_text_styles.py tests/unittest/test_postprocess_paragraphs.py -q
+```
+
+逐项裁决和最终运行结果见 `tests/fixtures/flash_round3_review_decisions.json`。公式继续使用现有图片资产路径；本轮不处理原 PDF 的错误字符映射或引入数学内容识别。
+
+## 最终验收结果
+
+- **1445 项测试通过**，耗时 198.50 秒；日志：`output/pdf/flash-round3/accepted-tests.log`。19 个修改／新增 Python 文件通过 Ruff 和格式检查，`git diff --check` 通过。
+- 两份新文档 **41 页**全部重放，**36 组标注**通过针对性结构测试及视觉审阅；画廊覆盖 **25 个标注页与 2 个额外变化页**。额外变化为第一份 P12 短尾接回同段、fix P7 附录标题与正文分离。
+- 历史 **19 份／168 页**可见内容、类型、顺序和块框指纹均与修改前一致。
+- 第一轮 **8 份／118 页**中 114 页一致，4 页变化逐项接受，见下表。第二轮 **6 份／98 页**是上述完整文档的子集，已全部覆盖；不将重叠页累加为独立覆盖量。
+- `parse → MiddleJson → HTML／资产包` 已完成，两份导出共 34 个资产，缺失图片和解析诊断均为空。浏览器检查了正文标题、图例分组阅读顺序及图片加载。公式仍使用原生裁图，不改变数学内容识别方式。
+- 对原生正文、图注、表格及公式检测内容进行非空白字符守恒核对；仅第一份 P5、P17 和 fix P20 共四处行末连字符随正常断词连接被移除，无其他非空白字符丢失或新增。
+- 未修改原有测试金标。以下四页是完整重放产生的自然改善，已保存旧／新指纹和逐项接受理由；拒绝的候选变化通过收紧规则恢复原基线。
+
+| 文档／页 | 接受理由 |
+| --- | --- |
+| fornax P1 | 独立双行主标题由 `paragraph_title` 恢复为 `doc_title`，作者和机构顺序保持。 |
+| mmlu_redux P13 | 独立加粗的 Checklist 由正文恢复为段落标题。 |
+| k2_treap P3 | 保留行内区间右括号对应的原生映射字符，避免与后继正文粘连；不做字符替换。 |
+| k2_treap P9 | 保留行内矩阵维数右括号对应的原生映射字符；块框和阅读顺序不变。 |
+
+既有语料变化页与恢复旧基线的页面对比：`output/pdf/flash-round3/manual-visuals/index.html`。全部裁决（包括源码、原件及页面指纹）保存在 `tests/fixtures/flash_round3_review_decisions.json`。
+
+本次结果为指定 macOS／Python／PDFium 运行时的本地验收；未执行远端 CI，未提交或推送。原 PDF 的字符映射错误仍沿用原有处理，本轮没有引入 OCR／VLM。
+
+## 后续补充验收
+
+用户新增的标题与段落成员问题已在补充轮完成，见 [补充修复验收](flash-spatial-layout-followup-2026-09-16.md)。本报告保留第一轮实现时的验证记录。

docvortex-0.4.8/docs/flash-title-coverage-2026-09-16.md

@@ -0,0 +1,25 @@
+# 栏首与近满栏小标题补充验收
+
+已修复 dual_caption P8 块1（Altered Protein Metabolism）和 P11 块10（Cyproheptadine and Other Antiserotonergic Drugs）。两者均输出为 `paragraph_title`，最终 HTML 均为一个 h2。
+
+## 原因与通用修复
+
+- P8 标题为栏内第一行，原规则因没有上一行而直接跳过。现在允许缺少上方正文，但要求位置与全页正文区顶部相符；页眉不参与上方正文判定，字体、字重、下方留白及真实后继正文等条件仍保留。
+- P11 标题约占局部正文宽度 95%，被 90% 固定比例上限排除。现在使用标题是否落在实际栏左右边界内判断，右边允许半个正文行高的几何误差；越栏标题不能通过。
+- 没有增加文件名、页码、块号、原句或字体名称条件。新增 24 个合成正反例，独立改变栏宽、字号和位置，覆盖栏首、长标题、越栏与侧栏中部情形；新增两处原件断言。
+
+## 验收
+
+**1506 项测试通过**（230.72 秒），其中针对性检查 123 项通过。Ruff、格式和差异检查通过。
+
+两份原件 41 页仅上述两个块改变类型，全部文字和块框保持不变。第一轮 8 份／118 页与历史 19 份／168 页相对本次冻结基线均零差异；第二轮 6 份／98 页包含在第一轮完整文档中，不累计覆盖量。未更新旧基线。
+
+完整解析、MiddleJson、HTML 和资产包重放通过；两个导出共 34 个资产，无缺失图片或解析诊断。原页与前后标框已审阅，浏览器确认两个 h2。
+
+- 两页对比：`output/pdf/flash-title-coverage/final/changes.html`
+- 完整画廊：`output/pdf/flash-title-coverage/final/index.html`
+- 导出：`output/pdf/flash-title-coverage/exports/`
+- 裁决：`tests/fixtures/flash_title_coverage_review_decisions.json`
+- 测试日志：`output/pdf/flash-title-coverage/tests.log`
+
+修改前未提交代码和输出已冻结于 `output/pdf/flash-title-coverage/baseline-code/` 与 `baseline/`，源码指纹与上一轮验收记录核对一致。本轮仍在 `codex/flash-spatial-layout-round3`；未提交、推送或运行远端 CI。

docvortex-0.4.8/src/docvortex/analyzers/native/pdf/annotation_bands.py

@@ -0,0 +1,161 @@
+"""按图旁连续的物理行恢复分离图注与带符号的图例，不依赖图中文字。"""
+
+from __future__ import annotations
+
+import statistics
+import re
+
+from .geometry import _bbox_axis_overlap_ratio, _bbox_center_y
+from .text_assembly.common import _merge_internal_text_block_group
+from .text_assembly.continuity import _reassemble_member_lines
+from .visual_annotations import _is_strong_caption_text, _is_strong_footnote_text
+
+
+def _annotation_em(block):
+    """按原始行高确定图注邻接尺度，避免固定页面坐标或像素阈值。"""
+    return statistics.median(block.get("_line_heights") or [block["bbox"][3] - block["bbox"][1]])
+
+
+def recover_image_annotation_bands(blocks, page_size, drawing_lines):
+    """只从紧邻图片的显式编号出发，恢复说明带及带重复符号的图例。"""
+    removed = set()
+    for image in [block for block in blocks if block.get("type") == "image"]:
+        bounds = image["bbox"]
+        seeds = [
+            block
+            for block in blocks
+            if _is_strong_caption_text(str(block.get("content", "")))
+            and block.get("_text_lines")
+            and block["bbox"][0] < bounds[2]
+            and re.fullmatch(r"\s*(?:fig(?:ure)?\.?|图)\s*(?:\d+[A-Za-z]?|[IVX]+)[.:：]?\s*", str(block["content"]), re.I)
+            and (
+                abs(block["bbox"][3] - bounds[1]) < 1.5 * _annotation_em(block)
+                or 0 <= block["bbox"][1] - bounds[3] < 2 * _annotation_em(block)
+            )
+        ]
+        if not seeds:
+            continue
+        seed = min(seeds, key=lambda b: min(abs(b["bbox"][3] - bounds[1]), abs(b["bbox"][1] - bounds[3])))
+        heights = seed.get("_line_heights") or [seed["bbox"][3] - seed["bbox"][1]]
+        em = statistics.median(heights)
+        leading = seed["bbox"][3] <= bounds[1] + em
+        seed["type"] = "caption"
+        seed["_annotation_band_parent"] = image
+        candidates = [
+            b
+            for b in blocks
+            if b is not image
+            and id(b) not in removed
+            and b.get("_text_lines")
+            and b.get("type") in {"text", "paragraph_title", "caption", "footnote"}
+            and b["bbox"][1] >= bounds[3] - 0.25 * em
+            and _bbox_axis_overlap_ratio(b["bbox"], bounds, axis="x") >= 0.5
+        ]
+        candidates.sort(key=lambda b: (b["bbox"][1], b["bbox"][0]))
+        if not candidates:
+            continue
+        first = candidates[0] if leading else seed
+        if first["bbox"][1] - bounds[3] > 2 * em:
+            continue
+        left, right = first["bbox"][0], max(first["bbox"][2], bounds[2])
+        if not leading:
+            # 碎片化首行的编号很窄，后续实际满行给出图注宽度。
+            followers = [b for b in candidates if b["bbox"][1] <= first["bbox"][3] + em]
+            right = max([right] + [b["bbox"][2] for b in followers])
+        group = []
+        bottom = first["bbox"][1]
+        for block in candidates:
+            b = block["bbox"]
+            if b[0] < left - em or b[2] > right + em:
+                continue
+            if b[1] - bottom > 1.4 * em:
+                break
+            if leading and b[2] - b[0] < 0.65 * (right - left):
+                break
+            if block is not seed and _is_strong_caption_text(str(block.get("content", ""))):
+                break
+            if _is_strong_footnote_text(str(block.get("content", ""))):
+                break
+            group.append(block)
+            bottom = max(bottom, b[3])
+        if not group:
+            continue
+        merged = _merge_internal_text_block_group(group, list(range(len(group))))
+        merged["content"] = _reassemble_member_lines(merged["_text_lines"], merged["content"])
+        merged["type"] = "caption"
+        merged["_annotation_band_parent"] = image
+        removed.update(id(b) for b in group)
+        blocks.append(merged)
+        if not leading:
+            continue
+        separators = [
+            rule.bbox[1]
+            for rule in drawing_lines
+            if rule.orientation == "horizontal"
+            and rule.bbox[1] > bottom
+            and rule.bbox[2] - rule.bbox[0] >= 0.8 * (right - left)
+            and abs(rule.bbox[0] - left) < 2 * em
+        ]
+        if not separators:
+            continue
+        end = min(separators)
+        legend = [
+            b
+            for b in blocks
+            if id(b) not in removed
+            and b.get("_text_lines")
+            and b.get("type") in {"text", "paragraph_title"}
+            and bottom <= b["bbox"][1] < end
+            and left - em <= b["bbox"][0] < right
+        ]
+        symbols = [b for b in legend if len(str(b.get("content", "")).strip()) == 1 and str(b["content"]).strip().isalpha()]
+        if len(symbols) < 3:
+            continue
+        # 多栏图例按名称的实际左缘分组，同行的小字母只认领最近的左侧名称。
+        physical_rows = []
+        for block in sorted(legend, key=lambda b: (_bbox_center_y(b["bbox"]), b["bbox"][0])):
+            row = next(
+                (
+                    r
+                    for r in reversed(physical_rows)
+                    if abs(_bbox_center_y(r[0]["bbox"]) - _bbox_center_y(block["bbox"])) < 0.65 * em
+                ),
+                None,
+            )
+            if row is None:
+                physical_rows.append([block])
+            else:
+                row.append(block)
+        rows = []
+        for physical in physical_rows:
+            group = []
+            for block in sorted(physical, key=lambda b: b["bbox"][0]):
+                if group and block["bbox"][0] - group[-1]["bbox"][2] > 3 * em:
+                    rows.append(group)
+                    group = []
+                group.append(block)
+            if group:
+                rows.append(group)
+        heading_tops = [b["bbox"][1] for b in legend if b.get("type") == "paragraph_title"]
+        starts = sorted(row[0]["bbox"][0] for row in rows if len(str(row[0].get("content", ""))) > 2)
+        columns = []
+        for start in starts:
+            if columns and start - statistics.median(columns[-1]) <= 1.5 * em:
+                columns[-1].append(start)
+            else:
+                columns.append([start])
+        stable_lefts = [statistics.median(column) for column in columns if len(column) >= 3]
+        for row in rows:
+            note = _merge_internal_text_block_group(row, list(range(len(row))), preserve_visual_spaces=True)
+            note["type"] = "footnote"
+            note["_annotation_band_parent"] = image
+            if len(stable_lefts) >= 2 and note["bbox"][2] - note["bbox"][0] < 0.65 * (right - left):
+                # 分类标题开启新分组；组内各栏自上而下，避免右栏子类标题插入左栏药名中。
+                section = max([bottom] + [top for top in heading_tops if top <= note["bbox"][1] + 0.25 * em])
+                lane = min(stable_lefts, key=lambda start: abs(start - note["bbox"][0]))
+                if any(block.get("type") == "paragraph_title" for block in row):
+                    lane = left - em
+                note["_legend_sort_band"] = (section, lane)
+            blocks.append(note)
+            removed.update(id(b) for b in row)
+    blocks[:] = [block for block in blocks if id(block) not in removed]

{docvortex-0.4.7 → docvortex-0.4.8}/src/docvortex/analyzers/native/pdf/formulas.py

@@ -40,6 +40,7 @@ from .line_merging import _join_formula_visual_row, _merge_overlapping_inline_cl
 from .models import _AxisLine, _FormulaAnchor, _LineItem, _PageSource, _TextLane
 from .native_text import _sanitize_pdf_control_text
 from .text_roles import has_prose, prose_residue, publication_text
+from .layout_evidence import build_layout_evidence
 
 _FORMULA_NUMBER_SUFFIX_RE = re.compile(r"^(?P<prefix>.*?)(?P<marker>[(（﹙][^()（）﹙﹚\r\n]+[)）﹚])\s*$")
 _FORMULA_NUMBER_MARKER_RE = re.compile(
@@ -844,7 +845,7 @@ def _build_formula_like_blocks(
             and _bbox_axis_overlap_ratio(bbox, line.ink_bbox or line.bbox, axis="y") >= 0.25
             and max(0.0, bbox[0] - line.bbox[2], line.bbox[0] - bbox[2]) <= 3 * _line_effective_height(line, line.bbox)
         ]
-        if member_ids and hosts and "\\tag{" not in block["content"]:
+        if member_ids and hosts and "\\tag{" not in block["content"] and not block.get("_spatial_display_band"):
             claimed_source_indices.difference_update(member_ids)
             for line in lines:
                 if line.source_index in member_ids:
@@ -882,6 +883,32 @@ def _build_formula_like_blocks(
             block["_tight_output_bbox"] = _bbox_union(core, ink)
             block["content"] += "\n" + text
             claimed_source_indices.add(line.source_index)
+    bands, _ = _build_spatial_numbered_bands(lines, table_bboxes, page_size, drawing_lines or [])
+    recovered_band_ids = set()
+    for band in bands:
+        bbox = band.get("_tight_output_bbox", band["bbox"])
+        overlaps = [
+            block for block in blocks if _bbox_overlap_in_smaller(bbox, block.get("_tight_output_bbox", block["bbox"])) >= 0.5
+        ]
+        if any(
+            all(old[i] <= bbox[i] + 1 if i < 2 else old[i] >= bbox[i] - 1 for i in range(4))
+            for old in [block.get("_tight_output_bbox", block["bbox"]) for block in overlaps]
+        ):
+            continue
+        # 只补齐缺失成员，既有完整公式的内容、裁图和顺序保持原结果。
+        ids = set(band["_formula_members"]).union(*(block.get("_formula_members", []) for block in overlaps))
+        members = [(line, line.ink_bbox or line.bbox) for line in lines if line.source_index in ids]
+        if not members:
+            continue
+        merged = _formula_members_to_block(
+            members, page_size, 0, anchor_source_index=band["_formula_members"][-1], include_member_ids=True
+        )
+        if merged:
+            blocks = [block for block in blocks if not any(block is old for old in overlaps)]
+            blocks.append(merged)
+            claimed_source_indices.update(ids)
+            recovered_band_ids.update(ids)
+    for block in blocks:
         block.pop("_formula_members", None)
     remaining_lines = [
         line
@@ -889,7 +916,142 @@ def _build_formula_like_blocks(
         if line.source_index not in claimed_source_indices
         and (not line.formula_candidate_only or line.paragraph_formula_context)
     ]
-    return blocks, remaining_lines + paragraph_lines
+    return blocks, remaining_lines + [line for line in paragraph_lines if line.source_index not in recovered_band_ids]
+
+
+def _build_spatial_numbered_bands(lines, table_bboxes, page_size, rules):
+    """在成员被拆散认领前，用正文栏右缘的短编号与独立数学带恢复完整公式。"""
+    prose = [line for line in lines if line.angle == 0 and len(line.text) >= 25 and _has_sentence_words(line.text)]
+    layout = build_layout_evidence(prose, page_size, barriers=table_bboxes)
+    blocks, claimed = [], set()
+    for lane in layout.lanes:
+        em = statistics.median(_line_effective_height(line, bounds) for line, bounds in lane.lines)
+
+        def is_body(line):
+            """短数学簇的拉丁变量不等同于正文词行，实际正文宽度及词组提供屏障。"""
+            return _has_sentence_words(line.text) and (
+                line.bbox[2] - line.bbox[0] >= 0.6 * (lane.right - lane.left)
+                or len(re.findall(r"\b[A-Za-z]{3,}\b", line.text)) >= 3
+                or len(re.findall(r"[\u3400-\u9fff]", line.text)) >= 3
+                or re.search(r"\b(?:where|with|when|which|the|this|these|is|are|from|that|then)\b", line.text, re.I)
+            )
+
+        local = [
+            line
+            for line in lines
+            if line.angle == 0
+            and line.paragraph_group is None
+            and line.semantic_type is None
+            and lane.left - em <= line.bbox[0]
+            and line.bbox[2] <= lane.right + em
+        ]
+        markers = [
+            line
+            for line in local
+            if 2 <= len(line.text.strip()) <= 8
+            and not re.search(r"\s", line.text.strip())
+            and re.search(r"\d", line.text)
+            and not line.text.strip()[0].isdigit()
+            and not line.text.strip()[-1].isdigit()
+            and (
+                _standalone_formula_number_marker(line.text) is not None
+                or re.fullmatch(r"[^A-Za-z0-9][A-Za-z]?[.]?\d+(?:[.\-]\d+)*[^A-Za-z0-9]", line.text.strip())
+            )
+            and abs(line.bbox[2] - lane.right) < 1.5 * em
+            and line.bbox[2] - line.bbox[0] <= 4 * em
+        ]
+        for marker in markers:
+            if marker.source_index in claimed:
+                continue
+            mb = marker.ink_bbox or marker.bbox
+            nearby = [
+                line
+                for line in local
+                if line is not marker
+                and line.source_index not in claimed
+                and line not in markers
+                and not is_body(line)
+                and (line.ink_bbox or line.bbox)[3] >= mb[1] - 4.5 * em
+                and (line.ink_bbox or line.bbox)[1] <= mb[3] + 1.1 * em
+            ]
+            if not nearby:
+                continue
+            # 先形成二维数学主体，再关联隔着水平空白或位于右下角的编号。
+            pending = set(range(len(nearby)))
+            components = []
+            while pending:
+                seed = pending.pop()
+                component, frontier = [seed], [seed]
+                while frontier:
+                    current = nearby[frontier.pop()]
+                    bounds = current.ink_bbox or current.bbox
+                    connected = []
+                    for index in pending:
+                        other = nearby[index].ink_bbox or nearby[index].bbox
+                        xgap = max(0.0, bounds[0] - other[2], other[0] - bounds[2])
+                        ygap = max(0.0, bounds[1] - other[3], other[1] - bounds[3])
+                        if (
+                            ygap <= 0.8 * em
+                            and _bbox_axis_overlap_ratio(bounds, other, axis="x") > 0.1
+                            or xgap <= 3 * em
+                            and _bbox_axis_overlap_ratio(bounds, other, axis="y") > 0.15
+                        ):
+                            connected.append(index)
+                    pending.difference_update(connected)
+                    frontier.extend(connected)
+                    component.extend(connected)
+                components.append([nearby[index] for index in component])
+            candidates = []
+            for members in components:
+                bounds = _bbox_union_many([line.ink_bbox or line.bbox for line in members])
+                if (bounds[2] >= mb[0] + em and bounds[3] > mb[1]) or bounds[2] - bounds[0] < 3 * em:
+                    continue
+                gap = max(0.0, mb[1] - bounds[3], bounds[1] - mb[3])
+                if gap > 2 * em or bounds[3] - bounds[1] > 6 * em:
+                    continue
+                if any(_bbox_intersects(bounds, table) for table in table_bboxes):
+                    continue
+                if any(
+                    _bbox_axis_overlap_ratio(bounds, line.ink_bbox or line.bbox, axis="y") > 0.1
+                    for line in local
+                    if is_body(line)
+                ):
+                    continue
+                math = any(_formula_line_has_math_operator(line.text) for line in members)
+                fraction = any(
+                    rule.orientation == "horizontal"
+                    and bounds[0] <= rule.bbox[0] < rule.bbox[2] <= bounds[2]
+                    and bounds[1] < rule.bbox[1] < bounds[3]
+                    for rule in rules
+                )
+                if (
+                    not math
+                    and not fraction
+                    and not (
+                        (len(members) >= 3 or any(line.compact_formula_cluster for line in members))
+                        and bounds[3] - bounds[1] >= 1.3 * em
+                    )
+                ):
+                    continue
+                candidates.append((gap, members))
+            if not candidates:
+                continue
+            candidates.sort(key=lambda item: item[0])
+            if len(candidates) > 1 and abs(candidates[0][0] - candidates[1][0]) < 0.25 * em:
+                continue
+            members = candidates[0][1] + [marker]
+            block = _formula_members_to_block(
+                [(line, line.ink_bbox or line.bbox) for line in members],
+                page_size,
+                0,
+                anchor_source_index=marker.source_index,
+                include_member_ids=True,
+            )
+            if block:
+                block["_spatial_display_band"] = True
+                blocks.append(block)
+                claimed.update(line.source_index for line in members)
+    return blocks, claimed
 
 
 def _recover_detached_display_components(

{docvortex-0.4.7 → docvortex-0.4.8}/src/docvortex/analyzers/native/pdf/line_layout.py

@@ -87,7 +87,8 @@ def _should_connect_semantic_rows(
     vertical_gap = _effective_text_row_gap(previous, current)
     if not -0.25 * pair_height <= vertical_gap <= max(1.25 * pair_height, regular_gap + 0.75 * pair_height):
         return False
-    if previous_line.semantic_type == "paragraph_title" and vertical_gap > 0.5 * pair_height:
+    shared_title_band = previous_line.title_band_id is not None and previous_line.title_band_id == current_line.title_band_id
+    if previous_line.semantic_type == "paragraph_title" and vertical_gap > 0.5 * pair_height and not shared_title_band:
         return False
     font_conflicts = (
         previous_line.font_signature is not None

{docvortex-0.4.7 → docvortex-0.4.8}/src/docvortex/analyzers/native/pdf/line_merging.py

@@ -431,6 +431,7 @@ def _merge_post_semantic_text_runs(
     if len(lines) < 2:
         return list(lines)
     local_bboxes = [_rotate_bbox_to_upright(line.bbox, page_size, line.angle) for line in lines]
+    layout = build_layout_evidence(lines, page_size, barriers=table_bboxes)
     parents = list(range(len(lines)))
 
     def find(index: int) -> int:
@@ -470,11 +471,53 @@ def _merge_post_semantic_text_runs(
                 continue
             second_bbox = local_bboxes[second_index]
             second_height = _line_effective_height(second_line, second_bbox)
-            if _post_semantic_same_baseline_geometry(
-                first_bbox,
-                first_height,
-                second_bbox,
-                second_height,
+            left, right = sorted((first_bbox, second_bbox), key=lambda bbox: bbox[0])
+            pair_height = min(first_height, second_height)
+            shared_physical_row = (
+                first_line.visual_row_id is not None
+                and first_line.visual_row_id == second_line.visual_row_id
+                # 宽空格放宽只服务连续文字，数值列与标签列不能据此跨单元格连接。
+                and all(
+                    any(char.isalpha() for char in member.text)
+                    for member in lines
+                    if member.angle == first_line.angle and member.visual_row_id == first_line.visual_row_id
+                )
+            )
+            row_bounds = (
+                _bbox_union_many(
+                    [
+                        local_bboxes[index]
+                        for index, member in enumerate(lines)
+                        if member.angle == first_line.angle and member.visual_row_id == first_line.visual_row_id
+                    ]
+                )
+                if shared_physical_row
+                else _bbox_union_many([first_bbox, second_bbox])
+            )
+            justified_row = (
+                first_line.font_signature == second_line.font_signature
+                and first_line.paragraph_group == second_line.paragraph_group
+                and first_line.angle == 0
+                and abs(_bbox_center_y(first_bbox) - _bbox_center_y(second_bbox)) < 0.2 * pair_height
+                and 0 <= right[0] - left[2] <= (3 if shared_physical_row else 2) * pair_height
+                and not layout.separated(first_bbox, second_bbox)
+                and any(
+                    other is not first_line
+                    and other is not second_line
+                    and 0 < other.bbox[1] - max(first_bbox[3], second_bbox[3]) <= pair_height
+                    and abs(other.bbox[0] - row_bounds[0]) < (1.5 if shared_physical_row else 1) * pair_height
+                    and other.bbox[2] >= row_bounds[2] - pair_height
+                    for other in lines
+                )
+            )
+            if (
+                _post_semantic_same_baseline_geometry(
+                    first_bbox,
+                    first_height,
+                    second_bbox,
+                    second_height,
+                )
+                or justified_row
             ):
                 union(first_index, second_index)
 

{docvortex-0.4.7 → docvortex-0.4.8}/src/docvortex/analyzers/native/pdf/models.py

@@ -52,6 +52,8 @@ class _LineItem:
     inline_math_regions: list[BBox] = field(default_factory=list)
     paragraph_group: int | None = None
     paragraph_terminal: bool = False
+    reference_start: bool | None = None
+    title_band_id: int | None = None
     caption_start: bool = False
 
     def __post_init__(self) -> None:
@@ -193,6 +195,7 @@ class _PreparedPage:
     canonical_formula_source_lines: list[_LineItem] = field(default_factory=list)
     page_footnote_groups: list[set[int]] = field(default_factory=list)
     reference_regions: list[BBox] = field(default_factory=list)
+    numbered_references: bool = False
     script_lines: list[PDFTextScriptLine] = field(default_factory=list)
     formula_candidate_lines: list[_LineItem] = field(default_factory=list)
     formula_ink_bboxes: list[BBox] = field(default_factory=list)