README.md

---
title: PDF to PPT Converter
emoji: 📄
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---
# PDFtoPPT

這是一個可以將 PDF 或包含文字的圖片轉換成 **「可完全編輯的 PowerPoint (.pptx)」** 簡報檔的開源工具。

透過結合 `easyocr` 與 `python-pptx`，本工具解決了常見的 OCR 轉檔問題：
1. **支援傾斜文字**：能精準計算文字旋轉角度，並套用於 PPT 的文字方塊上。
2. **精確的排版與字體大小**：自動將原圖文字區域的大小對應至 PPTX，且將內邊距設為 0，確保生成的文字大小與原始圖片排版一致。
3. **無縫替換**：使用 OpenCV 的影像修補技術 (Inpainting) 自動將圖片上的原文字抹除，再疊加可編輯的文字方塊，防止文字重疊。

---

## 系統需求

- Python 3.8 或以上版本。
- **Poppler** (用於解析 PDF 檔案)。

### 1. 安裝系統依賴 (Poppler)

如果您需要轉換 PDF 檔案，系統必須先安裝 `poppler`：

*   **Windows**: 
    1. 從 [Poppler for Windows](https://github.com/oschwartz10612/poppler-windows/releases/) 下載最新版。
    2. 解壓縮並將 `bin/` 資料夾路徑加入到系統的環境變數 `PATH` 中。
*   **macOS (Homebrew)**:
    ```bash
    brew install poppler
    ```
*   **Linux (Ubuntu/Debian)**:
    ```bash
    sudo apt-get update
    sudo apt-get install poppler-utils
    ```

### 2. 建立 Python 虛擬環境與安裝套件

建議使用虛擬環境來安裝，避免套件衝突：

```bash
# 建立虛擬環境 (可選)
python -m venv venv

# 啟動虛擬環境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 安裝必要的 Python 套件
pip install python-pptx easyocr opencv-python-headless pdf2image numpy pillow streamlit
```

*(註：首次執行 `easyocr` 時，程式會自動從網路下載文字辨識的模型，請耐心等候。)*

---

## 雲端免費部署 (免安裝)

如果您不想在本地端安裝，您可以將此 GitHub 專案一鍵部署到 **Streamlit Community Cloud** 或 **Hugging Face Spaces** 上。

### 部署到 Streamlit Community Cloud (推薦)

1. 將本專案 Fork 或上傳到您自己的 GitHub 儲存庫。
2. 前往 [Streamlit Community Cloud](https://share.streamlit.io/) 並登入。
3. 點擊 **"New app"**。
4. 選擇您的 GitHub 儲存庫與分支，並在 **"Main file path"** 填寫 `webui.py`。
5. 點擊 **"Deploy!"**。
6. 系統會自動讀取 `requirements.txt` 與 `packages.txt`，並在幾分鐘內為您建立專屬的線上轉換網頁！

---

## 本機操作說明

### 啟動 Web UI (推薦)

我們提供了一個基於 Streamlit 的現代化網頁圖形介面，讓您可以直接在瀏覽器中上傳檔案並下載轉換後的 PPTX。

```bash
streamlit run webui.py
```
啟動後，瀏覽器會自動開啟 `http://localhost:8501`，您可以在網頁中輕鬆操作。

---

### 命令列基本用法

```bash
# 轉換 PDF
python convert.py input.pdf

# 轉換單張圖片 (支援 png, jpg, webp)
python convert.py input_image.png
```

預設情況下，程式會在當前目錄生成一個名為 `output.pptx` 的檔案。

### 進階參數設定

```bash
# 指定輸出檔名 (-o)
python convert.py input.pdf -o presentation_editable.pptx

# 指定 OCR 辨識語言 (--lang)
# 預設為繁體中文與英文 (ch_tra,en)
# 例如若只要辨識英文與日文：
python convert.py input.pdf --lang en,ja
```

### 支援的語言代碼 (部分常見)
* `ch_tra` : 繁體中文
* `ch_sim` : 簡體中文
* `en` : 英文
* `ja` : 日文
* `ko` : 韓文

完整的語言代碼請參考 [EasyOCR 官方文件](https://www.jaided.ai/easyocr/)。

---

## 開發者筆記

本專案包含以下核心腳本：
- `convert.py`: CLI 主程式入口，處理檔案讀取、PDF 拆圖與暫存檔清理。
- `ppt_converter.py`: 核心轉換邏輯，包含圖片修補 (Inpainting) 與使用 `python-pptx` 建構投影片。
- `ocr_utils.py`: 負責處理 EasyOCR 回傳的 4 點座標，計算旋轉角度、長寬與中心點。