Sunrich-HT/figure-extractor

Figure Extractor 技能

當使用者需要從 PDF、arXiv 論文或 HTML 文章中提取完整的圖形或影像時，使用此技能。

此技能的實際內容（請先閱讀）

figure-extractor 是一個命令列工具（Python + PyMuPDF）。「使用它」表示在 shell 中執行其 CLI，例如：figure-extractor extract paper.pdf。它不是代理內可呼叫的函式、託管服務或可啟用的「頁面」，也無法在沒有 shell 或無法安裝 Python 套件的環境中執行（例如 Notion Agent、僅瀏覽器的代理）。

呼叫合約

• 機制： shell 命令 figure-extractor <子命令> ...（透過 pip install -e . 安裝）。
• 輸入： 本機 PDF/HTML 路徑或 PDF/arXiv/HTML URL。
• 輸出： PNG 檔案 + manifest.json + contact_sheet.jpg（+ 可選的 figures.zip）寫入 --out 指定的目錄。

步驟 0 — 前置條件檢查（務必先執行此步驟）

在您承諾進行圖形提取之前，請先驗證此工具是否確實可在當前環境中執行：

figure-extractor --help     # 如果此指令出錯，或沒有 shell，則工具不可用

• 可用（指令可執行） → 遵循 偏好演算法。
• 不可用（無 shell / 未安裝 / 沙箱環境） → 進入 降級模式。沒有此工具並非失敗，也不違反規則 — 請優雅地降級處理，並告訴使用者您做了什麼。

核心規則（當提取器可用時）

請不要僅依賴內嵌的 PDF 影像提取。許多圖形由向量繪圖、文字標籤、圖例和點陣圖片段組成。內嵌影像提取常常回傳不完整的片段 — 偏好使用標題邊界框渲染與裁剪的流程。

偏好演算法（需要 shell + CLI）

1. 解析輸入來源：
   • 本機 PDF
   • PDF URL
   • arXiv 摘要 URL（/abs/ 會自動正規化為 /pdf/）
   • HTML URL
   • 本機 HTML
2. 如果有 HTML，先嘗試從 <figure>、<img>、<picture>、srcset 和懶加載屬性中提取原始圖形影像。
3. 如果 HTML 未能提供足夠高品質的圖形，請定位或下載 PDF。
4. 對於 PDF：
   • 定位每個標題：Figure 2.1、Figure B.1、Extended Data Fig. 1、Supplementary Table S3、Scheme/Algorithm/Listing/Box、图 1；
   • 恢復頁面的欄位網格，並將每個裁剪區域限制在其標題所在欄位；
   • 從圖形基本元素開始擴展邊界框，在遇到其他標題或文字時停止；
   • 以 300 dpi 渲染頁面並進行裁剪；
   • 生成 PNG 檔案、manifest.json 和 contact_sheet.jpg。
5. 讀取 manifest.json 中每個條目的 status 欄位。 任何標記為 suspect 或 failed 的項目都帶有 quality_reasons 欄位，說明出了什麼問題。請不要將 failed 的裁剪結果當作圖形呈現給使用者。
6. 如果裁剪結果錯誤，請使用 crop --bbox 進行修正，從 manifest 中記錄的邊界框開始。

降級模式（無 shell / CLI 不可用 / 位元圖無法取得）

當您無法執行 figure-extractor（無 shell、無 Python/pip、沙箱環境），或當您無法執行任何能取得實際位元圖的操作時（例如 HTML 會移除 <img> src、arXiv 影像 URL 回傳 404、頁面需要驗證），使用此模式。此路徑明確允許，不視為違反「核心規則」：

1. 提供原始連結。 提供直接的圖形 URL、來源頁面，或 arXiv PDF 頁碼加上圖形編號，以便使用者開啟真實影像。
2. 忠實描述。 根據每個圖形的標題和周圍文字，提供結構化的解讀：展示的內容、軸/面板/圖例、關鍵趨勢。切勿編造您實際上無法看到的圖形內容。
3. 標明差距。 明確說明，例如：位元圖未嵌入 — 原因：無可用 shell（或 影像 404、src 被清理器移除、需要驗證）。

降級輸出 = 原始連結 + 忠實的結構化描述 + 明確的「為何缺少位元圖」說明。這是可接受的結果，並非違規。

設定

缺少套件並非降級的理由 — 請安裝它。 依賴套件數量很少（PyMuPDF、Pillow、beautifulsoup4）；不需 GPU、不需模型、不需服務。

pip install git+https://github.com/Sunrich-HT/figure-extractor

若已簽出儲存庫：pip install -e .

有 PDF？直接在 PDF 上執行。

如果使用者附加了 PDF，或者您可以下載到 PDF，這是最簡單且最可靠的方式。請不要從 HTML 或瀏覽器開始。

figure-extractor extract <pdf-path> --out ./figures --dpi 300 --zip

只有在無法取得 PDF 時，才應嘗試 HTML 路徑。請注意，某些環境的 HTML 擷取器會移除 <img src>，僅留下文字 — 發生這種情況時，請停止處理 HTML，回頭去抓取 PDF。

指令

# 自動提取（本機 PDF、PDF URL、arXiv 摘要 URL 或 HTML 文章）
figure-extractor extract paper.pdf --out ./figures --dpi 300 --zip
figure-extractor extract https://arxiv.org/abs/2606.23443 --out ./figures --zip
figure-extractor extract https://openreview.net/forum?id=XXXX --out ./figures
figure-extractor extract https://example.com/article --prefer html --fallback pdf

# 僅提取圖形，或僅提取最可能承載論點的裁剪結果
figure-extractor extract paper.pdf --kinds figure --tiers A,B

# 手動修正單個圖形的邊界框
figure-extractor crop paper.pdf --page 5 --bbox 295,245,556,475 --out fig04.png --dpi 300

預設設定

• dpi：300
• margin：8 PDF 點數
• prefer：auto
• fallback：pdf
• kinds：all — 預設為窮舉提取
• tiers：A,B,C — 預設不過濾任何內容；分級是分類訊號，而非判斷哪些圖示承載論點
• contact_sheet：true

品質控制指引

當提取器執行過後，請務必檢查 contact_sheet.jpg 以及 manifest 中每個條目的 status。suspect 和 failed 的裁剪結果會在聯絡頁面上以橙色和紅色標記。如果某個圖形包含了周圍的正文或遺漏了圖形的部分，請使用手動邊界框重新執行 crop。

manifest 會記錄工具所看到的每一個候選項目。如果 containers_found 的數量超過了實際渲染的數量，dropped 列表會說明每個項目未被渲染的原因 — 將無法解釋的差距視為錯誤，而非正常執行。