Sunrich-HT/figure-extractor

Figure Extractor 스킬

사용자가 PDF, arXiv 논문 또는 HTML 문서 페이지에서 완전한 그림이나 이미지를 추출해야 할 때 이 스킬을 사용하세요.

이 스킬의 실제 정체 (먼저 읽어주세요)

figure-extractor는 명령줄 도구(Python + PyMuPDF)입니다. "사용한다"는 것은 셸에서 CLI를 실행하는 것을 의미합니다. 예: figure-extractor extract paper.pdf. 인-에이전트 호출 가능 도구나 호스팅 서비스, 활성화하는 "페이지"가 아니며, 셸이 없거나 Python 패키지를 설치할 수 없는 런타임(예: Notion Agent, 브라우저 전용 에이전트)에서는 실행할 수 없습니다.

호출 계약

• 메커니즘: 셸 명령어 figure-extractor <하위명령> ... (pip install -e .로 설치).
• 입력: 로컬 PDF/HTML 경로 또는 PDF/arXiv/HTML URL.
• 출력: PNG 파일 + manifest.json + contact_sheet.jpg (+ 선택적 figures.zip)를 --out 디렉터리에 기록.

0단계 — 전제 조건 확인 (항상 먼저 수행)

그림 추출을 약속하기 전에, 이 환경에서 도구가 실제로 실행 가능한지 확인하세요:

figure-extractor --help     # 오류가 발생하거나 셸이 없으면 도구를 사용할 수 없음

• 사용 가능 (명령어 실행됨) → 선호 알고리즘을 따르세요.
• 사용 불가 (셸 없음 / 설치되지 않음 / 샌드박스됨) → 대체 모드로 이동하세요. 도구가 없는 것은 실패도 아니고 규칙 위반도 아닙니다. 우아하게 대체하고 사용자에게 무엇을 했는지 알려주세요.

핵심 규칙 (추출기를 사용할 수 있는 경우)

임베디드 PDF 이미지 추출에만 의존하지 마세요. 많은 그림이 벡터 드로잉, 텍스트 레이블, 범례 및 래스터 조각으로 구성됩니다. 임베디드 이미지 추출은 종종 불완전한 조각을 반환합니다. 아래의 캡션-경계상자 렌더-크롭 파이프라인을 선호하세요.

선호 알고리즘 (셸 + CLI 필요)

1. 입력 소스를 확인:
   • 로컬 PDF
   • PDF URL
   • arXiv abs URL (/abs/는 자동으로 /pdf/로 정규화)
   • HTML URL
   • 로컬 HTML
2. HTML을 사용할 수 있는 경우, 먼저 <figure>, <img>, <picture>, srcset, 지연 로딩 속성에서 원본 그림 이미지를 추출합니다.
3. HTML이 충분한 고품질 그림을 제공하지 못하면 PDF를 찾거나 다운로드합니다.
4. PDF의 경우:
   • 모든 캡션 찾기: Figure 2.1, Figure B.1, Extended Data Fig. 1, Supplementary Table S3, Scheme/Algorithm/Listing/Box, 图 1;
   • 페이지의 컬럼 그리드를 복구하고 각 크롭을 해당 캡션의 대역으로 제한;
   • 그래픽 프리미티브에서 경계 상자를 확장하고, 다른 캡션과 본문에서 멈춤;
   • 페이지를 300dpi로 렌더링하고 크롭;
   • PNG, manifest.json, contact_sheet.jpg 생성.
5. manifest.json의 모든 항목에서 status 필드를 읽으세요. suspect 또는 failed로 표시된 항목에는 문제가 무엇인지 설명하는 quality_reasons가 포함되어 있습니다. failed 크롭을 마치 그림인 것처럼 사용자에게 제시하지 마세요.
6. 크롭이 잘못된 경우, 매니페스트에 이미 기록된 경계 상자에서 시작하여 crop --bbox로 수정하세요.

대체 모드 (셸 / CLI 사용 불가 / 비트맵 접근 불가)

