API Reference

LiteParse — open-source PDF parsing with spatial text extraction, OCR, and bounding boxes.

This crate is the core Rust library. Language bindings for Node.js, Python, and WebAssembly re-export the same types with language-idiomatic wrappers.

Struct LiteParseConfig

Configuration for LiteParse document parsing.

pub struct LiteParseConfig {
    pub ocr_language: String,
    pub ocr_enabled: bool,
    pub ocr_server_url: Option<String>,
    pub ocr_server_headers: Vec<(String, String)>,
    pub tessdata_path: Option<String>,
    pub max_pages: usize,
    pub target_pages: Option<String>,
    pub dpi: f32,
    pub output_format: OutputFormat,
    pub preserve_very_small_text: bool,
    pub password: Option<String>,
    pub quiet: bool,
    pub num_workers: usize,
    pub image_mode: ImageMode,
    pub extract_links: bool,
}

Fields

Name	Type	Documentation
ocr_language	String	OCR language code (Tesseract format: “eng”, “fra”, “deu”, etc.).
ocr_enabled	bool	Whether OCR is enabled. When true, runs on text-sparse pages and embedded images.
ocr_server_url	Option<String>	HTTP OCR server URL (uses Tesseract if not provided)
ocr_server_headers	Vec<(String, String)>	Extra HTTP headers sent with every request to ocr_server_url, as (name, value) pairs. Use for auth, e.g. ("Authorization", "Bearer …"). Ignored when ocr_server_url is None.
tessdata_path	Option<String>	Path to tessdata directory. Falls back to TESSDATA_PREFIX env var if not set.
max_pages	usize	Maximum number of pages to parse.
target_pages	Option<String>	Specific pages to parse (e.g., “1-5,10,15-20”). None means all pages.
dpi	f32	DPI for rendering pages (used for OCR and screenshots).
output_format	OutputFormat	Output format.
preserve_very_small_text	bool	Keep very small text that would normally be filtered out.
password	Option<String>	Password for encrypted/protected documents.
quiet	bool	Suppress progress output.
num_workers	usize	Number of concurrent OCR workers. Defaults to (number of CPU cores - 1), minimum 1.
image_mode	ImageMode	Controls how raster images are surfaced in markdown output. Has no effect on JSON / text outputs.
extract_links	bool	Extract hyperlink annotations and render them as [text](url) in markdown output. Default on. Disable for benchmark parity with plain-text ground truth (the GT corpora never use link syntax).

Enum ImageMode

Attributes:

• Other("#[serde(rename_all = \"lowercase\")]")

Image handling for the markdown emitter.

• Off — strip image references entirely.
• Placeholder (default) — emit ![](image_pN_K.png) references in reading order at each image’s y position, but do not extract or return pixel bytes. Keeps response size small while letting the LLM see where figures live in the document.
• Embed — same references, plus bytes returned via ParseResult.images. Opt-in because pixel bytes can dwarf the text payload on image-heavy PDFs. (Bytes plumbing lands in stage 11b — current variant is parsed but behaves like Placeholder until then.)

pub enum ImageMode {
    Off,
    Placeholder,
    Embed,
}

Variants

Off

Placeholder

Embed

Enum OutputFormat

Attributes:

• Other("#[serde(rename_all = \"lowercase\")]")

Supported output formats.

pub enum OutputFormat {
    Json,
    Text,
    Markdown,
}

Variants

Json

Text

Markdown

Enum LiteParseError

pub enum LiteParseError {
    Pdf(pdfium::PdfiumError),
    Io(std::io::Error),
    Json(serde_json::Error),
    Image(image::ImageError),
    Ocr(String),
    Conversion(String),
    Config(String),
    Other(String),
}

Variants

Pdf(pdfium::PdfiumError)

Io(std::io::Error)

Json(serde_json::Error)

Image(image::ImageError)

Ocr(String)

Conversion(String)

Config(String)

Other(String)

Struct ParseResult

Result of parsing a document.

pub struct ParseResult {
    pub pages: Vec<crate::types::ParsedPage>,
    pub text: String,
    pub outline: Vec<crate::types::OutlineTarget>,
    pub images: Vec<crate::types::ExtractedImage>,
}

Fields

