Skip to content

A fast, helpful, and open-source document parser

Add PDF embedded image extraction parity

Pierre-Loic doulcetd5d7d87fbfb6
diff --git a/README.md b/README.md
index afc18c4..6f34856 100644
--- a/README.md
+++ b/README.md
@@ -190,7 +190,12 @@ Image handling is controlled by `--image-mode`:
|------|----------|
| `placeholder` (default) | Emits `![](image_pN_K.png)` 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.rs
index 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 `![](image_pN_K.png)` 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 raster
images 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.rs
index 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.rs
index 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 the
diff --git a/crates/liteparse/src/main.rs b/crates/liteparse/src/main.rs
index 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 `![](image_pN_K.png)`
- /// 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.rs
index 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
- /// `![](image_{id}.png)`. Suppressed entirely when `ImageMode::Off`.
+ /// `![](image_{id}.{format})`. 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("![](image_");
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(),
+ }]),
+ "![](image_p1_0.jpg)"
+ );
+ }
+
#[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.rs
index 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.rs
index 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.rs
index 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 `![](image_{id}.png)`, 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index f3898ba..5be2ea2 100644
--- a/packages/node/README.md
+++ b/packages/node/README.md
@@ -58,6 +58,7 @@ const parser = new LiteParse({
dpi: 150, // Rendering DPI
outputFormat: '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 output
preserveVerySmallText: false, // Keep tiny text
includeTextMetadata: 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 Bytes
Pass 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.ts
index 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 `![](image_pN_K.png)` 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: string
images: Array<JsExtractedImage>
+ imageErrorCount: number
+}
+export interface JsImageRect {
+ x: number
+ y: number
+ width: number
+ height: number
}
export interface JsExtractedImage {
id: string
+ name: string
+ path?: string
page: number
+ bbox: JsImageRect
+ width: number
+ height: number
+ rotation: number
format: string
+ duplicateOf?: string
bytes: Buffer
}
export interface JsScreenshotResult {
diff --git a/packages/node/src/cli.ts b/packages/node/src/cli.ts
index c82e528..713b40a 100644
--- a/packages/node/src/cli.ts
+++ b/packages/node/src/cli.ts
@@ -106,6 +106,8 @@ program
if (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 @@ program
text: 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 @@ program
text: 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.ts
index 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. `![](image_p1_0.png)` → `"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.ts
index 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.md
index 0454b2b..4925a62 100644
--- a/packages/python/README.md
+++ b/packages/python/README.md
@@ -57,6 +57,7 @@ parser = LiteParse(
dpi=150, # Rendering DPI
output_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 output
preserve_very_small_text=False, # Keep tiny text
include_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 Bytes
Pass raw PDF bytes directly — useful for web uploads or downloaded files:
diff --git a/packages/python/liteparse/__init__.py b/packages/python/liteparse/__init__.py
index 196657f..a5b57d6 100644
--- a/packages/python/liteparse/__init__.py
+++ b/packages/python/liteparse/__init__.py
@@ -3,6 +3,7 @@ from importlib.metadata import PackageNotFoundError, version
from .parser import LiteParse, search_items
from .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.py
index 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_items
from .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)`` in
markdown 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 task
failed and at least one was a text-sparse page) aborts the whole
parse (default: True). Set False to keep already-recovered native
@@ -245,6 +263,8 @@ class LiteParse:
kwargs["num_workers"] = num_workers
if 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_links
if 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.py
index 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
+
+
@dataclass
class ExtractedImage:
"""An embedded raster image extracted from a page.
@@ -73,9 +82,16 @@ class ExtractedImage:
(e.g. ``![](image_p1_0.png)`` → ``id="p1_0"``).
"""
id: str
+ name: str
+ path: Optional[str]
page: int
+ bbox: ImageRect
+ width: int
+ height: int
+ rotation: float
format: str
bytes: bytes
+ duplicate_of: Optional[str] = None
@dataclass
@@ -84,6 +100,7 @@ class ParseResult:
pages: List[ParsedPage]
text: str
images: List[ExtractedImage] = field(default_factory=list)
+ image_error_count: int = 0
@property
def num_pages(self) -> int:
@@ -170,6 +187,7 @@ class LiteParseConfig:
quiet: bool
num_workers: int
image_mode: str
+ image_output_dir: Optional[str]
extract_links: bool
ocr_failure_fatal: bool
ocr_hedge_delays_ms: List[int]