Figure Extractor – Fähigkeit zum Extrahieren von Abbildungen

Figure Extractor – Fähigkeit

Verwende diese Fähigkeit, wenn der Benutzer vollständige Abbildungen oder Bilder aus PDFs, arXiv-Artikeln oder HTML-Artikeleseiten benötigt.

Was diese Fähigkeit tatsächlich ist (zuerst lesen)

figure-extractor ist ein Kommandozeilenwerkzeug (Python + PyMuPDF). „Es verwenden“ bedeutet, seine CLI in einer Shell auszuführen – z.B. figure-extractor extract paper.pdf. Es ist kein im Agenten aufrufbares Tool, kein gehosteter Dienst oder eine „Seite“, die aktiviert wird, und es kann nicht in einer Laufzeitumgebung ausgeführt werden, die keine Shell hat oder keine Python-Pakete installieren kann (z.B. Notion Agent, reine Browser-Agenten).

Aufrufvertrag

• Mechanismus: Shell-Befehl figure-extractor <Unterbefehl> ... (installiert über pip install -e .).
• Eingabe: ein lokaler PDF-/HTML-Pfad oder eine PDF-/arXiv-/HTML-URL.
• Ausgabe: PNG-Dateien + manifest.json + contact_sheet.jpg (+ optional figures.zip) geschrieben nach --out.

Schritt 0 – Voraussetzungsprüfung (immer zuerst durchführen)

Bevor du die Figurenextraktion zusagst, überprüfe, ob das Werkzeug in dieser Umgebung tatsächlich ausführbar ist:

figure-extractor --help     # falls dies einen Fehler ergibt oder es keine Shell gibt, ist das Werkzeug NICHT VERFÜGBAR

• Verfügbar (Befehl wird ausgeführt) → befolge den Bevorzugten Algorithmus.
• Nicht verfügbar (keine Shell / nicht installiert / Sandbox) → wechsle in den Degraded Mode. Das Fehlen des Werkzeugs ist kein Fehler und keine Regelverletzung – degradiere elegant und teile dem Benutzer mit, was du getan hast.

Kernregel (wenn der Extraktor verfügbar ist)

Verlasse dich nicht allein auf die Extraktion eingebetteter PDF-Bilder. Viele Abbildungen bestehen aus Vektorgrafiken, Textbeschriftungen, Legenden und Rasterfragmenten. Die Extraktion eingebetteter Bilder liefert oft unvollständige Fragmente – bevorzuge die untenstehende Caption-BBox-Render-Crop-Pipeline.

Bevorzugter Algorithmus (erfordert eine Shell + die CLI)

1. Bestimme die Eingabequelle:
   • lokales PDF
   • PDF-URL
   • arXiv-URL (/abs/ wird automatisch zu /pdf/ normalisiert)
   • HTML-URL
   • lokale HTML-Datei
2. Falls HTML verfügbar ist, versuche zunächst, originale Abbildungsbilder aus <figure>, <img>, <picture>, srcset und lazy-load-Attributen zu extrahieren.
3. Falls HTML nicht genügend hochwertige Abbildungen liefert, lokalisiere oder lade das PDF herunter.
4. Für PDFs:
   • finde jede Bildunterschrift: Figure 2.1, Figure B.1, Extended Data Fig. 1, Supplementary Table S3, Scheme/Algorithm/Listing/Box, 图 1;
   • stelle das Seiten-Spaltenraster wieder her und beschränke jeden Zuschnitt auf den Band der Bildunterschrift;
   • vergrößere die Bounding Box ausgehend von grafischen Primitiven, stoppe bei anderen Bildunterschriften und Fließtext;
   • rendere die Seite mit 300 dpi und schneide zu;
   • erzeuge PNGs, manifest.json und contact_sheet.jpg.
5. Lies das status-Feld jedes Eintrags in manifest.json. Alles, was als suspect oder failed markiert ist, enthält quality_reasons, die erklären, was schiefgelaufen ist. Präsentiere dem Benutzer keinen failed-Zuschnitt, als wäre es die Abbildung.
6. Falls ein Zuschnitt falsch ist, korrigiere ihn mit crop --bbox, ausgehend von der BBox, die das Manifest bereits aufgezeichnet hat.

