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,1200
Output:
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
Aut_Sci_Write — 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.)