Struct ExtractOptions 

#[non_exhaustive]
pub struct ExtractOptions {

    pub first_page: usize,
    pub page_count: Option<usize>,
    pub pages: Option<Vec<usize>>,
    pub learned: bool,
    pub use_tags: bool,
    pub document_font_names: bool,
    pub include_headers: bool,
    pub include_footers: bool,
    pub page_separators: PageSeparators,
    pub code: bool,
    pub heading_overrides: Vec<HeadingOverride>,
    pub include_hidden: bool,
    pub raw_order: bool,
    pub ocr: OcrMode,
    pub ocr_language: String,
    pub ocr_dpi: u32,
    pub clip_margins: Option<ClipMargins>,
    pub quality: Quality,
    pub model_dir: Option<PathBuf>,
    pub keep_furniture: bool,
    pub word_boxes: bool,
    pub include_figures: bool,
    pub embed_figures: bool,
    pub figure_image_dir: Option<PathBuf>,
    pub drop_text_over_images: bool,
    pub table_strategy: TableStrategy,
    pub table_render_mode: TableRenderMode,
    pub cell_path_words: bool,
    pub actual_text: bool,
    /* private fields */
}

Which part of the document crate::PdfDocument::extract_blocks and crate::PdfDocument::extract_markdown hand back (#573).

A struct rather than two arguments, because this is the parameter both methods take across six languages: a field added here is a field added to every binding at once, and a caller that built it from ExtractOptions::default() keeps compiling. #[non_exhaustive], so that is the only way to build one from outside this crate: struct literals are refused, and a field added here cannot break a caller that never named it. Start from Default, Self::all or Self::window and assign the fields you want – the fields stay public and assignable, only the literal is gone. (Unlike crate::RenderOptions, which still takes literals.)

THE WINDOW IS A WINDOW ON THE ANSWER, NOT ON THE WORK. Whatever it asks for, the document is read whole, because everything the block model says about a block is said against the rest of the document: a size is a heading against what the body is set in (#568), a line is a running head because THREE pages repeat it (#571), and a window that re-derived those from its own pages would call a different thing a heading than the same document does. A caller that wants one page read on its own, and the statistics of that page alone, asks crate::PdfDocument::extract_page_blocks instead – which is the cheap path, and says so.

Example

use pdf_engine::{ExtractOptions, PdfDocument};

let document = PdfDocument::open(std::fs::read("report.pdf").unwrap()).unwrap();

// The whole document.
let all = document.extract_blocks(&ExtractOptions::default()).unwrap();

// Pages 10 to 19, for a caller indexing a long document in windows.
let window = document.extract_blocks(&ExtractOptions::window(10, 10)).unwrap();

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

first_page: usize

The first page of the window, counted from zero. Default 0.

page_count: Option<usize>

How many pages from Self::first_page, or None for the rest of the document. Default None.

pages: Option<Vec<usize>>

An explicit list of pages, counted from zero, instead of the Self::first_page/Self::page_count window. Default None.

A SELECTION, NOT AN ORDER: [2, 0] hands back the blocks of pages 0 and 2 in the document’s reading order, the same order the window would. Anything else would renumber Block::index and break Block::continues_previous, which both speak document order.

A page past the last one is an error, where a window past the last page is empty: a window walks a document until the answer runs out, but a list names its pages and a name that is not there is a mistake. Setting this beside a window – first_page other than 0 or page_count set – is an error too.

learned: bool

Whether the learned pass runs over the finished blocks. Default true, which is what a caller gets.

FOR A TEST OF A HEURISTIC, AND NOT FOR A CALLER TO TUNE. The rules in headings, lists and blocks each have operator tests that assert what THAT rule does; the learned pass is a stage after them with a switch of its own (learned::SWITCHES), and a test of the first that silently measures the second tells you nothing about either. Every such test says so where it sets this (#599).

use_tags: bool

Whether a tagged PDF’s own structure tree may decide kinds and order. Default false: geometry decides, exactly as without the option.

When true and the document carries a structure tree that passes the validity check, heading levels come from H1-H6, list items from LI, table cells and spans from TD/TH, the reading order from the tree, and /Artifact content becomes furniture. A tree that fails the check – or a document without one – falls back to the geometric answer, so the option can only replace output the tree earns (#636).

document_font_names: bool

Whether spans carry the document’s own font names and the descriptor’s metrics. Default false: embedded Type1/CFF spans report the substitute face and its AFM pair, exactly as without the option.

When true, TextSpan::font_name is the font dictionary’s /BaseFont with any subset prefix stripped – the name the page set its text in – and TextSpan::font_metrics is the FontDescriptor /Ascent /Descent pair (/CapHeight /XHeight), in /1000 em, falling back to the substitute face’s AFM values where the descriptor carries none. Span merging still reads the face either way (#643).

include_headers: bool

Whether the running heads reach the Markdown. Default false: they are marked BlockKind::Header and left out of PdfDocument::extract_markdown, exactly as without the option.

When true they are written as plain paragraphs at their reading-order position – never as headings, which they are not – for callers that need running titles in the text (citations, legal documents). Read only by extract_markdown: extract_blocks always carries the furniture, whatever this says.

include_footers: bool

Whether the running footers and page numbers reach the Markdown. Default false: they are marked BlockKind::Footer and left out of PdfDocument::extract_markdown, exactly as without the option.

When true they are written as plain paragraphs at their reading-order position – never as headings, which they are not – for callers that need page numbers in the text. Read only by extract_markdown: extract_blocks always carries the furniture, whatever this says.

page_separators: PageSeparators

How a change of page is marked in the Markdown. Default PageSeparators::Comment: today’s <!-- page N --> marker. PageSeparators::None writes no marker at all, and the paragraphs on either side stand separated by a blank line. Read only by PdfDocument::extract_markdown.

code: bool

Whether monospace runs reach the Markdown as code. Default true.

A run of spans set in a monospace face (TextSpan::is_monospace) inside a paragraph or a list item is written `like this`, and a paragraph output from before code existed, byte for byte – the off switch pymupdf4llm spells ignore_code (#636).

heading_overrides: Vec<HeadingOverride>

Caller-supplied heading steers, applied after every other heading decision. Default empty: the document’s own statistics decide.

Each override relevels the block whose text matches exactly: None demotes it to prose, Some(n) promotes it to a heading. The front door steers its own headings the same way, with a detector object the caller hands in (SPEC G24).

include_hidden: bool

Whether text the page hides reaches the blocks. Default false: text drawn with render mode 3 or painted with zero alpha is dropped, the way the front door’s own default engine drops hidden lines from its output (SPEC G165).

Invisible text that is a page’s ONLY text is kept either way: without it the page would read empty, and that is how a scanned page reads through its own layer. Pass true to keep every hidden line, for callers that filter themselves.

raw_order: bool

Whether blocks follow the content stream instead of the reading order. Default false: the reading order decides, exactly as without the option.

When true, extract_blocks hands back the runs the page draws in the order it draws them, grouped into lines and blocks by content-order proximity – and the reading-order sort, the furniture, the headings and the learned pass never run (#643). The compat layer reads through this where the recorded shapes need draw order rather than reading order.

ocr: OcrMode

Whether pages that need it are OCR’d before extraction. Default OcrMode::Never: the SDK and the rig read what the document draws, and OCR is an explicit request.

OcrMode::Auto recognizes the pages under pdf-ocr’s text threshold and leaves the rest untouched; OcrMode::Force recognizes every page in the window, replacing a born-digital page’s own text with the OCR layer rather than emitting both. Either way the recognized words go through the same segmentation as born-digital text, because extraction reads a copy of the document carrying them as an invisible text layer.

ocr_language: String

The Tesseract language tag OCR runs in (-l). Default "eng". Read only when Self::ocr is not OcrMode::Never; several tags join with + as Tesseract takes them.

ocr_dpi: u32

The resolution OCR renders pages at, in dots per inch. Default 150. Read only when Self::ocr is not OcrMode::Never; must be positive when it is read.

clip_margins: Option<ClipMargins>

Clip margins in points, or None for the whole page. Default None.

quality: Quality

Which tier reads the document. Default Quality::Fast: the shipping engine, byte for byte what a caller got before this field existed.

Quality::Balanced is read by crate::PdfDocument::extract_markdown only; a call that returns blocks answers OptionsError::BalancedIsMarkdownOnly for it.

model_dir: Option<PathBuf>

Where the model tier looks for its weights. Default None: PDFLUENT_MODEL_DIR, else the per-user <data dir>/pdfluent/models/.

Read only when Self::quality is Quality::Balanced: an explicit dir for a caller – and a test – that keeps models outside the default. Wins over the environment and the default, exactly as the shared runtime resolves it.

keep_furniture: bool

Whether the balanced tier keeps running heads and feet as paragraphs. Default false: furniture lines are dropped, exactly as without the option.

Read only when Self::quality is Quality::Balanced, where it maps to the balanced assembly’s keep-furniture switch.

word_boxes: bool

Whether the word boxes travel with the answer. Default false: the blocks, the markdown and crate::to_json read exactly as without the option. Set with Self::with_word_boxes.

include_figures: bool

Whether figures reach the Markdown as image references. Default true.

Read only by PdfDocument::extract_markdown, the way Self::include_headers is: extract_blocks always carries the figures, whatever this says. False writes no reference at all.

embed_figures: bool

Whether figure references embed the figure’s pixels. Default false: references are markers naming the figure.

True writes ![](data:image/png;base64,...) with the figure’s box rendered at 150 dots per inch. Read only by PdfDocument::extract_markdown; Self::figure_image_dir wins where both are set.

figure_image_dir: Option<PathBuf>

Where figure image files are written, or None for no files. Default None.

Read only by PdfDocument::extract_markdown: each figure is rendered at 150 dots per inch, written under the directory, and referenced from the Markdown under that path. The directory – and any parents – is created; a write failure fails the extraction. The one writer of files on this path, so the references and the files cannot disagree.

drop_text_over_images: bool

Whether text drawn over a placed image is dropped. Default false: every line is kept, wherever it stands.

True drops a body block whose centre falls inside a placed image’s box on the same page – the over-picture line of a caption pair – before figures merge into the blocks. Running heads and feet are never dropped: page chrome is positioned independently of figures.

table_strategy: TableStrategy

Which evidence may find a table. Default TableStrategy::Both: today’s combined detection, byte for byte.

TableStrategy::Lines keeps only the tables a drawn rule crosses – the rest go back to the paragraph merge – and TableStrategy::Text drops the drawn grid from the evidence. Read by crate::PdfDocument::extract_blocks and, through it, crate::PdfDocument::extract_markdown; the balanced tier and crate::PdfDocument::extract_page_blocks read every table.

table_render_mode: TableRenderMode

How tables reach the Markdown. Default TableRenderMode::Auto: pipes where Markdown holds the table’s shape, HTML elsewhere – today’s output, byte for byte.

TableRenderMode::Markdown writes every table as pipes and TableRenderMode::Html every table as HTML. Read only by PdfDocument::extract_markdown: PdfDocument::extract_blocks always carries the cells, whatever this says.

cell_path_words: bool

Whether table-cell words join on the cell path. Default false: the leader fold, the cell-word join, the TATR fill and the quarter-em word-space boundary read exactly as without the option.

When true, the four cell-path word rules run: leader dots abutting their label join it as text and box, keeping the dots’ glyph boxes; cell words join by the shared gap rule with only a drawn space vetoing; the TATR fill aligns fragments onto text tokens in both directions; and a word space set at exactly a quarter em reads as a space (#659). Read by the extract_blocks family; the direct learned entries keep the shipped words either way. Independent of Self::actual_text: this option never applies /ActualText.

actual_text: bool

Whether /ActualText replacements read instead of their marked runs. Default false: replacements are ignored, exactly as without the option.

When true, an /ActualText replacement reads instead of the glyphs of its marked run, once, on the run’s first glyph; a run that closes without a glyph to carry it reads once at the box it drew instead. Without the option the run reads what the page drew (#663). Opt-in pending a variant measurement: the default output is what it was before the replacements were read. A glyphless replacement in a widget appearance reads either way: the appearance is the only place that value is painted (#549). Read by the extract_blocks family; independent of Self::cell_path_words, which moves only the four word rules.

Implementations

impl ExtractOptions

pub fn all() -> Self

The whole document, which is what Default gives too.

pub fn without_the_learned_pass(self) -> Self

The same window with the learned pass off, for a test that asserts what a heuristic does (#599).

pub fn with_tatr(self, tatr: TatrOptions) -> Self

Rebuild table regions with TATR first, where it fires.

The only way to set the TATR opt-in: there is no public field. With it set, every table region is offered to the Table Transformer before the current grid runs; where TATR fires its cells are the region’s table, and where it declines, or a region’s inference fails, the current grid runs unchanged. A missing model is an error, never a silent fast run – as is asking on a build without the ort-tables feature.

Example

use pdf_engine::{ExtractOptions, TatrOptions};

let options = ExtractOptions::default().with_tatr(TatrOptions::default());

pub fn window(first: usize, count: usize) -> Self

count pages from first, counted from zero.

A window past the last page is EMPTY rather than an error, and so is a count of zero: a caller stepping through a long document a window at a time stops when the answer is empty, and an error at the end would make the ordinary end of that loop indistinguishable from a broken file.

pub fn with_quality(self, quality: Quality) -> Self

Which tier reads the document: Quality::Fast (the default) or Quality::Balanced, read by crate::PdfDocument::extract_markdown only.

pub fn with_model_dir(self, dir: impl Into<PathBuf>) -> Self

Where the model tier looks for its weights, winning over PDFLUENT_MODEL_DIR and the per-user default. Read only when Self::quality is Quality::Balanced.

pub fn with_keep_furniture(self, keep: bool) -> Self

Keep running heads and feet as paragraphs in balanced markdown (true) or drop them (the default). Read only when Self::quality is Quality::Balanced, where it maps to the balanced assembly’s keep-furniture switch.

impl ExtractOptions

pub fn with_word_boxes(self, word_boxes: bool) -> Self

Carry the word boxes beside the blocks. Default off: crate::to_json writes exactly what it wrote before this option existed.

Trait Implementations

impl Clone for ExtractOptions

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ExtractOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ExtractOptions

fn default() -> Self

Returns the “default value” for a type.

impl Eq for ExtractOptions

impl From<&ExtractOptions> for MarkdownOptions

fn from(options: &ExtractOptions) -> Self

The markdown half of an ExtractOptions: what extract_markdown serializes with.

impl PartialEq for ExtractOptions

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ExtractOptions