MinerU 深度优化

本文档详细说明 NotebookLM2PPT 中 MinerU 深度优化功能的技术实现细节，适合技术人员参考。

🧠 核心原理

MinerU 优化功能通过解析 MinerU 生成的 JSON 文件，提取页面结构信息，对基础转换生成的 PPT 进行深度优化，提升排版质量、图片清晰度和文本准确性。

🔧 核心模块

文件: notebooklm2ppt/utils/ppt_refiner.py

主要函数:

python

def refine_ppt(tmp_image_dir, json_file, ppt_file, png_dir, png_files, final_out_ppt_file, unify_font=None, font_name=None)

参数说明:

tmp_image_dir: 临时图片目录
json_file: MinerU 生成的 JSON 文件路径
ppt_file: 基础转换生成的 PPT 文件路径
png_dir: PDF 转换生成的 PNG 图片目录
png_files: PNG 文件列表
final_out_ppt_file: 最终输出的优化后 PPT 文件路径
unify_font: 是否统一字体（可选，默认为配置文件中的设置）
font_name: 统一使用的字体名称（可选，默认为"微软雅黑"）

📊 优化流程

1. 智能文本框筛选

问题: 基础转换可能会识别出无关的文本框

解决方案: 使用 IOU（交并比）算法评估文本框与 PDF 内容块的重叠程度

实现:

python

def compute_iou(boxA, boxB):
    # 计算两个矩形的交集面积
    xA = max(boxA[0], boxB[0])
    yA = max(boxA[1], boxB[1])
    xB = min(boxA[2], boxB[2])
    yB = min(boxA[3], boxB[3])

    interWidth = max(0, xB - xA)
    interHeight = max(0, yB - yA)
    interArea = interWidth * interHeight

    boxAArea = (boxA[2] - boxA[0]) * (boxA[3] - boxA[1])
    boxBArea = (boxB[2] - boxB[0]) * (boxB[3] - boxB[1])

    iou = interArea / float(boxAArea + boxBArea - interArea)
    return iou

筛选逻辑:

计算每个文本框与 PDF 内容块的 IOU
保留 IOU > 0.01 的文本框（相关性强）
删除 IOU ≤ 0.01 的文本框（可能是无关元素）

2. 字体统一处理

问题: 基础转换生成的 PPT 中，文本框字体可能各不相同

解决方案: 统一所有文本框字体为"微软雅黑"

实现:

python

# 创建微软雅黑字体对象
newFont = TextFont("微软雅黑")

# 遍历文本框中的所有文本范围
for textRange in paragraph.TextRanges:
    textRange.LatinFont = newFont

3. 高质量图片替换

问题: 基础转换过程中图片可能被压缩或质量降低

解决方案: 从 PDF 渲染的高清 PNG 中裁剪出原始图片区域并替换

实现:

python

# 裁剪并保存临时图片
image_crop = image_cv[top_bg:bottom_bg, left_bg:right_bg]
Image.fromarray(image_crop).save(tmp_image_path)

# 替换 PPT 中的图片
rect1 = RectangleF.FromLTRB(left, top + delta_y, right, bottom + delta_y)
image = slide.Shapes.AppendEmbedImageByPath(ShapeType.Rectangle, tmp_image_path, rect1)
image.Line.FillType = FillFormatType.none
image.ZOrderPosition = 0  # 设置图片在最底层

4. 智能背景处理

问题: 需要平衡纯色区域填充和复杂背景保留

解决方案: 基于边缘颜色一致性（多样性）和旧背景可用性的智能判断

实现:

python

from notebooklm2ppt.utils.edge_diversity import compute_edge_diversity_numpy

diversity, fill_color = compute_edge_diversity_numpy(image_cv, left, top, right, bottom, tolerance=15)

if old_bg_cv is None or diversity < 0.5:
    # 边缘颜色较一致（接近纯色）或无旧背景，直接填充主色
    image_cv[top:bottom, left:right] = fill_color
else:
    # 边缘颜色变化较大（复杂背景），保留原背景
    image_cv[top:bottom, left:right] = old_bg_cv[top:bottom, left:right]

其中：

diversity ∈ [0, 1]，数值越小表示边缘颜色越接近单一纯色
fill_color 为根据边缘主色计算得到的填充颜色

📈 完整工作流程

1. 数据准备

python

# 1. 加载 MinerU JSON
data = load_json(json_file)
pdf_info = data['pdf_info']

# 2. 根据页码筛选信息
indices = get_indices_from_png_names(png_files)
pdf_info = [pdf_info[i] for i in indices]