Name	Type	Documentation
pages	Vec<crate::types::ParsedPage>	Parsed pages with projected text layout.
text	String	Full document text, concatenated from all pages.
outline	Vec<crate::types::OutlineTarget>	Document outline (bookmarks) when present. Used by the markdown emitter as a high-priority heading source on untagged PDFs.
images	Vec<crate::types::ExtractedImage>	Raster images extracted from the document. Empty unless the parser was configured with ImageMode::Embed. Each entry carries the same id the markdown emitter referenced in , so the caller can match them up without parsing markdown.

Struct ScreenshotResult

Result of rendering a single page screenshot.

pub struct ScreenshotResult {
    pub page_num: u32,
    pub width: u32,
    pub height: u32,
    pub image_bytes: Vec<u8>,
}

Fields

Name	Type	Documentation
page_num	u32
width	u32
height	u32
image_bytes	Vec<u8>

Struct LiteParse

Main LiteParse orchestrator.

Thread safety

LiteParse is Send + Sync and safe to share across threads (e.g. behind an Arc, or used concurrently from a multi-threaded tokio runtime).

PDFium itself is not thread-safe, so all PDFium FFI work — document loading, page rendering, text extraction — is serialized through a process-global lock held by [pdfium::Library]. From a caller’s perspective, this means concurrent parse_* / screenshot* calls are safe but their PDFium portions run sequentially. The OCR pass and grid projection (which dominate runtime for OCR-heavy documents) run outside the lock and remain fully concurrent.

pub struct LiteParse {
    // Some fields omitted
}

Methods

• pub fn new(config: LiteParseConfig) -> Self { /* ... */ }

• pub fn with_ocr_engine(self: Self, engine: std::sync::Arc<dyn OcrEngine>) -> Self { /* ... */ }

  Override the OCR engine. When set, the engine is used regardless of

• pub async fn is_complex(self: &Self, input: PdfInput) -> Result<Vec<ocr_merge::PageComplexityStats>, LiteParseError> { /* ... */ }

  Determine the complexity of each page in a document, returning a vector

• pub async fn parse(self: &Self, input: &str) -> Result<ParseResult, LiteParseError> { /* ... */ }

  Parse a document from a file path, returning structured results.

• pub async fn parse_input(self: &Self, input: PdfInput) -> Result<ParseResult, LiteParseError> { /* ... */ }

  Parse a document from either a file path or raw bytes.

• pub fn parse_from_pages(self: &Self, pages: Vec<Page>, outline: Vec<OutlineTarget>) -> ParseResult { /* ... */ }

  Parse from pre-extracted pages, skipping PDFium text extraction.

• pub async fn screenshot(self: &Self, input: &str, page_numbers: Option<Vec<u32>>) -> Result<Vec<ScreenshotResult>, LiteParseError> { /* ... */ }

  Generate screenshots of document pages as PNG bytes.

• pub async fn screenshot_input(self: &Self, input: PdfInput, page_numbers: Option<Vec<u32>>) -> Result<Vec<ScreenshotResult>, LiteParseError> { /* ... */ }

  Generate screenshots from a file path or raw bytes.

• pub fn config(self: &Self) -> &LiteParseConfig { /* ... */ }

Struct SearchOptions

Options for searching text items.

pub struct SearchOptions {
    pub phrase: String,
    pub case_sensitive: bool,
}

Fields

Name	Type	Documentation
phrase	String
case_sensitive	bool

Function search_items

Search text items for phrase matches, returning synthetic merged items.

Consecutive text items are concatenated and searched. When a phrase spans multiple items, the result is a single merged item with a combined bounding box and the matched text. Font metadata is taken from the first matched item.

pub fn search_items(items: &[crate::types::TextItem], options: &SearchOptions) -> Vec<crate::types::TextItem> { /* ... */ }

Struct TextItem

Represents a single text item extracted from a PDF page, including its content, position, size, rotation, and font metadata.

pub struct TextItem {
    pub text: String,
    pub x: f32,
    pub y: f32,
    pub width: f32,
    pub height: f32,
    pub rotation: f32,
    pub font_name: Option<String>,
    pub font_size: Option<f32>,
    pub font_height: Option<f32>,
    pub font_ascent: Option<f32>,
    pub font_descent: Option<f32>,
    pub font_weight: Option<i32>,
    pub font_flags: Option<i32>,
    pub text_width: Option<f32>,
    pub font_is_buggy: bool,
    pub has_unicode_map_error: bool,
    pub mcid: Option<i32>,
    pub fill_color: Option<String>,
    pub stroke_color: Option<String>,
    pub confidence: Option<f32>,
    pub link: Option<String>,
    pub strike: bool,
}

