Metadata-Version: 2.4
Name: moxptt
Version: 0.0.1
Summary: MoxPtt CLI Application
Author: Morgan Chen
Author-email: tetsuhou@gmail.com
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: click
Requires-Dist: pyyaml
Requires-Dist: moxtools>=0.9.7
Requires-Dist: comtypes
Requires-Dist: python-pptx
Requires-Dist: pillow
Provides-Extra: gui
Requires-Dist: streamlit; extra == "gui"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# moxptt 使用者操作手冊

**Author:** `Morgan Chen` &emsp;|&emsp; **Date:** `2026-07-13`  &emsp;|&emsp; **Version:** `v0.0.1`

## 1. 專案概述 (Project Overview)
`moxptt` 是一個基於 Python 的簡報影像裁剪工具與 CLI 框架。本專案核心模組 `to_img.py` 旨在自動化投影片重點區塊的擷取。它會利用 `python-pptx` 套件在簡報中尋找含有特定關鍵字（例如 `crop_region`）的簡報形狀區塊，並計算其相對比例位置，隨後透過 Windows PowerPoint COM 元件將該投影片頁面匯出為高解析度全圖，最後使用 Pillow (PIL) 影像處理函式庫，根據前述比例位置與自訂緩衝區間（Padding）精確裁剪出目標區域，並產出 GIF 檔案，同時生成網頁預覽檔案 `img_previous.md`。

本專案亦整合了 Click 與 Streamlit，提供健全的命令列介面（在 `cli.py`)實作。

若要在 Python 專案中導入此模組進行程式化呼叫，可以使用以下方式：
```python
from moxptt import to_img
# 或者導入核心應用類別
from moxptt.to_img import ToImgApp
```

- **支援的平台與環境**：
  - **作業系統**：Windows (因為簡報高解析度全圖匯出功能強烈依賴 Windows COM 套件 `comtypes` 呼叫 Microsoft PowerPoint 應用程式)
  - **語言/運行環境版本**：Python = 3.11, 3.12

## 2. 🛠️ 環境準備 (Prerequisites)
- **必要套件**：
  專案依賴 `click` 作為 CLI 解析工具、`pyyaml` 讀取設定檔、`moxtools` 提供核心套件工具、`comtypes` 控制 PowerPoint COM 元件、`python-pptx` 解析簡報結構、以及 `pillow` 處理圖片裁剪。

  ```bash
  pip install click pyyaml moxtools comtypes python-pptx pillow
  ```
  *(註：本專案必須在已安裝 Microsoft Office PowerPoint 的 Windows 系統環境下執行，以確保 PowerPoint COM 能正常調用進行高解析度圖片導出。)*

- **安裝 moxptt CLI**：
  安裝成功後，即可在終端機直接使用 `mox-ptt` 命令。
  - **從發行平台安裝（推薦）**：
    ```bash
    pip install moxptt
    ```
  - **本地開發模式安裝**（可編輯模式 Editable Mode）：
    請在專案根目錄下執行以下指令：
    ```bash
    pip install -e .
    ```

- **環境變數 / 設定檔**：
  - **除錯模式**：可透過 `--debug` 參數或設定環境變藝 `PYCLI_DEBUG` 來啟用全域除錯模式。
  - **設定檔載入**：各子指令支援讀取 `YAML` 格式的設定檔。若無指定，將會使用內置的預設設定。若在指令中指定 `-c` / `--config` 但未填寫路徑，系統會自動在目前目錄下搜尋以 `config` 開頭且副檔名為 `.yaml` 或 `.yml` 的檔案，進行自動選取或進入互動式選單。

- **YAML 設定檔說明**:
  以 `to-img` 為例，其預設設定檔內容如下：
  ```yaml
  config:
    target_slides: "all"
    search_keyword: "crop_region"
    output_dir: "./img"
    scale_width: 4800
    padding: -40
  ```

  - **設定欄位/選項對照說明**：
    - `target_slides`：欲處理的簡報投影片頁碼範圍。可設為 `"all"`（代表處理所有頁面），或是單一頁碼整數（如 `3`），亦可使用逗號分隔指定多個頁碼（如 `"1,2,4"`）。頁碼皆從 1 開始計算。
    - `search_keyword`：在簡報投影片中用來搜尋目標裁剪框/形狀的文字關鍵字。預設為 `"crop_region"`。
    - `output_dir`：裁剪後影像的儲存路徑。預設為 `"./img"`。
    - `scale_width`：PowerPoint 匯出投影片全圖時的高解析度寬度像素。預設為 `4800`，高度會按比例縮放。
    - `padding`：裁切邊緣的緩衝像素值。正值代表向外擴大裁切區域，負值代表向內縮小裁切區域。預設為 `-40`。