# 3. 计算缩放比例
pdf_w, _ = pdf_info[0]['page_size']
presentation = Presentation()
presentation.LoadFromFile(ppt_file)
ppt_H, ppt_W = presentation.SlideSize.Size.Height, presentation.SlideSize.Size.Width
ppt_scale = ppt_W / pdf_w

2. 逐页处理

python

for page_index, slide in enumerate(presentation.Slides):
    # 1. 智能文本框筛选和字体统一
    # 2. 高质量图片替换
    # 3. 智能背景处理

3. 保存结果

python

presentation.SaveToFile(final_out_ppt_file, FileFormat.Pptx2019)
print(f"优化完成! 输出文件: {final_out_ppt_file}")

# 清理 PPT
clean_ppt(final_out_ppt_file, final_out_ppt_file)

🔍 关键算法

IOU（交并比）算法

应用: 文本框筛选原理: 计算两个矩形区域的重叠程度阈值: 0.01（经过实验验证的合理阈值）

边缘多样性检测算法

应用: 背景处理原理: 统计文本块四条边缘像素的主色占比，主色占比越高，多样性越低输出:

diversity = 1 - main_ratio，main_ratio 为主色占比
fill_color 为主色对应的平均 RGB 颜色阈值: 0.5（diversity < 0.5 时认为接近纯色区域，可用主色填充）

⚙️ 技术参数

参数	默认值	作用	影响
IOU 阈值	0.01	文本框筛选	影响文本框保留数量
边缘多样性阈值	0.5	背景处理	越小越容易判定为纯色区域
边缘颜色容差	15	边缘颜色量化	容差越大越不敏感，主色更稳定
图片缓存	启用	性能优化	减少重复裁剪操作

🚀 性能优化

局部裁剪: 直接从高清页面渲染图中裁剪图片区域，保证了图片与背景的高度一致性。
逐页处理: 以页为单位顺序处理，逻辑清晰，便于调试和扩展并行化。
内存管理: 利用 Python 垃圾回收逐页释放临时数组，避免内存占用过高。

🐛 故障排查

常见问题

问题	可能原因	解决方案
图片裁剪位置偏移	缩放比例计算不准确或 PDF 布局复杂	检查 `ppt_scale` 和 `image_scale` 计算逻辑
文本框筛选不准确	IOU 阈值不合适或 JSON 解析质量差	调整 IOU 阈值，检查 JSON 质量
背景处理效果不理想	阈值设置不合适	调整边缘多样性阈值或边缘颜色容差
优化速度慢	文档较大或页面图片分辨率极高	适当降低 PNG 渲染分辨率

调试建议

启用调试模式: 设置环境变量 NOTEBOOKLM2PPT_DEBUG=1
检查 JSON 文件: 确认 JSON 文件格式正确，包含完整的页面信息
调整阈值: 根据实际情况调整算法阈值（IOU、多样性、容差）

📚 技术依赖

Spire.Presentation: 用于 PPT 操作和修改
NumPy: 用于数值计算、图像数组操作和边缘颜色统计
Requests: 用于下载 MinerU 图片
Pillow: 用于图像读写与缩放（背景图和页面截图）

🔗 相关文档

工作原理：了解整体工作流程
快速开始：了解如何使用 MinerU 优化
功能介绍：了解 MinerU 优化的核心功能

MinerU 深度优化 ​

🧠 核心原理 ​

🔧 核心模块 ​

📊 优化流程 ​

1. 智能文本框筛选 ​

2. 字体统一处理 ​

3. 高质量图片替换 ​

4. 智能背景处理 ​

📈 完整工作流程 ​

1. 数据准备 ​

2. 逐页处理 ​

3. 保存结果 ​

🔍 关键算法 ​

IOU（交并比）算法 ​

边缘多样性检测算法 ​

⚙️ 技术参数 ​

🚀 性能优化 ​

🐛 故障排查 ​

常见问题 ​

调试建议 ​

📚 技术依赖 ​

🔗 相关文档 ​

MinerU 深度优化

🧠 核心原理

🔧 核心模块

📊 优化流程

1. 智能文本框筛选

2. 字体统一处理

3. 高质量图片替换

4. 智能背景处理

📈 完整工作流程

1. 数据准备

2. 逐页处理

3. 保存结果

🔍 关键算法

IOU（交并比）算法

边缘多样性检测算法

⚙️ 技术参数

🚀 性能优化

🐛 故障排查

常见问题

调试建议

📚 技术依赖

🔗 相关文档