Metadata-Version: 2.4
Name: figcrop
Version: 0.3.0
Summary: High-quality figure extraction from dense research-paper PDFs
Author: TadaLab Keio
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/tadalab-keio/figcrop
Project-URL: Repository, https://github.com/tadalab-keio/figcrop
Project-URL: Issues, https://github.com/tadalab-keio/figcrop/issues
Keywords: pdf,figures,research-papers,layout-analysis,openvino
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: LICENSES/Apache-2.0.txt
Requires-Dist: openvino>=2026.2
Requires-Dist: pymupdf>=1.27.2
Requires-Dist: numpy
Requires-Dist: pillow
Requires-Dist: shapely>=2
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: mcp>=1.0
Provides-Extra: legacy
Requires-Dist: mineru[core]<4,>=2; extra == "legacy"
Dynamic: license-file

# figcrop

Extract complete figures and subpanels from research-paper PDFs by their real
`Fig.N` numbers.

figcrop combines a bundled PP-DocLayoutV2 detector with the PDF's own text,
vector, image, and drawing objects. The detector only proposes where figures
are; figcrop assigns the underlying PDF objects to figures and panels, then
replays the selected objects in their original paint order. This is designed
for dense papers where a single detected rectangle often clips axes, tables,
legends, or neighboring panels.

## Install

For the command-line tool, `pipx` is recommended because it manages an isolated
Python environment automatically:

```powershell
pipx install figcrop
```

To install the current GitHub version instead of the latest PyPI release:

```powershell
pipx install git+https://github.com/tadalab-keio/figcrop.git
```

Regular pip installation is also supported:

```powershell
python -m pip install figcrop
```

Starting with figcrop 0.3.0, installation automatically includes OpenVINO and
the PP-DocLayoutV2 model. There is no first-run model download, OpenVINO
conversion, or separate MinerU, Torch, PaddleOCR, or PaddleX setup.

The current runtime supports Python 3.10-3.14. figcrop has no upper Python bound,
so a future Python version becomes installable when its dependencies, chiefly
OpenVINO, publish compatible wheels.

## Quick Start

Extract every numbered figure without captions:

```powershell
figcrop extract paper.pdf out
```

Common variants:

```powershell
figcrop extract paper.pdf out --figs 1,2
figcrop extract paper.pdf out_panels --mode panel
figcrop extract paper.pdf out_caption --mode caption
figcrop review paper.pdf review_out
```

Each extraction directory contains JPEG crops and a `figures.json` manifest.
Always inspect representative crops before using them in a dataset or
publication.

## Output Modes

| Mode | Output |
| --- | --- |
| `figure` | One complete figure body per `Fig.N`, without its caption. This is the default. |
| `panel` | Groups and leaf panels such as `(a)`, `(bcde)`, `(b)`, `(c)`, and so on. |
| `caption` | The complete figure together with its matched caption. |

Useful selection options:

| Option | Meaning |
| --- | --- |
| `--figs 1,2` | Extract only the listed real figure numbers. |
| `--top 3` | Positional fallback: use the first three visual regions per page. |
| `--mode MODE` | Select `figure`, `panel`, or `caption`. |
| `--debug DIR` | Write detector and ownership diagnostics. |

Legacy `figs=1,2`, `top=3`, `panels=true`, and `caption=include` forms remain
accepted.

## Visual Review

The preferred QA command runs all three modes with one loaded model:

```powershell
figcrop review paper.pdf review_out
```

It creates:

```text
review_out/
  caption/
  figure/
  panel/
  fig_montages/
  review_montage.jpg
```

Each montage row is ordered as caption, full figure, then panel groups and leaf
panels in visual hierarchy order. Tiles keep their native resolution, use
readable labels, and have no artificial borders.

To build a montage from existing extraction directories:

```powershell
figcrop montage out_figure out_panel review.jpg
```

This step only reads the JPEGs and `figures.json`; it does not need the original
PDF or layout model.

## Server and AI Use

For repeated requests, keep the detector loaded in a local server:

```powershell
figcrop serve
```

