Extracción de imágenes

PDF Oxide extrae imágenes de las páginas PDF analizando el flujo de contenido, resolviendo las referencias a XObject mediante operadores Do, descendiendo recursivamente en los Form XObjects anidados y decodificando las imágenes inline. Usa extract_images() para obtener objetos de imagen en memoria, o extract_images_to_files() para guardarlas directamente en disco como archivos PNG o JPEG.

Desde la v0.3.5, la extracción de imágenes procesa el flujo de contenido completo de la página en lugar de limitarse a recorrer el diccionario de XObjects. Esto maneja correctamente las imágenes colocadas mediante operadores Do, los Form XObjects anidados con detección de ciclos y las imágenes inline embebidas con secuencias BI/ID/EI.

Soporte de espacios de color

Las imágenes extraídas se decodifican y entregan en su espacio de color original, sin conversiones de ida y vuelta con pérdida:

• DeviceRGB / DeviceGray / DeviceCMYK — se devuelven tal cual.
• Indexed (1, 2, 4, 8 bits por componente) — la paleta se resuelve mediante resolve_indexed_palette y se expande con expand_indexed_to_rgb. Admite paletas Indexed basadas en espacios de color RGB, escala de grises y CMYK. Anteriormente generaba errores Invalid RGB image dimensions en muchos PDFs del mundo real.
• CalRGB / CalGray / ICCBased — se convierten a RGB durante la decodificación.

La expansión de paletas está reforzada frente a entradas maliciosas con una guarda de desbordamiento checked_mul y un límite de asignación de 256 MiB; los flujos truncados se rechazan de forma limpia en lugar de producir píxeles corruptos.

Tolerancia a imágenes malformadas

Las imágenes con entradas /ColorSpace ausentes, dimensiones cero o flujos inválidos se omiten con una advertencia: ya no provocan un panic en el renderizado de la página. La misma tolerancia se aplica a las imágenes malformadas anidadas dentro de Form XObjects.

Ejemplo rápido

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("report.pdf")
images = doc.extract_image_bytes(0)
for img in images:
    print(f"{img['width']}x{img['height']}")

Node.js

const { PdfDocument } = require("pdf-oxide");

const doc = new PdfDocument("report.pdf");
const images = doc.getEmbeddedImages(0);
for (const img of images) {
    console.log(`${img.width}x${img.height}`);
}

Go

import pdfoxide "github.com/yfedoseev/pdf_oxide/go"

doc, _ := pdfoxide.Open("report.pdf")
defer doc.Close()
images, _ := doc.Images(0)
for _, img := range images {
    fmt.Printf("%dx%d\n", img.Width, img.Height)
}

C#

using PdfOxide.Core;

using var doc = PdfDocument.Open("report.pdf");
var images = doc.ExtractImages(0);
foreach (var img in images)
{
    Console.WriteLine($"{img.Width}x{img.Height}");
}

WASM

const doc = new WasmPdfDocument(bytes);
const images = doc.extractImages(0);
for (const img of images) {
    console.log(`${img.width}x${img.height}`);
}

Rust

use pdf_oxide::PdfDocument;

let mut doc = PdfDocument::open("report.pdf")?;
let images = doc.extract_images(0)?;
for img in &images {
    println!("{}x{} {:?}", img.width(), img.height(), img.color_space());
}

---

Referencia de API

extract_images(page_index) -> Vec<PdfImage>

Extrae todas las imágenes de una página. Analiza el flujo de contenido de la página para encontrar:

1. Imágenes XObject referenciadas mediante operadores Do
2. Form XObjects que contienen imágenes anidadas (recursivo, con detección de ciclos)
3. Imágenes inline embebidas con secuencias BI/ID/EI

El seguimiento de la CTM (Current Transformation Matrix) proporciona los bounding boxes de cada imagen.

Parámetro	Tipo	Descripción
page_index	int / usize	Índice de página de base cero

Devuelve: Un vector de objetos PdfImage.

Campos y métodos de PdfImage

Método / Campo	Tipo	Descripción
width()	u32	Ancho de la imagen en píxeles
height()	u32	Alto de la imagen en píxeles
color_space()	&ColorSpace	Espacio de color (DeviceRGB, DeviceGray, DeviceCMYK, etc.)
bits_per_component()	u8	Bits por componente de color (normalmente 8)
data()	&ImageData	Datos de imagen sin procesar (bytes JPEG o píxeles crudos)
bbox()	Option<&Rect>	Bounding box en el espacio de usuario del PDF (si se rastreó la CTM)
save_as_png(path)	Result<()>	Guarda la imagen como archivo PNG
save_as_jpeg(path)	Result<()>	Guarda la imagen como archivo JPEG
to_png_bytes()	Result<Vec<u8>>	Codifica como bytes PNG en memoria
to_jpeg_bytes()	Result<Vec<u8>>	Codifica como bytes JPEG en memoria

Variantes de ColorSpace

