A fast, helpful, and open-source document parser
feat: return screenshots from parse
Pierre-Loic doulcetbcd8d7751f09
diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rsindex a2ee1ae..764557a 100644--- a/crates/liteparse-napi/src/types.rs+++ b/crates/liteparse-napi/src/types.rs@@ -32,6 +32,9 @@ pub struct JsLiteParseConfig {pub max_pages: Option<u32>,/// Specific pages to parse (e.g., "1-5,10,15-20").pub target_pages: Option<String>,+ /// Render parsed pages to PNG and return them in `ParseResult.screenshots`.+ /// Default false; PNG payloads can be large.+ pub extract_screenshots: Option<bool>,/// DPI for rendering pages (used for OCR and screenshots).pub dpi: Option<f64>,/// Output format: "json", "text", or "markdown".@@ -145,6 +148,9 @@ impl JsLiteParseConfig {if let Some(v) = self.target_pages {cfg.target_pages = Some(v);}+ if let Some(v) = self.extract_screenshots {+ cfg.extract_screenshots = v;+ }if let Some(v) = self.dpi {cfg.dpi = v as f32;}@@ -255,6 +261,7 @@ impl JsLiteParseConfig {tessdata_path: cfg.tessdata_path.clone(),max_pages: Some(cfg.max_pages as u32),target_pages: cfg.target_pages.clone(),+ extract_screenshots: Some(cfg.extract_screenshots),dpi: Some(cfg.dpi as f64),output_format: Some(match cfg.output_format {OutputFormat::Json => "json".to_string(),@@ -884,6 +891,7 @@ pub struct JsParseResult {pub pages: Vec<JsParsedPage>,pub text: String,pub images: Vec<JsExtractedImage>,+ pub screenshots: Vec<JsScreenshotResult>,pub image_error_count: u32,pub form_type: Option<i32>,/// The document's `/Info` `Creator` entry, when present.@@ -1031,6 +1039,23 @@ impl JsScreenshotRect {}}+impl JsScreenshotResult {+ pub fn from_rust(result: &liteparse::parser::ScreenshotResult) -> Self {+ Self {+ page_num: result.page_num,+ width: result.width,+ height: result.height,+ image_buffer: result.image_bytes.clone().into(),+ is_solid_fill: result.is_solid_fill,+ rects: result+ .rects+ .iter()+ .map(JsScreenshotRect::from_rust)+ .collect(),+ }+ }+}+#[napi(object)]#[derive(Clone)]pub struct JsLayoutComplexityStats {@@ -1162,6 +1187,11 @@ impl JsParseResult {bytes: img.bytes.as_slice().to_vec().into(),}).collect(),+ screenshots: result+ .screenshots+ .iter()+ .map(JsScreenshotResult::from_rust)+ .collect(),}}}diff --git a/crates/liteparse-python/src/lib.rs b/crates/liteparse-python/src/lib.rsindex 2859a2c..9d3fee7 100644--- a/crates/liteparse-python/src/lib.rs+++ b/crates/liteparse-python/src/lib.rs@@ -603,6 +603,8 @@ struct PyParseResult {#[pyo3(get)]images: Vec<PyExtractedImage>,#[pyo3(get)]+ screenshots: Vec<PyScreenshotResult>,+ #[pyo3(get)]image_error_count: u32,#[pyo3(get)]form_type: Option<i32>,@@ -729,6 +731,11 @@ impl PyParseResult {.into_iter().map(PyExtractedImage::from_rust).collect(),+ screenshots: result+ .screenshots+ .into_iter()+ .map(PyScreenshotResult::from_rust)+ .collect(),image_error_count: result.image_error_count,form_type: result.form_type,creator: result.creator,@@ -874,6 +881,30 @@ impl PyScreenshotRect {}}+impl PyScreenshotResult {+ fn from_rust(result: liteparse::parser::ScreenshotResult) -> Self {+ Self {+ page_num: result.page_num,+ width: result.width,+ height: result.height,+ image_buffer: result.image_bytes,+ is_solid_fill: result.is_solid_fill,+ rects: result+ .rects+ .into_iter()+ .map(|rect| PyScreenshotRect {+ x: rect.x as f64,+ y: rect.y as f64,+ width: rect.width as f64,+ height: rect.height as f64,+ color: rect.color,+ is_line: rect.is_line,+ })+ .collect(),+ }+ }+}+#[pymethods]impl PyScreenshotResult {#[getter]@@ -1044,6 +1075,8 @@ struct PyLiteParseConfig {#[pyo3(get)]target_pages: Option<String>,#[pyo3(get)]+ extract_screenshots: bool,+ #[pyo3(get)]dpi: f32,#[pyo3(get)]output_format: String,@@ -1123,6 +1156,7 @@ impl PyLiteParseConfig {tessdata_path: cfg.tessdata_path.clone(),max_pages: cfg.max_pages,target_pages: cfg.target_pages.clone(),+ extract_screenshots: cfg.extract_screenshots,dpi: cfg.dpi,output_format: match cfg.output_format {OutputFormat::Json => "json".to_string(),@@ -1188,6 +1222,7 @@ impl LiteParse {tessdata_path = None,max_pages = None,target_pages = None,+ extract_screenshots = None,dpi = None,output_format = None,preserve_very_small_text = None,@@ -1224,6 +1259,7 @@ impl LiteParse {tessdata_path: Option<String>,max_pages: Option<usize>,target_pages: Option<String>,+ extract_screenshots: Option<bool>,dpi: Option<f32>,output_format: Option<String>,preserve_very_small_text: Option<bool>,@@ -1274,6 +1310,9 @@ impl LiteParse {if let Some(v) = target_pages {cfg.target_pages = Some(v);}+ if let Some(v) = extract_screenshots {+ cfg.extract_screenshots = v;+ }if let Some(v) = dpi {cfg.dpi = v;}diff --git a/crates/liteparse/src/config.rs b/crates/liteparse/src/config.rsindex a33db5e..1c91bca 100644--- a/crates/liteparse/src/config.rs+++ b/crates/liteparse/src/config.rs@@ -19,6 +19,10 @@ pub struct LiteParseConfig {pub max_pages: usize,/// Specific pages to parse (e.g., "1-5,10,15-20"). None means all pages.pub target_pages: Option<String>,+ /// Render parsed pages to PNG and return them in `ParseResult.screenshots`.+ /// Default `false`; PNG payloads can be large.+ #[serde(default)]+ pub extract_screenshots: bool,/// DPI for rendering pages (used for OCR and screenshots).pub dpi: f32,/// Output format.@@ -213,6 +217,7 @@ impl Default for LiteParseConfig {tessdata_path: None,max_pages: 1000,target_pages: None,+ extract_screenshots: false,dpi: 150.0,output_format: OutputFormat::Json,preserve_very_small_text: false,@@ -353,6 +358,7 @@ mod tests {// OCR defaults on only when a built-in engine is compiled in.assert_eq!(c.ocr_enabled, cfg!(feature = "tesseract"));assert_eq!(c.max_pages, 1000);+ assert!(!c.extract_screenshots);assert_eq!(c.dpi, 150.0);assert_eq!(c.output_format, OutputFormat::Json);assert!(!c.preserve_very_small_text);diff --git a/crates/liteparse/src/output/json.rs b/crates/liteparse/src/output/json.rsindex bccbf76..e1196f2 100644--- a/crates/liteparse/src/output/json.rs+++ b/crates/liteparse/src/output/json.rs@@ -391,6 +391,7 @@ mod tests {text: String::new(),outline: vec![],images: vec![image],+ screenshots: vec![],image_error_count: 2,form_type: None,creator: Some("LibreOffice".into()),diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rsindex 772c186..31b7501 100644--- a/crates/liteparse/src/parser.rs+++ b/crates/liteparse/src/parser.rs@@ -33,6 +33,9 @@ pub struct ParseResult {/// `id` and `format` the markdown emitter referenced, so the caller can/// match them up without parsing markdown.pub images: Vec<ExtractedImage>,+ /// Page screenshots encoded as PNG. Empty unless `extract_screenshots`+ /// is enabled.+ pub screenshots: Vec<ScreenshotResult>,/// Number of embedded image objects that could not be extracted. A bad/// image does not fail the rest of the document parse.pub image_error_count: u32,@@ -444,6 +447,7 @@ impl LiteParse {ocr_rendered,outline,mut images,+ screenshots,image_error_count,complexity,form_type,@@ -544,8 +548,9 @@ impl LiteParse {// widget appearances into page content, so the raster is the same// either way. Complexity likewise runs on the flattened document// by design (see `is_complex`).- let needs_pristine_document =- flattened_form_widgets && self.config.ocr_enabled && self.config.render_form_fields;+ let needs_pristine_document = flattened_form_widgets+ && (self.config.ocr_enabled || self.config.extract_screenshots)+ && self.config.render_form_fields;let pristine_document = needs_pristine_document.then(|| extract::load_document_from_input(&lib, document_input, password)).transpose()?;@@ -588,12 +593,41 @@ impl LiteParse {} else {Vec::new()};+ #[cfg(not(target_arch = "wasm32"))]+ let screenshots = if self.config.extract_screenshots {+ let page_numbers = pages+ .iter()+ .map(|page| page.page_number as u32)+ .collect::<Vec<_>>();+ render::render_document_pages(+ analysis_document,+ Some(&page_numbers),+ self.config.dpi,+ self.config.detect_screenshot_rects,+ self.config.render_form_fields,+ )?+ .into_iter()+ .map(|page| ScreenshotResult {+ page_num: page.page_num,+ width: page.width,+ height: page.height,+ image_bytes: page.png_bytes,+ is_solid_fill: page.is_solid_fill,+ rects: page.rects,+ })+ .collect()+ } else {+ Vec::new()+ };+ #[cfg(target_arch = "wasm32")]+ let screenshots = Vec::new();// `lib` is dropped here, releasing the PDFium lock.(pages,rendered,outline,images,+ screenshots,image_error_count,complexity,form_type,@@ -691,6 +725,7 @@ impl LiteParse {text: full_text,outline,images,+ screenshots,image_error_count,form_type,creator,@@ -736,6 +771,7 @@ impl LiteParse {text: full_text,outline,images: Vec::new(),+ screenshots: Vec::new(),image_error_count: 0,form_type: None,creator: None,diff --git a/crates/liteparse/src/render.rs b/crates/liteparse/src/render.rsindex d8c961f..4a7ee70 100644--- a/crates/liteparse/src/render.rs+++ b/crates/liteparse/src/render.rs@@ -49,7 +49,7 @@ pub fn render_pages_to_png()}-fn render_document_pages(+pub(crate) fn render_document_pages(document: &pdfium::Document,page_numbers: Option<&[u32]>,dpi: f32,diff --git a/crates/liteparse/tests/integration_test.rs b/crates/liteparse/tests/integration_test.rsindex fea5dea..3a8747e 100644--- a/crates/liteparse/tests/integration_test.rs+++ b/crates/liteparse/tests/integration_test.rs@@ -39,6 +39,31 @@ async fn test_screenshot_pdf_integration() {assert!(!results[0].image_bytes.is_empty());}+#[tokio::test]+#[serial]+async fn test_parse_can_return_screenshots() {+ let lit = LiteParse::new(LiteParseConfig {+ ocr_enabled: false,+ extract_screenshots: true,+ ..LiteParseConfig::default()+ });+ let parsed = lit+ .parse("../../integration_tests_data/sample.pdf")+ .await+ .expect("Should parse and render PDF pages");++ assert_eq!(parsed.screenshots.len(), parsed.pages.len());+ assert_eq!(+ parsed.screenshots[0].page_num,+ parsed.pages[0].page_number as u32+ );+ assert!(+ parsed.screenshots[0]+ .image_bytes+ .starts_with(b"\x89PNG\r\n\x1a\n")+ );+}+#[tokio::test]async fn test_screenshot_rejects_text_file() {let dir = tempfile::tempdir().unwrap();diff --git a/packages/node/README.md b/packages/node/README.mdindex 12b4e60..e9c3b73 100644--- a/packages/node/README.md+++ b/packages/node/README.md@@ -55,6 +55,7 @@ const parser = new LiteParse({tessdataPath: undefined, // Path to tessdata directory (optional)maxPages: 1000, // Max pages to parsetargetPages: '1-5,10', // Specific pages (optional)+ extractScreenshots: false, // Return parsed pages as PNG buffersdpi: 150, // Rendering DPIoutputFormat: 'json', // "json" | "text" | "markdown"imageMode: 'placeholder', // Markdown image handling: "placeholder" | "off" | "embed"diff --git a/packages/node/native.d.ts b/packages/node/native.d.tsindex db77ecc..6a37ce9 100644--- a/packages/node/native.d.ts+++ b/packages/node/native.d.ts@@ -21,6 +21,11 @@ export interface JsLiteParseConfig {maxPages?: number/** Specific pages to parse (e.g., "1-5,10,15-20"). */targetPages?: string+ /**+ * Render parsed pages to PNG and return them in `ParseResult.screenshots`.+ * Default false; PNG payloads can be large.+ */+ extractScreenshots?: boolean/** DPI for rendering pages (used for OCR and screenshots). */dpi?: number/** Output format: "json", "text", or "markdown". */@@ -314,6 +319,7 @@ export interface JsParseResult {pages: Array<JsParsedPage>text: stringimages: Array<JsExtractedImage>+ screenshots: Array<JsScreenshotResult>imageErrorCount: numberformType?: number/** The document's `/Info` `Creator` entry, when present. */diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.tsindex cd49388..4df0fe5 100644--- a/packages/node/src/lib.ts+++ b/packages/node/src/lib.ts@@ -9,6 +9,7 @@ import {type NativeExtractedImage,type NativeStructureTreeElement,type NativePageComplexityStats,+ type NativeScreenshotResult,} from "./native.js";// ---------------------------------------------------------------------------@@ -28,6 +29,8 @@ export interface LiteParseConfig {tessdataPath?: string;maxPages: number;targetPages?: string;+ /** Render parsed pages to PNG and return them in `ParseResult.screenshots`. */+ extractScreenshots: boolean;dpi: number;outputFormat: OutputFormat;/** How to surface raster images in markdown output (default: "placeholder"). */@@ -351,6 +354,8 @@ export interface ParseResult {text: string;/** Populated only when `extractImages` is true. */images: ExtractedImage[];+ /** PNG screenshots of parsed pages when `extractScreenshots` is enabled. */+ screenshots: ScreenshotResult[];/** Embedded image objects that PDFium could not render or encode. */imageErrorCount: number;/** PDFium form type, present only when `extractFormFields` is enabled. */@@ -531,6 +536,7 @@ export class LiteParse {tessdataPath: userConfig.tessdataPath,maxPages: userConfig.maxPages,targetPages: userConfig.targetPages,+ extractScreenshots: userConfig.extractScreenshots,dpi: userConfig.dpi,outputFormat: userConfig.outputFormat,imageMode: userConfig.imageMode,@@ -572,6 +578,7 @@ export class LiteParse {tessdataPath: resolved.tessdataPath ?? undefined,maxPages: resolved.maxPages ?? 1000,targetPages: resolved.targetPages ?? undefined,+ extractScreenshots: resolved.extractScreenshots ?? false,dpi: resolved.dpi ?? 150,outputFormat: (resolved.outputFormat as OutputFormat) ?? "json",imageMode: (resolved.imageMode as ImageMode) ?? "placeholder",@@ -611,6 +618,7 @@ export class LiteParse {pages: result.pages.map(toPage),text: result.text,images: (result.images ?? []).map(toImage),+ screenshots: (result.screenshots ?? []).map(toScreenshot),imageErrorCount: result.imageErrorCount ?? 0,formType: result.formType,creator: result.creator,@@ -639,6 +647,7 @@ export class LiteParse {pages: result.pages.map(toPage),text: result.text,images: (result.images ?? []).map(toImage),+ screenshots: (result.screenshots ?? []).map(toScreenshot),imageErrorCount: result.imageErrorCount ?? 0,docMeta: result.docMeta,};@@ -791,6 +800,17 @@ function toImage(img: NativeExtractedImage): ExtractedImage {};}+function toScreenshot(result: NativeScreenshotResult): ScreenshotResult {+ return {+ pageNum: result.pageNum,+ width: result.width,+ height: result.height,+ imageBuffer: result.imageBuffer,+ isSolidFill: result.isSolidFill,+ rects: result.rects,+ };+}+function toTextItem(item: NativeTextItem): TextItem {return {text: item.text,diff --git a/packages/node/src/native.ts b/packages/node/src/native.tsindex 874a1bf..00c0015 100644--- a/packages/node/src/native.ts+++ b/packages/node/src/native.ts@@ -27,6 +27,7 @@ export interface LiteParseNativeConfig {tessdataPath?: string;maxPages?: number;targetPages?: string;+ extractScreenshots?: boolean;dpi?: number;outputFormat?: string;imageMode?: string;@@ -237,6 +238,7 @@ export interface NativeParseResult {pages: NativeParsedPage[];text: string;images: NativeExtractedImage[];+ screenshots: NativeScreenshotResult[];imageErrorCount: number;formType?: number;creator?: string;diff --git a/packages/python/README.md b/packages/python/README.mdindex 594e113..bef05ae 100644--- a/packages/python/README.md+++ b/packages/python/README.md@@ -54,6 +54,7 @@ parser = LiteParse(tessdata_path=None, # Path to tessdata directory (optional)max_pages=1000, # Max pages to parsetarget_pages="1-5,10", # Specific pages (optional)+ extract_screenshots=False, # Return parsed pages as PNG bytesdpi=150, # Rendering DPIoutput_format="json", # "json" | "text" | "markdown"image_mode="placeholder", # Markdown image handling: "placeholder" | "off" | "embed"diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.pyindex a2b27b4..62eed93 100644--- a/packages/python/liteparse/parser.py+++ b/packages/python/liteparse/parser.py@@ -340,6 +340,27 @@ def _convert_native_result(native_result: Any) -> ParseResult:pages=pages,text=native_result.text,images=images,+ screenshots=[+ ScreenshotResult(+ page_num=screenshot.page_num,+ width=screenshot.width,+ height=screenshot.height,+ image_bytes=screenshot.image_bytes,+ is_solid_fill=getattr(screenshot, "is_solid_fill", False),+ rects=[+ ScreenshotRect(+ x=rect.x,+ y=rect.y,+ width=rect.width,+ height=rect.height,+ color=rect.color,+ is_line=rect.is_line,+ )+ for rect in getattr(screenshot, "rects", [])+ ],+ )+ for screenshot in getattr(native_result, "screenshots", [])+ ],image_error_count=getattr(native_result, "image_error_count", 0),form_type=getattr(native_result, "form_type", None),creator=getattr(native_result, "creator", None),@@ -384,6 +405,7 @@ class LiteParse:tessdata_path: Optional[str] = None,max_pages: Optional[int] = None,target_pages: Optional[str] = None,+ extract_screenshots: Optional[bool] = None,dpi: Optional[float] = None,output_format: Optional[str] = None,preserve_very_small_text: Optional[bool] = None,@@ -424,6 +446,8 @@ class LiteParse:tessdata_path: Path to tessdata directory for Tesseractmax_pages: Maximum number of pages to parsetarget_pages: Specific pages to parse (e.g., "1-5,10,15-20")+ extract_screenshots: Render parsed pages to PNG and return them in+ ``ParseResult.screenshots``. Default False; PNG payloads can be large.dpi: DPI for rendering (affects OCR quality)output_format: Output format: "json", "text", or "markdown" (default: "json")preserve_very_small_text: Whether to preserve very small text@@ -497,6 +521,8 @@ class LiteParse:kwargs["max_pages"] = max_pagesif target_pages is not None:kwargs["target_pages"] = target_pages+ if extract_screenshots is not None:+ kwargs["extract_screenshots"] = extract_screenshotsif dpi is not None:kwargs["dpi"] = dpiif output_format is not None:@@ -689,6 +715,7 @@ class LiteParse:tessdata_path=cfg.tessdata_path,max_pages=cfg.max_pages,target_pages=cfg.target_pages,+ extract_screenshots=cfg.extract_screenshots,dpi=cfg.dpi,output_format=cfg.output_format,preserve_very_small_text=cfg.preserve_very_small_text,diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.pyindex d22da18..cef6a26 100644--- a/packages/python/liteparse/types.py+++ b/packages/python/liteparse/types.py@@ -249,6 +249,7 @@ class ParseResult:pages: List[ParsedPage]text: strimages: List[ExtractedImage] = field(default_factory=list)+ screenshots: List["ScreenshotResult"] = field(default_factory=list)image_error_count: int = 0#: PDFium form type, present only when ``extract_form_fields=True``.form_type: Optional[int] = None@@ -382,6 +383,7 @@ class LiteParseConfig:tessdata_path: Optional[str]max_pages: inttarget_pages: Optional[str]+ extract_screenshots: booldpi: floatoutput_format: strpreserve_very_small_text: bool