PDF2OMML

把 PDF 中的数学公式 提取并转换为 Word 中可编辑的公式对象（OMML / Office Math）， 输出包含这些公式的 .docx 文档。

• 提取显示公式与行内公式，自动跳过表格 / 图片区域
• 输出的是真实 Office Math 公式对象（m:oMath），在 Word / WPS 中双击即可编辑 —— 不是图片
• 版面分析 + LaTeX→OMML 转换 + Word 组装 零外部服务、纯本地；仅公式识别（OCR）这一步可选外接引擎

本仓库同时是一个 WorkBuddy 技能（ Skill ），根目录的 SKILL.md 即为技能描述；你也可以直接把仓库作为独立 Python 工具使用。

---

原理

PDF ──(PyMuPDF 版面分析)──▶ 公式区域(显示/行内) ──(OCR)──▶ LaTeX
                                                                │
                                                       (omml_engine)
                                                                ▼
                                              Word 可编辑公式 (m:oMath)

安装

需要 Python 3.10+。

核心依赖（必装，零权重下载） —— 仅这三项即可完成「找公式 + LaTeX→OMML + 组装 docx」，全程不涉及任何神经网络、不下载任何模型权重：

pip install -r requirements.txt

可选 OCR 后端（按需装） —— 只有在「把公式图片 / 扫描图反推成 LaTeX」时才需要，详见 requirements-ocr.txt：

pip install -r requirements-ocr.txt   # pix2tex(本地视觉模型) + requests(Mathpix 后端)

不下载权重也能用 ✅

整套工具的核心转换链路零依赖、零下载。所谓「下载权重」只来自可选的 pix2tex（LaTeX-OCR）本地后端，首次运行会自动拉取约 100MB 模型权重。如果你不想下载任何权重，有三种等价替代方案：

方式	命令	说明
嵌入公式图片（最省事）	--ocr none	不识别，直接把公式裁图嵌进 docx；内容不丢，但公式不可双击编辑
远程 API	--ocr mathpix	调 Mathpix 云端模型，本机不下载权重（需 MATHPIX_APP_ID / MATHPIX_APP_KEY）
自有程序	--ocr cli --cli-cmd "..."	用你本机任何能输出 LaTeX 的程序，零额外依赖

如果你手上是已有 LaTeX 源码 / 公式文本（比如想把论文公式批量灌进 Word），直接用 omml_engine.py 的 latex_to_oMath，连 PDF 和 OCR 都不需要，彻底零下载。

OCR 后端（可选，四选一）：

后端	说明	安装 / 配置
pix2tex (LaTeX-OCR)	本地、免费、无需密钥	pip install pix2tex，首次运行自动下载权重（约 100MB）
mathpix	Mathpix Snip API	设置环境变量 MATHPIX_APP_ID / MATHPIX_APP_KEY
cli	任意外部程序（输出 LaTeX 到 stdout）	用 --cli-cmd "simpletex {image}" 指定， {image} 为图片路径占位符
none	不识别，直接嵌入公式裁剪图（仍可用，但不可编辑）	——

auto 模式会优先使用 pix2tex，否则回退到 mathpix（若已配置），再否则报错。

使用

# 1) 自动选 OCR 后端
python scripts/pdf_formulas_to_word.py --pdf paper.pdf

# 2) 指定本地 LaTeX-OCR，自定义输出
python scripts/pdf_formulas_to_word.py --pdf paper.pdf --ocr pix2tex --out out.docx

# 3) 用 Mathpix API
python scripts/pdf_formulas_to_word.py --pdf paper.pdf --ocr mathpix

# 4) 用任意外部 CLI
python scripts/pdf_formulas_to_word.py --pdf paper.pdf --ocr cli --cli-cmd "simpletex {image}"

# 5) 没有 OCR 时，退化为嵌入公式图片
python scripts/pdf_formulas_to_word.py --pdf paper.pdf --ocr none

# 6) 仅提取某几页、尽力还原正文（含行内公式）
python scripts/pdf_formulas_to_word.py --pdf paper.pdf --mode doc --pages 0:10

命令行参数

参数	说明	默认
--pdf	必填，源 PDF 路径	—
--out	输出 .docx 路径	<pdf名>_formulas.docx
--ocr	OCR 后端：auto/pix2tex/mathpix/cli/none	auto
--cli-cmd	--ocr cli 时的外部命令，用 {image} 占位图片路径	—
--dpi	公式裁剪分辨率	300
--pages	页码范围：3 或 0:5（0 基）	全部
--mode	formulas（逐条列出）/ doc（尽力还原全文）	formulas
--crop-dir	公式裁剪图目录	<pdf目录>/_formula_crops
--manifest	识别结果 JSON（每公式的 LaTeX）路径	<out名>_manifest.json

作为库复用

from omml_engine import latex_to_oMath, insert_display_equation, insert_inline_equation
from docx import Document

doc = Document()
insert_display_equation(doc, r"\frac{a^2+b^2}{c} = \sqrt{x_i^2 + \sum_{k=1}^{n}\alpha_k}")
insert_inline_equation(doc.add_paragraph(), r"\lambda_{\max} \leq \gamma")
doc.save("demo.docx")

from formula_extractor import FormulaExtractor
ex = FormulaExtractor("paper.pdf")
regions = ex.extract()          # 有序 FormulaRegion 列表（display/inline + 裁剪图）
for r in regions:
    print(r.page + 1, r.kind, r.label, r.crop_path)
ex.close()

文件结构

PDF2OMML/
├── SKILL.md                      # WorkBuddy 技能描述（也是本仓库的说明）
├── README.md
├── LICENSE
├── .gitignore
└── scripts/
    ├── pdf_formulas_to_word.py   # 主入口（CLI 编排）
    ├── omml_engine.py            # LaTeX → OMML（可编辑公式核心，纯 lxml）
    ├── formula_extractor.py      # PyMuPDF 公式区域检测 + 裁剪
    └── ocr_adapter.py            # 可插拔公式 OCR（pix2tex/mathpix/cli）

实现要点 / 注意事项

• 公式识别基于字体线索（Computer / Latin Modern 等数学字体）+ 数学符号特征，并跳过表格 / 图片区域， 对 LaTeX 编译出的学术 PDF 效果好。
• 输出的真实 Office Math 公式对象（m:oMath / m:oMathPara）在 Word 中双击即可编辑； LaTeX 解析器覆盖分式、上下标（含上下标同体）、根式、矩阵、希腊字母、常见算子与重音（点 / 帽 / 矢量等）。
• OCR 失败的个别公式会自动回退为嵌入图片（标注「非可编辑」），保证内容不丢失； 全部识别结果（及失败项）记录在 --manifest JSON 中，便于二次校对。
• doc 模式是对版面的尽力还原，复杂多栏 / 跨页表格场景可能需人工微调。

许可证

MIT —— 可自由用于商业 / 非商业用途。