A fast, helpful, and open-source document parser
Make embedded image extraction opt-in
Pierre-Loic doulcetc694fdc41eeb
diff --git a/README.md b/README.mdindex 6f34856..85887d4 100644--- a/README.md+++ b/README.md@@ -180,6 +180,9 @@ lit parse document.pdf --format markdown --image-mode off# Extract embedded images to disk and reference them from the markdownlit parse document.pdf --format markdown --image-mode embed --image-output-dir ./images+# Extract image bytes and metadata without changing Markdown image handling+lit parse document.pdf --format json --extract-images+# Emit link text as plain text (no [text](url) syntax)lit parse document.pdf --format markdown --no-links```@@ -197,6 +200,11 @@ contains each image's `name`, `path`, page bbox, intrinsic pixel dimensions, rotformat, and duplicate relationship; pixel bytes are never embedded in JSON. Identicalimage resources reuse the same output file.+Library callers can opt in with `extract_images: true` (Rust), `extractImages: true`+(Node/WASM), or `extract_images=True` (Python). It defaults to false. For backward+compatibility, `image_mode=embed` and a configured image output directory also imply+extraction; the default placeholder mode alone only discovers lightweight page refs.+> Markdown reconstruction quality varies with document complexity. For the> hardest documents (dense tables, multi-column layouts, scans),> [LlamaParse](https://developers.llamaindex.ai/python/cloud/llamaparse/?utm_source=github&utm_medium=liteparse)diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rsindex 0e159be..aebff63 100644--- a/crates/liteparse-napi/src/types.rs+++ b/crates/liteparse-napi/src/types.rs@@ -44,6 +44,8 @@ pub struct JsLiteParseConfig {/// (default — emits `` references with no bytes), or/// "embed" (also returns each image's bytes and metadata on `images`).pub image_mode: Option<String>,+ /// Extract embedded image bytes and metadata (default false).+ pub extract_images: Option<bool>,/// Directory where embedded image files are written. Also enables image/// extraction even when `imageMode` is `placeholder`.pub image_output_dir: Option<String>,@@ -141,6 +143,9 @@ impl JsLiteParseConfig {_ => ImageMode::Placeholder,};}+ if let Some(v) = self.extract_images {+ cfg.extract_images = v;+ }if let Some(v) = self.image_output_dir {cfg.image_output_dir = Some(v);}@@ -204,6 +209,7 @@ impl JsLiteParseConfig {ImageMode::Placeholder => "placeholder".to_string(),ImageMode::Embed => "embed".to_string(),}),+ extract_images: Some(cfg.extract_images),image_output_dir: cfg.image_output_dir.clone(),extract_links: Some(cfg.extract_links),ocr_failure_fatal: Some(cfg.ocr_failure_fatal),diff --git a/crates/liteparse-python/src/cli.rs b/crates/liteparse-python/src/cli.rsindex 9c21f6d..5d92bea 100644--- a/crates/liteparse-python/src/cli.rs+++ b/crates/liteparse-python/src/cli.rs@@ -65,6 +65,8 @@ struct ParseCommand {/// (default), or `embed` (extracts image bytes and metadata).#[arg(long, default_value = "placeholder")]image_mode: String,+ #[arg(long)]+ extract_images: bool,/// Directory to write embedded images to. Valid source JPEGs keep their/// format; other images are PNG. Setting this enables extraction/// independently of image mode. Created if missing.@@ -157,6 +159,8 @@ struct BatchParseCommand {/// Include rich PDF text metadata in text items and JSON output.#[arg(long)]include_text_metadata: bool,+ #[arg(long)]+ extract_images: bool,}/// Parse a `Name: Value` header string into a `(name, value)` pair.@@ -233,6 +237,7 @@ pub fn run_cli(args: Vec<String>) -> Result<(), Box<dyn std::error::Error>> {ocr_server_url: cmd.ocr_server_url,ocr_server_headers: cmd.ocr_server_headers,image_mode,+ extract_images: cmd.extract_images,image_output_dir: cmd.image_output_dir.clone(),extract_links: !cmd.no_links,include_complexity: cmd.complexity,@@ -327,6 +332,7 @@ pub fn run_cli(args: Vec<String>) -> Result<(), Box<dyn std::error::Error>> {ocr_server_headers: cmd.ocr_server_headers,include_complexity: cmd.complexity,include_text_metadata: cmd.include_text_metadata,+ extract_images: cmd.extract_images,..Default::default()};if let Some(n) = cmd.num_workers {diff --git a/crates/liteparse-python/src/lib.rs b/crates/liteparse-python/src/lib.rsindex 39663ae..0e17862 100644--- a/crates/liteparse-python/src/lib.rs+++ b/crates/liteparse-python/src/lib.rs@@ -554,6 +554,8 @@ struct PyLiteParseConfig {include_text_metadata: bool,#[pyo3(get)]image_output_dir: Option<String>,+ #[pyo3(get)]+ extract_images: bool,}#[pymethods]@@ -607,6 +609,7 @@ impl PyLiteParseConfig {include_complexity: cfg.include_complexity,include_text_metadata: cfg.include_text_metadata,image_output_dir: cfg.image_output_dir.clone(),+ extract_images: cfg.extract_images,}}}@@ -641,6 +644,7 @@ impl LiteParse {quiet = None,num_workers = None,image_mode = None,+ extract_images = None,image_output_dir = None,extract_links = None,ocr_failure_fatal = None,@@ -666,6 +670,7 @@ impl LiteParse {quiet: Option<bool>,num_workers: Option<usize>,image_mode: Option<String>,+ extract_images: Option<bool>,image_output_dir: Option<String>,extract_links: Option<bool>,ocr_failure_fatal: Option<bool>,@@ -727,6 +732,9 @@ impl LiteParse {_ => ImageMode::Placeholder,};}+ if let Some(v) = extract_images {+ cfg.extract_images = v;+ }if let Some(v) = image_output_dir {cfg.image_output_dir = Some(v);}diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rsindex 77a05c3..d841785 100644--- a/crates/liteparse-wasm/src/lib.rs+++ b/crates/liteparse-wasm/src/lib.rs@@ -54,6 +54,7 @@ pub struct LiteParseConfig {output_format: Option<String>,#[tsify(type = "\"off\" | \"none\" | \"placeholder\" | \"embed\"")]image_mode: Option<String>,+ extract_images: Option<bool>,extract_links: Option<bool>,ocr_failure_fatal: Option<bool>,ocr_hedge_delays_ms: Option<Vec<u64>>,@@ -133,6 +134,9 @@ impl LiteParseConfig {_ => ImageMode::Placeholder,};}+ if let Some(v) = self.extract_images {+ cfg.extract_images = v;+ }if let Some(v) = self.extract_links {cfg.extract_links = v;}@@ -196,6 +200,7 @@ impl LiteParseConfig {ImageMode::Placeholder => "placeholder".into(),ImageMode::Embed => "embed".into(),}),+ extract_images: Some(cfg.extract_images),extract_links: Some(cfg.extract_links),ocr_failure_fatal: Some(cfg.ocr_failure_fatal),ocr_hedge_delays_ms: Some(cfg.ocr_hedge_delays_ms.clone()),diff --git a/crates/liteparse/README.md b/crates/liteparse/README.mdindex 16b996b..c42e768 100644--- a/crates/liteparse/README.md+++ b/crates/liteparse/README.md@@ -75,6 +75,9 @@ images, and links reconstructed from the spatial layout. Set- `image_mode` (`ImageMode::Placeholder` default | `Off` | `Embed`) — how rasterimages are surfaced in the output.+- `extract_images` (default `false`) — return embedded image bytes and metadata+ without changing Markdown image handling. `ImageMode::Embed` remains an+ extraction opt-in for backward compatibility.- `image_output_dir` — write extracted image files and return their names/paths;setting it enables extraction even without `ImageMode::Embed`. Duplicate imageresources reuse the same file.@@ -87,6 +90,7 @@ use liteparse::config::{ImageMode, LiteParseConfig, OutputFormat};let config = LiteParseConfig {output_format: OutputFormat::Markdown,image_mode: ImageMode::Placeholder,+ extract_images: true,image_output_dir: Some("./images".into()),extract_links: true,..Default::default()diff --git a/crates/liteparse/src/config.rs b/crates/liteparse/src/config.rsindex 05777a1..bb90af7 100644--- a/crates/liteparse/src/config.rs+++ b/crates/liteparse/src/config.rs@@ -34,6 +34,10 @@ pub struct LiteParseConfig {/// Controls how raster images are surfaced in markdown output. `Embed`/// also exposes image bytes and metadata to callers.pub image_mode: ImageMode,+ /// Extract embedded image bytes and metadata into `ParseResult.images`.+ /// Defaults to false. `ImageMode::Embed` and `image_output_dir` also imply+ /// extraction for backward compatibility.+ pub extract_images: bool,/// Directory where extracted embedded images are written. Setting this/// also enables image extraction, independently of `image_mode`.pub image_output_dir: Option<String>,@@ -153,6 +157,7 @@ impl Default for LiteParseConfig {quiet: false,num_workers: default_num_workers(),image_mode: ImageMode::Placeholder,+ extract_images: false,image_output_dir: None,extract_links: true,ocr_failure_fatal: true,@@ -281,6 +286,7 @@ mod tests {assert!(!c.quiet);assert!(!c.include_text_metadata);assert!(c.password.is_none());+ assert!(!c.extract_images);}#[test]diff --git a/crates/liteparse/src/main.rs b/crates/liteparse/src/main.rsindex b3f4933..3f5ef8d 100644--- a/crates/liteparse/src/main.rs+++ b/crates/liteparse/src/main.rs@@ -106,6 +106,10 @@ struct ParseCommand {#[arg(long, default_value = "placeholder")]image_mode: String,+ /// Extract embedded image bytes and metadata.+ #[arg(long)]+ extract_images: bool,+/// Directory to write embedded images to. Valid source JPEGs keep their/// format; other images are PNG. Setting this enables image extraction/// independently of `--image-mode`. Created if missing.@@ -223,6 +227,9 @@ struct BatchParseCommand {/// Include rich PDF text metadata in text items and JSON output.#[arg(long)]include_text_metadata: bool,+ /// Extract embedded image bytes and metadata.+ #[arg(long)]+ extract_images: bool,}#[derive(Args, Debug)]@@ -339,6 +346,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {ocr_server_url: cmd.ocr_server_url,ocr_server_headers: cmd.ocr_server_headers,image_mode,+ extract_images: cmd.extract_images,image_output_dir: cmd.image_output_dir.clone(),extract_links: !cmd.no_links,include_complexity: cmd.complexity,@@ -438,6 +446,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {ocr_server_headers: cmd.ocr_server_headers,include_complexity: cmd.complexity,include_text_metadata: cmd.include_text_metadata,+ extract_images: cmd.extract_images,..Default::default()};if let Some(n) = cmd.num_workers {diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rsindex 5fca294..b299e17 100644--- a/crates/liteparse/src/parser.rs+++ b/crates/liteparse/src/parser.rs@@ -51,6 +51,12 @@ pub struct ScreenshotResult {#[cfg(not(target_arch = "wasm32"))]const FONT_DB_DIR_ENV: &str = "LITEPARSE_FONT_DB_DIR";+fn should_extract_images(config: &LiteParseConfig) -> bool {+ config.extract_images+ || matches!(config.image_mode, crate::config::ImageMode::Embed)+ || config.image_output_dir.is_some()+}+#[cfg(not(target_arch = "wasm32"))]fn write_extracted_images(output_dir: &str,@@ -295,8 +301,7 @@ impl LiteParse {// projection (pure Rust) do not touch PDFium, so they can run// concurrently with other `LiteParse` calls.let password = self.config.password.as_deref();- let render_images = matches!(self.config.image_mode, crate::config::ImageMode::Embed)- || self.config.image_output_dir.is_some();+ let render_images = should_extract_images(&self.config);// Build the OCR engine up front so the renderer knows whether to emit a// grayscale buffer (cheaper, for engines that binarize internally) or RGB.@@ -696,6 +701,30 @@ mod tests {assert!(item.tsg);}+ #[test]+ fn image_extraction_is_opt_in_with_compatibility_implications() {+ let default = LiteParseConfig::default();+ assert!(!should_extract_images(&default));++ let explicit = LiteParseConfig {+ extract_images: true,+ ..Default::default()+ };+ assert!(should_extract_images(&explicit));++ let embed = LiteParseConfig {+ image_mode: crate::config::ImageMode::Embed,+ ..Default::default()+ };+ assert!(should_extract_images(&embed));++ let output_dir = LiteParseConfig {+ image_output_dir: Some("images".into()),+ ..Default::default()+ };+ assert!(should_extract_images(&output_dir));+ }+#[test]fn image_output_reuses_canonical_file_for_duplicates() {fn image(id: &str, duplicate_of: Option<&str>, bytes: &[u8]) -> ExtractedImage {diff --git a/crates/pdfium/src/page.rs b/crates/pdfium/src/page.rsindex 38695f2..cffedf0 100644--- a/crates/pdfium/src/page.rs+++ b/crates/pdfium/src/page.rs@@ -403,41 +403,46 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {);let mut metadata = pdfium_sys::FPDF_IMAGEOBJ_METADATA::default();- let metadata_ok = unsafe {- ffi!(FPDFImageObj_GetImageMetadata(- obj,- self.handle,- &mut metadata- ))- };- let mut pixel_width = metadata.width;- let mut pixel_height = metadata.height;- let ok = unsafe {- ffi!(FPDFImageObj_GetImagePixelSize(- obj,- &mut pixel_width,- &mut pixel_height- ))- };- if ok == 0 && metadata_ok == 0 {- pixel_width = 0;- pixel_height = 0;- error_count += 1;- }+ let (pixel_width, pixel_height, rotation) = if include_data {+ let metadata_ok = unsafe {+ ffi!(FPDFImageObj_GetImageMetadata(+ obj,+ self.handle,+ &mut metadata+ ))+ };+ let mut pixel_width = metadata.width;+ let mut pixel_height = metadata.height;+ let pixel_size_ok = unsafe {+ ffi!(FPDFImageObj_GetImagePixelSize(+ obj,+ &mut pixel_width,+ &mut pixel_height+ ))+ };+ if pixel_size_ok == 0 && metadata_ok == 0 {+ pixel_width = 0;+ pixel_height = 0;+ error_count += 1;+ }- let mut matrix = pdfium_sys::FS_MATRIX {- a: 1.0,- b: 0.0,- c: 0.0,- d: 1.0,- e: 0.0,- f: 0.0,- };- let matrix_ok = unsafe { ffi!(FPDFPageObj_GetMatrix(obj, &mut matrix)) };- let rotation = if matrix_ok != 0 {- matrix.b.atan2(matrix.a).to_degrees().rem_euclid(360.0)+ let mut matrix = pdfium_sys::FS_MATRIX {+ a: 1.0,+ b: 0.0,+ c: 0.0,+ d: 1.0,+ e: 0.0,+ f: 0.0,+ };+ let matrix_ok = unsafe { ffi!(FPDFPageObj_GetMatrix(obj, &mut matrix)) };+ let rotation = if matrix_ok != 0 {+ matrix.b.atan2(matrix.a).to_degrees().rem_euclid(360.0)+ } else {+ 0.0+ };+ (pixel_width, pixel_height, rotation)} else {- 0.0+ (0, 0, 0.0)};let raw_bytes = include_datadiff --git a/packages/node/README.md b/packages/node/README.mdindex 5be2ea2..08a48dc 100644--- a/packages/node/README.md+++ b/packages/node/README.md@@ -58,6 +58,7 @@ const parser = new LiteParse({dpi: 150, // Rendering DPIoutputFormat: 'json', // "json" | "text" | "markdown"imageMode: 'placeholder', // Markdown image handling: "placeholder" | "off" | "embed"+ extractImages: true, // Extract image bytes + metadata (default: false)imageOutputDir: './images', // Write images and return name/path metadata (optional)extractLinks: true, // Render [text](url) links in markdown outputpreserveVerySmallText: false, // Keep tiny text@@ -72,6 +73,9 @@ When `imageOutputDir` is set, image extraction is enabled automatically. Each`result.images` entry includes its page bbox, intrinsic pixel dimensions, rotation,format, `name`, and `path`. Valid source JPEGs are preserved, exact duplicates reuseone file, and JSON CLI output contains metadata only—never base64 image data.+`imageMode: "embed"` also continues to imply extraction. With the defaults+(`imageMode: "placeholder"`, `extractImages: false`), only lightweight Markdown+placement refs are collected and `result.images` stays empty.## Parsing from Bytesdiff --git a/packages/node/native.d.ts b/packages/node/native.d.tsindex d578fec..85f71a7 100644--- a/packages/node/native.d.ts+++ b/packages/node/native.d.ts@@ -39,6 +39,7 @@ export interface JsLiteParseConfig {* "embed" (also returns each image's bytes and metadata on `images`).*/imageMode?: string+ extractImages?: booleanimageOutputDir?: string/*** Render hyperlink annotations as `[text](url)` in markdown outputdiff --git a/packages/node/src/cli.ts b/packages/node/src/cli.tsindex 713b40a..d99bbe0 100644--- a/packages/node/src/cli.ts+++ b/packages/node/src/cli.ts@@ -62,6 +62,7 @@ program"--image-output-dir <dir>","Directory to write embedded images to when --image-mode embed is set",)+ .option("--extract-images", "Extract embedded image bytes and metadata").option("--no-links", "Disable hyperlink extraction (emit plain anchor text)").option("--ocr-server-url <url>", "HTTP OCR server URL").option(@@ -108,6 +109,7 @@ programconfig.imageMode = opts.imageMode as "off" | "placeholder" | "embed";if (opts.imageOutputDir)config.imageOutputDir = opts.imageOutputDir as string;+ if (opts.extractImages) config.extractImages = true;if (opts.links === false) config.extractLinks = false;if (opts.ocrServerUrl)config.ocrServerUrl = opts.ocrServerUrl as string;@@ -314,6 +316,7 @@ program"--include-text-metadata","Include rich PDF text metadata in text items and JSON output",)+ .option("--extract-images", "Extract embedded image bytes and metadata").action(async (inputDir: string,@@ -336,6 +339,7 @@ programif (opts.quiet) config.quiet = true;if (opts.numWorkers) config.numWorkers = opts.numWorkers as number;if (opts.includeTextMetadata) config.includeTextMetadata = true;+ if (opts.extractImages) config.extractImages = true;const parser = new LiteParse(config);const outExt = format === "json" ? ".json" : format === "markdown" ? ".md" : ".txt";diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.tsindex a860d8f..a6dfea1 100644--- a/packages/node/src/lib.ts+++ b/packages/node/src/lib.ts@@ -31,6 +31,8 @@ export interface LiteParseConfig {outputFormat: OutputFormat;/** How to surface raster images in markdown output (default: "placeholder"). */imageMode: ImageMode;+ /** Extract embedded image bytes and metadata (default: false). */+ extractImages: boolean;/** Directory where extracted embedded image files are written. */imageOutputDir?: string;/** Render hyperlink annotations as `[text](url)` in markdown output (default: true). */@@ -222,7 +224,7 @@ export interface ExtractedImage {export interface ParseResult {pages: ParsedPage[];text: string;- /** Populated only when configured with `imageMode: "embed"`. */+ /** Populated when image extraction is explicitly or implicitly enabled. */images: ExtractedImage[];/** Embedded image objects that PDFium could not render or encode. */imageErrorCount: number;@@ -331,6 +333,7 @@ export class LiteParse {dpi: userConfig.dpi,outputFormat: userConfig.outputFormat,imageMode: userConfig.imageMode,+ extractImages: userConfig.extractImages,imageOutputDir: userConfig.imageOutputDir,extractLinks: userConfig.extractLinks,preserveVerySmallText: userConfig.preserveVerySmallText,@@ -361,6 +364,7 @@ export class LiteParse {dpi: resolved.dpi ?? 150,outputFormat: (resolved.outputFormat as OutputFormat) ?? "json",imageMode: (resolved.imageMode as ImageMode) ?? "placeholder",+ extractImages: resolved.extractImages ?? false,imageOutputDir: resolved.imageOutputDir ?? undefined,extractLinks: resolved.extractLinks ?? true,preserveVerySmallText: resolved.preserveVerySmallText ?? false,diff --git a/packages/node/src/native.ts b/packages/node/src/native.tsindex f58c3d2..50f21ec 100644--- a/packages/node/src/native.ts+++ b/packages/node/src/native.ts@@ -30,6 +30,7 @@ export interface LiteParseNativeConfig {dpi?: number;outputFormat?: string;imageMode?: string;+ extractImages?: boolean;imageOutputDir?: string;extractLinks?: boolean;preserveVerySmallText?: boolean;diff --git a/packages/python/README.md b/packages/python/README.mdindex 4925a62..8d15471 100644--- a/packages/python/README.md+++ b/packages/python/README.md@@ -57,6 +57,7 @@ parser = LiteParse(dpi=150, # Rendering DPIoutput_format="json", # "json" | "text" | "markdown"image_mode="placeholder", # Markdown image handling: "placeholder" | "off" | "embed"+ extract_images=True, # Extract image bytes + metadata (default: False)image_output_dir="./images", # Write images and return name/path metadata (optional)extract_links=True, # Render [text](url) links in markdown outputpreserve_very_small_text=False, # Keep tiny text@@ -71,6 +72,9 @@ When ``image_output_dir`` is set, image extraction is enabled automatically. Eac``result.images`` entry includes its page bbox, intrinsic pixel dimensions, rotation,format, ``name``, and ``path``. Valid source JPEGs are preserved, exact duplicatesreuse one file, and JSON CLI output contains metadata only—never base64 image data.+``image_mode="embed"`` also continues to imply extraction. With the defaults+(``image_mode="placeholder"``, ``extract_images=False``), only lightweight Markdown+placement refs are collected and ``result.images`` stays empty.## Parsing from Bytesdiff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.pyindex 13c3e67..d142fdb 100644--- a/packages/python/liteparse/parser.py+++ b/packages/python/liteparse/parser.py@@ -168,6 +168,7 @@ class LiteParse:quiet: Optional[bool] = None,num_workers: Optional[int] = None,image_mode: Optional[str] = None,+ extract_images: Optional[bool] = None,image_output_dir: Optional[Union[str, Path]] = None,extract_links: Optional[bool] = None,ocr_failure_fatal: Optional[bool] = None,@@ -201,6 +202,9 @@ class LiteParse:image_output_dir: Directory where extracted embedded images arewritten. Setting it enables image extraction and returns filenames/paths in each ``ExtractedImage``.+ extract_images: Extract embedded image bytes and metadata. Defaults+ to False; ``image_mode="embed"`` and ``image_output_dir`` also+ imply extraction for compatibility.ocr_failure_fatal: Whether a systemic OCR failure (every OCR taskfailed and at least one was a text-sparse page) aborts the wholeparse (default: True). Set False to keep already-recovered native@@ -263,6 +267,8 @@ class LiteParse:kwargs["num_workers"] = num_workersif image_mode is not None:kwargs["image_mode"] = image_mode+ if extract_images is not None:+ kwargs["extract_images"] = extract_imagesif image_output_dir is not None:kwargs["image_output_dir"] = str(image_output_dir)if extract_links is not None:@@ -423,6 +429,7 @@ class LiteParse:skip_diagonal_text=cfg.skip_diagonal_text,include_complexity=cfg.include_complexity,include_text_metadata=cfg.include_text_metadata,+ extract_images=cfg.extract_images,)def __repr__(self) -> str:diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.pyindex 3dcfcf3..5c48d03 100644--- a/packages/python/liteparse/types.py+++ b/packages/python/liteparse/types.py@@ -77,7 +77,8 @@ class ImageRect:class ExtractedImage:"""An embedded raster image extracted from a page.- Populated only when the parser was configured with ``image_mode="embed"``.+ Populated when ``extract_images=True``, ``image_mode="embed"``, or an image+ output directory is configured.The ``id`` matches the reference used in the markdown output(e.g. ```` → ``id="p1_0"``)."""@@ -198,6 +199,7 @@ class LiteParseConfig:skip_diagonal_text: boolinclude_complexity: boolinclude_text_metadata: bool = False+ extract_images: bool = Falseclass ParseError(Exception):