SKILL.md
Sci-Figure — Scientific Figure Extractor
Precisely extract figures and sub-figures from academic PDF papers.
License note: sci-figure is licensed under AGPL-3.0-or-later because it links PyMuPDF (fitz), which is AGPL-licensed.
Installation
Install the package from the skill directory before first use:
cd ${SKILL_DIR}
pip install -e .This registers the sh-sci-fig CLI command. Requires Tesseract OCR:
- Windows:
winget install UB-Mannheim.TesseractOCR - Linux:
apt install tesseract-ocr - macOS:
brew install tesseract
Preferences (EXTEND.md)
Use Bash to check EXTEND.md existence (priority order):
# 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 Supports: Default DPI | Default output format | Tesseract path
Usage
sh-sci-fig <input.pdf> [options]Options
| Option | Short | Description | Default |
|---|---|---|---|
<input> |
PDF file path | Required | |
--figure |
-f |
Figure number (1, 2, 3...) | Required (except --list/--all) |
--subfigure |
-s |
Sub-figure label (a, b, c...) | None (returns whole figure) |
--output |
-o |
Output directory | Current directory |
--dpi |
-d |
Output resolution | 600 |
--list |
-l |
List all available figure numbers | false |
--all |
Extract all figures | false | |
--format |
Output format (png/jpg) | png | |
--strategy |
Extraction strategy: hybrid/native/cv | hybrid | |
--ocr |
OCR engine: tesseract/easyocr/none | tesseract | |
--render-page |
Render full page with annotations | false | |
--annotate |
Draw bounding boxes on rendered page | false | |
--bbox |
Manual bbox override (x0,y0,x1,y1 in px) | None | |
--no-trim |
Disable whitespace trimming | false | |
--debug |
Enable debug logging | false | |
--quiet |
-q |
Suppress info messages | false |
Examples
# 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,1200Output:
Extracted: figure_2c.png (1920x1080, 600 DPI)Error Handling
| Scenario | Behavior |
|---|---|
| Figure number not found | Error + list all available figure numbers |
| OCR recognition failed | Return entire figure region |
| Sub-figure split failed | Return entire figure region |
| No sub-figure labels found | Return entire figure region |
Tech Stack
| Library | Role |
|---|---|
| pdfplumber | Text + coordinate extraction (caption detection) |
| PyMuPDF (fitz) | Native image extraction + high-quality page rendering |
| opencv-python | CV region detection, connected-component analysis, content validation |
| Pillow | Final cropping, format conversion |
| pytesseract | OCR for sub-figure label recognition (default) |
| easyocr | Alternative OCR engine (optional, pip install sci-figure[ocr]) |
| numpy | Image array operations |
Extraction Engines (v2)
| Engine | Priority | Best For |
|---|---|---|
| Native (PyMuPDF) | 1st | Raster images embedded in PDF |
| CV (connected-component) | 2nd | Vector graphics, colored plots |
| Caption-anchored | 3rd | Fallback when above engines fail |
The hybrid strategy (default) tries all three in order and validates results.
Detected Figure Fields
Each figure returned by FigureExtractor.detect_all() is a dict with these keys:
| Field | Type | Description |
|---|---|---|
number |
int | Figure number |
page |
int | Page index (0-based) |
bbox_pdf |
tuple | Crop region in PDF points (x0, y0, x1, y1) |
bbox_px |
tuple | Crop region in pixels (x0, y0, x1, y1) |
caption_text |
str | Full caption text |
figure_type |
str | One of: figure, scheme, chart, supplementary, extended_data |
sublabels |
list[str] | Sub-figure labels, e.g. ["a","b","c"] |
image |
ndarray | Cropped figure image (numpy array) |
engine_used |
str | Engine that produced the crop: native, cv, or fallback |
list_figures() returns the same dicts without the image field.
Extension Support
Custom configurations via EXTEND.md. See Preferences section for paths and supported options.
© License & Copyright
AutSciWrite — Autonomous Scientific Writer
- Author: Shuo Zhao
- License: MIT License
- Copyright: © 2026 Shuo Zhao. All rights reserved.
- Original Work: This is an original work created by the author. No reproduction, redistribution, or commercial use without explicit permission.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software... (See the LICENSE file in the root directory for the full MIT terms.)
This skill is part of the AutSciWrite suite. For full license terms, see the [LICENSE](../LICENSE) file in the project root.