Skip to content
PDF Oxide

Извлечение изображений

PDF Oxide извлекает изображения со страниц PDF, разбирая поток содержимого, разрешая ссылки на XObject через операторы Do, рекурсивно обходя вложенные Form XObject и декодируя встроенные изображения. Используйте extract_images(), чтобы получить объекты изображений в памяти, или extract_images_to_files(), чтобы сохранить их прямо на диск в формате PNG или JPEG.

Начиная с v0.3.5 извлечение изображений обрабатывает полный поток содержимого страницы, а не только сканирует словарь XObject. Это позволяет корректно обрабатывать изображения, размещённые через операторы Do, вложенные Form XObject с обнаружением циклов, а также встроенные изображения в последовательностях BI/ID/EI.

Поддержка цветовых пространств

Извлечённые изображения декодируются и возвращаются в исходном цветовом пространстве — без потерь при перекодировании:

  • DeviceRGB / DeviceGray / DeviceCMYK — возвращаются как есть.
  • Indexed (1, 2, 4, 8 бит на компонент) — палитра разрешается через resolve_indexed_palette и разворачивается через expand_indexed_to_rgb. Поддерживаются индексированные палитры на основе RGB, Grayscale и CMYK. Раньше на многих реальных PDF-файлах возникала ошибка Invalid RGB image dimensions.
  • CalRGB / CalGray / ICCBased — при декодировании преобразуются в RGB.

Раскрытие палитры защищено от вредоносных входных данных: используется проверка переполнения checked_mul и ограничение выделяемой памяти в 256 МиБ; усечённые потоки отклоняются корректно, без порчи пикселей.

Устойчивость к повреждённым изображениям

Изображения с отсутствующим /ColorSpace, нулевыми размерами или недопустимым потоком пропускаются с предупреждением — они больше не вызывают паники при рендеринге страницы. Та же устойчивость применяется к повреждённым изображениям внутри Form XObject.

Быстрый пример

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

Java

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.image.ExtractedImage;
import java.nio.file.Path;
import java.util.List;

try (PdfDocument doc = PdfDocument.open(Path.of("report.pdf"))) {
    List<ExtractedImage> images = doc.page(0).images();
    for (ExtractedImage img : images) {
        System.out.println(img.width() + "x" + img.height());
    }
}

Kotlin

import fyi.oxide.pdf.PdfDocument

PdfDocument.open(java.nio.file.Path.of("report.pdf")).use { doc ->
    for (img in doc.page(0).images()) {
        println("${img.width()}x${img.height()}")
    }
}

Scala

import fyi.oxide.pdf.{PdfDocument, imagesSeq}
import scala.util.Using

Using.resource(PdfDocument.open("report.pdf")) { doc =>
  for (img <- doc.page(0).imagesSeq) {
    println(s"${img.width}x${img.height}")
  }
}

Clojure

