Semantic Reconstruction Engine

Semantic Reconstruction Engine 是一個以 Python 撰寫的 PDF → EPUB 語意重建工具。它會解析 PDF 的版面、欄位、段落、標題、註腳、圖片與表格區域，嘗試把固定版面的 PDF 還原成更適合閱讀器瀏覽的 EPUB；也能輸出標註版 PDF，協助開發者檢查分類與版面判讀結果。

目前專案仍在早期開發階段，歡迎 issue、討論、文件補充與 pull request。

功能特色

• PDF 語意解析：使用 PyMuPDF 讀取 PDF，並透過管線分析頁面、段落、標題與註腳。
• EPUB 匯出：把重建後的文字流輸出為 EPUB，並保留基本章節與圖片內容。
• Debug PDF：輸出帶有分類框線與標籤的 PDF，方便調整版面與語意分類規則。
• 診斷 JSON：可選擇輸出轉換摘要、頁面錯誤、警告與 EPUB 基本結構檢查結果。
• CLI 與 Web UI：支援命令列批次轉換，也提供本機網頁介面上傳 PDF。

專案結構

pdf_engine/
├── main.py            # CLI 入口與 PDF 處理流程
├── web.py             # 標準函式庫實作的本機 Web UI
├── pipeline.py        # 文件解析管線
├── layout_engine.py   # 行、欄、區域與閱讀順序推論
├── classifier.py      # 段落語意分類
├── epub_exporter.py   # EPUB 產生器
├── diagnostics.py     # 轉換診斷與 EPUB 基本驗證
├── templates/         # Web UI HTML 模板
├── static/            # Web UI 樣式
└── models/            # ONNX 模型資產

系統需求

• Python 3.9 或更新版本
• 建議使用 virtual environment
• 依賴套件會由 pyproject.toml 安裝：
  • PyMuPDF
  • EbookLib
  • onnxruntime
  • numpy

安裝(macOS, linux)

git clone https://github.com/codinguniversefromEric/semantic-reconstruction-engine.git
cd semantic-reconstruction-engine
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

安裝(windows)

git clone https://github.com/codinguniversefromEric/semantic-reconstruction-engine.git
cd semantic-reconstruction-engine
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Windows PowerShell 啟用虛擬環境：

.venv\Scripts\Activate.ps1

使用方式

CLI：轉成 EPUB

pdf2epub -i input.pdf -o output.epub

CLI：輸出標註版 Debug PDF

只要輸出副檔名不是 .epub，工具就會走 Debug PDF 輸出模式：

pdf2epub -i input.pdf -o output.debug.pdf

CLI：輸出診斷 JSON

pdf2epub -i input.pdf -o output.epub --diagnostics output.diagnostics.json

Web UI

pdf2epub-web

預設服務位置：http://127.0.0.1:8000

可用環境變數：

變數	預設值	說明
PDF_ENGINE_WEB_HOST	127.0.0.1	Web UI 綁定的 host
PDF_ENGINE_WEB_PORT	8000	Web UI 連接埠
PDF_ENGINE_WEB_WORKDIR	系統暫存目錄下的 semantic-reconstruction-engine	上傳與輸出檔案暫存位置
PDF_ENGINE_MAX_UPLOAD_MB	100	單一 PDF 上傳大小上限（MB）

開發

安裝 editable package 後即可直接修改 pdf_engine/ 內的程式並重跑指令測試：

python -m pip install -e .
python -m compileall pdf_engine

建議在提交前至少確認：

1. 受影響的 Python 檔案可成功編譯。
2. CLI 可對一份小型 PDF 產生預期輸出。
3. 若修改 Web UI，請手動啟動 pdf2epub-web 並測試上傳流程。
4. 若修改 EPUB 輸出，請開啟輸出的 EPUB 或檢查診斷 JSON。

歡迎貢獻

本專案開放社群貢獻，歡迎協助：

• 回報轉換失敗或版面判讀錯誤的 PDF 案例。
• 改善段落、標題、註腳、圖片或表格的語意分類。
• 補充測試、範例文件與診斷工具。
• 改善 Web UI、CLI 體驗與錯誤訊息。
• 撰寫或翻譯文件。

請先閱讀 CONTRIBUTING.md 了解開發流程、commit/PR 建議與回報問題時需要提供的資訊。

注意事項

• 請只轉換你有權處理的 PDF 文件。
• 純掃描圖片型 PDF 可能無法萃取有效文字，需要 OCR 前處理。
• 目前沒有宣告正式穩定 API；內部資料結構仍可能隨版本調整。

授權

此儲存庫目前尚未包含授權條款檔案。若你想在其他專案中使用、散布或商業化本專案，請先與維護者確認授權方式。

##⚙️ 模型來源 本專案的核心功能是由以下開源模型直接驅動：

模型名稱： vaivTA/yolov8n_doclaynet

開發團隊： VAIV-TA-LAB

開源授權： Apache license 2.0

模型連結： https://huggingface.co/vaivTA/yolov8n_doclaynet/tree/main/weights