Sunrich-HT/figure-extractor

Compétence d'extraction de figures

Utilisez cette compétence lorsque l'utilisateur a besoin de figures ou d'images complètes extraites de PDF, d'articles arXiv ou de pages HTML.

Ce qu'est réellement cette compétence (à lire en premier)

figure-extractor est un outil en ligne de commande (Python + PyMuPDF). « L'utiliser » signifie exécuter son CLI dans un shell — par ex. figure-extractor extract paper.pdf. Ce n'est pas un appelable intégré à l'agent, un service hébergé, ni une « page » que vous activez, et il ne peut pas fonctionner dans un environnement sans shell ou sans possibilité d'installer des paquets Python (par ex. Notion Agent, agents purement navigateur).

Contrat d'invocation

• Mécanisme : commande shell figure-extractor <sous-commande> ... (installé via pip install -e .).
• Entrée : un chemin local PDF/HTML ou une URL PDF/arXiv/HTML.
• Sortie : fichiers PNG + manifest.json + contact_sheet.jpg (+ éventuellement figures.zip) écrits dans --out.

Étape 0 — vérification des prérequis (toujours à faire en premier)

Avant de promettre l'extraction de figures, vérifiez que l'outil est réellement exécutable dans cet environnement :

figure-extractor --help     # si ceci échoue, ou s'il n'y a pas de shell, l'outil est INDISPONIBLE

• Disponible (la commande s'exécute) → suivez l'algorithme préféré.
• Indisponible (pas de shell / non installé / sandboxé) → passez en mode dégradé. Ne pas disposer de l'outil n'est pas un échec ni une violation de règle — dégradez-vous gracieusement et dites à l'utilisateur ce que vous avez fait.

Règle fondamentale (quand l'extracteur est disponible)

Ne vous fiez pas uniquement à l'extraction d'images intégrées dans le PDF. De nombreuses figures sont composées de dessins vectoriels, d'étiquettes de texte, de légendes et de fragments raster. L'extraction d'images intégrées renvoie souvent des fragments incomplets — privilégiez le pipeline de détection de légende et de recadrage par rendu ci-dessous.

Algorithme préféré (nécessite un shell + le CLI)

1. Résolvez la source d'entrée :
   • PDF local
   • URL PDF
   • URL arXiv abs (/abs/ est automatiquement normalisé en /pdf/)
   • URL HTML
   • HTML local
2. Si HTML est disponible, essayez d'abord d'extraire les images originales des figures à partir de <figure>, <img>, <picture>, srcset et des attributs de chargement différé.
3. Si le HTML ne fournit pas assez de figures de haute qualité, localisez ou téléchargez le PDF.
4. Pour les PDF :
   • localisez chaque légende : Figure 2.1, Figure B.1, Extended Data Fig. 1, Supplementary Table S3, Scheme/Algorithm/Listing/Box, 图 1;
   • récupérez la grille de colonnes de la page et limitez chaque recadrage à la bande de sa légende ;
   • élargissez le boîte englobante à partir des primitives graphiques, en vous arrêtant aux autres légendes et au texte ;
   • effectuez le rendu de la page à 300 dpi et recadrez ;
   • générez les PNG, manifest.json et contact_sheet.jpg.
5. Lisez le champ status de chaque entrée dans manifest.json. Tout élément marqué suspect ou failed contient quality_reasons expliquant ce qui n'a pas fonctionné. Ne présentez pas un recadrage failed à l'utilisateur comme s'il s'agissait de la figure.
6. Si un recadrage est incorrect, corrigez-le avec crop --bbox, en partant du boîte englobante déjà enregistrée dans le manifeste.

Mode dégradé (pas de shell / CLI indisponible / bitmaps inaccessibles)

Utilisez ceci lorsque vous ne pouvez pas exécuter figure-extractor (pas de shell, pas de Python/pip, environnement sandboxé), ou lorsque vous ne pouvez rien exécuter qui récupère le bitmap réel (par ex. le HTML supprime src des <img>, les URL d'images arXiv renvoient 404, page derrière authentification). Ce chemin est explicitement autorisé et ne compte pas comme un échec de la « règle fondamentale » :

1. Liez l'original. Fournissez l'URL directe de la figure, la page source, ou le numéro de page PDF arXiv + numéro de figure afin que l'utilisateur puisse ouvrir l'image réelle.
2. Décrivez fidèlement. Donnez une lecture structurée de chaque figure à partir de sa légende + du texte environnant : ce qu'elle montre, axes/panneaux/légende, tendance clé. N'inventez jamais un contenu de figure que vous n'avez pas réellement vu.
3. Étiquetez la lacune. Indiquez clairement, par ex. : Bitmap non intégré — raison : pas de shell disponible (ou image 404, src supprimé par le désinfectant, derrière authentification).

La sortie en mode dégradé = lien original + description structurée fidèle + une note explicite sur « pourquoi le bitmap est manquant ». C'est un résultat acceptable, pas une violation.

Configuration

Un paquet manquant n'est pas une raison pour dégrader — installez-le. L'ensemble des dépendances est réduit (PyMuPDF, Pillow, beautifulsoup4) ; pas de GPU, pas de modèle, pas de service.

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

Depuis un checkout : pip install -e .

Vous avez un PDF ? Exécutez-le sur le PDF.

Si l'utilisateur a joint un PDF, ou si vous pouvez en télécharger un, c'est le chemin le plus simple et le plus fiable. Ne commencez pas par le HTML ou un navigateur.

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

Ce n'est que lorsqu'aucun PDF n'est disponible que vous devriez essayer la voie HTML. Notez que certains environnements de récupération HTML suppriment <img src>, ne laissant que le texte — lorsque cela se produit, arrêtez de travailler sur le HTML et revenez à la récupération du PDF.

Commandes

# Extraction automatique (PDF local, URL PDF, URL arXiv abs, ou article 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

# Figures uniquement, ou seulement les recadrages les plus susceptibles d'être porteurs
figure-extractor extract paper.pdf --kinds figure --tiers A,B

# Correction manuelle de boîte englobante pour une seule figure
figure-extractor crop paper.pdf --page 5 --bbox 295,245,556,475 --out fig04.png --dpi 300

Paramètres par défaut

• dpi : 300
• margin : 8 points PDF
• prefer : auto
• fallback : pdf
• kinds : all — l'extraction est exhaustive par défaut
• tiers : A,B,C — rien n'est filtré par défaut ; le niveau est un signal de triage, pas un jugement sur les éléments qui portent l'argumentation
• contact_sheet : true

Conseils de contrôle qualité

Lorsque l'extracteur a été exécuté, inspectez toujours contact_sheet.jpg et le status de chaque entrée du manifeste. Les recadrages suspect et failed sont signalés en orange et rouge sur la planche. Si une figure inclut du texte environnant ou manque une partie de la figure, relancez crop avec un boîte englobante manuelle.

Le manifeste rend compte de chaque candidat que l'outil a vu. Si containers_found dépasse ce qui a été rendu, la liste dropped indique pourquoi chacun ne l'a pas été — considérez un écart inexpliqué comme un bogue, pas comme une exécution propre.