## 3. 🚀 執行方式 (Execution Guide)

### 基本指令
透過主命令 `mox-ptt` 作為進入點，執行各項子功能：

| 參數 | 短指令 | 型態 | 預設值 | 說明 |
| :--- | :--- | :--- | :--- | :--- |
| `--debug / --no-debug` | (無) | Flag | `False` | 啟用或停用全域除錯模式。啟用時會輸出詳細的日誌，並設定環境變數 `PYCLI_DEBUG=1`。 |
| `--version` | `-v` | Flag | `False` | 顯示 `moxptt` 與 `moxtools` 套件的版本資訊並離開。 |

> [!NOTE]
> 1. 請確保在執行指令前，簡報檔案（.pptx）未被其他應用程式（如 PowerPoint 編輯視窗）獨佔鎖定，否則 COM 元件可能無法載入。
> 2. 由於工具需要搜尋投影片中的關鍵字，請確保簡報文字框或形狀內確實含有 `crop_region`（或自訂的關鍵字）。

### 預期結果
- **CLI 模式**：終端機將會顯示處理進度與裁切狀態日誌（例如 `🎉 【第 1 頁區域 1 裁切成功】已儲存為: img1_slide1.gif` 等）。
- **檔案輸出**：於指定的輸出資料夾中產生裁切後的 GIF 影像檔案，並於執行目錄下自動產出 `img_previous.md` 預覽文件。

### 📋 子指令功能說明 (Sub-commands Overview)
`moxptt` 提供了以下核心子指令來自動化您的開發流程：

| 子指令 | 功能簡介 | 詳細說明與用途 |
| :--- | :--- | :--- |
| **`to-img`** | 依簡報設定裁剪投影片重點區塊 | 自動解析簡報、定位含有關鍵字之物件並以 Pillow 裁切成 GIF。支援讀取 YAML 設定檔、互動式選用設定檔，以及使用 `--generate-config` 產生預設的 YAML 設定範本。 |


## 4. 📝 使用範例 (Examples)

### 範例一：使用預設設定進行簡報圖片裁剪 (Direct Mode)
在含有簡報檔案（.pptx）的目錄下直接執行此命令，系統會自動選取簡報，並使用預設的 `crop_region` 關鍵字與 `./img` 輸出目錄進行裁剪。
```bash
mox-ptt to-img
```

## 5. 📅 版本更新紀錄 (Change Log)

### v0.0.1 (2026-07-13)
- **新功能 (Features)**：
  - 專案初始化，提供 `mox-ptt` 命令列工具與 `to-img`子指令。
  - 支援使用 `python-pptx` 自動搜尋簡報投影片中帶有關鍵字的形狀，並透過 `comtypes` 串接 Windows PowerPoint 匯出高解析度全圖。
  - 支援 Pillow 進行精確影像裁剪並輸出 GIF。
  - 在生成 `img1_slide1.gif` 預覽時插入自訂排版區塊，並自動產生 `img_previous.md` 預覽文件。
- **重構與優化 (Refactoring & Optimization)**：
  - 將投影片圖片裁切與 markdown 預覽內容生成邏輯抽取為獨立函式 `crop_slide_targets` 與 `generate_preview_content`，提升程式碼模組化與可維護性。
  - 統一重構流程步驟的行內註解格式，使用 `[步驟 1]` 到 `[步驟 4]` 標籤以分隔線框包裹，語意更精確且提升可讀性。
  - 優化 `img_previous.md` 圖片路徑，移除 `./` 前綴。
- **防呆與容錯 (Robustness)**：
  - 在 `crop_slide_targets` 中加入座標反轉之防呆與錯誤處理機制。
  - 預處理 `sys.argv` 以防 `-c` / `--config` 後方無參數時 Click 報錯的問題。
  - 自動重組 Windows Console 編碼（若不為 UTF-8 則 reconfigure 為 UTF-8）避免印出特殊字元時報錯。