(require '[pdf-oxide.core :as pdf])

(with-open [doc (pdf/open "report.pdf")]
  (doseq [img (pdf/images (pdf/page doc 0))]
    (println (str (.width img) "x" (.height img)))))

C++

#include <pdf_oxide/pdf_oxide.hpp>

auto doc = pdf_oxide::Document::open("report.pdf");
for (const auto& img : doc.embedded_images(0)) {
    std::printf("%dx%d\n", img.width, img.height);
}

Swift

import PdfOxide

let doc = try Document.open("report.pdf")
for img in try doc.embeddedImages(0) {
    print("\(img.width)x\(img.height)")
}

Dart

import 'package:pdf_oxide/pdf_oxide.dart';

final doc = PdfDocument.open('report.pdf');
for (final img in doc.embeddedImages(0)) {
    print('${img.width}x${img.height}');
}

R

library(pdfoxide)

doc <- pdf_open("report.pdf")
for (img in pdf_embedded_images(doc, 0)) {
    cat(sprintf("%dx%d\n", img$width, img$height))
}

Julia

using PdfOxide

doc = open_document("report.pdf")
for img in embedded_images(doc, 0)
    println("$(img.width)x$(img.height)")
end

Zig

const pdf_oxide = @import("pdf_oxide");
const a = std.heap.page_allocator;

var doc = try pdf_oxide.Document.open("report.pdf");
const images = try doc.embeddedImages(a, 0);
for (images) |img| {
    std.debug.print("{d}x{d}\n", .{ img.width, img.height });
}

Objective-C

#import "POXPdfOxide.h"
NSError *err = nil;

POXDocument *doc = [POXDocument openPath:@"report.pdf" error:&err];
for (POXImage *img in [doc embeddedImages:0 error:&err]) {
    NSLog(@"%ldx%ld", (long)img.width, (long)img.height);
}

Elixir

{:ok, doc} = PdfOxide.open("report.pdf")
{:ok, images} = PdfOxide.embedded_images(doc, 0)
for img <- images do
  IO.puts("#{img.width}x#{img.height}")
end

Справочник API

extract_images(page_index) -> Vec<PdfImage>

Извлекает все изображения со страницы. Разбирает поток содержимого страницы в поисках:

  1. XObject-изображений — на которые ссылаются операторы Do
  2. Form XObject — содержащих вложенные изображения (рекурсивно, с обнаружением циклов)
  3. Встроенных изображений — внедрённых через последовательности BI/ID/EI

Отслеживание CTM (матрицы текущего преобразования) обеспечивает вычисление ограничивающих прямоугольников для каждого изображения.

Параметр Тип Описание
page_index int / usize Индекс страницы, начиная с нуля

Возвращает: вектор объектов PdfImage.

Поля и методы PdfImage

Метод / поле Тип Описание
width() u32 Ширина изображения в пикселях
height() u32 Высота изображения в пикселях
color_space() &ColorSpace Цветовое пространство (DeviceRGB, DeviceGray, DeviceCMYK и др.)
bits_per_component() u8 Бит на цветовой компонент (как правило, 8)
data() &ImageData Необработанные данные изображения (байты JPEG или сырые пиксели)
bbox() Option<&Rect> Ограничивающий прямоугольник в пользовательском пространстве PDF (если отслеживался CTM)
save_as_png(path) Result<()> Сохранить изображение как PNG-файл
save_as_jpeg(path) Result<()> Сохранить изображение как JPEG-файл
to_png_bytes() Result<Vec<u8>> Закодировать в PNG-байты в памяти
to_jpeg_bytes() Result<Vec<u8>> Закодировать в JPEG-байты в памяти

Варианты ColorSpace

Вариант Описание
DeviceRGB 3-канальный RGB
DeviceGray Одноканальный оттенки серого
DeviceCMYK 4-канальный CMYK
Indexed Палитровый цвет
ICCBased Цвет на основе ICC-профиля
CalGray Калиброванный оттенок серого
CalRGB Калиброванный RGB
Lab Цвет CIE Lab*

Варианты ImageData

Вариант Описание
Jpeg(Vec<u8>) Данные JPEG-сжатия (DCT pass-through)
Raw { pixels, format } Декодированные пиксельные данные с 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>

Извлекает изображения со страницы и сохраняет их прямо в файлы. JPEG-изображения сохраняются в исходном формате (без потерь при перекодировании); остальные сохраняются в PNG.

Параметр Тип По умолчанию Описание
page_index usize – Индекс страницы, начиная с нуля
output_dir impl AsRef<Path> – Директория для сохранения изображений (создаётся, если отсутствует)
prefix Option<&str> "img" Префикс имён файлов
start_index Option<usize> 1 Начальный индекс для имён файлов

Возвращает: вектор объектов ExtractedImageRef, описывающих сохранённые файлы.

Поля ExtractedImageRef

Поле Тип Описание
filename String Имя сохранённого файла (например, "img_001.png")
format ImageFormat Png или Jpeg
width u32 Ширина изображения в пикселях
height u32 Высота изображения в пикселях

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

Расширенные примеры

Извлечь все изображения со всех страниц

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

Получить байты изображения в памяти (без записи на диск)

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.
}

Фильтрация изображений по размеру

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

Различить JPEG pass-through и перекодированные изображения

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

