PicToDocx

将图片（数学教材、试卷、笔记）通过视觉大模型 OCR 转换为可编辑的 Word 文档（.docx），完整保留数学公式（LaTeX → OMML）。

---

核心链路

图片 → VLM OCR → Markdown（含 LaTeX）→ Word(.docx)

也支持直接将已有 Markdown 文件转换为 Word。

---

快速上手

第一步：克隆并安装

git clone https://github.com/your-org/PicToDocx.git
cd PicToDocx
pip install -r requirements.txt

第二步：配置 API Key

方式 A（推荐）：写入项目根目录的 .env 文件

在项目根目录新建 .env 文件（不会被提交到 Git）：

ZHIPUAI_API_KEY=your_key_here

然后在运行前加载它：

# Windows PowerShell
Get-Content .env | ForEach-Object { $k,$v = $_ -split '=',2; [System.Environment]::SetEnvironmentVariable($k,$v) }

# macOS / Linux
export $(cat .env | xargs)

方式 B：直接设置环境变量（当前终端生效）

# Windows PowerShell
$env:ZHIPUAI_API_KEY = "your_key_here"

# macOS / Linux
export ZHIPUAI_API_KEY=your_key_here

方式 C：每次命令中传入

python main.py image --api-key your_key_here

智谱 API Key 申请地址：https://open.bigmodel.cn （注册后免费使用 glm-4v-flash）

第三步：放入图片，一键运行

# 将图片复制到 input/ 目录
cp your_image.jpg input/

# 一键批量转换（输出到 output/）
python main.py image

完成后在 output/ 目录找到生成的 .docx 文件。

---

特性

• 高质量数学公式：LaTeX → MathML → OMML，Word 原生可编辑公式
• 多引擎支持：内置智谱（zhipu）和 MiniMax（minimax）两个 OCR 引擎，架构可扩展
• 批量处理：只需将文件放入 input/ 目录，一条命令处理全部
• 中间产物可保留：支持同时保存 OCR 输出的 Markdown 文件
• 回退机制：找不到 Office XSLT 时自动降级为 Cambria Math 文本渲染

---

目录结构

PicToDocx/
├── input/                  # 放入待转换的图片 / .md 文件
├── output/                 # 所有生成的 .docx 文件
│
├── ocr/
│   ├── base.py             # OCREngine 抽象基类
│   ├── zhipu_engine.py     # 智谱 GLM-4V 引擎
│   ├── minimax_engine.py   # MiniMax 视觉引擎
│   └── __init__.py         # 引擎工厂 get_engine()
│
├── converter.py            # Markdown / LaTeX → Word 转换核心
├── utils.py                # 文本后处理工具
├── main.py                 # CLI 统一入口
├── requirements.txt
└── pic_to_word_skill/      # 可独立分发的 skill 版本

---

依赖说明

包	用途
python-docx	生成 Word 文档
lxml	XML / XSLT 处理（MathML → OMML）
latex2mathml	LaTeX 字符串 → MathML
Pillow	图片压缩与编码
zhipuai	智谱 AI OCR 引擎
requests	MiniMax OCR 引擎（可选）

---

使用方法

批量处理（推荐）

将图片放入 input/ 目录，然后运行：

# 使用默认引擎（zhipu）批量转换所有图片
python main.py image

# 使用 minimax 引擎
python main.py image --engine minimax

# 批量转换所有 Markdown 文件
python main.py md

输出文件自动保存到 output/ 目录，文件名与输入同名。

---

单文件处理

# 图片 → Word（指定输出路径）
python main.py image input/page.jpg -o output/page.docx

# 图片 → Word（同时保存 OCR 中间 Markdown）
python main.py image input/page.jpg --save-markdown

# 图片 → Word（指定模型）
python main.py image input/page.jpg --engine zhipu --model glm-4v-plus

# Markdown → Word
python main.py md input/notes.md -o output/notes.docx

---

查看帮助

python main.py --help
python main.py image --help
python main.py md --help

---

使用独立 Skill（pic_to_word_skill/）

pic_to_word_skill/ 是一个可独立运行、独立分发的封装版本，适合：

• 直接给 Agent / 自动化流程调用
• 作为独立包发布（含 pyproject.toml，可 pip install）
• 嵌入其他项目使用

独立安装

cd pic_to_word_skill
pip install -r requirements.txt
# 或作为包安装
pip install .

CLI 调用

# 在 pic_to_word_skill/ 目录下执行
cd pic_to_word_skill

# 基础用法：图片 → Word
python skill_pictoword.py examples/math_textbook.jpg -o output.docx

# 同时保存 OCR 中间 Markdown
python skill_pictoword.py examples/math_textbook.jpg -o output.docx -m output.md

# 指定 API Key 和模型
python skill_pictoword.py examples/math_textbook.jpg \
  --api-key your_key_here \
  --model glm-4v-plus \
  -o output.docx

Python API 调用

from pic_to_word_skill import PicToWordSkill

skill = PicToWordSkill(zhipu_api_key="your_key_here")

result = skill.run(
    image_path="examples/math_textbook.jpg",
    output_docx="output.docx",
    intermediate_markdown="output.md",  # 可选，保存 OCR Markdown
)

print(result["word_path"])      # 输出的 docx 路径
print(result["markdown_path"])  # 中间 Markdown 路径
print(result["success"])        # True / False

Skill 目录结构

pic_to_word_skill/
├── skill_pictoword.py   # 主入口（CLI + Python API）
├── converter.py         # Markdown/LaTeX → Word
├── utils.py             # 文本后处理
├── zhipu_ocr.py         # OCR 调用
├── requirements.txt     # 最小依赖
├── pyproject.toml       # 打包配置
├── SKILL.md             # Agent 执行说明
├── skill.yaml           # 通用 YAML 技能清单
└── manifest.json        # JSON 清单（兼容多种 Agent 框架）

---

扩展新 OCR 引擎

只需两步：

1. 在 ocr/ 下新建引擎文件，继承 OCREngine：

# ocr/my_engine.py
from .base import OCREngine

class MyEngine(OCREngine):
    def __init__(self, api_key: str, model: str = "my-model"):
        self._api_key = api_key
        self._model = model

    @property
    def name(self) -> str:
        return "my_engine"

    def is_available(self) -> bool:
        try:
            import my_sdk
            return True
        except ImportError:
            return False

    def recognize(self, image_path: str, **kwargs) -> str:
        # 调用 API，返回 Markdown 字符串
        ...

2. 在 ocr/__init__.py 中注册：

from .my_engine import MyEngine

_ENGINE_REGISTRY = {
    "zhipu": ZhipuEngine,
    "minimax": MinimaxEngine,
    "my_engine": MyEngine,   # ← 添加这一行
}

注册后即可通过 --engine my_engine 使用，无需修改其他代码。

---

数学公式说明

公式转换链路：LaTeX → MathML (latex2mathml) → OMML (MML2OMML.XSL) → Word

• 需要安装 Microsoft Office 或 WPS Office（提供 MML2OMML.XSL），路径由程序自动探测
• 未找到 XSL 时自动降级：以 Cambria Math 字体渲染 LaTeX 原文（可读但不可编辑）

---

License

MIT