docs/FORMAT_COMPARISON.md

# MathML vs OMML 格式对比

## 快速选择指南

| 使用场景 | 推荐格式 | API 端点 |
|---------|---------|----------|
| 手动复制粘贴到 Word | MathML | `/image/ocr` 返回 `mathml` |
| 网页显示公式 | MathML | `/image/ocr` 返回 `mathml` |
| Office.js 插件开发 | OMML | `/convert/latex-to-omml` |
| Python 生成 Word 文档 | OMML | `/convert/latex-to-omml` |
| 跨平台显示 | MathML | `/image/ocr` 返回 `mathml` |

## 格式详解

### MathML (Mathematical Markup Language)

**标准**: W3C 标准
**浏览器支持**: Chrome, Firefox, Safari (原生支持)
**Word 支持**: 可粘贴 (Word 自动转换为 OMML)

#### 示例
```xml
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mfrac>
    <mi>a</mi>
    <mi>b</mi>
  </mfrac>
</math>
```

#### 优点
- ✅ 跨平台标准
- ✅ 浏览器原生支持
- ✅ 可读性好
- ✅ 可直接粘贴到 Word

#### 缺点
- ❌ Word 内部需要转换
- ❌ 渲染精度依赖 Word 转换器

### OMML (Office Math Markup Language)

**标准**: Microsoft 专有格式
**浏览器支持**: 不支持
**Word 支持**: 原生格式 (最佳兼容性)

#### 示例
```xml
<m:oMath xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math">
  <m:f>
    <m:num><m:r><m:t>a</m:t></m:r></m:num>
    <m:den><m:r><m:t>b</m:t></m:r></m:den>
  </m:f>
</m:oMath>
```

#### 优点
- ✅ Word 原生格式，渲染最准确
- ✅ 适合编程生成 Word 文档
- ✅ Office.js API 直接支持

#### 缺点
- ❌ 仅 Word 支持
- ❌ 可读性差
- ❌ 不能浏览器渲染

## API 使用示例

### 1. 获取 MathML (手动粘贴到 Word)

```bash
# OCR 识别图片，返回 MathML
curl -X POST "http://localhost:8000/api/v1/image/ocr" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/formula.png",
    "model_name": "mineru"
  }'
```

响应：
```json
{
  "latex": "\\frac{a}{b}",
  "markdown": "$\\frac{a}{b}$",
  "mathml": "<math>...</math>",  // 👈 复制这个粘贴到 Word
  "mml": "<mml:math>...</mml:math>"
}
```

### 2. 获取 OMML (编程插入 Word)

```bash
# 转换 LaTeX 为 OMML
curl -X POST "http://localhost:8000/api/v1/convert/latex-to-omml" \
  -H "Content-Type: application/json" \
  -d '{
    "latex": "\\frac{a}{b}"
  }'
```

响应：
```json
{
  "omml": "<m:oMath>...</m:oMath>"  // 👈 用于编程插入
}
```

## 编程使用示例

### Python: 插入 OMML 到 Word

```python
from docx import Document
from docx.oxml import parse_xml

# 获取 OMML
import requests
response = requests.post(
    "http://localhost:8000/api/v1/convert/latex-to-omml",
    json={"latex": "\\frac{a}{b}"}
)
omml = response.json()["omml"]

# 插入到 Word 文档
doc = Document()
paragraph = doc.add_paragraph()
paragraph._element.append(parse_xml(omml))
doc.save("output.docx")
```

### JavaScript: Office Add-in 插入 OMML

```javascript
// 获取 OMML
const response = await fetch('http://localhost:8000/api/v1/convert/latex-to-omml', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ latex: '\\frac{a}{b}' })
});
const { omml } = await response.json();

// 插入到 Word
Office.context.document.setSelectedDataAsync(
  omml,
  { coercionType: Office.CoercionType.Ooxml }
);
```

### Web: 显示 MathML

```html
<!DOCTYPE html>
<html>
<body>
  <!-- MathML 可以直接在浏览器中渲染 -->
  <math xmlns="http://www.w3.org/1998/Math/MathML">
    <mfrac>
      <mi>a</mi>
      <mi>b</mi>
    </mfrac>
  </math>
</body>
</html>
```

## 性能对比

| 操作 | MathML | OMML |
|------|--------|------|
| 生成速度 | 快 (~100ms) | 慢 (~500ms, 需要 Pandoc) |
| 文件大小 | 较小 | 较大 |
| 转换质量 | 依赖转换器 | 原生最佳 |

## 常见问题

### Q1: 为什么我的 OMML 看起来很长？

**A**: OMML 包含了完整的命名空间和样式信息，所以比 MathML 长。这是正常的。

### Q2: 我应该使用哪个格式？

**A**: 
- **手动操作** → MathML (复制粘贴)
- **编程操作** → OMML (API 插入)

### Q3: 能否将 MathML 转换为 OMML？

**A**: 可以！使用我们的 API：
1. 先从 OCR 获取 `latex`
2. 再调用 `/convert/latex-to-omml` 获取 OMML

### Q4: OMML 能在浏览器显示吗？

**A**: 不能。OMML 是 Word 专用格式。浏览器显示请使用 MathML。

## 总结

- 📋 **用户复制粘贴** → 使用 MathML
- 💻 **编程生成文档** → 使用 OMML
- 🌐 **网页显示** → 使用 MathML
- 🔌 **Office 插件** → 使用 OMML