pdf2html-engine 1.0.0

A PDF to HTML converter focused on layout preservation and table extraction.

PDF to HTML Engine

一个高性能、高保真度的 PDF 转 HTML 引擎，专注于 精准布局还原、复杂表格提取 以及 跨页表格无缝处理。它针对复杂报表和布局进行了深度优化，能够满足各种高要求的 PDF 转换场景。

🚀 核心功能

• 高保真布局还原：基于原子级坐标分析，通过 padding 和动态字体计算，精确还原文本的视觉位置。
• 智能表格解析：利用几何分析能力，完美支持复杂单元格合并（rowspan/colspan）及文本对齐。
• 跨页表格合并：独有的跨页逻辑，可识别并自动合并跨页断裂的表格，支持自动剔除重复表头。
• 双阶段扫描 (Two-Pass)：通过预扫描统一全局表格网格坐标，解决 PDF 转换中常见的列对齐微差问题。
• 智能下划线识别：自动关联文本与其下方的图形线条，将填空下划线还原为语义化的 HTML 标签。

🛠️ 安装

pip install pdf2html-engine

📖 快速上手

1. 作为 Python 库使用

from pdf2html_engine import parse_pdf

# 简单转换
html_content = parse_pdf("sample.pdf")

# 或者使用 PDFConverter 进行精细控制
from pdf2html_engine import PDFConverter

converter = PDFConverter("sample.pdf")
# pages: 指定页码（例如 [1, 2, 3]）
# full_html: 是否包含完整的 HTML 文档结构（html, body, head 等）
html = converter.convert(pages=[1, 2], full_html=True)

with open("output.html", "w", encoding="utf-8") as f:
    f.write(html)

2. 命令行工具 (CLI)

安装后，你可以直接在终端使用 pdf2html 命令：

# 基本转换
pdf2html input.pdf -o output.html

# 转换指定页码
pdf2html input.pdf -o output.html --pages 1-5,10

CLI 参数说明：

• input_pdf: 输入的 PDF 文件路径。
• -o, --output: 输出的 HTML 文件路径（默认为 output.html）。
• -p, --pages: 指定转换的页码（例如 1,2,3 或 1-5）。

🧠 核心架构原理

1. 视觉行聚类 (Visual Line Grouping)：按 Y 轴坐标对字符进行聚类，容忍微小垂直偏移，实现“所见即所得”的行合并。
2. 网格统一 (Grid Unification)：在 Pass 1 阶段收集所有页面的表格坐标，Pass 2 强制使用统一网格，确保跨页表格视觉对齐。
3. 图形关联：扫描 PDF 的 drawings 层，将线条与文本位置匹配，智能判定下划线语义。