Sunrich-HT/figure-extractor

Habilidad de Extractor de Figuras

Utiliza esta habilidad cuando el usuario necesite figuras o imágenes completas extraídas de PDFs, artículos de arXiv o páginas de artículos HTML.

Qué es realmente esta habilidad (lee primero)

figure-extractor es una herramienta de línea de comandos (Python + PyMuPDF). "Usarla" significa ejecutar su CLI en una terminal — por ejemplo figure-extractor extract paper.pdf. No es un invocable dentro del agente, un servicio alojado, ni una "página" que actives, y no puede ejecutarse dentro de un runtime que no tenga terminal o no pueda instalar paquetes de Python (por ejemplo, Notion Agent, agentes solo de navegador).

Contrato de invocación

• Mecanismo: comando de shell figure-extractor <subcomando> ... (instalado mediante pip install -e .).
• Entrada: una ruta local de PDF/HTML o una URL de PDF/arXiv/HTML.
• Salida: archivos PNG + manifest.json + contact_sheet.jpg (+ figures.zip opcional) escritos en --out.

Paso 0 — verificación de requisitos previos (hazlo siempre primero)

Antes de prometer la extracción de figuras, verifica que la herramienta se pueda ejecutar realmente en este entorno:

figure-extractor --help     # Si esto da error, o no hay shell, la herramienta NO ESTÁ DISPONIBLE

• Disponible (el comando funciona) → sigue el Algoritmo preferido.
• No disponible (sin shell / no instalado / en entorno aislado) → ve al Modo degradado. No tener la herramienta no es un fallo ni una violación de reglas: degrada con elegancia e informa al usuario de lo que hiciste.

Regla principal (cuando el extractor está disponible)

No te bases solo en la extracción de imágenes incrustadas en PDF. Muchas figuras están compuestas por dibujos vectoriales, etiquetas de texto, leyendas y fragmentos rasterizados. La extracción de imágenes incrustadas a menudo devuelve fragmentos incompletos — prefiere el siguiente proceso de recorte basado en detección de subtítulos y renderizado.

Algoritmo preferido (requiere una terminal + la CLI)

1. Resuelve la fuente de entrada:
   • PDF local
   • URL de PDF
   • URL de resumen de arXiv (/abs/ se normaliza automáticamente a /pdf/)
   • URL HTML
   • HTML local
2. Si hay HTML disponible, primero intenta extraer las imágenes originales de figuras de los elementos <figure>, <img>, <picture>, srcset y atributos de carga diferida.
3. Si el HTML no proporciona suficientes figuras de alta calidad, localiza o descarga el PDF.
4. Para PDFs:
   • localiza cada subtítulo: Figure 2.1, Figure B.1, Extended Data Fig. 1, Supplementary Table S3, Scheme/Algorithm/Listing/Box, 图 1;
   • recupera la rejilla de columnas de la página y limita cada recorte a la banda de su subtítulo;
   • expande el cuadro delimitador (bbox) a partir de primitivas gráficas, deteniéndote en otros subtítulos y texto en prosa;
   • renderiza la página a 300 DPI y recorta;
   • genera PNGs, manifest.json y contact_sheet.jpg.
5. Lee el campo status de cada entrada en manifest.json. Cualquier cosa marcada como suspect o failed contiene quality_reasons que explican qué salió mal. No presentes un recorte failed al usuario como si fuera la figura.
6. Si un recorte es incorrecto, corrígelo con crop --bbox, partiendo del bbox que el manifiesto ya registró.

Modo degradado (sin shell / CLI no disponible / mapas de bits inaccesibles)

Usa esto cuando no puedas ejecutar figure-extractor (sin shell, sin Python/pip, runtime aislado), o cuando no puedas ejecutar nada que recupere el mapa de bits real (por ejemplo, el HTML elimina <img> src, las URLs de imágenes de arXiv devuelven 404, página detrás de autenticación). Este camino está explícitamente permitido y no cuenta como incumplimiento de la "regla principal":

1. Enlaza el original. Proporciona la URL directa de la figura, la página de origen o el número de página del PDF de arXiv + el número de figura para que el usuario pueda abrir la imagen real.
2. Describe fielmente. Da una lectura estructurada de cada figura a partir de su subtítulo + texto circundante: qué muestra, ejes/paneles/leyenda, tendencia clave. Nunca inventes contenido de figuras que no hayas podido ver realmente.
3. Etiqueta la brecha. Indica claramente, por ejemplo: Mapa de bits no incrustado — motivo: no hay shell disponible (o imagen 404, src eliminado por el saneador, restringido por autenticación).

La salida degradada = enlace original + descripción estructurada fiel + una nota explícita de "por qué falta el mapa de bits". Eso es un resultado aceptable, no una violación.

Configuración

Un paquete faltante no es motivo para degradar — instálalo. El conjunto de dependencias es pequeño (PyMuPDF, Pillow, beautifulsoup4); sin GPU, sin modelo, sin servicio.

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

Desde un clon del repositorio: pip install -e .

¿Tienes un PDF? Ejecútalo sobre el PDF.

Si el usuario adjuntó un PDF, o puedes descargar uno, ese es el camino más simple y confiable. No empieces con HTML o un navegador.

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

Solo cuando no se pueda obtener ningún PDF, prueba la ruta HTML. Ten en cuenta que algunos entornos de obtención de HTML eliminan <img src>, dejando solo texto — cuando eso ocurra, deja de trabajar con el HTML y vuelve a obtener el PDF.

Comandos

# Extracción automática (PDF local, URL de PDF, URL de resumen de arXiv o artículo 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

# Solo figuras, o solo los recortes más probablemente importantes
figure-extractor extract paper.pdf --kinds figure --tiers A,B

# Corrección manual de bbox para una sola figura
figure-extractor crop paper.pdf --page 5 --bbox 295,245,556,475 --out fig04.png --dpi 300

Configuración por defecto

• dpi: 300
• margin: 8 puntos PDF
• prefer: auto
• fallback: pdf
• kinds: all — la extracción es exhaustiva por defecto
• tiers: A,B,C — nada filtrado por defecto; el nivel es una señal de triaje, no un juicio sobre qué elementos sustentan el argumento
• contact_sheet: true

Guía de control de calidad

Cuando el extractor se haya ejecutado, inspecciona siempre contact_sheet.jpg y el status de cada entrada del manifiesto. Los recortes suspect y failed se marcan en naranja y rojo en la hoja. Si una figura incluye texto circundante del cuerpo o falta parte de la figura, vuelve a ejecutar crop con un bbox manual.

El manifiesto da cuenta de cada candidato que la herramienta vio. Si containers_found supera lo que se renderizó, la lista dropped explica por qué cada uno no se procesó — trata un vacío no explicado como un error, no como una ejecución limpia.