Fields

Name	Type	Documentation
text	String
x	f32	Viewport-space coordinates (top-left origin, 72 DPI).
y	f32
width	f32
height	f32
rotation	f32	Rotation in degrees (counter-clockwise, adjusted for page rotation).
font_name	Option<String>
font_size	Option<f32>
font_height	Option<f32>	Font size * scale_y from the text matrix — accounts for CTM scaling.
font_ascent	Option<f32>
font_descent	Option<f32>
font_weight	Option<i32>
font_flags	Option<i32>
text_width	Option<f32>	Sum of glyph widths (using charcode-based lookup when possible).
font_is_buggy	bool	Whether the font has buggy encoding (private-use codepoints, TT subset, etc.)
has_unicode_map_error	bool	Whether most characters in this item could not be mapped to Unicode (e.g. a Type3 font with no ToUnicode map). The text content is PDFium’s char-code fallback and does not reflect the rendered glyphs.
mcid	Option<i32>	Marked content ID from the PDF structure tree.
fill_color	Option<String>	Fill color as ARGB hex string (e.g. “ff000000”).
stroke_color	Option<String>	Stroke color as ARGB hex string.
confidence	Option<f32>	OCR confidence score (0.0–1.0). None for native PDF text.
link	Option<String>	Target URI when this item falls inside a hyperlink annotation’s rectangle. Populated in extract.rs; consumed by the markdown emitter.
strike	bool	Whether a thin horizontal stroke/rect crosses this item’s vertical middle band (a strikethrough line). Populated in extract.rs; consumed by the markdown emitter to wrap the text in ~~…~~.

Struct ParsedPage

Represents a fully parsed page with projected text layout.

pub struct ParsedPage {
    pub page_number: usize,
    pub page_width: f32,
    pub page_height: f32,
    pub text: String,
    pub text_items: Vec<TextItem>,
    pub projected_lines: Vec<ProjectedLine>,
    pub regions: Region,
    pub graphics: Vec<GraphicPrimitive>,
    pub figures: Vec<Rect>,
    pub struct_nodes: Vec<StructNode>,
    pub image_refs: Vec<ImageRef>,
}

Fields

Name	Type	Documentation
page_number	usize
page_width	f32
page_height	f32
text	String
text_items	Vec<TextItem>
projected_lines	Vec<ProjectedLine>	Per-line structural metadata used by the markdown emitter. Not part of the JSON/text outputs (consumed internally) so it is #[serde(skip)].
regions	Region	Root of the XY-cut region tree for this page. Leaves correspond to the region_path on each ProjectedLine. Internal-only.
graphics	Vec<GraphicPrimitive>	Vector graphics on the page (decomposed paths) used by the markdown emitter for ruled-table / HR / figure-cluster detection. Not part of the JSON/text output.
figures	Vec<Rect>	Figure-region bounding rectangles derived from graphics. Pre-computed in to_parsed_pages so the XY-cut layout pass can treat them as obstacles, and reused downstream for figure classification.
struct_nodes	Vec<StructNode>	Structure-tree nodes for this page (tagged PDFs only). Pre-flattened in pre-order. Consumed by the markdown classifier for highest-priority heading / figure / table detection.
image_refs	Vec<ImageRef>	Raster image objects on the page. Bbox in viewport coords. Populated during extraction; consumed by the markdown emitter to interleave Block::Figure references at the right y position. Empty when the page has no embedded images. Not part of JSON/text output.

Struct ExtractedImage

A raster image extracted from a page along with its pixel bytes. Surfaced on ParseResult.images only when ImageMode::Embed is configured — otherwise the extraction step skips the render and only ImageRefs are produced. format is currently always "png" (encoded from the FPDFImageObj_GetRenderedBitmap output via the same path used for page screenshots).

pub struct ExtractedImage {
    pub id: String,
    pub page: u32,
    pub bbox: Rect,
    pub format: String,
    pub bytes: Vec<u8>,
}

Fields

Name	Type	Documentation
id	String
page	u32
bbox	Rect
format	String
bytes	Vec<u8>