123 lines
3.5 KiB
Markdown
123 lines
3.5 KiB
Markdown
# LaTeX 字符渲染问题 - 快速修复指南
|
||
|
||
## 问题
|
||
|
||
识别完成后，`\lambda` 和 `\vdots` 等 LaTeX 字符没有被正确渲染。
|
||
|
||
## 根本原因
|
||
|
||
**不是前端二次处理问题，也不是 LaTeX 语法问题，而是后端 MathML Unicode 实体映射不完整。**
|
||
|
||
在 `app/services/converter.py` 的 `_postprocess_mathml_for_word()` 函数中，Pandoc 生成的 Unicode 实体（如 `λ` 和 `⋮`）没有被完整转换为实际字符（λ 和 ⋮）。
|
||
|
||
## 已实施的修复
|
||
|
||
### 1. 扩展 Unicode 实体映射表
|
||
|
||
**文件**: `app/services/converter.py`
|
||
|
||
**修改内容**:
|
||
- ✅ 新增 24 个小写希腊字母映射
|
||
- ✅ 新增 24 个大写希腊字母映射
|
||
- ✅ 新增所有省略号符号（`\vdots`, `\cdots`, `\ddots`, `\iddots`, `\ldots`）
|
||
- ✅ 新增 50+ 个常用数学符号
|
||
- ✅ 新增十进制格式实体处理
|
||
|
||
### 2. 支持的字符示例
|
||
|
||
| 问题字符 | Unicode | 修复前 | 修复后 |
|
||
|---------|---------|--------|--------|
|
||
| `\lambda` | λ | `λ` 未转换 | ✅ 转换为 λ |
|
||
| `\vdots` | ⋮ | `⋮` 未转换 | ✅ 转换为 ⋮ |
|
||
| `\Lambda` | Λ | `Λ` 未转换 | ✅ 转换为 Λ |
|
||
| `\cdots` | ⋯ | `⋯` 未转换 | ✅ 转换为 ⋯ |
|
||
| `\infty` | ∞ | `∞` 未转换 | ✅ 转换为 ∞ |
|
||
| `\sum` | ∑ | `∑` 未转换 | ✅ 转换为 ∑ |
|
||
|
||
## 验证步骤
|
||
|
||
### 1. 运行测试（可选）
|
||
|
||
```bash
|
||
cd /Users/yoge/dev/yoge/doc_processer
|
||
python test_unicode_fix.py
|
||
```
|
||
|
||
### 2. 测试 API 端点
|
||
|
||
```bash
|
||
# 测试 lambda 和 vdots
|
||
curl -X POST "http://localhost:8000/api/v1/convert/latex-to-omml" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"latex": "\\lambda_1, \\lambda_2, \\vdots, \\lambda_n"}'
|
||
```
|
||
|
||
### 3. 检查前端（如果后端正常）
|
||
|
||
如果 API 返回正确但前端显示有问题:
|
||
|
||
1. **检查 API 响应**: 使用浏览器开发者工具查看实际返回的内容
|
||
2. **检查 MathJax/KaTeX**: 确认渲染库版本和配置
|
||
3. **检查字体加载**: 确认数学字体正确加载
|
||
4. **检查 JS 错误**: 控制台是否有报错
|
||
|
||
## 诊断工具
|
||
|
||
### 如果仍有问题，使用诊断工具
|
||
|
||
```bash
|
||
# 诊断后处理管道
|
||
python diagnose_latex_rendering.py "$\lambda + \vdots$"
|
||
|
||
# 测试完整转换流程
|
||
python test_unicode_fix.py
|
||
```
|
||
|
||
## 技术细节
|
||
|
||
### 修改位置
|
||
|
||
文件: `app/services/converter.py`
|
||
函数: `_postprocess_mathml_for_word()`
|
||
行数: ~420-485
|
||
|
||
### 修改内容
|
||
|
||
1. **扩展 `unicode_map` 字典**:
|
||
- 从 ~33 个映射增加到 ~180 个映射
|
||
- 覆盖所有常用希腊字母和数学符号
|
||
|
||
2. **新增十进制实体处理**:
|
||
```python
|
||
decimal_patterns = [
|
||
(r'λ', 'λ'), # lambda (decimal)
|
||
(r'⋮', '⋮'), # vdots (decimal)
|
||
# ... 更多映射
|
||
]
|
||
```
|
||
|
||
### 为什么这样修复
|
||
|
||
1. **Pandoc 输出格式多样**: 可能输出十六进制或十进制实体
|
||
2. **Word 偏好 Unicode**: 直接使用 Unicode 字符而非实体
|
||
3. **性能优化**: 字符串替换速度快，影响小
|
||
4. **兼容性好**: 不影响现有功能
|
||
|
||
## 总结
|
||
|
||
| 方面 | 状态 |
|
||
|-----|------|
|
||
| LaTeX 语法 | ✅ 正确 |
|
||
| OCR 后处理 | ✅ 不修改 `\lambda` 和 `\vdots` |
|
||
| MathML 转换 | ✅ 已修复（扩展实体映射） |
|
||
| 前端处理 | ❓ 需要验证 |
|
||
|
||
**建议**:
|
||
1. 先测试后端 API 是否返回正确的 Unicode 字符
|
||
2. 如果后端正常，再检查前端渲染
|
||
3. 使用提供的诊断工具定位具体问题
|
||
|
||
## 文档
|
||
|
||
详细报告: `/Users/yoge/dev/yoge/doc_processer/docs/LATEX_RENDERING_FIX_REPORT.md`
|