A fast, helpful, and open-source document parser
Add PDF embedded image extraction parity
Pierre-Loic doulcetd5d7d87fbfb6
diff --git a/README.md b/README.mdindex afc18c4..6f34856 100644--- a/README.md+++ b/README.md@@ -190,7 +190,12 @@ Image handling is controlled by `--image-mode`:|------|----------|| `placeholder` (default) | Emits `` references in reading order || `off` | Strips images entirely |-| `embed` | Writes each image's PNG bytes to `--image-output-dir` and references them |+| `embed` | Returns image bytes and metadata; valid embedded JPEG streams remain JPEG |++`--image-output-dir` enables extraction independently of the Markdown mode. JSON output+contains each image's `name`, `path`, page bbox, intrinsic pixel dimensions, rotation,+format, and duplicate relationship; pixel bytes are never embedded in JSON. Identical+image resources reuse the same output file.> Markdown reconstruction quality varies with document complexity. For the> hardest documents (dense tables, multi-column layouts, scans),diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rsindex 9606a99..0e159be 100644--- a/crates/liteparse-napi/src/types.rs+++ b/crates/liteparse-napi/src/types.rs@@ -42,8 +42,11 @@ pub struct JsLiteParseConfig {pub num_workers: Option<u32>,/// How to surface raster images in markdown output: "off", "placeholder"/// (default — emits `` references with no bytes), or- /// "embed" (also returns each image's PNG bytes on `images`).+ /// "embed" (also returns each image's bytes and metadata on `images`).pub image_mode: Option<String>,+ /// Directory where embedded image files are written. Also enables image+ /// extraction even when `imageMode` is `placeholder`.+ pub image_output_dir: Option<String>,/// Render hyperlink annotations as `[text](url)` in markdown output/// (default true). Set false for plain anchor text.pub extract_links: Option<bool>,@@ -138,6 +141,9 @@ impl JsLiteParseConfig {_ => ImageMode::Placeholder,};}+ if let Some(v) = self.image_output_dir {+ cfg.image_output_dir = Some(v);+ }if let Some(v) = self.extract_links {cfg.extract_links = v;}@@ -198,6 +204,7 @@ impl JsLiteParseConfig {ImageMode::Placeholder => "placeholder".to_string(),ImageMode::Embed => "embed".to_string(),}),+ image_output_dir: cfg.image_output_dir.clone(),extract_links: Some(cfg.extract_links),ocr_failure_fatal: Some(cfg.ocr_failure_fatal),ocr_hedge_delays_ms: Some(@@ -506,14 +513,31 @@ pub struct JsParseResult {pub pages: Vec<JsParsedPage>,pub text: String,pub images: Vec<JsExtractedImage>,+ pub image_error_count: u32,+}++#[napi(object)]+#[derive(Clone)]+pub struct JsImageRect {+ pub x: f64,+ pub y: f64,+ pub width: f64,+ pub height: f64,}#[napi(object)]#[derive(Clone)]pub struct JsExtractedImage {pub id: String,+ pub name: String,+ pub path: Option<String>,pub page: u32,+ pub bbox: JsImageRect,+ pub width: u32,+ pub height: u32,+ pub rotation: f64,pub format: String,+ pub duplicate_of: Option<String>,pub bytes: napi::bindgen_prelude::Buffer,}@@ -618,13 +642,26 @@ impl JsParseResult {.map(|page| JsParsedPage::from_rust(page, config.include_text_metadata)).collect(),text: result.text.clone(),+ image_error_count: result.image_error_count,images: result.images.iter().map(|img| JsExtractedImage {id: img.id.clone(),+ name: img.name.clone(),+ path: img.path.clone(),page: img.page,+ bbox: JsImageRect {+ x: img.bbox.x as f64,+ y: img.bbox.y as f64,+ width: img.bbox.width as f64,+ height: img.bbox.height as f64,+ },+ width: img.width,+ height: img.height,+ rotation: img.rotation as f64,format: img.format.clone(),+ duplicate_of: img.duplicate_of.clone(),bytes: img.bytes.clone().into(),}).collect(),diff --git a/crates/liteparse-python/src/cli.rs b/crates/liteparse-python/src/cli.rsindex df46d62..9c21f6d 100644--- a/crates/liteparse-python/src/cli.rs+++ b/crates/liteparse-python/src/cli.rs@@ -62,13 +62,12 @@ struct ParseCommand {#[arg(long)]num_workers: Option<usize>,/// How to surface raster images in markdown output: `off`, `placeholder`- /// (default), or `embed` (extracts PNG bytes, written next to the output- /// when `--image-output-dir` is set).+ /// (default), or `embed` (extracts image bytes and metadata).#[arg(long, default_value = "placeholder")]image_mode: String,- /// Directory to write embedded images to when `--image-mode embed` is set.- /// Each image is written as `image_{id}.png` to match the markdown- /// references. Created if missing.+ /// 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.#[arg(long)]image_output_dir: Option<String>,/// Disable hyperlink extraction. By default URI link annotations render as@@ -234,6 +233,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,+ image_output_dir: cmd.image_output_dir.clone(),extract_links: !cmd.no_links,include_complexity: cmd.complexity,include_text_metadata: cmd.include_text_metadata,@@ -249,29 +249,15 @@ pub fn run_cli(args: Vec<String>) -> Result<(), Box<dyn std::error::Error>> {rt.block_on(lp.parse(&cmd.file))?};let formatted = match lp.config().output_format {- OutputFormat::Json => json::format_json_with_text_metadata(+ OutputFormat::Json => json::format_json_result(&result.pages,+ &result.images,+ result.image_error_count,lp.config().include_text_metadata,)?,OutputFormat::Text => text::format_text(&result.pages),OutputFormat::Markdown => result.text.clone(),};- if let Some(dir) = cmd.image_output_dir.as_deref()- && !result.images.is_empty()- {- std::fs::create_dir_all(dir)?;- for img in &result.images {- let path = format!("{}/image_{}.{}", dir, img.id, img.format);- std::fs::write(&path, &img.bytes)?;- }- if !cmd.quiet {- eprintln!(- "[liteparse] wrote {} image(s) to {}",- result.images.len(),- dir- );- }- }match cmd.output {Some(path) => {std::fs::write(&path, &formatted)?;@@ -381,8 +367,10 @@ pub fn run_cli(args: Vec<String>) -> Result<(), Box<dyn std::error::Error>> {Ok(result) => {let fmt_result: Result<String, Box<dyn std::error::Error>> =match lp.config().output_format {- OutputFormat::Json => json::format_json_with_text_metadata(+ OutputFormat::Json => json::format_json_result(&result.pages,+ &result.images,+ result.image_error_count,lp.config().include_text_metadata,).map_err(|e| e.into()),diff --git a/crates/liteparse-python/src/lib.rs b/crates/liteparse-python/src/lib.rsindex 8f8a8d5..39663ae 100644--- a/crates/liteparse-python/src/lib.rs+++ b/crates/liteparse-python/src/lib.rs@@ -229,6 +229,8 @@ struct PyParseResult {text: String,#[pyo3(get)]images: Vec<PyExtractedImage>,+ #[pyo3(get)]+ image_error_count: u32,}#[pymethods]@@ -266,6 +268,7 @@ impl PyParseResult {.into_iter().map(PyExtractedImage::from_rust).collect(),+ image_error_count: result.image_error_count,}}}@@ -276,12 +279,39 @@ struct PyExtractedImage {#[pyo3(get)]id: String,#[pyo3(get)]+ name: String,+ #[pyo3(get)]+ path: Option<String>,+ #[pyo3(get)]page: u32,#[pyo3(get)]+ bbox: PyImageRect,+ #[pyo3(get)]+ width: u32,+ #[pyo3(get)]+ height: u32,+ #[pyo3(get)]+ rotation: f32,+ #[pyo3(get)]format: String,+ #[pyo3(get)]+ duplicate_of: Option<String>,bytes_buffer: Vec<u8>,}+#[pyclass(frozen, from_py_object)]+#[derive(Clone)]+struct PyImageRect {+ #[pyo3(get)]+ x: f32,+ #[pyo3(get)]+ y: f32,+ #[pyo3(get)]+ width: f32,+ #[pyo3(get)]+ height: f32,+}+#[pymethods]impl PyExtractedImage {#[getter]@@ -304,8 +334,20 @@ impl PyExtractedImage {fn from_rust(img: liteparse::types::ExtractedImage) -> Self {Self {id: img.id,+ name: img.name,+ path: img.path,page: img.page,+ bbox: PyImageRect {+ x: img.bbox.x,+ y: img.bbox.y,+ width: img.bbox.width,+ height: img.bbox.height,+ },+ width: img.width,+ height: img.height,+ rotation: img.rotation,format: img.format,+ duplicate_of: img.duplicate_of,bytes_buffer: img.bytes,}}@@ -510,6 +552,8 @@ struct PyLiteParseConfig {include_complexity: bool,#[pyo3(get)]include_text_metadata: bool,+ #[pyo3(get)]+ image_output_dir: Option<String>,}#[pymethods]@@ -562,6 +606,7 @@ impl PyLiteParseConfig {skip_diagonal_text: cfg.skip_diagonal_text,include_complexity: cfg.include_complexity,include_text_metadata: cfg.include_text_metadata,+ image_output_dir: cfg.image_output_dir.clone(),}}}@@ -596,6 +641,7 @@ impl LiteParse {quiet = None,num_workers = None,image_mode = None,+ image_output_dir = None,extract_links = None,ocr_failure_fatal = None,ocr_hedge_delays_ms = None,@@ -620,6 +666,7 @@ impl LiteParse {quiet: Option<bool>,num_workers: Option<usize>,image_mode: Option<String>,+ image_output_dir: Option<String>,extract_links: Option<bool>,ocr_failure_fatal: Option<bool>,ocr_hedge_delays_ms: Option<Vec<u64>>,@@ -680,6 +727,9 @@ impl LiteParse {_ => ImageMode::Placeholder,};}+ if let Some(v) = image_output_dir {+ cfg.image_output_dir = Some(v);+ }if let Some(v) = extract_links {cfg.extract_links = v;}@@ -879,6 +929,7 @@ fn _liteparse(m: &Bound<'_, PyModule>) -> PyResult<()> {m.add_class::<PyLiteParseConfig>()?;m.add_class::<PyParseResult>()?;m.add_class::<PyExtractedImage>()?;+ m.add_class::<PyImageRect>()?;m.add_class::<PyParsedPage>()?;m.add_class::<PyTextItem>()?;m.add_class::<PyWordBox>()?;diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rsindex ce76178..77a05c3 100644--- a/crates/liteparse-wasm/src/lib.rs+++ b/crates/liteparse-wasm/src/lib.rs@@ -274,6 +274,7 @@ pub struct ParseResult {pub pages: Vec<ParsedPage>,pub text: String,pub images: Vec<ExtractedImage>,+ pub image_error_count: u32,}#[derive(Serialize, Tsify)]@@ -281,13 +282,30 @@ pub struct ParseResult {#[serde(rename_all = "camelCase")]pub struct ExtractedImage {pub id: String,+ pub name: String,+ pub path: Option<String>,pub page: u32,+ pub bbox: ImageRect,+ pub width: u32,+ pub height: u32,+ pub rotation: f32,pub format: String,+ pub duplicate_of: Option<String>,/// Raw image bytes, serialized as a JS `number[]`. Callers that want a/// Uint8Array can wrap with `new Uint8Array(image.bytes)`.pub bytes: Vec<u8>,}+#[derive(Serialize, Tsify)]+#[tsify(into_wasm_abi)]+#[serde(rename_all = "camelCase")]+pub struct ImageRect {+ pub x: f32,+ pub y: f32,+ pub width: f32,+ pub height: f32,+}+// ---------------------------------------------------------------------------// JS OCR engine bridge// ---------------------------------------------------------------------------@@ -511,8 +529,20 @@ impl LiteParse {.iter().map(|img| ExtractedImage {id: img.id.clone(),+ name: img.name.clone(),+ path: img.path.clone(),page: img.page,+ bbox: ImageRect {+ x: img.bbox.x,+ y: img.bbox.y,+ width: img.bbox.width,+ height: img.bbox.height,+ },+ width: img.width,+ height: img.height,+ rotation: img.rotation,format: img.format.clone(),+ duplicate_of: img.duplicate_of.clone(),bytes: img.bytes.clone(),}).collect();@@ -521,6 +551,7 @@ impl LiteParse {pages,text: result.text.clone(),images,+ image_error_count: result.image_error_count,})}diff --git a/crates/liteparse/README.md b/crates/liteparse/README.mdindex 8a54672..16b996b 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.+- `image_output_dir` — write extracted image files and return their names/paths;+ setting it enables extraction even without `ImageMode::Embed`. Duplicate image+ resources reuse the same file.- `extract_links` (default `true`) — render hyperlink annotations as`[text](url)`; set `false` for plain anchor text.@@ -84,6 +87,7 @@ use liteparse::config::{ImageMode, LiteParseConfig, OutputFormat};let config = LiteParseConfig {output_format: OutputFormat::Markdown,image_mode: ImageMode::Placeholder,+ 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 0b5c60f..05777a1 100644--- a/crates/liteparse/src/config.rs+++ b/crates/liteparse/src/config.rs@@ -31,9 +31,12 @@ pub struct LiteParseConfig {pub quiet: bool,/// Number of concurrent OCR workers. Defaults to (number of CPU cores - 1), minimum 1.pub num_workers: usize,- /// Controls how raster images are surfaced in markdown output. Has no- /// effect on JSON / text outputs.+ /// Controls how raster images are surfaced in markdown output. `Embed`+ /// also exposes image bytes and metadata to callers.pub image_mode: ImageMode,+ /// Directory where extracted embedded images are written. Setting this+ /// also enables image extraction, independently of `image_mode`.+ pub image_output_dir: Option<String>,/// 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).@@ -103,10 +106,9 @@ pub struct CropBox {/// 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.)+/// * `Embed` — same references, plus bytes and metadata returned via+/// `ParseResult.images`. Opt-in because pixel bytes can dwarf the text+/// payload on image-heavy PDFs.#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]#[serde(rename_all = "lowercase")]pub enum ImageMode {@@ -151,6 +153,7 @@ impl Default for LiteParseConfig {quiet: false,num_workers: default_num_workers(),image_mode: ImageMode::Placeholder,+ image_output_dir: None,extract_links: true,ocr_failure_fatal: true,ocr_hedge_delays_ms: Vec::new(),diff --git a/crates/liteparse/src/extract.rs b/crates/liteparse/src/extract.rsindex 6f25c3a..f5ea9ed 100644--- a/crates/liteparse/src/extract.rs+++ b/crates/liteparse/src/extract.rs@@ -53,7 +53,7 @@ pub(crate) fn extract_pages_from_document(}/// Same as `extract_pages_from_document` but optionally also renders every-/// raster image object to PNG bytes (when `render_images = true`). Returned+/// raster image object to bytes (when `render_images = true`). Returned/// `ExtractedImage`s carry the same ids the markdown emitter will reference,/// so callers can match them up by id. When `render_images = false` the/// returned image vec is always empty.@@ -65,10 +65,12 @@ pub(crate) fn extract_pages_and_images(extract_links: bool,glyph_resolver: Option<&dyn crate::GlyphResolver>,emit_word_boxes: bool,-) -> Result<(Vec<LitePage>, Vec<ExtractedImage>), LiteParseError> {+) -> Result<(Vec<LitePage>, Vec<ExtractedImage>, u32), LiteParseError> {let page_count = document.page_count();let mut pages = Vec::new();let mut images: Vec<ExtractedImage> = Vec::new();+ let mut image_cache: Vec<CachedImage> = Vec::new();+ let mut image_error_count = 0u32;for page_index in 0..page_count {let page_number = page_index as u32 + 1;@@ -104,10 +106,18 @@ pub(crate) fn extract_pages_and_images(let graphics = extract_page_graphics(&page, &view_box);assign_strikethrough(&mut text_items, &graphics);let struct_nodes = extract_page_struct_nodes(&page, &view_box);- let image_refs = extract_page_image_refs(&page, page_number);+ let extracted_refs = extract_page_image_refs(&page, page_number, render_images);+ let mut image_refs = extracted_refs.refs;+ image_error_count += extracted_refs.error_count;if render_images && !image_refs.is_empty() {- images.extend(render_page_images(&page, page_number, &image_refs));+ let rendered = render_page_images(&page, page_number, &image_refs, &mut image_cache);+ image_error_count += rendered.error_count;+ images.extend(rendered.images);+ for image_ref in &mut image_refs {+ image_ref.jpeg_bytes = None;+ image_ref.raw_bytes = None;+ }}pages.push(LitePage {@@ -121,7 +131,7 @@ pub(crate) fn extract_pages_and_images(});}- Ok((pages, images))+ Ok((pages, images, image_error_count))}/// Assign hyperlink URIs to text items whose bbox center falls inside a link@@ -345,42 +355,116 @@ const IMAGE_MIN_SIZE_PT: f32 = 25.0;/// images (scanned pages, watermarks).const IMAGE_MAX_COVERAGE: f32 = 0.9;-/// Render every image referenced in `refs` to PNG bytes using-/// `Page::render_image_object`. Returns one `ExtractedImage` per ref. Used by-/// the parser only when `ImageMode::Embed` is configured — otherwise the-/// extraction loop skips this entirely. Failures for individual images are-/// silently dropped (a malformed embedded image shouldn't fail the whole-/// parse).-pub(crate) fn render_page_images(+/// Extract every image referenced in `refs`, preserving valid JPEG streams and+/// rendering other images to PNG. Returns one `ExtractedImage` per ref. Used+/// when `ImageMode::Embed` or an output directory is configured. Failures for+/// individual images are counted but do not fail the whole parse.+struct CachedImage {+ raw_bytes: Vec<u8>,+ id: String,+ format: String,+ bytes: Vec<u8>,+ width: u32,+ height: u32,+ bits_per_pixel: u32,+ colorspace: i32,+}++pub(crate) struct RenderedImages {+ pub images: Vec<ExtractedImage>,+ pub error_count: u32,+}++fn render_page_images(page: &Page,page_number: u32,refs: &[ImageRef],-) -> Vec<ExtractedImage> {+ cache: &mut Vec<CachedImage>,+) -> RenderedImages {let mut out = Vec::with_capacity(refs.len());+ let mut error_count = 0;for r in refs {- let bmp = match page.render_image_object(r.obj_index) {- Ok(b) => b,- Err(_) => continue,- };- let w = bmp.width().max(0) as u32;- let h = bmp.height().max(0) as u32;- if w == 0 || h == 0 {+ if let Some(raw_bytes) = r.raw_bytes.as_ref()+ && let Some(cached) = cache.iter().find(|entry| {+ entry.raw_bytes == *raw_bytes+ && entry.width == r.pixel_width+ && entry.height == r.pixel_height+ && entry.bits_per_pixel == r.bits_per_pixel+ && entry.colorspace == r.colorspace+ })+ {+ out.push(ExtractedImage {+ id: r.id.clone(),+ name: format!("image_{}.{}", r.id, cached.format),+ path: None,+ page: page_number,+ bbox: r.bbox.clone(),+ width: r.pixel_width,+ height: r.pixel_height,+ rotation: r.rotation,+ format: cached.format.clone(),+ duplicate_of: Some(cached.id.clone()),+ bytes: cached.bytes.clone(),+ });continue;}- let rgba = bmp.to_rgba();- let png = match encode_png(&rgba, w, h) {- Ok(p) => p,- Err(_) => continue,++ let encoded = if let Some(jpeg) = r.jpeg_bytes.clone() {+ Ok(("jpg".to_string(), jpeg))+ } else {+ let bmp = match page.render_image_object(r.obj_index) {+ Ok(b) => b,+ Err(_) => {+ error_count += 1;+ continue;+ }+ };+ let w = bmp.width().max(0) as u32;+ let h = bmp.height().max(0) as u32;+ if w == 0 || h == 0 {+ error_count += 1;+ continue;+ }+ let rgba = bmp.to_rgba();+ encode_png(&rgba, w, h).map(|png| ("png".to_string(), png))+ };+ let (format, bytes) = match encoded {+ Ok(value) => value,+ Err(_) => {+ error_count += 1;+ continue;+ }};out.push(ExtractedImage {id: r.id.clone(),+ name: format!("image_{}.{}", r.id, format),+ path: None,page: page_number,bbox: r.bbox.clone(),- format: "png".into(),- bytes: png,+ width: r.pixel_width,+ height: r.pixel_height,+ rotation: r.rotation,+ format: format.clone(),+ duplicate_of: None,+ bytes: bytes.clone(),});+ if let Some(raw_bytes) = r.raw_bytes.clone() {+ cache.push(CachedImage {+ raw_bytes,+ id: r.id.clone(),+ format,+ bytes,+ width: r.pixel_width,+ height: r.pixel_height,+ bits_per_pixel: r.bits_per_pixel,+ colorspace: r.colorspace,+ });+ }+ }+ RenderedImages {+ images: out,+ error_count,}- out}/// Encode RGBA pixel bytes to PNG. Lives here (always-compiled) rather than in@@ -398,21 +482,48 @@ pub(crate) fn encode_png(rgba: &[u8], width: u32, height: u32) -> Result<Vec<u8>/// page objects), so a later embed pass can pull pixel bytes via/// `Page::render_image_object`. IDs are scoped to the page number so they/// remain stable across runs.-fn extract_page_image_refs(page: &Page, page_number: u32) -> Vec<ImageRef> {- page.image_bounds(IMAGE_MIN_SIZE_PT, IMAGE_MAX_COVERAGE)+struct ExtractedImageRefs {+ refs: Vec<ImageRef>,+ error_count: u32,+}++fn extract_page_image_refs(+ page: &Page,+ page_number: u32,+ include_data: bool,+) -> ExtractedImageRefs {+ let extracted = page.image_objects(IMAGE_MIN_SIZE_PT, IMAGE_MAX_COVERAGE, include_data);+ let refs = extracted+ .images.into_iter().enumerate()- .map(|(i, b)| ImageRef {+ .map(|(i, image)| ImageRef {id: format!("p{}_{}", page_number, i),bbox: Rect {- x: b.x,- y: b.y,- width: b.width,- height: b.height,+ x: image.bounds.x,+ y: image.bounds.y,+ width: image.bounds.width,+ height: image.bounds.height,},- obj_index: i,+ obj_index: image.object_index,+ format: if image.jpeg_bytes.is_some() {+ "jpg".to_string()+ } else {+ "png".to_string()+ },+ pixel_width: image.pixel_width,+ pixel_height: image.pixel_height,+ rotation: image.rotation,+ jpeg_bytes: image.jpeg_bytes,+ raw_bytes: image.raw_bytes,+ bits_per_pixel: image.bits_per_pixel,+ colorspace: image.colorspace,})- .collect()+ .collect();+ ExtractedImageRefs {+ refs,+ error_count: extracted.error_count,+ }}/// Extract simplified vector graphics from a page. We keep only what thediff --git a/crates/liteparse/src/main.rs b/crates/liteparse/src/main.rsindex 198c026..b3f4933 100644--- a/crates/liteparse/src/main.rs+++ b/crates/liteparse/src/main.rs@@ -101,16 +101,14 @@ struct ParseCommand {/// How to surface raster images in markdown output:/// `off` strips them, `placeholder` (default) emits ``- /// references in reading order, `embed` extracts each image's PNG bytes- /// and writes them next to the markdown output when `--image-output-dir`- /// is set.+ /// references in reading order, and `embed` extracts image bytes and+ /// metadata.#[arg(long, default_value = "placeholder")]image_mode: String,- /// Directory to write embedded images to when `--image-mode embed` is- /// set. Each image is written as `image_{id}.png` to match the- /// references in the markdown output. Has no effect for other image- /// modes. Created if missing.+ /// 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.#[arg(long)]image_output_dir: Option<String>,@@ -341,6 +339,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,+ image_output_dir: cmd.image_output_dir.clone(),extract_links: !cmd.no_links,include_complexity: cmd.complexity,include_text_metadata: cmd.include_text_metadata,@@ -357,29 +356,15 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {lp.parse(&cmd.file).await?};let formatted = match lp.config().output_format {- OutputFormat::Json => json::format_json_with_text_metadata(+ OutputFormat::Json => json::format_json_result(&result.pages,+ &result.images,+ result.image_error_count,lp.config().include_text_metadata,)?,OutputFormat::Text => text::format_text(&result.pages),OutputFormat::Markdown => result.text.clone(),};- if let Some(dir) = cmd.image_output_dir.as_deref()- && !result.images.is_empty()- {- std::fs::create_dir_all(dir)?;- for img in &result.images {- let path = format!("{}/image_{}.{}", dir, img.id, img.format);- std::fs::write(&path, &img.bytes)?;- }- if !cmd.quiet {- eprintln!(- "[liteparse] wrote {} image(s) to {}",- result.images.len(),- dir- );- }- }match cmd.output {Some(path) => {@@ -496,8 +481,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {Ok(result) => {let fmt_result: Result<String, Box<dyn std::error::Error>> =match lp.config().output_format {- OutputFormat::Json => json::format_json_with_text_metadata(+ OutputFormat::Json => json::format_json_result(&result.pages,+ &result.images,+ result.image_error_count,lp.config().include_text_metadata,).map_err(|e| e.into()),diff --git a/crates/liteparse/src/markdown_layout/blocks.rs b/crates/liteparse/src/markdown_layout/blocks.rsindex b5d25bb..f2a7505 100644--- a/crates/liteparse/src/markdown_layout/blocks.rs+++ b/crates/liteparse/src/markdown_layout/blocks.rs@@ -49,9 +49,10 @@ pub enum Block {/// page's vector graphics (e.g. divider line between sections).HorizontalRule,/// Reference to a raster image on the page. Rendered as- /// ``. Suppressed entirely when `ImageMode::Off`.+ /// ``. Suppressed entirely when `ImageMode::Off`.Figure {id: String,+ format: String,},}@@ -238,10 +239,12 @@ pub fn render_blocks(blocks: &[Block]) -> String {Block::HorizontalRule => {out.push_str("---");}- Block::Figure { id, .. } => {+ Block::Figure { id, format } => {out.push_str(";out.push_str(id);- out.push_str(".png)");+ out.push('.');+ out.push_str(format);+ out.push(')');}}}@@ -273,6 +276,17 @@ mod tests {assert_eq!(s, "# Title\n\nA paragraph.\n\n## Sub");}+ #[test]+ fn render_figure_uses_extracted_format() {+ assert_eq!(+ render_blocks(&[Block::Figure {+ id: "p1_0".into(),+ format: "jpg".into(),+ }]),+ ""+ );+ }+#[test]fn render_lists_are_tight() {let blocks = vec![diff --git a/crates/liteparse/src/markdown_layout/classify.rs b/crates/liteparse/src/markdown_layout/classify.rsindex 2858d2b..41faa58 100644--- a/crates/liteparse/src/markdown_layout/classify.rs+++ b/crates/liteparse/src/markdown_layout/classify.rs@@ -323,7 +323,10 @@ pub fn classify_page_with_filters(let push_interruption = |blocks: &mut Vec<Block>, kind: Interruption| {blocks.push(match kind {Interruption::Hr => Block::HorizontalRule,- Interruption::Figure(r) => Block::Figure { id: r.id },+ Interruption::Figure(r) => Block::Figure {+ id: r.id,+ format: r.format,+ },Interruption::Table(b) => b,});};@@ -453,7 +456,10 @@ impl FlowState {self.reset_list();blocks.push(match kind {Interruption::Hr => Block::HorizontalRule,- Interruption::Figure(r) => Block::Figure { id: r.id },+ Interruption::Figure(r) => Block::Figure {+ id: r.id,+ format: r.format,+ },Interruption::Table(b) => b,});}diff --git a/crates/liteparse/src/output/json.rs b/crates/liteparse/src/output/json.rsindex dbba09d..73d673e 100644--- a/crates/liteparse/src/output/json.rs+++ b/crates/liteparse/src/output/json.rs@@ -1,5 +1,5 @@use crate::ocr_merge::PageComplexityStats;-use crate::types::ParsedPage;+use crate::types::{ExtractedImage, ParsedPage, Rect};use serde::Serialize;#[derive(Debug, Serialize)]@@ -55,11 +55,37 @@ pub(crate) struct JsonPage {#[derive(Debug, Serialize)]pub(crate) struct ParseResultJson {pub pages: Vec<JsonPage>,+ #[serde(skip_serializing_if = "Vec::is_empty")]+ pub images: Vec<JsonImage>,+ #[serde(skip_serializing_if = "is_zero")]+ pub image_error_count: u32,+}++fn is_zero(value: &u32) -> bool {+ *value == 0+}++#[derive(Debug, Serialize)]+pub(crate) struct JsonImage {+ pub id: String,+ pub name: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub path: Option<String>,+ pub page: u32,+ pub bbox: Rect,+ pub width: u32,+ pub height: u32,+ pub rotation: f32,+ pub format: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub duplicate_of: Option<String>,}/// Build structured JSON output from parsed pages.pub(crate) fn build_json(pages: &[ParsedPage], include_text_metadata: bool) -> ParseResultJson {ParseResultJson {+ images: Vec::new(),+ image_error_count: 0,pages: pages.iter().map(|page| JsonPage {@@ -107,6 +133,34 @@ pub(crate) fn build_json(pages: &[ParsedPage], include_text_metadata: bool) -> P}}+/// Format complete parse output, including extracted-image metadata. Pixel+/// bytes are written separately by the CLI's `--image-output-dir` option.+pub fn format_json_result(+ pages: &[ParsedPage],+ images: &[ExtractedImage],+ image_error_count: u32,+ include_text_metadata: bool,+) -> Result<String, serde_json::Error> {+ let mut result = build_json(pages, include_text_metadata);+ result.images = images+ .iter()+ .map(|image| JsonImage {+ id: image.id.clone(),+ name: image.name.clone(),+ path: image.path.clone(),+ page: image.page,+ bbox: image.bbox.clone(),+ width: image.width,+ height: image.height,+ rotation: image.rotation,+ format: image.format.clone(),+ duplicate_of: image.duplicate_of.clone(),+ })+ .collect();+ result.image_error_count = image_error_count;+ serde_json::to_string_pretty(&result)+}+/// Format parsed pages as pretty-printed JSON string.pub fn format_json(pages: &[ParsedPage]) -> Result<String, serde_json::Error> {format_json_with_text_metadata(pages, false)@@ -240,4 +294,34 @@ mod tests {assert!(item.get("char_codes").is_none());assert!(item.get("tsg").is_none());}++ #[test]+ fn test_format_json_result_includes_image_metadata_and_errors() {+ let image = ExtractedImage {+ id: "p2_0".into(),+ name: "image_p2_0.jpg".into(),+ path: Some("/tmp/images/image_p2_0.jpg".into()),+ page: 2,+ bbox: Rect {+ x: 10.0,+ y: 20.0,+ width: 30.0,+ height: 40.0,+ },+ width: 640,+ height: 480,+ rotation: 90.0,+ format: "jpg".into(),+ duplicate_of: Some("p1_0".into()),+ bytes: vec![1, 2, 3],+ };+ let value: serde_json::Value =+ serde_json::from_str(&format_json_result(&[], &[image], 2, false).unwrap()).unwrap();+ assert_eq!(value["images"][0]["bbox"]["x"], 10.0);+ assert_eq!(value["images"][0]["width"], 640);+ assert_eq!(value["images"][0]["rotation"], 90.0);+ assert_eq!(value["images"][0]["duplicate_of"], "p1_0");+ assert!(value["images"][0].get("bytes").is_none());+ assert_eq!(value["image_error_count"], 2);+ }}diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rsindex d6cd56a..5fca294 100644--- a/crates/liteparse/src/parser.rs+++ b/crates/liteparse/src/parser.rs@@ -27,9 +27,12 @@ pub struct ParseResult {pub outline: Vec<OutlineTarget>,/// 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.+ /// `id` and `format` the markdown emitter referenced, so the caller can+ /// match them up without parsing markdown.pub images: Vec<ExtractedImage>,+ /// 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,}/// Result of rendering a single page screenshot.@@ -48,6 +51,34 @@ pub struct ScreenshotResult {#[cfg(not(target_arch = "wasm32"))]const FONT_DB_DIR_ENV: &str = "LITEPARSE_FONT_DB_DIR";+#[cfg(not(target_arch = "wasm32"))]+fn write_extracted_images(+ output_dir: &str,+ images: &mut [ExtractedImage],+) -> Result<(), LiteParseError> {+ use std::collections::HashMap;+ use std::path::Path;++ std::fs::create_dir_all(output_dir)?;+ let mut written: HashMap<String, (String, String)> = HashMap::new();+ for image in images {+ if let Some(canonical) = image.duplicate_of.as_ref()+ && let Some((name, path)) = written.get(canonical)+ {+ image.name = name.clone();+ image.path = Some(path.clone());+ continue;+ }++ let path = Path::new(output_dir).join(&image.name);+ std::fs::write(&path, &image.bytes)?;+ let path = path.to_string_lossy().into_owned();+ image.path = Some(path.clone());+ written.insert(image.id.clone(), (image.name.clone(), path));+ }+ Ok(())+}+/// Build the default glyph resolver from the environment, if configured.#[cfg(not(target_arch = "wasm32"))]fn default_glyph_resolver() -> Option<std::sync::Arc<dyn crate::GlyphResolver>> {@@ -170,7 +201,7 @@ impl LiteParse {let lib = Library::init();let document = extract::load_document_from_input(&lib, &validated_input, password)?;- let (pages, _) = extract::extract_pages_and_images(+ let (pages, _, _) = extract::extract_pages_and_images(&document,target_pages.as_deref(),self.config.max_pages,@@ -264,7 +295,8 @@ 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);+ let render_images = matches!(self.config.image_mode, crate::config::ImageMode::Embed)+ || self.config.image_output_dir.is_some();// Build the OCR engine up front so the renderer knows whether to emit a// grayscale buffer (cheaper, for engines that binarize internally) or RGB.@@ -312,11 +344,11 @@ impl LiteParse {};let ocr_grayscale = ocr_engine.as_ref().is_some_and(|e| e.prefers_grayscale());- let (pages, ocr_rendered, outline, images, complexity) = {+ let (pages, ocr_rendered, outline, mut images, image_error_count, complexity) = {let lib = Library::init();let document = extract::load_document_from_input(&lib, &validated_input, password)?;let outline = extract::extract_outline(&document);- let (pages, images) = extract::extract_pages_and_images(+ let (pages, images, image_error_count) = extract::extract_pages_and_images(&document,target_pages.as_deref(),self.config.max_pages,@@ -364,7 +396,14 @@ impl LiteParse {Vec::new()};// `lib` is dropped here, releasing the PDFium lock.- (pages, rendered, outline, images, complexity)+ (+ pages,+ rendered,+ outline,+ images,+ image_error_count,+ complexity,+ )};let mut pages = pages;let t1 = web_time::Instant::now();@@ -440,11 +479,17 @@ impl LiteParse {let total = web_time::Instant::now().duration_since(t0).as_secs_f64() * 1000.0;log(&format!("[liteparse] total: {:.1}ms", total));+ #[cfg(not(target_arch = "wasm32"))]+ if let Some(output_dir) = self.config.image_output_dir.as_deref() {+ write_extracted_images(output_dir, &mut images)?;+ }+Ok(ParseResult {pages: parsed_pages,text: full_text,outline,images,+ image_error_count,})}@@ -484,6 +529,7 @@ impl LiteParse {text: full_text,outline,images: Vec::new(),+ image_error_count: 0,}}@@ -649,4 +695,38 @@ mod tests {assert_eq!(item.char_codes, vec![104, 101, 108, 108, 111]);assert!(item.tsg);}++ #[test]+ fn image_output_reuses_canonical_file_for_duplicates() {+ fn image(id: &str, duplicate_of: Option<&str>, bytes: &[u8]) -> ExtractedImage {+ ExtractedImage {+ id: id.into(),+ name: format!("image_{id}.png"),+ path: None,+ page: 1,+ bbox: crate::types::Rect::default(),+ width: 2,+ height: 2,+ rotation: 0.0,+ format: "png".into(),+ duplicate_of: duplicate_of.map(str::to_owned),+ bytes: bytes.to_vec(),+ }+ }++ let dir = tempfile::tempdir().unwrap();+ let mut images = vec![+ image("p1_0", None, b"canonical"),+ image("p2_0", Some("p1_0"), b"canonical"),+ ];+ write_extracted_images(dir.path().to_str().unwrap(), &mut images).unwrap();++ assert_eq!(images[0].name, images[1].name);+ assert_eq!(images[0].path, images[1].path);+ assert_eq!(+ std::fs::read(images[0].path.as_ref().unwrap()).unwrap(),+ b"canonical"+ );+ assert_eq!(std::fs::read_dir(dir.path()).unwrap().count(), 1);+ }}diff --git a/crates/liteparse/src/types.rs b/crates/liteparse/src/types.rsindex 81bea49..2bc6472 100644--- a/crates/liteparse/src/types.rs+++ b/crates/liteparse/src/types.rs@@ -206,20 +206,36 @@ pub struct ImageRef {pub id: String,pub bbox: Rect,pub obj_index: usize,+ pub format: String,+ pub pixel_width: u32,+ pub pixel_height: u32,+ pub rotation: f32,+ pub jpeg_bytes: Option<Vec<u8>>,+ pub raw_bytes: Option<Vec<u8>>,+ pub bits_per_pixel: u32,+ pub colorspace: i32,}/// 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 `ImageRef`s are-/// produced. `format` is currently always `"png"` (encoded from the-/// FPDFImageObj_GetRenderedBitmap output via the same path used for page-/// screenshots).+/// produced. Other images are encoded as PNG from PDFium's rendered bitmap.+/// JPEG streams are preserved without re-encoding when PDFium+/// exposes a valid directly decoded DCT stream.#[derive(Debug, Clone, Serialize)]pub struct ExtractedImage {pub id: String,+ pub name: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub path: Option<String>,pub page: u32,pub bbox: Rect,+ pub width: u32,+ pub height: u32,+ pub rotation: f32,pub format: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub duplicate_of: Option<String>,#[serde(skip)]pub bytes: Vec<u8>,}diff --git a/crates/pdfium-sys/src/dynamic.rs b/crates/pdfium-sys/src/dynamic.rsindex 5581f3a..194692f 100644--- a/crates/pdfium-sys/src/dynamic.rs+++ b/crates/pdfium-sys/src/dynamic.rs@@ -72,6 +72,31 @@ pub struct PdfiumBindings {unsafe extern "C" fn(FPDF_PAGEOBJECT) -> std::os::raw::c_int,pub FPDFImageObj_GetRenderedBitmap:unsafe extern "C" fn(FPDF_DOCUMENT, FPDF_PAGE, FPDF_PAGEOBJECT) -> FPDF_BITMAP,+ pub FPDFImageObj_GetImageDataDecoded: unsafe extern "C" fn(+ FPDF_PAGEOBJECT,+ *mut std::os::raw::c_void,+ std::os::raw::c_ulong,+ ) -> std::os::raw::c_ulong,+ pub FPDFImageObj_GetImageDataRaw: unsafe extern "C" fn(+ FPDF_PAGEOBJECT,+ *mut std::os::raw::c_void,+ std::os::raw::c_ulong,+ ) -> std::os::raw::c_ulong,+ pub FPDFImageObj_GetImageFilterCount:+ unsafe extern "C" fn(FPDF_PAGEOBJECT) -> std::os::raw::c_int,+ pub FPDFImageObj_GetImageFilter: unsafe extern "C" fn(+ FPDF_PAGEOBJECT,+ std::os::raw::c_int,+ *mut std::os::raw::c_void,+ std::os::raw::c_ulong,+ ) -> std::os::raw::c_ulong,+ pub FPDFImageObj_GetImageMetadata:+ unsafe extern "C" fn(FPDF_PAGEOBJECT, FPDF_PAGE, *mut FPDF_IMAGEOBJ_METADATA) -> FPDF_BOOL,+ pub FPDFImageObj_GetImagePixelSize: unsafe extern "C" fn(+ FPDF_PAGEOBJECT,+ *mut std::os::raw::c_uint,+ *mut std::os::raw::c_uint,+ ) -> FPDF_BOOL,pub FPDFPageObj_GetMatrix: unsafe extern "C" fn(FPDF_PAGEOBJECT, *mut FS_MATRIX) -> FPDF_BOOL,pub FPDFPageObj_GetStrokeColor: unsafe extern "C" fn(FPDF_PAGEOBJECT,@@ -356,6 +381,12 @@ impl PdfiumBindings {FPDFPageObj_GetBounds: load_fn!(lib, "FPDFPageObj_GetBounds"),FPDFPageObj_GetMarkedContentID: load_fn!(lib, "FPDFPageObj_GetMarkedContentID"),FPDFImageObj_GetRenderedBitmap: load_fn!(lib, "FPDFImageObj_GetRenderedBitmap"),+ FPDFImageObj_GetImageDataDecoded: load_fn!(lib, "FPDFImageObj_GetImageDataDecoded"),+ FPDFImageObj_GetImageDataRaw: load_fn!(lib, "FPDFImageObj_GetImageDataRaw"),+ FPDFImageObj_GetImageFilterCount: load_fn!(lib, "FPDFImageObj_GetImageFilterCount"),+ FPDFImageObj_GetImageFilter: load_fn!(lib, "FPDFImageObj_GetImageFilter"),+ FPDFImageObj_GetImageMetadata: load_fn!(lib, "FPDFImageObj_GetImageMetadata"),+ FPDFImageObj_GetImagePixelSize: load_fn!(lib, "FPDFImageObj_GetImagePixelSize"),FPDFPageObj_GetMatrix: load_fn!(lib, "FPDFPageObj_GetMatrix"),FPDFPageObj_GetStrokeColor: load_fn!(lib, "FPDFPageObj_GetStrokeColor"),FPDFPageObj_GetFillColor: load_fn!(lib, "FPDFPageObj_GetFillColor"),diff --git a/crates/pdfium/src/lib.rs b/crates/pdfium/src/lib.rsindex f357b3c..6cdbc6f 100644--- a/crates/pdfium/src/lib.rs+++ b/crates/pdfium/src/lib.rs@@ -14,7 +14,8 @@ pub use error::PdfiumError;pub use font::{Font, FontType};pub use library::Library;pub use page::{- ImageBounds, Page, PathObject, PathSegment, PdfLink, SegmentKind, ViewportTransform,+ ImageBounds, ImageObjectInfo, ImageObjects, Page, PathObject, PathSegment, PdfLink,+ SegmentKind, ViewportTransform,};pub use struct_tree::StructNode;pub use text_page::{TextChar, TextCharIter, TextPage};diff --git a/crates/pdfium/src/page.rs b/crates/pdfium/src/page.rsindex f6db71b..38695f2 100644--- a/crates/pdfium/src/page.rs+++ b/crates/pdfium/src/page.rs@@ -17,6 +17,126 @@ pub struct ImageBounds {pub height: f32,}+fn image_object_data(obj: pdfium_sys::FPDF_PAGEOBJECT, decoded: bool) -> Option<Vec<u8>> {+ let size = unsafe {+ if decoded {+ ffi!(FPDFImageObj_GetImageDataDecoded(+ obj,+ std::ptr::null_mut(),+ 0+ ))+ } else {+ ffi!(FPDFImageObj_GetImageDataRaw(obj, std::ptr::null_mut(), 0))+ }+ };+ if size == 0 || size > usize::MAX as std::os::raw::c_ulong {+ return None;+ }+ let mut bytes = vec![0u8; size as usize];+ let written = unsafe {+ if decoded {+ ffi!(FPDFImageObj_GetImageDataDecoded(+ obj,+ bytes.as_mut_ptr().cast(),+ size+ ))+ } else {+ ffi!(FPDFImageObj_GetImageDataRaw(+ obj,+ bytes.as_mut_ptr().cast(),+ size+ ))+ }+ };+ if written == 0 || written > size {+ return None;+ }+ bytes.truncate(written as usize);+ Some(bytes)+}++fn image_filters(obj: pdfium_sys::FPDF_PAGEOBJECT) -> Vec<String> {+ let count = unsafe { ffi!(FPDFImageObj_GetImageFilterCount(obj)) };+ if count <= 0 {+ return Vec::new();+ }+ (0..count)+ .filter_map(|index| {+ let size = unsafe {+ ffi!(FPDFImageObj_GetImageFilter(+ obj,+ index,+ std::ptr::null_mut(),+ 0+ ))+ };+ if size == 0 || size > 256 {+ return None;+ }+ let mut bytes = vec![0u8; size as usize];+ let written = unsafe {+ ffi!(FPDFImageObj_GetImageFilter(+ obj,+ index,+ bytes.as_mut_ptr().cast(),+ size+ ))+ };+ if written == 0 {+ return None;+ }+ let end = bytes+ .iter()+ .position(|byte| *byte == 0)+ .unwrap_or(bytes.len());+ std::str::from_utf8(&bytes[..end]).ok().map(str::to_owned)+ })+ .collect()+}++fn is_jpeg(bytes: &[u8]) -> bool {+ bytes.starts_with(&[0xff, 0xd8, 0xff]) && bytes.ends_with(&[0xff, 0xd9])+}++#[cfg(test)]+mod image_tests {+ use super::is_jpeg;++ #[test]+ fn validates_complete_jpeg_streams() {+ assert!(is_jpeg(&[0xff, 0xd8, 0xff, 0xe0, 1, 2, 0xff, 0xd9]));+ assert!(!is_jpeg(&[0xff, 0xd8, 0xff, 0xe0]));+ assert!(!is_jpeg(&[0x89, b'P', b'N', b'G', 0xff, 0xd9]));+ }+}++/// Metadata for an embedded image page object retained by the extraction+/// filters. `object_index` is its index among all image objects on the page.+#[derive(Debug, Clone)]+pub struct ImageObjectInfo {+ pub object_index: usize,+ pub bounds: ImageBounds,+ pub pixel_width: u32,+ pub pixel_height: u32,+ /// Clockwise page-object rotation in degrees, normalized to `[0, 360)`.+ pub rotation: f32,+ /// Original JPEG stream bytes when PDFium reports a directly decodable+ /// DCT stream and the decoded data has a valid JPEG signature.+ pub jpeg_bytes: Option<Vec<u8>>,+ /// Raw encoded stream bytes, used to identify repeated image resources.+ pub raw_bytes: Option<Vec<u8>>,+ #[doc(hidden)]+ pub bits_per_pixel: u32,+ #[doc(hidden)]+ pub colorspace: i32,+}++#[derive(Debug, Clone)]+pub struct ImageObjects {+ pub images: Vec<ImageObjectInfo>,+ pub error_count: u32,+}+/// One segment of a vector path. Coordinates are in viewport space/// (top-left origin, 72 DPI) after the object's matrix has been applied.#[derive(Debug, Clone, Copy)]@@ -204,10 +324,32 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {/// Filters out images smaller than `min_size_pt` and images covering more than/// `max_page_coverage` fraction of the page.pub fn image_bounds(&self, min_size_pt: f32, max_page_coverage: f32) -> Vec<ImageBounds> {+ self.image_objects(min_size_pt, max_page_coverage, false)+ .images+ .into_iter()+ .map(|image| image.bounds)+ .collect()+ }++ /// Extract metadata for embedded image objects on this page.+ pub fn image_objects(+ &self,+ min_size_pt: f32,+ max_page_coverage: f32,+ include_data: bool,+ ) -> ImageObjects {let page_width = self.width();let page_height = self.height();+ let view_box = self.view_box().unwrap_or(RectF {+ left: 0.0,+ top: page_height,+ right: page_width,+ bottom: 0.0,+ });let obj_count = unsafe { ffi!(FPDFPage_CountObjects(self.handle)) };let mut results = Vec::new();+ let mut error_count = 0;+ let mut image_index = 0usize;for i in 0..obj_count {let obj = unsafe { ffi!(FPDFPage_GetObject(self.handle, i)) };@@ -219,6 +361,8 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {if obj_type != pdfium_sys::FPDF_PAGEOBJ_IMAGE as i32 {continue;}+ let object_index = image_index;+ image_index += 1;let mut left: f32 = 0.0;let mut bottom: f32 = 0.0;@@ -234,6 +378,7 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {))};if ok == 0 {+ error_count += 1;continue;}@@ -247,16 +392,89 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {continue;}- // Convert from PDF coords (bottom-left origin) to viewport (top-left origin)- results.push(ImageBounds {- x: left,- y: page_height - top,- width: w,- height: h,+ let viewport = self.bounds_to_viewport(+ &view_box,+ &RectF {+ left,+ top,+ right,+ bottom,+ },+ );++ 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 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+ };++ let raw_bytes = include_data+ .then(|| image_object_data(obj, false))+ .flatten();+ let jpeg_bytes = if include_data+ && image_filters(obj)+ .iter()+ .any(|filter| filter == "DCTDecode")+ {+ image_object_data(obj, true).filter(|bytes| is_jpeg(bytes))+ } else {+ None+ };++ results.push(ImageObjectInfo {+ object_index,+ bounds: ImageBounds {+ x: viewport.left,+ y: viewport.top,+ width: viewport.right - viewport.left,+ height: viewport.bottom - viewport.top,+ },+ pixel_width,+ pixel_height,+ rotation,+ jpeg_bytes,+ raw_bytes,+ bits_per_pixel: metadata.bits_per_pixel,+ colorspace: metadata.colorspace,});}- results+ ImageObjects {+ images: results,+ error_count,+ }}/// Extract bounding boxes of filled vector path objects on this page,diff --git a/packages/node/README.md b/packages/node/README.mdindex f3898ba..5be2ea2 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"+ imageOutputDir: './images', // Write images and return name/path metadata (optional)extractLinks: true, // Render [text](url) links in markdown outputpreserveVerySmallText: false, // Keep tiny textincludeTextMetadata: false, // Opt in to MCID, font metrics, colors, char codes, and tsg@@ -67,6 +68,11 @@ const parser = new LiteParse({});```+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 reuse+one file, and JSON CLI output contains metadata only—never base64 image data.+## Parsing from BytesPass a `Buffer` or `Uint8Array` directly — useful for HTTP responses or in-memory data:diff --git a/packages/node/native.d.ts b/packages/node/native.d.tsindex 37d2dd5..d578fec 100644--- a/packages/node/native.d.ts+++ b/packages/node/native.d.ts@@ -36,9 +36,10 @@ export interface JsLiteParseConfig {/*** How to surface raster images in markdown output: "off", "placeholder"* (default — emits `` references with no bytes), or- * "embed" (also returns each image's PNG bytes on `images`).+ * "embed" (also returns each image's bytes and metadata on `images`).*/imageMode?: string+ imageOutputDir?: string/*** Render hyperlink annotations as `[text](url)` in markdown output* (default true). Set false for plain anchor text.@@ -188,11 +189,25 @@ export interface JsParseResult {pages: Array<JsParsedPage>text: stringimages: Array<JsExtractedImage>+ imageErrorCount: number+}+export interface JsImageRect {+ x: number+ y: number+ width: number+ height: number}export interface JsExtractedImage {id: string+ name: string+ path?: stringpage: number+ bbox: JsImageRect+ width: number+ height: number+ rotation: numberformat: string+ duplicateOf?: stringbytes: Buffer}export interface JsScreenshotResult {diff --git a/packages/node/src/cli.ts b/packages/node/src/cli.tsindex c82e528..713b40a 100644--- a/packages/node/src/cli.ts+++ b/packages/node/src/cli.ts@@ -106,6 +106,8 @@ programif (opts.format) config.outputFormat = opts.format as "json" | "text" | "markdown";if (opts.imageMode)config.imageMode = opts.imageMode as "off" | "placeholder" | "embed";+ if (opts.imageOutputDir)+ config.imageOutputDir = opts.imageOutputDir as string;if (opts.links === false) config.extractLinks = false;if (opts.ocrServerUrl)config.ocrServerUrl = opts.ocrServerUrl as string;@@ -140,24 +142,14 @@ programtext: p.text,textItems: p.textItems,})),+ images: result.images.map(({ bytes: _bytes, ...image }) => image),+ imageErrorCount: result.imageErrorCount,},null,2,): result.text;- if (opts.imageOutputDir && result.images.length > 0) {- const dir = opts.imageOutputDir as string;- mkdirSync(dir, { recursive: true });- for (const img of result.images) {- writeFileSync(join(dir, `image_${img.id}.${img.format}`), img.bytes);- }- if (!opts.quiet) {- console.error(- `[liteparse] wrote ${result.images.length} image(s) to ${dir}`,- );- }- }if (opts.output) {writeFileSync(opts.output as string, output, "utf-8");@@ -401,6 +393,8 @@ programtext: p.text,textItems: p.textItems,})),+ images: result.images.map(({ bytes: _bytes, ...image }) => image),+ imageErrorCount: result.imageErrorCount,},null,2,diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.tsindex c4fbc1d..a860d8f 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;+ /** Directory where extracted embedded image files are written. */+ imageOutputDir?: string;/** Render hyperlink annotations as `[text](url)` in markdown output (default: true). */extractLinks: boolean;preserveVerySmallText: boolean;@@ -199,8 +201,21 @@ export interface ParsedPage {export interface ExtractedImage {/** Reference id used in the markdown output (e.g. `` → `"p1_0"`). */id: string;+ /** File name used when `imageOutputDir` is configured. */+ name: string;+ /** Written file path, absent for in-memory-only extraction. */+ path?: string;page: number;+ /** Placement on the page in viewport coordinates (top-left origin, 72 DPI). */+ bbox: { x: number; y: number; width: number; height: number };+ /** Intrinsic pixel dimensions of the image resource. */+ width: number;+ height: number;+ /** Clockwise page-object rotation in degrees. */+ rotation: number;format: string;+ /** First occurrence with identical encoded source data, when duplicated. */+ duplicateOf?: string;bytes: Buffer;}@@ -209,6 +224,8 @@ export interface ParseResult {text: string;/** Populated only when configured with `imageMode: "embed"`. */images: ExtractedImage[];+ /** Embedded image objects that PDFium could not render or encode. */+ imageErrorCount: number;}export interface ScreenshotResult {@@ -314,6 +331,7 @@ export class LiteParse {dpi: userConfig.dpi,outputFormat: userConfig.outputFormat,imageMode: userConfig.imageMode,+ imageOutputDir: userConfig.imageOutputDir,extractLinks: userConfig.extractLinks,preserveVerySmallText: userConfig.preserveVerySmallText,password: userConfig.password,@@ -343,6 +361,7 @@ export class LiteParse {dpi: resolved.dpi ?? 150,outputFormat: (resolved.outputFormat as OutputFormat) ?? "json",imageMode: (resolved.imageMode as ImageMode) ?? "placeholder",+ imageOutputDir: resolved.imageOutputDir ?? undefined,extractLinks: resolved.extractLinks ?? true,preserveVerySmallText: resolved.preserveVerySmallText ?? false,password: resolved.password ?? undefined,@@ -367,6 +386,7 @@ export class LiteParse {pages: result.pages.map(toPage),text: result.text,images: (result.images ?? []).map(toImage),+ imageErrorCount: result.imageErrorCount ?? 0,};}@@ -389,6 +409,7 @@ export class LiteParse {pages: result.pages.map(toPage),text: result.text,images: (result.images ?? []).map(toImage),+ imageErrorCount: result.imageErrorCount ?? 0,};}@@ -473,8 +494,15 @@ function toPage(p: NativeParsedPage): ParsedPage {function toImage(img: NativeExtractedImage): ExtractedImage {return {id: img.id,+ name: img.name,+ path: img.path,page: img.page,+ bbox: img.bbox,+ width: img.width,+ height: img.height,+ rotation: img.rotation,format: img.format,+ duplicateOf: img.duplicateOf,bytes: img.bytes,};}diff --git a/packages/node/src/native.ts b/packages/node/src/native.tsindex a512109..f58c3d2 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;+ imageOutputDir?: string;extractLinks?: boolean;preserveVerySmallText?: boolean;password?: string;@@ -120,8 +121,15 @@ export interface NativeParsedPage {export interface NativeExtractedImage {id: string;+ name: string;+ path?: string;page: number;+ bbox: { x: number; y: number; width: number; height: number };+ width: number;+ height: number;+ rotation: number;format: string;+ duplicateOf?: string;bytes: Buffer;}@@ -129,6 +137,7 @@ export interface NativeParseResult {pages: NativeParsedPage[];text: string;images: NativeExtractedImage[];+ imageErrorCount: number;}export interface NativeScreenshotResult {diff --git a/packages/python/README.md b/packages/python/README.mdindex 0454b2b..4925a62 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"+ 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 textinclude_text_metadata=False, # Opt in to MCID, font metrics, colors, char codes, and tsg@@ -66,6 +67,11 @@ parser = LiteParse()```+When ``image_output_dir`` 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+reuse one file, and JSON CLI output contains metadata only—never base64 image data.+## Parsing from BytesPass raw PDF bytes directly — useful for web uploads or downloaded files:diff --git a/packages/python/liteparse/__init__.py b/packages/python/liteparse/__init__.pyindex 196657f..a5b57d6 100644--- a/packages/python/liteparse/__init__.py+++ b/packages/python/liteparse/__init__.py@@ -3,6 +3,7 @@ from importlib.metadata import PackageNotFoundError, versionfrom .parser import LiteParse, search_itemsfrom .types import (ExtractedImage,+ ImageRect,LayoutComplexityStats,LiteParseConfig,PageComplexityStats,@@ -29,6 +30,7 @@ __all__ = ["PageComplexityStats","LayoutComplexityStats","ExtractedImage",+ "ImageRect","ParseError","search_items",]diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.pyindex 1e04abf..13c3e67 100644--- a/packages/python/liteparse/parser.py+++ b/packages/python/liteparse/parser.py@@ -8,6 +8,7 @@ from liteparse._liteparse import search_items as _native_search_itemsfrom .types import (ExtractedImage,+ ImageRect,LayoutComplexityStats,LiteParseConfig,PageComplexityStats,@@ -111,9 +112,21 @@ def _convert_native_result(native_result: Any) -> ParseResult:images = [ExtractedImage(id=img.id,+ name=img.name,+ path=img.path,page=img.page,+ bbox=ImageRect(+ x=img.bbox.x,+ y=img.bbox.y,+ width=img.bbox.width,+ height=img.bbox.height,+ ),+ width=img.width,+ height=img.height,+ rotation=img.rotation,format=img.format,bytes=img.bytes,+ duplicate_of=img.duplicate_of,)for img in getattr(native_result, "images", [])]@@ -121,6 +134,7 @@ def _convert_native_result(native_result: Any) -> ParseResult:pages=pages,text=native_result.text,images=images,+ image_error_count=getattr(native_result, "image_error_count", 0),)@@ -154,6 +168,7 @@ class LiteParse:quiet: Optional[bool] = None,num_workers: Optional[int] = None,image_mode: Optional[str] = None,+ image_output_dir: Optional[Union[str, Path]] = None,extract_links: Optional[bool] = None,ocr_failure_fatal: Optional[bool] = None,ocr_hedge_delays_ms: Optional[List[int]] = None,@@ -183,6 +198,9 @@ class LiteParse:num_workers: Number of concurrent OCR workers (default: CPU cores - 1)extract_links: Render hyperlink annotations as ``[text](url)`` inmarkdown output (default: True). Set False for plain anchor text.+ image_output_dir: Directory where extracted embedded images are+ written. Setting it enables image extraction and returns file+ names/paths in each ``ExtractedImage``.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@@ -245,6 +263,8 @@ class LiteParse:kwargs["num_workers"] = num_workersif image_mode is not None:kwargs["image_mode"] = image_mode+ if image_output_dir is not None:+ kwargs["image_output_dir"] = str(image_output_dir)if extract_links is not None:kwargs["extract_links"] = extract_linksif ocr_failure_fatal is not None:@@ -394,6 +414,7 @@ class LiteParse:quiet=cfg.quiet,num_workers=cfg.num_workers,image_mode=cfg.image_mode,+ image_output_dir=cfg.image_output_dir,extract_links=cfg.extract_links,ocr_failure_fatal=cfg.ocr_failure_fatal,ocr_hedge_delays_ms=list(cfg.ocr_hedge_delays_ms),diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.pyindex 3951bbc..3dcfcf3 100644--- a/packages/python/liteparse/types.py+++ b/packages/python/liteparse/types.py@@ -64,6 +64,15 @@ class ParsedPage:complexity: Optional[PageComplexityStats] = None+@dataclass+class ImageRect:+ """Image placement in viewport coordinates (top-left origin, 72 DPI)."""+ x: float+ y: float+ width: float+ height: float++@dataclassclass ExtractedImage:"""An embedded raster image extracted from a page.@@ -73,9 +82,16 @@ class ExtractedImage:(e.g. ```` → ``id="p1_0"``)."""id: str+ name: str+ path: Optional[str]page: int+ bbox: ImageRect+ width: int+ height: int+ rotation: floatformat: strbytes: bytes+ duplicate_of: Optional[str] = None@dataclass@@ -84,6 +100,7 @@ class ParseResult:pages: List[ParsedPage]text: strimages: List[ExtractedImage] = field(default_factory=list)+ image_error_count: int = 0@propertydef num_pages(self) -> int:@@ -170,6 +187,7 @@ class LiteParseConfig:quiet: boolnum_workers: intimage_mode: str+ image_output_dir: Optional[str]extract_links: boolocr_failure_fatal: boolocr_hedge_delays_ms: List[int]