sci-figure

# 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)](https://pymupdf.readthedocs.io/), which is AGPL-licensed. ## Installation Install the package from the skill directory before first use: ```bash 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): ```bash # 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 ```bash 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 ```bash # 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.**) --- *This skill is part of the Aut_Sci_Write suite. For full license terms, see the [LICENSE](../LICENSE) file in the project root.* ---