moxptt 0.0.1

MoxPtt CLI Application

moxptt 使用者操作手冊

Author: Morgan Chen  |  Date: 2026-07-13  |  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 專案中導入此模組進行程式化呼叫，可以使用以下方式：

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 處理圖片裁剪。

  pip install click pyyaml moxtools comtypes python-pptx pillow
  

  (註：本專案必須在已安裝 Microsoft Office PowerPoint 的 Windows 系統環境下執行，以確保 PowerPoint COM 能正常調用進行高解析度圖片導出。)

• 安裝 moxptt CLI： 安裝成功後，即可在終端機直接使用 mox-ptt 命令。

  • 從發行平台安裝（推薦）：

    pip install moxptt
    

  • 本地開發模式安裝（可編輯模式 Editable Mode）： 請在專案根目錄下執行以下指令：

    pip install -e .
    

• 環境變數 / 設定檔：

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

• YAML 設定檔說明: 以 to-img 為例，其預設設定檔內容如下：

  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 輸出目錄進行裁剪。

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）避免印出特殊字元時報錯。