Struct PdfDocument 

pub struct PdfDocument<'a> { /* private fields */ }

A parsed PDF document.

Implementations

impl<'a> PdfDocument<'a>

pub fn from_bytes(data: &'a [u8]) -> Result<Self, PdfError>

Parse a PDF from bytes.

pub fn from_bytes_with_icc( data: &'a [u8], icc_cache: IccCache, ) -> Result<Self, PdfError>

Parse a PDF from bytes, using a pre-loaded ICC cache.

Use this when the caller already has an IccCache with the system CMYK profile loaded (e.g., from the PostScript interpreter context).

pub fn from_bytes_with_password( data: &'a [u8], icc_cache: IccCache, password: &[u8], ) -> Result<Self, PdfError>

Parse a PDF from bytes using a user-supplied password.

Returns PdfError::PasswordRequired if the password does not match; callers can retry by calling this again with a different password.

pub fn set_overprint(&mut self, enabled: bool)

Enable or disable PDF overprint simulation.

Enabled by default. When disabled, OP/op flags in graphics state dicts are ignored, avoiding CMYK buffer tracking.

pub fn set_font_provider(&mut self, provider: FontProvider)

Set a font data provider for environments without filesystem access.

pub fn page_count(&self) -> usize

Number of pages in the document.

pub fn page_size(&self, page: usize) -> Result<(f64, f64), PdfError>

Page dimensions in points (width, height), accounting for rotation.

pub fn page_info(&self, page: usize) -> Result<&PageInfo, PdfError>

Get page info (MediaBox, CropBox, rotation, resources).

pub fn page_contents(&self, page: usize) -> Result<Vec<u8>, PdfError>

Get the decompressed content stream bytes for a page. If the page has multiple content streams, they are concatenated with a newline separator.

pub fn render_page( &self, page: usize, dpi: f64, ) -> Result<DisplayList, PdfError>

Render a page to a DisplayList at the given DPI.

The display list uses device-space coordinates (paths pre-transformed through the initial CTM). The initial CTM applies DPI scaling, Y-flip, and CropBox offset.

pub fn render_page_to_rgba( &self, page: usize, dpi: f64, ) -> Result<(Vec<u8>, u32, u32), PdfError>

Render a page to RGBA pixel data at the given DPI.

Returns (pixel_data, width, height). Pixel data is RGBA, 4 bytes per pixel.

pub fn render_page_to_rgba_with_layers( &self, page: usize, dpi: f64, layer_set: &LayerSet, ) -> Result<(Vec<u8>, u32, u32), PdfError>

Like render_page_to_rgba but consults the supplied LayerSet when evaluating each OcgGroup’s visibility.

Pass an empty LayerSet::new() (or use the plain render_page_to_rgba) to fall back to each layer’s default_visible baked from the document’s default configuration. Use layers::layer_set_from_document or layers::layer_set_from_configuration to build a populated set, then mutate it with set / clear before passing it here.

pub fn icc_cache(&self) -> &IccCache

Access the ICC color profile cache.

pub fn output_intent_icc(&self) -> Option<&[u8]>

Decompressed ICC profile bytes from the PDF’s OutputIntent, if any. PDF/X files declare their intended CMYK rendering space here (e.g. ISO Coated v2 300% (ECI)); using it at render time matches the document author’s colour expectations, which system-default profiles (GS default_cmyk.icc, FOGRA39) often approximate only coarsely.

pub fn apply_output_intent_as_default_cmyk(&mut self) -> bool

Register the PDF’s OutputIntent ICC profile as the default CMYK profile in this document’s ICC cache, replacing whatever was loaded from search_system_cmyk_profile. Returns true when the profile was present and registered.

pub fn output_intents(&self) -> Vec<OutputIntentRecord>

Parse every entry in /Catalog /OutputIntents into round-tripable records. Unlike output_intent_icc, which is a renderer optimization that only captures CMYK profile bytes, this preserves all output intents (any color space) with their full metadata so the PDF writer can emit a faithful /OutputIntents chain in the output catalog.

pub fn resolver(&self) -> &Resolver<'a>

Access the resolver for arbitrary object lookups.

pub fn pages(&self) -> &[PageInfo]

Access page info list.

pub fn metadata(&self) -> &DocumentMetadata

Document metadata: the trailer’s /Info dict (title, author, dates, etc.) and the catalog’s /Metadata XMP stream.

Parsed lazily on first call and cached. All fields are optional; a document without an /Info dict still returns a value with every field empty.

pub fn viewer_preferences(&self) -> &ViewerPreferences

Viewer preferences: how the document hints it should be displayed (page layout, page mode, hide-toolbar, fit-window, print preferences, etc.).

Parsed lazily on first call and cached. Fields default per the PDF spec when the corresponding entries are absent.

pub fn outline(&self) -> &[OutlineItem]

Document outline (bookmarks) as a tree of OutlineItems.

Returns an empty slice if the document has no outline. Parsed lazily on first call and cached. Cycles, broken /First//Next chains, and pathological depth are tolerated by hard caps; each truncation pushes a warning visible through parse_warnings.

pub fn destinations(&self) -> &HashMap<String, Destination>

All named destinations in the document, merged from both /Catalog /Dests (legacy) and /Catalog /Names /Dests (name tree). Legacy entries take precedence on key conflict per ISO 32000-2 §12.3.2.3.

Parsed lazily on first call and cached. Returns an empty map when neither source is present.

pub fn resolve_named_destination(&self, name: &str) -> Option<Destination>

Resolve a named destination by name to its explicit destination.

Looks up the document’s full name table (legacy + name tree). If the looked-up entry is itself another named destination (legal but unusual), the chain is not followed — the caller receives the raw NamedDest. This avoids cycles without bookkeeping.

pub fn page_annotations(&self, page: usize) -> Result<&[Annotation], PdfError>

Annotations attached to page (0-based).

Returns an empty slice when the page has no annotations. Parsed lazily on first call per page and cached, so a 1000-page document with annotations only on a handful of pages doesn’t pay to parse the rest.

Returns Err(PdfError::PageOutOfRange) if page >= page_count().

pub fn form(&self) -> Option<&FormCatalog>

AcroForm — interactive form catalog with field tree, default appearance, calculation order, and signature flags.

Returns None when the document has no /AcroForm (most PDFs don’t). Parsed lazily on first call and cached.

Each terminal FormField carries the object numbers of its widget annotations (FormField::widget_obj_nums); cross-link with page_annotations to fetch renderable widget data.

pub fn parse_warnings(&self) -> Ref<'_, [ParseWarning]>

Parse-time warnings accumulated by the structural accessors.

Outline cycles, dropped annotations (missing /Rect), form-field tree truncations, and similar recoverable issues are surfaced here. The list grows as accessors are called for the first time; cached subsequent calls don’t re-emit.

Returns a borrow of the underlying slice — drop the returned Ref before calling any other accessor that could push more warnings (e.g. iterating with for w in doc.parse_warnings().iter() is fine; calling doc.outline() mid-iteration is not).

pub fn page_boxes(&self, page: usize) -> Result<PageBoxes, PdfError>

Page geometry for a page (0-based) — all five PDF page boxes (MediaBox, CropBox, BleedBox, TrimBox, ArtBox) plus rotation, user unit, and presentation hints.

Returns Err(PdfError::PageOutOfRange) if page >= page_count().

pub fn embedded_files(&self) -> &HashMap<String, EmbeddedFile>

All file attachments declared in the catalog’s /Names /EmbeddedFiles name tree, keyed by attachment name.

Parsed lazily on first call and cached. Returns an empty map when the document has no embedded files. Use embedded_file_bytes to read the underlying bytes of an attachment on demand.

pub fn embedded_file_bytes(&self, name: &str) -> Result<Vec<u8>, PdfError>

Read the decompressed bytes of a named embedded file.

Returns Err(PdfError::Other(...)) if the name is unknown.

pub fn layers(&self) -> &[Layer]

All Optional Content Groups (layers) declared by the document.

Each Layer carries the OCG’s display name, intent, lock state, full /Usage sub-dict, and its initial visibility under the default configuration. The hierarchy (/Order), alternate configurations, and runtime visibility overrides land in later phases of the layers API.

Returns an empty slice when the document has no /OCProperties. Parsed lazily on first call and cached.

pub fn layer(&self, ocg_id: u32) -> Option<&Layer>

Look up a single layer by its OCG object number.

Useful when the caller already has an ocg_id from a display list OcgGroup element and wants the layer’s metadata.

pub fn configurations(&self) -> &[Configuration]

All layer configurations declared by the document.

Index 0 is always the default configuration (/OCProperties /D); indices 1..N are the entries of /OCProperties /Configs in the order they appear. Returns an empty slice when the document has no /OCProperties.

Parsed lazily on first call and cached.

pub fn default_configuration(&self) -> Option<&Configuration>

The default configuration (/OCProperties /D).

Returns None when the document has no /OCProperties at all.

pub fn configuration(&self, index: usize) -> Option<&Configuration>

Look up a configuration by index — 0 for the default, 1..N for alternates in the order they appear in /Configs.

pub fn layer_tree(&self) -> LayerTree

The default configuration’s /Order hierarchy.

Convenience for layer-panel UIs that want the tree without traversing through default_configuration. Returns an empty tree when the document has no /OCProperties or no /Order on the default config.

pub fn layer_set_for(&self, intent: RenderIntent) -> LayerSet

Build a LayerSet for rendering under a specific RenderIntent.

Starts from the document’s default configuration (every layer at its default_visible state) and applies every /AS automatic-state rule whose /Event matches the requested intent. Pass the result to render_page_to_rgba_with_layers (or any other consumer of LayerSet) to honour “print-only” / “view-only” / “export-only” layer hints in the document.