📎 Stop screenshotting paper figures by hand. Extract figures, tables, and captions from research PDFs in one command.
The demo above uses a real WWW 2025 paper provided by the project author, showing actual CaptionCrop output rather than hand-made mockups.
CaptionCrop turns an academic paper into a folder of reusable visual assets:
p07_fig_5.pngp07_table_2.pngmetadata.json- optional
contact_sheet.png
It is built for the boring but painful job every researcher, engineer, analyst, and slide-maker eventually faces:
"I need the figures and tables from this PDF, cleanly cropped, with captions, without manually screenshotting every page."
Use it when you are building paper-reading workflows, literature-review notes, RAG datasets, slide decks, research reports, or agent pipelines that need visual evidence from PDFs instead of raw text alone.
CaptionCrop writes individual crops and an optional contact sheet for fast review. The preview grid below is built from real crops generated from WWW25_1202_rfp.pdf.
Most PDF tools extract text. Some extract embedded images. Academic figures are messier:
- many figures are vector drawings, not embedded images
- tables are text and lines, not screenshots
- captions may be above or below the artifact
- single-column papers may place narrow captions under wider figures
- two-column papers place figures, tables, and body text tightly together
- page headers and neighboring plots often sneak into manual crops
CaptionCrop uses caption detection plus PDF layout geometry to crop the visual region and its caption together.
This is a P1 release: useful today for single-column papers and IEEE/ACM/NDSS-style two-column papers, with explicit metadata and visual review support.
It is not trying to be perfect OCR, document understanding, or a full paper-reading system. It is a focused CLI for converting paper PDFs into figure/table image assets.
git clone https://github.com/2654400439/CaptionCrop.git
cd CaptionCrop
python -m pip install -r requirements.txtPython 3.10+ is recommended.
If you want an AI coding agent to use CaptionCrop for you, give the agent this command and ask it to fetch and follow the skill instructions:
curl -L https://raw.githubusercontent.com/2654400439/CaptionCrop/main/skill.mdThe skill file explains when to use CaptionCrop, how to install it, which CLI command to run, how to inspect metadata.json, and how to report extraction results back to the user.
python caption_crop.py paper.pdf -o output --dpi 240 --clean --contact-sheetOutput:
output/
p01_fig_1.png
p05_table_1.png
p07_fig_5.png
metadata.json
contact_sheet.png
metadata.json contains the page number, caption text, caption bounding box, crop bounding box, and output file for each extracted artifact.
python caption_crop.py PDF -o OUTPUT_DIR [--dpi 240] [--clean] [--contact-sheet]Options:
PDF: input academic PDF.-o, --output-dir: output folder.--dpi: crop render resolution. Default:220.--clean: remove previous PNG crops and metadata in the output folder before extracting.--contact-sheet: createcontact_sheet.pngfor quick visual review.--sheet-cols: number of columns in the contact sheet. Default:3.
CaptionCrop currently detects common academic caption styles:
Fig. 1. ...Figure 1: ...TABLE I ...Table 1: ...
It then estimates whether the artifact is single-column or page-wide, finds nearby visual/table content, filters body text and running headers, and renders the selected crop.
Local smoke tests across three security research papers:
| Paper style | Pages | Figures | Tables | Total extracted | Notes |
|---|---|---|---|---|---|
| IEEE-style APT detection paper | 9 | 7 | 3 | 10 | Handles two-column figures and compact tables |
| NDSS-style agent security paper | 23 | 17 | 9 | 26 | Handles dense same-page figure/table layouts |
| ACM WWW-style website fingerprinting paper | 15 | 14 | 8 | 22 | Handles ACM running headers and Figure N: captions |
| Single-column Web QoS/privacy paper | 15 | 6 | 4 | 10 | Handles single-column figures with narrow captions and full-width tables |
Total observed coverage in these smoke tests: 68/68 expected figure/table captions detected.
See benchmarks/RESULTS.md for details and caveats.
CaptionCrop is layout-heuristic based. It can still need review when:
- figures span pages
- captions are far away from the artifact
- subfigures need separate crops
- a table continues across pages
- a PDF has unusual fonts, broken text extraction, or scanned pages
- the intended crop should exclude the caption
The intended workflow is: run CaptionCrop, open contact_sheet.png, then optionally adjust a few crops.
The current release is P1. Planned P2 work:
- human-review JSON for manual crop adjustment
- rerender from adjusted metadata without re-detecting
- better subfigure splitting
- scanned-PDF OCR fallback
- optional HTML review UI
See docs/ROADMAP.md.
MIT.