Skip to content

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 parse
targetPages: '1-5,10', // Specific pages (optional)
+ extractScreenshots: false, // Return parsed pages as PNG buffers
dpi: 150, // Rendering DPI
outputFormat: '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.ts
index 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: string
images: Array<JsExtractedImage>
+ screenshots: Array<JsScreenshotResult>
imageErrorCount: number
formType?: number
/** The document's `/Info` `Creator` entry, when present. */
diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.ts
index 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.ts
index 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.md
index 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 parse
target_pages="1-5,10", # Specific pages (optional)
+ extract_screenshots=False, # Return parsed pages as PNG bytes
dpi=150, # Rendering DPI
output_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.py
index 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 Tesseract
max_pages: Maximum number of pages to parse
target_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_pages
if target_pages is not None:
kwargs["target_pages"] = target_pages
+ if extract_screenshots is not None:
+ kwargs["extract_screenshots"] = extract_screenshots
if dpi is not None:
kwargs["dpi"] = dpi
if 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.py
index 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: str
images: 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: int
target_pages: Optional[str]
+ extract_screenshots: bool
dpi: float
output_format: str
preserve_very_small_text: bool