figure-extractor를 실행할 수 없는 경우(셸 없음, Python/pip 없음, 샌드박스 런타임), 또는 실제 비트맵을 검색할 수 있는 아무것도 실행할 수 없는 경우(예: HTML이 <img> src를 제거, arXiv 이미지 URL 404, 페이지 인증 필요) 사용하세요. 이 경로는 명시적으로 허용되며 "핵심 규칙" 위반으로 간주되지 않습니다:

1. 원본에 링크. 직접 그림 URL, 소스 페이지, 또는 arXiv PDF 페이지 번호 + 그림 번호를 제공하여 사용자가 실제 이미지를 열 수 있도록 하세요.
2. 충실히 설명. 각 그림에 대해 캡션과 주변 텍스트를 바탕으로 구조화된 읽기를 제공하세요: 무엇을 보여주는지, 축/패널/범례, 주요 추세. 실제로 볼 수 없었던 그림 내용을 절대 지어내지 마세요.
3. 격차를 표시. 예를 들어 명확히 명시하세요: 비트맵이 포함되지 않음 — 이유: 셸 사용 불가 (또는 이미지 404, 소스가 살균기에 의해 제거됨, 인증 필요).

대체 출력 = 원본 링크 + 충실한 구조화된 설명 + "비트맵이 누락된 이유"에 대한 명시적 메모. 이는 수용 가능한 결과이며 위반이 아닙니다.

설정

누락된 패키지는 대체 모드로 전환할 이유가 아닙니다. 설치하세요. 종속성 세트는 작습니다(PyMuPDF, Pillow, beautifulsoup4). GPU, 모델, 서비스가 필요 없습니다.

pip install git+https://github.com/Sunrich-HT/figure-extractor

체크아웃에서: pip install -e .

PDF가 있나요? PDF에서 실행하세요.

사용자가 PDF를 첨부했거나 다운로드할 수 있다면, 그것이 가장 간단하고 신뢰할 수 있는 경로입니다. HTML이나 브라우저부터 시작하지 마세요.

figure-extractor extract <pdf-경로> --out ./figures --dpi 300 --zip

PDF를 얻을 수 없는 경우에만 HTML 경로를 시도하세요. 일부 환경의 HTML 가져오기 도구는 <img src>를 제거하여 텍스트만 남깁니다. 그런 경우 HTML 작업을 중단하고 PDF를 가져오는 쪽으로 돌아가세요.

명령어

# 자동 추출 (로컬 PDF, PDF URL, arXiv abs URL, 또는 HTML 문서)
figure-extractor extract paper.pdf --out ./figures --dpi 300 --zip
figure-extractor extract https://arxiv.org/abs/2606.23443 --out ./figures --zip
figure-extractor extract https://openreview.net/forum?id=XXXX --out ./figures
figure-extractor extract https://example.com/article --prefer html --fallback pdf

# 그림만, 또는 가장 중요한 크롭만
figure-extractor extract paper.pdf --kinds figure --tiers A,B

# 단일 그림에 대한 수동 경계 상자 수정
figure-extractor crop paper.pdf --page 5 --bbox 295,245,556,475 --out fig04.png --dpi 300

기본 설정

• dpi: 300
• margin: 8 PDF 포인트
• prefer: auto
• fallback: pdf
• kinds: all — 기본적으로 전체 추출
• tiers: A,B,C — 기본적으로 필터링 없음; 계층은 분류 신호일 뿐, 어떤 전시물이 논증을 전달하는지에 대한 판단이 아님
• contact_sheet: true

품질 관리 지침

추출기가 실행된 경우, 항상 contact_sheet.jpg 와 각 매니페스트 항목의 status를 검사하세요. suspect 및 failed 크롭은 시트에서 주황색과 빨간색으로 표시됩니다. 그림에 주변 본문 텍스트가 포함되거나 그림의 일부가 누락된 경우, 수동 경계 상자로 crop을 다시 실행하세요.

매니페스트는 도구가 본 모든 후보를 설명합니다. containers_found가 렌더링된 것보다 많으면 dropped 목록이 각각이 포함되지 않은 이유를 설명합니다. 설명되지 않은 차이는 버그로 간주하세요. 깨끗한 실행으로 취급하지 마세요.