The server listens on `127.0.0.1:8077` by default and exposes OpenAPI at
`/openapi.json`.

```bash
curl -s -X POST http://127.0.0.1:8077/extract \
  -H "Content-Type: application/json" \
  -d '{"pdf":"paper.pdf","out_dir":"out","figs":[1,2],"mode":"caption"}'
```

For MCP clients, register the installed command:

```powershell
figcrop-mcp
```

Direct CLI execution is usually simpler for Claude Code and Codex; MCP is an
optional integration, not a requirement.

## Detector Backends

The default backend is the bundled PP-DocLayoutV2 OpenVINO IR:

```powershell
figcrop extract paper.pdf out auto
```

`auto`, `ov`, and `v2` select this backend. OpenVINO compiles the IR for an
available device through `AUTO`; `GPU`, `NPU`, and `CPU` can be requested
explicitly.

The smaller PP-DocLayout-S model is included as a comparison and complementary
seed backend:

```powershell
figcrop extract paper.pdf out pp-s
```

The original MinerU/Torch path is only needed to compare the source model or
reproduce the bundled V2 conversion. It is an optional development extra for
Python 3.10-3.13:

```powershell
pipx install "figcrop[legacy]"
figcrop extract paper.pdf out xpu
```

## How It Works

1. Render each page at 150 dpi and run the selected layout detector.
2. Read `Fig.N` and `Table N` captions from the PDF text layer.
3. Match visual proposals to same-column captions and run local panel detection.
4. Enumerate PDF text, vector paths, images, forms, clips, and paint geometry.
5. Assign every visible source object to one figure, group, panel, caption,
   page-furniture, external, or unresolved owner.
6. Replay only the requested ownership subtree while preserving transforms,
   clipping, transparency, masks, images, overlays, and paint order.
7. Crop the 600 dpi result to the owned objects' actual visible bounds.

Figure numbering, panel grouping, ownership, and final crop boundaries are
figcrop logic; they are not the detector's reading-order output. The current
design is documented in [`所有権論理メモ.md`](所有権論理メモ.md).

## Output and Performance

JPEG is the default codec at quality 95 with 4:4:4 chroma. This keeps 600 dpi
review sets compact and encodes substantially faster than lossless PNG for
typical papers. The source PDF is not assumed to contain JPEGs; figcrop renders
the selected PDF paint operations and then encodes the result.

One-shot extraction is usually practical for occasional use. Server mode avoids
model initialization on every request and is preferable for repeated jobs.

Native-resolution montages can expand to several GiB in memory. figcrop uses a
bounded row pipeline and up to eight workers, limited by available CPUs and job
count. Override the worker count when needed:

```powershell
$env:FIGCROP_MONTAGE_WORKERS = "4"
figcrop review paper.pdf review_out
```

## Limitations

- Dense or unusual pages can still confuse proposal-to-caption assignment.
  `--top` is available as a positional fallback.
- `panel` mode only emits figures with a coherent panel-label sequence. Figures
  without panel labels are intentionally skipped.
- Slide grids, posters, and decorative page furniture can resemble figures or
  tables. Common local-cell cases are handled, but visual review remains
  necessary.

## Development

Run the focused test suite from a source checkout:

```powershell
python -m pytest
```

`tools/export_pp_doclayout_v2.py` reproduces the bundled V2 OpenVINO IR from the
upstream model. The previous Skia/OpenGL renderer is retained under
`experiments/skia/` for development comparison but is not included in the wheel
or supported as a production backend. Production PDF replay uses MuPDF CPU.

## License

figcrop is licensed under GNU Affero General Public License v3.0 only
(`AGPL-3.0-only`). See `LICENSE`.

The bundled PP-DocLayoutV2 conversion comes from OpenDataLab's AGPL-3.0
PDF-Extract-Kit-1.0 model repository. PP-DocLayout-S and OpenVINO are
Apache-2.0. PyMuPDF is used under its AGPL-3.0 terms. See `NOTICE` and the model
README files for source revisions, hashes, reproduction details, and third-party
attribution.