Degraded Mode (keine Shell / CLI nicht verfügbar / Bitmaps nicht erreichbar)

Verwende diesen, wenn du figure-extractor**nicht** ausführen kannst (keine Shell, kein Python/pip, Sandbox-Laufzeit) **oder** wenn du nichts ausführen kannst, das das tatsächliche Bitmap abruft (z.B. HTML entfernt -src`-Attribute, arXiv-Bild-URLs 404, Seite hinter Authentifizierung). Dieser Pfad ist explizit erlaubt und gilt nicht als Verstoß gegen die „Kernregel“:

1. Verlinke das Original. Gib die direkte Abbildungs-URL, die Quellseite oder die arXiv-PDF-Seitennummer + Abbildungsnummer an, damit der Benutzer das echte Bild öffnen kann.
2. Beschreibe getreu. Liefere eine strukturierte Wiedergabe jeder Abbildung anhand ihrer Bildunterschrift und des umgebenden Textes: was sie zeigt, Achsen/Teilbilder/Legende, wichtiger Trend. Erfinde niemals Abbildungsinhalte, die du nicht tatsächlich sehen konntest.
3. Kennzeichne die Lücke. Gib deutlich an, z.B.: Bitmap nicht eingebettet – Grund: keine Shell verfügbar (oder Bild 404, src durch Bereinigung entfernt, zugriffsgeschützt).

Degraded-Output = Original-Link + getreue strukturierte Beschreibung + ein expliziter Hinweis, warum das Bitmap fehlt. Das ist ein akzeptables Ergebnis, kein Verstoß.

Einrichtung

Ein fehlendes Paket ist kein Grund zu degradieren – installiere es. Der Abhängigkeitssatz ist klein (PyMuPDF, Pillow, beautifulsoup4); keine GPU, kein Modell, kein Dienst.

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

Aus einem Checkout: pip install -e .

Hast du ein PDF? Führe es auf dem PDF aus.

Wenn der Benutzer ein PDF angehängt hat oder du eines herunterladen kannst, ist das der einfachste und zuverlässigste Pfad. Beginne nicht mit HTML oder einem Browser.

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

Nur wenn kein PDF erhältlich ist, solltest du den HTML-Pfad versuchen. Beachte, dass einige HTML-Abrufer in bestimmten Umgebungen <img src> entfernen und nur Text übriglassen – wenn das passiert, höre auf, mit dem HTML zu arbeiten, und versuche erneut, das PDF zu beschaffen.

Befehle

# Automatische Extraktion (lokales PDF, PDF-URL, arXiv-URL oder HTML-Artikel)
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

# Nur Abbildungen oder nur die wahrscheinlich tragenden Zuschnitte
figure-extractor extract paper.pdf --kinds figure --tiers A,B

# Manuelle BBox-Korrektur für eine einzelne Abbildung
figure-extractor crop paper.pdf --page 5 --bbox 295,245,556,475 --out fig04.png --dpi 300

Standardeinstellungen

• dpi: 300
• margin: 8 PDF-Punkte
• prefer: auto
• fallback: pdf
• kinds: all – Extraktion ist standardmäßig erschöpfend
• tiers: A,B,C – standardmäßig wird nichts gefiltert; die Stufe ist ein Triage-Signal, kein Urteil darüber, welche Exponate das Argument tragen
• contact_sheet: true

Qualitätskontrolle

Wenn der Extraktor ausgeführt wurde, überprüfe immer contact_sheet.jpg und den status jedes Manifesteintrags. suspect- und failed-Zuschnitte sind auf dem Bogen orange und rot markiert. Wenn eine Abbildung umgebenden Text enthält oder Teile der Abbildung fehlen, führe crop mit einer manuellen BBox erneut aus.

Das Manifest erfasst jeden Kandidaten, den das Werkzeug gesehen hat. Falls containers_found die Anzahl der gerenderten übersteigt, erklärt die dropped-Liste, warum jeder nicht gerendert wurde – behandle eine unerklärte Lücke als Fehler, nicht als sauberen Lauf.