Variante	Descripción
DeviceRGB	RGB de 3 canales
DeviceGray	Escala de grises de un solo canal
DeviceCMYK	CMYK de 4 canales
Indexed	Color basado en paleta
ICCBased	Color basado en perfil ICC
CalGray	Escala de grises calibrada
CalRGB	RGB calibrado
Lab	Color CIE Lab*

Variantes de ImageData

Variante	Descripción
Jpeg(Vec<u8>)	Datos comprimidos JPEG (paso directo DCT)
Raw { pixels, format }	Datos de píxeles decodificados con PixelFormat (RGB, Gray, CMYK, RGBA)

Rust

let mut doc = PdfDocument::open("report.pdf")?;
let images = doc.extract_images(0)?;

for (i, image) in images.iter().enumerate() {
    println!(
        "Image {}: {}x{} {:?} {}bpc",
        i, image.width(), image.height(),
        image.color_space(), image.bits_per_component(),
    );

    if let Some(bbox) = image.bbox() {
        println!("  Position: ({:.1}, {:.1})", bbox.x, bbox.y);
    }

    image.save_as_png(&format!("output/image_{}.png", i))?;
}

---

extract_images_to_files(page_index, output_dir, prefix, start_index) -> Vec<ExtractedImageRef>

Extrae las imágenes de una página y las guarda directamente en archivos. Las imágenes JPEG se guardan en su formato original (sin pérdida por recodificación); el resto de las imágenes se guardan como PNG.

Parámetro	Tipo	Por defecto	Descripción
page_index	usize	–	Índice de página de base cero
output_dir	impl AsRef<Path>	–	Directorio donde guardar las imágenes (se crea si no existe)
prefix	Option<&str>	"img"	Prefijo del nombre de archivo
start_index	Option<usize>	1	Índice inicial para los nombres de archivo

Devuelve: Un vector de ExtractedImageRef que describe los archivos guardados.

Campos de ExtractedImageRef

Campo	Tipo	Descripción
filename	String	Nombre de archivo guardado (p. ej., "img_001.png")
format	ImageFormat	Png o Jpeg
width	u32	Ancho de la imagen en píxeles
height	u32	Alto de la imagen en píxeles

Rust

let mut doc = PdfDocument::open("report.pdf")?;
let refs = doc.extract_images_to_files(0, "output/images", Some("fig"), Some(1))?;

for img_ref in &refs {
    println!("Saved: {} ({}x{}, {:?})", img_ref.filename, img_ref.width, img_ref.height, img_ref.format);
}

---

Ejemplos avanzados

Extraer todas las imágenes de todas las páginas

use pdf_oxide::PdfDocument;
use std::path::Path;

let mut doc = PdfDocument::open("book.pdf")?;
let page_count = doc.page_count()?;
let mut total = 0;

for page in 0..page_count {
    let refs = doc.extract_images_to_files(
        page,
        "output/images",
        Some(&format!("page{}", page + 1)),
        Some(1),
    )?;
    total += refs.len();
    println!("Page {}: {} images", page + 1, refs.len());
}
println!("Total: {} images extracted", total);

Obtener los bytes de la imagen en memoria (sin E/S de disco)

let mut doc = PdfDocument::open("report.pdf")?;
let images = doc.extract_images(0)?;

for image in &images {
    let png_bytes = image.to_png_bytes()?;
    println!("PNG size: {} bytes", png_bytes.len());

    // Use png_bytes with an HTTP response, database, etc.
}

Filtrar imágenes por tamaño

let mut doc = PdfDocument::open("report.pdf")?;
let images = doc.extract_images(0)?;

// Only keep images larger than 100x100 pixels
let large_images: Vec<_> = images.iter()
    .filter(|img| img.width() > 100 && img.height() > 100)
    .collect();

println!("{} large images on page 1", large_images.len());
for img in &large_images {
    println!("  {}x{} {:?}", img.width(), img.height(), img.color_space());
}

Distinguir el paso directo de JPEG de las imágenes recodificadas

use pdf_oxide::extractors::ImageData;

let mut doc = PdfDocument::open("report.pdf")?;
let images = doc.extract_images(0)?;

for (i, image) in images.iter().enumerate() {
    match image.data() {
        ImageData::Jpeg(bytes) => {
            // Original JPEG data -- save directly for zero quality loss
            std::fs::write(format!("image_{}.jpg", i), bytes)?;
            println!("Image {}: JPEG pass-through ({} bytes)", i, bytes.len());
        }
        ImageData::Raw { pixels, format } => {
            // Raw pixels -- must encode to a file format
            image.save_as_png(&format!("image_{}.png", i))?;
            println!("Image {}: raw {:?} ({}x{})", i, format, image.width(), image.height());
        }
    }
}

---

Páginas relacionadas

• Extracción de texto – Extrae texto junto con las imágenes
• Conversión a HTML – Embebe las imágenes extraídas en la salida HTML
• Conversión a Markdown – Incluye imágenes en la salida Markdown