@type chars_opts() :: [
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  exclude_layers: [String.t()],
  exclude_inks: [String.t()]
]

Options accepted by the chars and chars! functions.

• :region — a PdfElixide.Geometry.Rect keeping only the characters inside it. Defaults to nil.
• :region_mode — how :region matches; see region_mode/0. Defaults to :intersects.
• :exclude_layers — names of optional-content (OCG) layers to suppress. Defaults to [].
• :exclude_inks — names of Separation/DeviceN inks to suppress. Defaults to [].

@type extraction_profile() ::
  :conservative
  | :tj_heavy
  | :aggressive
  | :balanced
  | :academic
  | :policy
  | :form
  | :government
  | :scanned_ocr
  | :adaptive

A span-extraction tuning preset, named after pdf_oxide's own ExtractionProfile constants. A profile changes the TJ-offset and word-margin thresholds used to turn glyphs into spans, before any word clustering happens.

@type html_opts() :: [
  preserve_layout: boolean(),
  detect_headings: boolean(),
  extract_tables: boolean(),
  include_images: boolean(),
  embed_images: boolean(),
  image_output_dir: Path.t() | nil,
  include_form_fields: boolean(),
  max_image_pixels: non_neg_integer() | nil,
  reading_order: :structure_tree | :column_aware | :top_to_bottom
]

Options accepted by the to_html and to_html! functions.

Only the options that upstream actually reads on its HTML path are exposed, so every one of them changes the output. In particular :bold_markers, :annotate_skipped_pages, :strip_running_headers_footers and :expand_ligatures — all valid for to_markdown/2 — are not part of this list, because pdf_oxide never consults them while converting to HTML. Like any other undeclared key, passing one is silently ignored rather than an error. A declared key given a value of the wrong type is reported as {:error, %PdfElixide.Error{reason: :other}}, with a message naming the offending field, rather than raising.

• :preserve_layout — emit one absolutely positioned <div> per text span, carrying that span's coordinates and font size in inline CSS (pt units), in place of the semantic flow of <p>/<h1>/<ul> elements. Colour is written only for non-black text. Note that this mode emits only those positioned spans: headings, lists and tables are not produced, so :detect_headings and :extract_tables have no effect under it. Defaults to false.

  The result is not directly renderable, and reproducing the page needs two corrections from you. Upstream writes the PDF's own user-space coordinates verbatim, so the top value is measured from the bottom of the page while CSS top measures from the top: flip it yourself with top = height - y, taking the page height from PdfElixide.Document.Page.height/1. And the per-page wrapper to_html/1 emits carries no styling, so it is not a positioned containing block and gives the spans no page-sized box to resolve against — add position: relative and an explicit size to each wrapper, or every page will pile up in the same place.

• :detect_headings — cluster font sizes to emit <h1>–<h6> elements instead of plain <p> paragraphs. Defaults to true.

• :extract_tables — detect tables and render them as <table>/<thead>/<tbody> markup, with colspan and rowspan on the cells. Defaults to true.

• :include_images — emit <img> elements. Defaults to false, since embedded images can add hundreds of kilobytes per page. Images are appended to the end of the page in a <div class="page-images"> rather than placed at their position in the content.

• :embed_images — when true, images are inlined as base64 data URIs and :image_output_dir is ignored. When false, they are written to :image_output_dir and referenced by path — and if that option is nil, no image is emitted at all. Only applies when :include_images is true. Defaults to true.

• :image_output_dir — directory to write extracted images to, used only when :include_images is true and :embed_images is false. It is created if missing, and one that cannot be created is an :io error. The writes themselves are best-effort: upstream drops an image that fails to encode or write, so a successful call does not guarantee every image reached disk. Defaults to nil.

  Upstream interpolates the resulting path into the src attribute without HTML escaping, so a directory whose name contains " or & produces malformed markup. Never build this path from untrusted input: a crafted directory name can close the attribute and inject others.

• :include_form_fields — inline AcroForm field values at their positions on the page. Defaults to true.

• :max_image_pixels — skip images whose width times height exceeds this count. nil means pdf_oxide's own 16 MP limit, not "no limit" — pass a large integer to lift it, or 0 to skip every image. Defaults to nil.

