Extração de imagens

O PDF Oxide extrai imagens das páginas de um PDF analisando o fluxo de conteúdo, resolvendo referências a XObjects por meio de operadores Do, percorrendo recursivamente Form XObjects aninhados e decodificando imagens inline. Use extract_images() para obter os objetos de imagem em memória ou extract_images_to_files() para salvá-los diretamente em disco como arquivos PNG ou JPEG.

Desde a v0.3.5, a extração de imagens processa o fluxo de conteúdo completo da página em vez de apenas varrer o dicionário de XObjects. Isso trata corretamente imagens posicionadas por operadores Do, Form XObjects aninhados com detecção de ciclos e imagens inline embutidas com sequências BI/ID/EI.

Suporte a espaços de cor

As imagens extraídas são decodificadas e entregues em seu espaço de cor original — sem conversões com perda:

• DeviceRGB / DeviceGray / DeviceCMYK — retornadas como estão.
• Indexed (1, 2, 4, 8 bits por componente) — a paleta é resolvida por resolve_indexed_palette e expandida por expand_indexed_to_rgb. Suporta paletas Indexed construídas sobre os espaços de cor base RGB, Grayscale e CMYK. Anteriormente, gerava erros Invalid RGB image dimensions em muitos PDFs do mundo real.
• CalRGB / CalGray / ICCBased — convertidas para RGB durante a decodificação.

A expansão de paleta é protegida contra entradas maliciosas com uma verificação de overflow checked_mul e um limite de alocação de 256 MiB; fluxos truncados são rejeitados de forma limpa em vez de produzir pixels corrompidos.

Tolerância a imagens malformadas

Imagens com entradas /ColorSpace ausentes, dimensões zero ou fluxos inválidos são ignoradas com um aviso — elas não causam mais panic na renderização da página. A mesma tolerância se aplica a imagens malformadas aninhadas dentro de Form XObjects.

Exemplo 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());
}

---

Referência de API

extract_images(page_index) -> Vec<PdfImage>

Extrai todas as imagens de uma página. Analisa o fluxo de conteúdo da página para encontrar:

1. Imagens XObject referenciadas por operadores Do
2. Form XObjects contendo imagens aninhadas (recursivo, com detecção de ciclos)
3. Imagens inline embutidas com sequências BI/ID/EI

O rastreamento da CTM (Current Transformation Matrix) fornece bounding boxes para cada imagem.

Parâmetro	Tipo	Descrição
page_index	int / usize	Índice de página com base zero

Retorna: um vetor de objetos PdfImage.

Campos e métodos de PdfImage

Método / Campo	Tipo	Descrição
width()	u32	Largura da imagem em pixels
height()	u32	Altura da imagem em pixels
color_space()	&ColorSpace	Espaço de cor (DeviceRGB, DeviceGray, DeviceCMYK, etc.)
bits_per_component()	u8	Bits por componente de cor (normalmente 8)
data()	&ImageData	Dados brutos da imagem (bytes JPEG ou pixels brutos)
bbox()	Option<&Rect>	Bounding box no espaço do usuário do PDF (se a CTM foi rastreada)
save_as_png(path)	Result<()>	Salva a imagem como arquivo PNG
save_as_jpeg(path)	Result<()>	Salva a imagem como arquivo JPEG
to_png_bytes()	Result<Vec<u8>>	Codifica como bytes PNG em memória
to_jpeg_bytes()	Result<Vec<u8>>	Codifica como bytes JPEG em memória

Variantes de ColorSpace

Variante	Descrição
DeviceRGB	RGB de 3 canais
DeviceGray	Tons de cinza de canal único
DeviceCMYK	CMYK de 4 canais
Indexed	Cor baseada em paleta
ICCBased	Cor baseada em perfil ICC
CalGray	Tons de cinza calibrados
CalRGB	RGB calibrado
Lab	Cor CIE Lab*

Variantes de ImageData

Variante	Descrição
Jpeg(Vec<u8>)	Dados comprimidos em JPEG (pass-through DCT)
Raw { pixels, format }	Dados de pixels decodificados com 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>

Extrai imagens de uma página e as salva diretamente em arquivos. Imagens JPEG são salvas em seu formato original (sem perda por recodificação); as demais imagens são salvas como PNG.

Parâmetro	Tipo	Padrão	Descrição
page_index	usize	–	Índice de página com base zero
output_dir	impl AsRef<Path>	–	Diretório onde salvar as imagens (criado se ausente)
prefix	Option<&str>	"img"	Prefixo do nome de arquivo
start_index	Option<usize>	1	Índice inicial para os nomes de arquivo

Retorna: um vetor de ExtractedImageRef descrevendo os arquivos salvos.

Campos de ExtractedImageRef

Campo	Tipo	Descrição
filename	String	Nome do arquivo salvo (ex.: "img_001.png")
format	ImageFormat	Png ou Jpeg
width	u32	Largura da imagem em pixels
height	u32	Altura da imagem em pixels

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);
}

---

Exemplos avançados

Extrair todas as imagens de todas as 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);

Obter bytes de imagem em memória (sem I/O em 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 imagens por tamanho

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 JPEG pass-through de imagens 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

• Extração de texto – Extraia texto junto com imagens
• Conversão para HTML – Embuta imagens extraídas na saída HTML
• Conversão para Markdown – Inclua imagens na saída Markdown