Metadata-Version: 2.4
Name: pdf2html-engine
Version: 0.1.4
Summary: A PDF to HTML converter focused on layout preservation and table extraction.
Author-email: Peng Go <your-email@example.com>
Project-URL: Homepage, https://github.com/youruser/pdf2html-engine
Project-URL: Bug Tracker, https://github.com/youruser/pdf2html-engine/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: PyMuPDF>=1.23.0
Requires-Dist: pdfplumber>=0.10.0
Requires-Dist: Jinja2>=3.1.0

# PDF to HTML Engine

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

## 🚀 核心功能

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

## 🛠️ 安装

```bash
pip install pdf2html-engine
```

## 📖 快速上手

### 1. 作为 Python 库使用

```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` 命令：

```bash
# 基本转换
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` 层，将线条与文本位置匹配，智能判定下划线语义。