• :reading_order — how text blocks are ordered: :structure_tree (follow a tagged PDF's structure tree, falling back to an XY-cut), :column_aware, or :top_to_bottom. Defaults to :structure_tree.

Defaults mirror pdf_oxide's ConversionOptions::default(), so calling to_html/1 is equivalent to to_html/2 with no options.

@type markdown_opts() :: [
  detect_headings: boolean(),
  extract_tables: boolean(),
  include_images: boolean(),
  embed_images: boolean(),
  image_output_dir: Path.t() | nil,
  include_form_fields: boolean(),
  strip_running_headers_footers: boolean(),
  expand_ligatures: boolean(),
  annotate_skipped_pages: boolean(),
  max_image_pixels: non_neg_integer() | nil,
  reading_order: :structure_tree | :column_aware | :top_to_bottom,
  bold_markers: :conservative | :aggressive
]

Options accepted by the to_markdown and to_markdown! functions.

• :detect_headings — cluster font sizes to emit # headings instead of plain paragraphs. Defaults to true.
• :extract_tables — detect tables and render them as Markdown tables. Defaults to true.
• :include_images — emit ![](…) image syntax. Defaults to false, since embedded images can add hundreds of kilobytes per page.
• :embed_images — when true, images are inlined as base64 data URIs and :image_output_dir is ignored. When false, they are written to :image_output_dir and referenced by path — and if that option is nil, no image is emitted at all. Only applies when :include_images is true. Defaults to true.
• :image_output_dir — directory to write extracted images to, used only when :include_images is true and :embed_images is false. It is created if missing, and one that cannot be created is an :io error. The writes themselves are best-effort: upstream drops an image that fails to encode or write, so a successful call does not guarantee every image reached disk. Defaults to nil.
• :include_form_fields — inline AcroForm field values at their positions on the page. Defaults to true.
• :strip_running_headers_footers — drop text lines that repeat in the top/bottom band of a majority of pages. Defaults to false.
• :expand_ligatures — expand U+FB00–U+FB06 ligatures to their component letters (fi to fi, and so on). Accepted for forward compatibility, but currently has no effect on Markdown output: upstream applies it only on its plain-text assembly path, which the Markdown converter does not use. Defaults to false.
• :annotate_skipped_pages — emit a block quote naming any page that is a scan with no usable text layer, rather than rendering it blank. Defaults to true.
• :max_image_pixels — skip images whose width times height exceeds this count. nil means pdf_oxide's own 16 MP limit, not "no limit" — pass a large integer to lift it, or 0 to skip every image. Defaults to nil.
• :reading_order — how text blocks are ordered: :structure_tree (follow a tagged PDF's structure tree, falling back to an XY-cut), :column_aware, or :top_to_bottom. Defaults to :structure_tree.
• :bold_markers — :conservative applies ** only to content-bearing text; :aggressive also wraps whitespace-only spans. Defaults to :conservative.

Defaults mirror pdf_oxide's ConversionOptions::default(), so calling to_markdown/1 is equivalent to to_markdown/2 with no options.

@type open_opts() :: [{:password, String.t()}]

Options accepted by open/2, open!/2, from_binary/2, and from_binary!/2.

• :password — password used to authenticate against an encrypted PDF. When the password is wrong, the call returns {:error, %PdfElixide.Error{reason: :wrong_password}} (or raises, for the bang variants). When omitted or nil, no authentication attempt is made beyond pdf_oxide's built-in empty-password try.

To check a password against an already-open document without treating a wrong one as an error, use authenticate/2, which returns {:ok, false} rather than a :wrong_password error.

@type region_mode() :: :intersects | :fully_contained | {:min_overlap, float()}

How a :region (or :exclude_regions) decides whether an object is inside it.

• :intersects — any overlap at all counts. The default, and what pdf_oxide uses everywhere it does not take a mode.
• :fully_contained — the object's bounding box must lie entirely within the region.
• {:min_overlap, ratio} — at least ratio of the object's area must lie within the region.

:min_overlap details

ratio must be between 0.0 and 1.0; anything outside that range is {:error, %PdfElixide.Error{reason: :other}}. The bound is checked here rather than upstream, which validates it nowhere — no other pdf_oxide binding can even select this mode, so an out-of-range value would otherwise fail silently and wrongly (a negative one matches every object, and one above 1.0 matches none).

Two behaviors worth knowing before choosing a value:

• The fraction is of the object's own area, not the region's. A large element clipped by a small region scores low however much of the region it covers, so :min_overlap answers "how much of this object is in the region?", never the reverse.
• {:min_overlap, 0.0} matches everything, including objects that do not touch the region at all — a non-overlapping object scores 0.0, and the comparison is >=. Use :intersects if you meant "any overlap".

@type span_merging_opts() :: [
  preset: :default | :aggressive | :conservative | :adaptive | :legacy,
  space_threshold_em_ratio: float() | nil,
  conservative_threshold_pt: float() | nil,
  column_boundary_threshold_pt: float() | nil,
  severe_overlap_threshold_pt: float() | nil,
  use_adaptive_threshold: boolean() | nil,
  adaptive: keyword() | nil,
  detect_email_patterns: boolean() | nil,
  email_threshold_multiplier: float() | nil,
  detect_citation_markers: boolean() | nil,
  citation_font_size_ratio: float() | nil,
  merge_tm_tj_runs: boolean() | nil
]

Options tuning how glyph runs are merged into spans, accepted as :span_merging. pdf_oxide's own bindings expose none of this.

• :preset — the base configuration every other key overrides: :default, :aggressive (merges across wider gaps), :conservative (splits more readily), :adaptive (derives thresholds from page gap statistics), or :legacy. Defaults to :default.
• :space_threshold_em_ratio — gap, as a fraction of font size, that becomes a space.
• :conservative_threshold_pt — floor gap in points below which no space is inserted.
• :column_boundary_threshold_pt — gap in points treated as a column break rather than a space.
• :severe_overlap_threshold_pt — negative gap indicating real glyph overlap.
• :use_adaptive_threshold — derive the space threshold from page gap statistics.
• :adaptive — a keyword list tuning that derivation: :median_multiplier, :min_threshold_pt, :max_threshold_pt, :use_iqr, :min_samples. Only consulted when :use_adaptive_threshold resolves to true.
• :detect_email_patterns / :email_threshold_multiplier — keep addresses from being split at the @.
• :detect_citation_markers / :citation_font_size_ratio — treat small raised runs as citation markers.
• :merge_tm_tj_runs — when false, every text-matrix operator starts a fresh span.

Every key except :preset defaults to nil, meaning "keep the preset's value".

@type spans_opts() :: [
  reading_order: :top_to_bottom | :column_aware | :structure,
  span_merging: span_merging_opts() | nil,
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  exclude_layers: [String.t()],
  exclude_inks: [String.t()]
]

Options accepted by the spans and spans! functions.

• :reading_order — how spans are ordered: :top_to_bottom (simple geometric sorting), :column_aware (XY-cut column detection), or :structure (follow a tagged PDF's structure tree). Defaults to :top_to_bottom. This is pdf_oxide's span-level reading order and names its values differently from the :reading_order of markdown_opts/0, which is a separate upstream type.
• :span_merging — a span_merging_opts/0 keyword list, or nil for upstream's default merging. Defaults to nil.
• :region — a PdfElixide.Geometry.Rect keeping only the spans inside it. Defaults to nil.
• :region_mode — how :region matches; see region_mode/0. Defaults to :intersects.
• :exclude_layers — names of optional-content (OCG) layers to suppress. Defaults to [].
• :exclude_inks — names of Separation/DeviceN inks to suppress. Defaults to [].

:span_merging drops the other options

Upstream serves a merging configuration through a call that accepts neither a reading order nor layer/ink filters. So when :span_merging is set, :reading_order, :exclude_layers and :exclude_inks are ignored. :region still applies — it is a post-filter, not an upstream argument.

@type t() :: %PdfElixide.Document{
  page_count: non_neg_integer() | nil,
  ref: reference(),
  source_path: Path.t() | nil,
  version: {non_neg_integer(), non_neg_integer()}
}

A handle on an open PDF document.

:version and :page_count arrive with the handle, from the same native call that opens the document, and are served from the struct thereafter, since both are immutable for a read-only document. A cached count cannot go stale: for an encrypted document upstream either fails or returns the real /Count, and authentication changes only whether the count is readable, never what it is.

:page_count is nil when the count could not be determined at open — an encrypted document whose page tree needs a password, opened without one — in which case page_count/1 asks the document instead.

@type table_detection_opts() :: [
  preset: :default | :strict | :relaxed,
  enabled: boolean() | nil,
  horizontal_strategy: :lines | :text | :both | nil,
  vertical_strategy: :lines | :text | :both | nil,
  column_tolerance: float() | nil,
  row_tolerance: float() | nil,
  min_table_cells: non_neg_integer() | nil,
  min_table_columns: non_neg_integer() | nil,
  regular_row_ratio: float() | nil,
  max_table_columns: non_neg_integer() | nil,
  column_merge_threshold: float() | nil,
  v_split_gap: float() | nil,
  text_fallback: boolean() | nil
]

Options tuning pdf_oxide's spatial table detector. Accepted directly by the tables functions, and as the :table_detection option of the text functions.

• :preset — the base configuration every other key overrides: :default, :strict (demands ruling lines and regular rows) or :relaxed (tolerant, text-driven). Defaults to :default.
• :horizontal_strategy / :vertical_strategy — what evidence delimits cells on that axis: :lines (ruling lines only), :text (glyph alignment only) or :both.
• :column_tolerance / :row_tolerance — coordinate slack in points when grouping cells into columns and rows.
• :min_table_cells / :min_table_columns — smallest grid accepted as a table.
• :max_table_columns — reject anything wider as a false positive.
• :regular_row_ratio — fraction of rows that must share the column count.
• :column_merge_threshold — slack for the post-clustering column merge pass.
• :v_split_gap — minimum gap between vertical-line groups that splits a cluster.
• :text_fallback — allow text-only detection when a page has no ruling lines. Ignored on the text path, where upstream forces it to false.
• :enabled — set to false to disable detection entirely.

Every key except :preset defaults to nil, meaning "keep the preset's value". The Python bindings' table_settings dict reaches only five of these.

@type tables_opts() :: [
  {:region, PdfElixide.Geometry.Rect.t() | nil} | {atom(), term()}
]

Options accepted by the tables and tables! functions: every table_detection_opts/0 key, plus

• :region — a PdfElixide.Geometry.Rect keeping only the tables overlapping it. Defaults to nil. There is no :region_mode: upstream filters tables by bounding-box intersection only.

Note that :region here keeps the detection options you passed, whereas pdf_oxide's own region call silently substitutes its :relaxed preset. Pass preset: :relaxed to ask for that explicitly.

@type text_lines_opts() :: [
  include_artifacts: boolean(),
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  word_gap_threshold: float() | nil,
  line_gap_threshold: float() | nil,
  profile: extraction_profile() | nil
]

Options accepted by the text_lines and text_lines! functions.

The same options as words_opts/0 — including the upstream deprecation of :word_gap_threshold and :profile documented there — plus:

• :line_gap_threshold — the vertical gap in points that starts a new line. nil lets upstream compute it. Defaults to nil, and is deprecated upstream alongside the other two.

@type text_opts() :: [
  extract_tables: boolean(),
  expand_ligatures: boolean(),
  table_detection: table_detection_opts() | nil,
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  exclude_regions: [PdfElixide.Geometry.Rect.t()],
  exclude_regions_mode: region_mode(),
  exclude_layers: [String.t()],
  exclude_inks: [String.t()],
  on_page_error: :skip | :halt
]

Options accepted by the text and text! functions.

• :extract_tables — detect tables and render them inline as space-padded, column-aligned rows. Defaults to true, matching pdf_oxide's own extract_text.
• :expand_ligatures — expand U+FB00–U+FB06 ligatures to their component letters (fi to fi, and so on). Defaults to false. Unlike in markdown_opts/0, this one is live: upstream applies it on the plain-text assembly path, which is exactly the path this function uses.
• :table_detection — a keyword list tuning the spatial table detector; see table_detection_opts/0. Only consulted when :extract_tables is true, and its :text_fallback key is ignored here — upstream forces it to false on the text path, so a page with no ruling lines yields no tables regardless. Defaults to nil (the upstream default config).
• :region — a PdfElixide.Geometry.Rect keeping only the text inside it. An extracted bbox can be handed straight back in. Defaults to nil.
• :region_mode — how :region matches; see region_mode/0. Defaults to :intersects.
• :exclude_regions — a list of rects whose text is dropped. Applied before :region, so exclusion wins. Defaults to [].
• :exclude_regions_mode — how :exclude_regions match. Defaults to :intersects.
• :exclude_layers — names of optional-content (OCG) layers to suppress. Defaults to [].
• :exclude_inks — names of Separation/DeviceN inks to suppress. Defaults to [].
• :on_page_error — what a page that fails to extract does to the whole-document result: :skip it (the default) or :halt, failing the call with the first page's error. See below.

:on_page_error and partly extractable documents

Read only on the whole-document arity. text/3 and PdfElixide.Document.Page.text/2 extract one page and always return its error, so the option is accepted and ignored there.

:skip matches pdf_oxide's extract_all_text, which is why it is the default: a failed page contributes an empty string, the page separator is emitted for it either way, and the call still returns {:ok, text} with content silently missing. That is the wrong default for an indexing, archival or compliance pipeline, where a document that lost a page must not look like one that never had it — :halt gives those callers {:error, %PdfElixide.Error{}} instead, with the failing page's zero-based index prefixed to the message.

Note that :halt is not a general corruption detector: upstream degrades almost every damaged page to empty text rather than an error — an undecodable content stream, missing fonts, a scan with no text layer and an undecryptable document all extract as "". What remains, and all :halt can catch, is a page whose page-tree entry cannot be resolved at all. Most other whole-document extractors (chars/1, words/1, text_lines/1, spans/1, paths/1, images/1, annotations/1, tables/1) fail the call on such a page unconditionally, having no upstream counterpart whose policy they must match.

fonts/1 is the exception, and it needs no option: it does have an upstream counterpart — PdfDocument::page_font_face_lookups — and follows its policy, so an unresolvable page contributes no fonts and the document still succeeds. fonts/1 and fonts/2 document what that makes an empty list mean.

Layer and ink filtering drops the other options

pdf_oxide serves layer and ink filtering only through extract_text_filtered / extract_text_filtered_in_rect, which build their own conversion options internally and offer no way to pass ours. So when :exclude_layers or :exclude_inks is non-empty, only :region and :region_mode still apply — :extract_tables, :expand_ligatures, :table_detection, :exclude_regions and :exclude_regions_mode fall back to their upstream defaults (:extract_tables to true, the rest to off). The Python bindings have the same limitation and do not document it.

Options to_markdown/2 accepts but this function does not — :reading_order, :include_form_fields, :strip_running_headers_footers — are omitted because upstream's text assembler never reads them. Like any other undeclared key, passing one is silently ignored.

@type words_opts() :: [
  include_artifacts: boolean(),
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  word_gap_threshold: float() | nil,
  profile: extraction_profile() | nil
]

Options accepted by the words and words! functions.

• :include_artifacts — keep spans tagged /Artifact (running headers and footers, page numbers, watermarks; ISO 32000-1 §14.8.2.2.1). Defaults to true, which is the current behavior and what the Python bindings default to; false selects upstream's spec-correct variant.
• :region — a PdfElixide.Geometry.Rect keeping only the words inside it. Defaults to nil.
• :region_mode — how :region matches; see region_mode/0. Defaults to :intersects.
• :word_gap_threshold — the inter-glyph gap in points that starts a new word. nil lets upstream compute it adaptively from page statistics (median character width × 0.3). Defaults to nil.
• :profile — a extraction_profile/0, or nil for none. Defaults to nil.

:word_gap_threshold and :profile are deprecated upstream

pdf_oxide plans to move both to a separate advanced API (its Python bindings already emit a DeprecationWarning for them), and :profile in particular is documented as pending removal. :profile also does more than its name suggests: passing any profile switches span extraction to a different, legacy ordering path (XY-cut plus a row-aware sort), so it can change word order and not merely word boundaries — even for :conservative, which is nominally the default profile. Prefer leaving both at nil.

Unlike the Python bindings, :region here composes with everything else: it is applied after extraction, so it does not discard the thresholds or the profile.