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,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.

Aut_Sci_Write — Autonomous Scientific Writer

Author: Shuo Zhao
License: MIT License
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.)

sci-figure