Аксессор встроенных изображений (embedded_images)

extract_images() — это богатый in-memory API для Rust. Кросс-языковые привязки предоставляют более лёгкий аксессор встроенных изображений, построенный на том же обходе потока содержимого и возвращающий размеры пикселей, формат, цветовое пространство, бит на компонент и сырые декодированные байты каждого изображения. Реализован через C ABI функцию pdf_document_get_embedded_images и семейство аксессоров pdf_oxide_image_*.

Как перечислить встроенные изображения через привязки

Go

import (
    "fmt"
    pdfoxide "github.com/yfedoseev/pdf_oxide/go"
)

doc, _ := pdfoxide.Open("report.pdf")
defer doc.Close()

images, _ := doc.Images(0) // []pdfoxide.Image
for _, img := range images {
    fmt.Printf("%dx%d %s/%s %dbpc, %d bytes\n",
        img.Width, img.Height, img.Format, img.Colorspace,
        img.BitsPerComponent, len(img.Data))
}

Swift

import PdfOxide

let doc = try Document.open("report.pdf")
let images = try doc.embeddedImages(0) // [Image]
for img in images {
    print("\(img.width)x\(img.height) \(img.format)/\(img.colorspace) "
        + "\(img.bitsPerComponent)bpc, \(img.data.count) bytes")
}

C ABI

#include "pdf_oxide.h"

int32_t err = 0;
FfiImageList *images = pdf_document_get_embedded_images(doc, /*page=*/0, &err);
int32_t n = pdf_oxide_image_count(images);
for (int32_t i = 0; i < n; i++) {
    int32_t w = pdf_oxide_image_get_width(images, i, &err);
    int32_t h = pdf_oxide_image_get_height(images, i, &err);
    char *fmt = pdf_oxide_image_get_format(images, i, &err);
    char *cs  = pdf_oxide_image_get_colorspace(images, i, &err);
    printf("%dx%d %s/%s\n", w, h, fmt, cs);
    free_string(fmt);
    free_string(cs);
}
pdf_oxide_image_list_free(images);

Java

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.image.ExtractedImage;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("report.pdf"))) {
    for (ExtractedImage img : doc.page(0).images()) {
        System.out.printf("%dx%d %s, %d bytes%n",
            img.width(), img.height(), img.format(), img.bytes().length);
    }
}

Kotlin

import fyi.oxide.pdf.PdfDocument

PdfDocument.open(java.nio.file.Path.of("report.pdf")).use { doc ->
    for (img in doc.page(0).images()) {
        println("${img.width()}x${img.height()} ${img.format()}, ${img.bytes().size} bytes")
    }
}

Scala

import fyi.oxide.pdf.{PdfDocument, imagesSeq}
import scala.util.Using

Using.resource(PdfDocument.open("report.pdf")) { doc =>
  for (img <- doc.page(0).imagesSeq) {
    println(s"${img.width}x${img.height} ${img.format}, ${img.bytes.length} bytes")
  }
}

Clojure

