sci-figure

Sci-Figure — 科学图表提取器

从学术 PDF 论文中精准提取图表及子图。

许可说明：sci-figure 使用 AGPL-3.0-or-later 许可，因为它链接了采用 AGPL 许可的 PyMuPDF (fitz)。

安装

首次使用前，请从技能目录安装软件包：

cd ${SKILL_DIR}
pip install -e .

这会注册 sh-sci-fig CLI 命令。需要 Tesseract OCR：

• Windows：winget install UB-Mannheim.TesseractOCR
• Linux：apt install tesseract-ocr
• macOS：brew install tesseract

偏好设置（EXTEND.md）

使用 Bash 按优先级检查 EXTEND.md 是否存在：

# Check project-level first
test -f .baoyu-skills/sci-figure/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.baoyu-skills/sci-figure/EXTEND.md" && echo "user"

EXTEND.md 支持：默认 DPI | 默认输出格式 | Tesseract 路径

用法

sh-sci-fig <input.pdf> [options]

选项

选项	简写	说明	默认值
<input>		PDF 文件路径	必需
--figure	-f	图表编号（1、2、3……）	必需（--list/--all 除外）
--subfigure	-s	子图标签（a、b、c……）	无（返回整张图表）
--output	-o	输出目录	当前目录
--dpi	-d	输出分辨率	600
--list	-l	列出所有可用的图表编号	false
--all		提取所有图表	false
--format		输出格式（png/jpg）	png
--strategy		提取策略：hybrid/native/cv	hybrid
--ocr		OCR 引擎：tesseract/easyocr/none	tesseract
--render-page		渲染带注释的整页	false
--annotate		在渲染的页面上绘制边界框	false
--bbox		手动覆盖 bbox（以 px 为单位的 x0,y0,x1,y1）	None
--no-trim		禁用空白裁剪	false
--debug		启用调试日志	false
--quiet	-q	不显示信息消息	false

示例

# Extract Figure 2, sub-figure c
sh-sci-fig paper.pdf -f 2 -s c

# Extract entire Figure 3
sh-sci-fig paper.pdf -f 3

# List all available figures in a PDF
sh-sci-fig paper.pdf --list

# Extract all figures
sh-sci-fig paper.pdf --all

# Custom output directory and DPI
sh-sci-fig paper.pdf -f 2 -s c -o ./output/ -d 300

# Use EasyOCR for sub-figure label detection
sh-sci-fig paper.pdf --all --ocr easyocr

# CV-only strategy (skip native extraction)
sh-sci-fig paper.pdf --all --strategy cv

# Render page with annotated bounding boxes (debugging)
sh-sci-fig paper.pdf -f 1 --render-page --annotate

# Manual bbox extraction (multimodal correction)
sh-sci-fig paper.pdf -f 1 --bbox 100,200,800,1200

输出：

Extracted: figure_2c.png (1920x1080, 600 DPI)

错误处理

情况	行为
未找到图表编号	报错并列出所有可用的图表编号
OCR 识别失败	返回整个图表区域
子图拆分失败	返回整个图表区域
未找到子图标签	返回整个图表区域

技术栈

库	作用
pdfplumber	文本和坐标提取（标题检测）
PyMuPDF (fitz)	原生图像提取和高质量页面渲染
opencv-python	CV 区域检测、连通分量分析、内容验证
Pillow	最终裁剪、格式转换
pytesseract	用于识别子图标签的 OCR（默认）
easyocr	备用 OCR 引擎（可选，pip install sci-figure[ocr]）
numpy	图像数组操作

提取引擎（v2）

引擎	优先级	适用场景
Native (PyMuPDF)	第 1 优先	嵌入 PDF 的栅格图像
CV（连通分量）	第 2 优先	矢量图形、彩色绘图
标题锚定	第 3 优先	上述引擎失败时的备用方案

hybrid 策略（默认）会按顺序尝试全部三种引擎并验证结果。

检测到的图表字段

FigureExtractor.detect_all() 返回的每个图表都是一个包含以下键的 dict：

字段	类型	说明
number	int	图表编号
page	int	页码索引（从 0 开始）
bbox_pdf	tuple	PDF 点数中的裁剪区域（x0、y0、x1、y1）
bbox_px	tuple	像素中的裁剪区域（x0、y0、x1、y1）
caption_text	str	完整标题文本
figure_type	str	类型之一：figure、scheme、chart、supplementary、extended_data
sublabels	list[str]	子图标签，例如 ["a","b","c"]
image	ndarray	裁剪后的图表图像（numpy 数组）
engine_used	str	生成裁剪结果的引擎：native、cv 或 fallback

list_figures() 返回相同的 dict，但不包含 image 字段。

扩展支持

通过 EXTEND.md 使用自定义配置。路径和支持的选项请参见偏好设置部分。

---

© 许可与版权

Aut_Sci_Write — 自主科学写作器

• 作者：Shuo Zhao
• 许可：MIT License
• 版权：© 2026 Shuo Zhao。保留所有权利。
• 原创作品：这是作者创作的原创作品。未经明确许可，不得复制、再分发或用于商业用途。 特此免费授予许可，允许任何人获取本软件的副本……（完整的 MIT 条款请参阅根目录中的 LICENSE 文件。）

---

此技能是 Aut_Sci_Write 套件的一部分。完整许可条款请参阅项目根目录中的 LICENSE 文件。