Metadata-Version: 2.4
Name: pdf2html-engine
Version: 0.1.0
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-left` 和动态字体大小还原 PDF 的原始视觉布局。
- **智能表格提取**：利用 `pdfplumber` 识别表格，支持复杂的单元格合并（rowspan/colspan）和文本对齐。
- **下划线处理**：自动识别文档中的填空下划线（包括文本中的和图形绘制的），并在 HTML 中保留。
- **中文字体支持**：内置对常用中文字体（如 微软雅黑、宋体、华文细黑等）的 CSS 优化。
- **模块化设计**：包含加载器、布局引擎、表格提取器和渲染器，易于扩展和集成。

## 技术栈

- **核心语言**：Python 3.12+
- **PDF 处理**：[PyMuPDF (fitz)](https://github.com/pymupdf/PyMuPDF) & [pdfplumber](https://github.com/jsvine/pdfplumber)
- **模板引擎**：[Jinja2](https://github.com/pallets/jinja)
- **布局算法**：基于坐标的行归类与间距计算

## 快速开始

### 1. 环境配置

建议使用虚拟环境：

```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境 (macOS/Linux)
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

### 2. 命令行使用 (调试功能)

```bash
# 转换全文档
python main.py path/to/your/input.pdf -o output.html

# 仅转换指定页面 (支持 1,2,3 或 1-5 格式)
python main.py path/to/your/input.pdf -p 1,3-5 -o output.html
```

### 3. 作为包集成 (API 调用)

现在你可以直接在其他 Python 项目中调用此包，获取 HTML 代码片段：

```python
from pdf2html_engine import parse_pdf

# 转换指定页面，返回 HTML 代码片段
file_path = "example.pdf"
html_snippets = parse_pdf(file_path, pages=[1, 2])

print(html_snippets)
```

如果你需要更多控制权，可以使用 `PDFConverter` 类：

```python
from pdf2html_engine import PDFConverter

converter = PDFConverter("example.pdf")

# 获取 HTML 片段 (默认)
snippets = converter.convert(pages=[1, 2])

# 获取完整的 HTML 文档 (包含 <html><body> 等标签)
full_doc = converter.convert(pages=[1, 2], full_html=True)
```

## 项目结构

```
pdf2html-engine/
├── main.py              # 程序入口，命令行工具
├── requirements.txt     # 项目依赖
├── pdf2html_engine/     # 核心解析引擎包
│   ├── __init__.py      # 暴露核心 API (PDFConverter, parse_pdf)
│   ├── converter.py     # 转换流程协调器，处理跨页逻辑
│   ├── pdf_loader.py    # 负责 PDF 文件的双引擎加载 (PyMuPDF + pdfplumber)
│   ├── layout_engine.py # 布局分析，处理文本、字体大小及位置
│   ├── table_extractor.py # 表格识别与 HTML 转换，处理合并单元格
│   └── html_renderer.py # 基于 Jinja2 的 HTML 生成器
└── venv/                # 虚拟环境目录（已忽略）
```

## 架构原理

### 1. 文本与布局 (LayoutEngine)
引擎通过 `PyMuPDF` 获取 PDF 中的每个文本块（Span）。通过计算其 `bbox` 坐标，将具有相近垂直坐标的文本归类为一行。对于每一行，通过 `padding-left` 实现相对于页面宽度的水平定位，通过 `margin-top` 实现行间距还原。

### 2. 表格处理 (TableExtractor)
利用 `pdfplumber` 强大的表格定位能力。通过分析表格的单元格结构，算法会自动识别合并的单元格并转换为 HTML 的 `rowspan` 和 `colspan`。同时，引擎会检测单元格内的细微线条，将其识别为填空下划线。

### 3. 混合排序
在处理每一页时，引擎会先提取表格位置，然后在提取普通文本布局时过滤掉表格所在的区域。最后，将文本行和表格块根据垂直坐标（y 轴）重新排序，确保生成的 HTML 逻辑顺序与原文档一致。

## 许可证

[MIT License](LICENSE)