(require '[pdf-oxide.core :as pdf])

(with-open [doc (pdf/open "report.pdf")]
  (doseq [img (pdf/images (pdf/page doc 0))]
    (println (format "%dx%d %s, %d bytes"
                     (.width img) (.height img) (.format img) (count (.bytes img))))))

C++

#include <pdf_oxide/pdf_oxide.hpp>

auto doc = pdf_oxide::Document::open("report.pdf");
for (const auto& img : doc.embedded_images(0)) {
    std::printf("%dx%d %s/%s %dbpc, %zu bytes\n",
        img.width, img.height, img.format.c_str(), img.colorspace.c_str(),
        img.bits_per_component, img.data.size());
}

Dart

import 'package:pdf_oxide/pdf_oxide.dart';

final doc = PdfDocument.open('report.pdf');
for (final img in doc.embeddedImages(0)) {
    print('${img.width}x${img.height} ${img.format}/${img.colorspace} '
        '${img.bitsPerComponent}bpc, ${img.data.length} bytes');
}

R

library(pdfoxide)

doc <- pdf_open("report.pdf")
for (img in pdf_embedded_images(doc, 0)) {
    cat(sprintf("%dx%d %s/%s %dbpc, %d bytes\n",
        img$width, img$height, img$format, img$colorspace,
        img$bits_per_component, length(img$data)))
}

Julia

using PdfOxide

doc = open_document("report.pdf")
for img in embedded_images(doc, 0)
    println("$(img.width)x$(img.height) $(img.format)/$(img.colorspace) " *
            "$(img.bitsPerComponent)bpc, $(length(img.data)) bytes")
end

Zig

const pdf_oxide = @import("pdf_oxide");
const a = std.heap.page_allocator;

var doc = try pdf_oxide.Document.open("report.pdf");
const images = try doc.embeddedImages(a, 0);
for (images) |img| {
    std.debug.print("{d}x{d} {s}/{s} {d}bpc, {d} bytes\n", .{
        img.width, img.height, img.format, img.colorspace,
        img.bits_per_component, img.data.len,
    });
}

Objective-C

#import "POXPdfOxide.h"
NSError *err = nil;

POXDocument *doc = [POXDocument openPath:@"report.pdf" error:&err];
for (POXImage *img in [doc embeddedImages:0 error:&err]) {
    NSLog(@"%ldx%ld %@/%@ %ldbpc, %lu bytes",
        (long)img.width, (long)img.height, img.format, img.colorspace,
        (long)img.bitsPerComponent, (unsigned long)img.data.length);
}

Elixir

{:ok, doc} = PdfOxide.open("report.pdf")
{:ok, images} = PdfOxide.embedded_images(doc, 0)
for img <- images do
  IO.puts("#{img.width}x#{img.height} #{img.format}/#{img.colorspace} " <>
          "#{img.bits_per_component}bpc, #{byte_size(img.data)} bytes")
end

Поля аксессора изображений

Поле (Go / Swift) Тип Описание
Width / width int Ширина изображения в пикселях
Height / height int Высота изображения в пикселях
Format / format string Строка исходного формата (например, "jpeg", "raw")
Colorspace / colorspace string Название цветового пространства (например, "DeviceRGB")
BitsPerComponent / bitsPerComponent int Бит на цветовой компонент
Data / data []byte / [UInt8] Сырые декодированные байты изображения

Покрытие привязок. Аксессор встроенных изображений доступен в Go (doc.Images(page)), Swift (doc.embeddedImages(page)) и C ABI (pdf_document_get_embedded_images). В Rust используйте более богатый extract_images(), описанный выше. Для WASM-таргета аксессор не компилируется.

Аксессор элементов страницы (page_elements)

page_elements возвращает все расположенные на странице элементы (текстовые фрагменты с их типом, текстом и ограничивающим прямоугольником) в виде единого списка. Привязки маршалируют весь список за один FFI-вызов через pdf_oxide_elements_to_json, поэтому это наиболее эффективный способ обойти разметку страницы без повторного запуска извлечения текста для каждого региона. Реализован через C ABI функцию pdf_page_get_elements и семейство аксессоров pdf_oxide_element_*.

Как обойти элементы разметки страницы

Go

import (
    "fmt"
    pdfoxide "github.com/yfedoseev/pdf_oxide/go"
)

doc, _ := pdfoxide.Open("report.pdf")
defer doc.Close()

elements, _ := doc.PageElements(0) // []pdfoxide.Element
for _, el := range elements {
    fmt.Printf("[%s] %q at (%.1f, %.1f) %.1fx%.1f\n",
        el.Type, el.Text, el.X, el.Y, el.Width, el.Height)
}

Swift

import PdfOxide

let doc = try Document.open("report.pdf")
let elements = try doc.pageElements(0) // ElementList
for el in try elements.all() {
    print("[\(el.type)] \(el.text) at "
        + "(\(el.rect.x), \(el.rect.y)) \(el.rect.width)x\(el.rect.height)")
}

// Serialize the whole list to JSON in one call:
let json = try elements.toJson()

C ABI

#include "pdf_oxide.h"

int32_t err = 0;
FfiElementList *els = pdf_page_get_elements(doc, /*page=*/0, &err);

// One-shot JSON serialization (caller frees with free_string):
char *json = pdf_oxide_elements_to_json(els, &err);
printf("%s\n", json);
free_string(json);

pdf_oxide_elements_free(els);

Dart

import 'package:pdf_oxide/pdf_oxide.dart';

final doc = PdfDocument.open('report.pdf');
final elements = doc.pageElements(0); // ElementList
for (final el in elements.toList()) {
    print('[${el.type}] ${el.text} at '
        '(${el.rect.x}, ${el.rect.y}) ${el.rect.width}x${el.rect.height}');
}

// Serialize the whole list to JSON in one call:
final json = elements.toJson();

Objective-C

#import "POXPdfOxide.h"
NSError *err = nil;

POXDocument *doc = [POXDocument openPath:@"report.pdf" error:&err];
POXElementList *els = [doc pageElements:0 error:&err];
for (int32_t i = 0; i < [els count]; i++) {
    NSString *type = [els typeAtIndex:i error:&err];
    NSString *text = [els textAtIndex:i error:&err];
    POXBbox rect = [els rectAtIndex:i error:&err];
    NSLog(@"[%@] %@ at (%.1f, %.1f) %.1fx%.1f",
        type, text, rect.x, rect.y, rect.width, rect.height);
}

// One-shot JSON serialization:
NSString *json = [els toJsonWithError:&err];

Elixir

{:ok, doc} = PdfOxide.open("report.pdf")
{:ok, els} = PdfOxide.page_elements(doc, 0)
for i <- 0..(PdfOxide.element_count(els) - 1) do
  {:ok, type} = PdfOxide.element_type(els, i)
  {:ok, text} = PdfOxide.element_text(els, i)
  {:ok, rect} = PdfOxide.element_rect(els, i)
  IO.puts("[#{type}] #{text} at (#{rect.x}, #{rect.y}) #{rect.width}x#{rect.height}")
end

# Serialize the whole list to JSON in one call:
{:ok, json} = PdfOxide.elements_to_json(els)

Поля элементов

Поле (Go / Swift) Тип Описание
Type / type string Тип элемента (например, "text")
Text / text string Текстовое содержимое элемента
X, Y / rect.x, rect.y float Начало ограничивающего прямоугольника в пользовательском пространстве PDF
Width, Height / rect.width, rect.height float Размеры ограничивающего прямоугольника

Покрытие привязок. page_elements доступен в Go (doc.PageElements(page)), Swift (doc.pageElements(page) → ElementList) и C ABI (pdf_page_get_elements + pdf_oxide_elements_to_json). Для WASM-таргета не компилируется.

Часто задаваемые вопросы

В чём разница между extract_images() и аксессором встроенных изображений? extract_images() (Rust) возвращает богатые объекты PdfImage с методами save_as_png, to_jpeg_bytes, ограничивающими прямоугольниками CTM и типизированными перечислениями ColorSpace/ImageData. Аксессор встроенных изображений (doc.Images / doc.embeddedImages / pdf_document_get_embedded_images) возвращает плоский список размеров, формата, цветового пространства и сырых байтов — кросс-языковый путь к тому же обходу потока содержимого.

Быстро ли работает извлечение изображений? Да. Ядро извлечения PDF Oxide работает со средним временем около 0,8 мс и p99 9 мс при 100% успешных попытках на тестовом корпусе, декодируя изображения в исходном цветовом пространстве без потерь.

Перекодирует ли аксессор встроенных изображений JPEG? Нет. Изображения на основе JPEG возвращаются с исходными байтами DCT (format == "jpeg"); декодируются только сырые пиксельные данные. Более богатый API extract_images() отображает то же различие через ImageData::Jpeg и ImageData::Raw.

Почему у некоторых изображений data пустой? Повреждённые изображения (отсутствует /ColorSpace, нулевые размеры, усечённые потоки) пропускаются с предупреждением без паники страницы, поэтому их байтовый буфер может вернуться пустым.

Связанные страницы