Skip to content

A fast, helpful, and open-source document parser

feat: add word-level bbox output (opt-in)

Logan Markewich99aa90bc71fb
diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rs
index d4a8cad..6dbde2f 100644
--- a/crates/liteparse-napi/src/types.rs
+++ b/crates/liteparse-napi/src/types.rs
@@ -4,7 +4,7 @@ use napi_derive::napi;
use liteparse::config::{ImageMode, LiteParseConfig, OutputFormat};
use liteparse::parser::ParseResult;
-use liteparse::types::{GraphicPrimitive, Page, ParsedPage, Rect, TextItem};
+use liteparse::types::{GraphicPrimitive, Page, ParsedPage, Rect, TextItem, WordBox};
// ---------------------------------------------------------------------------
// Config
@@ -55,6 +55,10 @@ pub struct JsLiteParseConfig {
/// delays (e.g. `[0, 5000, 10000]`) fire duplicate requests per attempt and
/// take the first success — lower tail latency at the cost of extra load.
pub ocr_hedge_delays_ms: Option<Vec<u32>>,
+ /// Emit per-word sub-boxes on each text item (`TextItem.words`). Default
+ /// false. Word boxes roughly double the text-item payload, so enable only
+ /// for word-level bbox attribution.
+ pub emit_word_boxes: Option<bool>,
}
impl JsLiteParseConfig {
@@ -119,6 +123,9 @@ impl JsLiteParseConfig {
if let Some(v) = self.ocr_hedge_delays_ms {
cfg.ocr_hedge_delays_ms = v.into_iter().map(u64::from).collect();
}
+ if let Some(v) = self.emit_word_boxes {
+ cfg.emit_word_boxes = v;
+ }
cfg
}
@@ -158,6 +165,7 @@ impl JsLiteParseConfig {
.map(|&v| u32::try_from(v).unwrap_or(u32::MAX))
.collect(),
),
+ emit_word_boxes: Some(cfg.emit_word_boxes),
}
}
}
@@ -166,6 +174,29 @@ impl JsLiteParseConfig {
// TextItem
// ---------------------------------------------------------------------------
+/// One word's sub-box within a `JsTextItem`, in the same viewport space.
+#[napi(object)]
+#[derive(Clone)]
+pub struct JsWordBox {
+ pub text: String,
+ pub x: f64,
+ pub y: f64,
+ pub width: f64,
+ pub height: f64,
+}
+
+impl JsWordBox {
+ pub fn from_rust(word: &WordBox) -> Self {
+ Self {
+ text: word.text.clone(),
+ x: word.x as f64,
+ y: word.y as f64,
+ width: word.width as f64,
+ height: word.height as f64,
+ }
+ }
+}
+
#[napi(object)]
#[derive(Clone)]
pub struct JsTextItem {
@@ -179,6 +210,9 @@ pub struct JsTextItem {
pub confidence: Option<f64>,
/// Rotation in degrees (viewport space). Defaults to 0 when omitted.
pub rotation: Option<f64>,
+ /// Per-word sub-boxes for attribution. Empty for items with no word split
+ /// (e.g. OCR-sourced or single-token items).
+ pub words: Vec<JsWordBox>,
}
impl JsTextItem {
@@ -208,6 +242,7 @@ impl JsTextItem {
font_name: item.font_name.clone(),
font_size: item.font_size.map(|v| v as f64),
confidence: item.confidence.map(|v| v as f64).or(Some(1.0)),
+ words: item.words.iter().map(JsWordBox::from_rust).collect(),
}
}
}
diff --git a/crates/liteparse-python/src/lib.rs b/crates/liteparse-python/src/lib.rs
index 11d11b5..90b4e26 100644
--- a/crates/liteparse-python/src/lib.rs
+++ b/crates/liteparse-python/src/lib.rs
@@ -12,6 +12,43 @@ mod cli;
// Python type wrappers
// ---------------------------------------------------------------------------
+#[pyclass(frozen, from_py_object)]
+#[derive(Clone)]
+struct PyWordBox {
+ #[pyo3(get)]
+ text: String,
+ #[pyo3(get)]
+ x: f64,
+ #[pyo3(get)]
+ y: f64,
+ #[pyo3(get)]
+ width: f64,
+ #[pyo3(get)]
+ height: f64,
+}
+
+#[pymethods]
+impl PyWordBox {
+ fn __repr__(&self) -> String {
+ format!(
+ "WordBox(text={:?}, x={}, y={}, width={}, height={})",
+ self.text, self.x, self.y, self.width, self.height
+ )
+ }
+}
+
+impl PyWordBox {
+ fn from_rust(word: liteparse::types::WordBox) -> Self {
+ Self {
+ text: word.text,
+ x: word.x as f64,
+ y: word.y as f64,
+ width: word.width as f64,
+ height: word.height as f64,
+ }
+ }
+}
+
#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyTextItem {
@@ -31,6 +68,13 @@ struct PyTextItem {
font_size: Option<f64>,
#[pyo3(get)]
confidence: Option<f64>,
+ /// Rotation in degrees (viewport space). Defaults to 0.
+ #[pyo3(get)]
+ rotation: f64,
+ /// Per-word sub-boxes for attribution. Empty unless the parse was
+ /// configured with `emit_word_boxes=True`.
+ #[pyo3(get)]
+ words: Vec<PyWordBox>,
}
#[pymethods]
@@ -51,6 +95,7 @@ impl PyTextItem {
y: self.y as f32,
width: self.width as f32,
height: self.height as f32,
+ rotation: self.rotation as f32,
font_name: self.font_name.clone(),
font_size: self.font_size.map(|v| v as f32),
confidence: self.confidence.map(|v| v as f32),
@@ -68,6 +113,8 @@ impl PyTextItem {
font_name: item.font_name,
font_size: item.font_size.map(|v| v as f64),
confidence: item.confidence.map(|v| v as f64).or(Some(1.0)),
+ rotation: item.rotation as f64,
+ words: item.words.into_iter().map(PyWordBox::from_rust).collect(),
}
}
}
@@ -405,6 +452,7 @@ impl LiteParse {
extract_links = None,
ocr_failure_fatal = None,
ocr_hedge_delays_ms = None,
+ emit_word_boxes = None,
))]
fn new(
ocr_language: Option<String>,
@@ -424,6 +472,7 @@ impl LiteParse {
extract_links: Option<bool>,
ocr_failure_fatal: Option<bool>,
ocr_hedge_delays_ms: Option<Vec<u64>>,
+ emit_word_boxes: Option<bool>,
) -> PyResult<Self> {
let mut cfg = LiteParseConfig::default();
if let Some(v) = ocr_language {
@@ -485,6 +534,9 @@ impl LiteParse {
if let Some(v) = ocr_hedge_delays_ms {
cfg.ocr_hedge_delays_ms = v;
}
+ if let Some(v) = emit_word_boxes {
+ cfg.emit_word_boxes = v;
+ }
let inner = liteparse::parser::LiteParse::new(cfg.clone());
let runtime = tokio::runtime::Runtime::new()
@@ -615,6 +667,7 @@ fn _liteparse(m: &Bound<'_, PyModule>) -> PyResult<()> {
m.add_class::<PyExtractedImage>()?;
m.add_class::<PyParsedPage>()?;
m.add_class::<PyTextItem>()?;
+ m.add_class::<PyWordBox>()?;
m.add_class::<PyScreenshotResult>()?;
m.add_class::<PyPageComplexityStats>()?;
m.add_function(wrap_pyfunction!(run_cli, m)?)?;
diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rs
index 9861738..04c68d2 100644
--- a/crates/liteparse-wasm/src/lib.rs
+++ b/crates/liteparse-wasm/src/lib.rs
@@ -54,6 +54,7 @@ struct JsLiteParseConfig {
preserve_very_small_text: Option<bool>,
password: Option<String>,
quiet: Option<bool>,
+ emit_word_boxes: Option<bool>,
}
impl JsLiteParseConfig {
@@ -121,6 +122,9 @@ impl JsLiteParseConfig {
if let Some(v) = self.quiet {
cfg.quiet = v;
}
+ if let Some(v) = self.emit_word_boxes {
+ cfg.emit_word_boxes = v;
+ }
cfg.num_workers = 1;
Ok(cfg)
}
@@ -155,6 +159,7 @@ impl JsLiteParseConfig {
preserve_very_small_text: Some(cfg.preserve_very_small_text),
password: cfg.password.clone(),
quiet: Some(cfg.quiet),
+ emit_word_boxes: Some(cfg.emit_word_boxes),
}
}
}
@@ -163,6 +168,16 @@ impl JsLiteParseConfig {
// JS-facing parse result
// ---------------------------------------------------------------------------
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct JsWordBox<'a> {
+ text: &'a str,
+ x: f32,
+ y: f32,
+ width: f32,
+ height: f32,
+}
+
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsTextItem<'a> {
@@ -177,6 +192,12 @@ struct JsTextItem<'a> {
font_size: Option<f32>,
#[serde(skip_serializing_if = "Option::is_none")]
confidence: Option<f32>,
+ /// Rotation in degrees (viewport space).
+ rotation: f32,
+ /// Per-word sub-boxes for attribution. Omitted when empty (the default —
+ /// only populated when parsing with `emitWordBoxes: true`).
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ words: Vec<JsWordBox<'a>>,
}
#[derive(Serialize)]
@@ -381,6 +402,18 @@ impl LiteParse {
font_name: i.font_name.as_deref(),
font_size: i.font_size,
confidence: i.confidence,
+ rotation: i.rotation,
+ words: i
+ .words
+ .iter()
+ .map(|w| JsWordBox {
+ text: &w.text,
+ x: w.x,
+ y: w.y,
+ width: w.width,
+ height: w.height,
+ })
+ .collect(),
})
.collect(),
})
@@ -543,6 +576,18 @@ pub fn search_items(items: JsValue, options: JsValue) -> Result<JsValue, JsError
font_name: i.font_name.as_deref(),
font_size: i.font_size,
confidence: i.confidence,
+ rotation: i.rotation,
+ words: i
+ .words
+ .iter()
+ .map(|w| JsWordBox {
+ text: &w.text,
+ x: w.x,
+ y: w.y,
+ width: w.width,
+ height: w.height,
+ })
+ .collect(),
})
.collect();
diff --git a/crates/liteparse/src/config.rs b/crates/liteparse/src/config.rs
index 88c6333..517286a 100644
--- a/crates/liteparse/src/config.rs
+++ b/crates/liteparse/src/config.rs
@@ -53,6 +53,13 @@ pub struct LiteParseConfig {
/// OCR-server load for lower tail latency on a slow/stuck pod. No effect on
/// the Tesseract engine.
pub ocr_hedge_delays_ms: Vec<u64>,
+ /// Emit per-word sub-boxes on each `TextItem` (`TextItem.words`). Default
+ /// `false`: a text item already carries its own box, and word boxes roughly
+ /// double the text-item payload (size + napi marshalling), so they are only
+ /// worth computing for callers doing word-level bbox attribution. When
+ /// `false`, `TextItem.words` is always empty and the per-word tracking is
+ /// skipped entirely (zero allocation).
+ pub emit_word_boxes: bool,
}
/// Image handling for the markdown emitter.
@@ -113,6 +120,7 @@ impl Default for LiteParseConfig {
extract_links: true,
ocr_failure_fatal: true,
ocr_hedge_delays_ms: Vec::new(),
+ emit_word_boxes: false,
}
}
}
diff --git a/crates/liteparse/src/extract.rs b/crates/liteparse/src/extract.rs
index 797eecd..13a8dc3 100644
--- a/crates/liteparse/src/extract.rs
+++ b/crates/liteparse/src/extract.rs
@@ -2,7 +2,7 @@ use crate::error::LiteParseError;
use crate::glyph_names::resolve_glyph_name;
use crate::types::{
ExtractedImage, GraphicPrimitive, ImageRef, OutlineTarget, Page as LitePage, PdfInput, Rect,
- StructNode, TextItem,
+ StructNode, TextItem, WordBox,
};
use image::ImageEncoder;
use pdfium::{
@@ -49,7 +49,7 @@ pub(crate) fn extract_pages_from_document(
target_pages: Option<&[u32]>,
max_pages: usize,
) -> Result<Vec<LitePage>, LiteParseError> {
- Ok(extract_pages_and_images(document, target_pages, max_pages, false, false, None)?.0)
+ Ok(extract_pages_and_images(document, target_pages, max_pages, false, false, None, false)?.0)
}
/// Same as `extract_pages_from_document` but optionally also renders every
@@ -64,6 +64,7 @@ pub(crate) fn extract_pages_and_images(
render_images: bool,
extract_links: bool,
glyph_resolver: Option<&dyn crate::GlyphResolver>,
+ emit_word_boxes: bool,
) -> Result<(Vec<LitePage>, Vec<ExtractedImage>), LiteParseError> {
let page_count = document.page_count();
let mut pages = Vec::new();
@@ -90,7 +91,13 @@ pub(crate) fn extract_pages_and_images(
right: page.width(),
bottom: 0.0,
});
- let mut text_items = extract_page_text_items(&page, &text_page, &view_box, glyph_resolver)?;
+ let mut text_items = extract_page_text_items(
+ &page,
+ &text_page,
+ &view_box,
+ glyph_resolver,
+ emit_word_boxes,
+ )?;
if extract_links {
assign_links(&mut text_items, &page.links(&view_box));
}
@@ -524,6 +531,7 @@ fn extract_page_text_items(
text_page: &TextPage,
view_box: &RectF,
glyph_resolver: Option<&dyn crate::GlyphResolver>,
+ emit_word_boxes: bool,
) -> Result<Vec<TextItem>, LiteParseError> {
let char_count = text_page.char_count();
if char_count <= 0 {
@@ -554,7 +562,7 @@ fn extract_page_text_items(
let page_rotation = page.rotation();
let vp_xform = page.viewport_transform(view_box);
let mut items: Vec<TextItem> = Vec::new();
- let mut seg = SegmentBuilder::new();
+ let mut seg = SegmentBuilder::new(emit_word_boxes);
let garbage_fonts = detect_garbage_unicode_fonts(text_page, char_count);
let mut glyph_decoder = GlyphDecoder::new(
std::env::var("LITEPARSE_DEBUG_GLYPH").is_ok(),
@@ -829,6 +837,7 @@ fn extract_page_text_items(
};
if both_alnum && thresh > 0.0 && loose_gap > thresh {
seg.text.push(' ');
+ seg.break_word();
}
seg.push_char(c, &vp_loose, &vp_strict, &ch);
seg.append_ligature_tail(ligature_tail);
@@ -1408,10 +1417,22 @@ struct SegmentBuilder {
stroke_color: Option<String>,
has_content: bool,
pending_space: bool,
+ // Per-word sub-boxes, finalized at each inter-word space break. The
+ // currently-open word is accumulated in the `word_*` fields below and
+ // flushed into `words` by `break_word`.
+ words: Vec<WordBox>,
+ cur_word: String,
+ word_left: f32,
+ word_right: f32,
+ word_top: f32,
+ word_bottom: f32,
+ word_has: bool,
+ // When false, per-word tracking is skipped entirely and `words` stays empty.
+ emit_words: bool,
}
impl SegmentBuilder {
- fn new() -> Self {
+ fn new(emit_words: bool) -> Self {
Self {
text: String::new(),
vp_left: f32::MAX,
@@ -1440,9 +1461,59 @@ impl SegmentBuilder {
stroke_color: None,
has_content: false,
pending_space: false,
+ words: Vec::new(),
+ cur_word: String::new(),
+ word_left: f32::MAX,
+ word_right: f32::MIN,
+ word_top: f32::MAX,
+ word_bottom: f32::MIN,
+ word_has: false,
+ emit_words,
}
}
+ /// Extend the currently-open word with a character's loose box, opening a
+ /// fresh word if none is active. No-op unless word emission is enabled.
+ fn add_word_char(&mut self, c: char, vp_loose: &RectF) {
+ if !self.emit_words {
+ return;
+ }
+ if self.word_has {
+ self.word_left = self.word_left.min(vp_loose.left);
+ self.word_right = self.word_right.max(vp_loose.right);
+ self.word_top = self.word_top.min(vp_loose.top);
+ self.word_bottom = self.word_bottom.max(vp_loose.bottom);
+ } else {
+ self.cur_word.clear();
+ self.word_left = vp_loose.left;
+ self.word_right = vp_loose.right;
+ self.word_top = vp_loose.top;
+ self.word_bottom = vp_loose.bottom;
+ self.word_has = true;
+ }
+ self.cur_word.push(c);
+ }
+
+ /// Finalize the open word (if any) into `words` and reset the accumulator.
+ /// Called at each inter-word space and at segment flush.
+ fn break_word(&mut self) {
+ if !self.word_has {
+ return;
+ }
+ let trimmed = self.cur_word.trim();
+ if !trimmed.is_empty() {
+ self.words.push(WordBox {
+ text: trimmed.to_string(),
+ x: self.word_left,
+ y: self.word_top,
+ width: self.word_right - self.word_left,
+ height: self.word_bottom - self.word_top,
+ });
+ }
+ self.cur_word.clear();
+ self.word_has = false;
+ }
+
/// Average width of non-space characters in the current segment.
/// Prefers actual glyph widths (text_width) over bbox width, since bbox
/// includes inter-character gaps that inflate the average and cause
@@ -1480,6 +1551,9 @@ impl SegmentBuilder {
self.unmapped_char_count = if ch.has_unicode_map_error() { 1 } else { 0 };
self.has_content = true;
self.pending_space = false;
+ self.words.clear();
+ self.word_has = false;
+ self.add_word_char(c, vp_loose);
self.text_width = 0.0;
self.font_is_buggy = false;
self.font_is_embedded = false;
@@ -1564,6 +1638,7 @@ impl SegmentBuilder {
/// Add a visible character to the current segment.
fn push_char(&mut self, c: char, vp_loose: &RectF, vp_strict: &RectF, ch: &pdfium::TextChar) {
self.text.push(c);
+ self.add_word_char(c, vp_loose);
self.vp_left = self.vp_left.min(vp_loose.left);
self.vp_right = self.vp_right.max(vp_loose.right);
self.vp_top = self.vp_top.min(vp_loose.top);
@@ -1601,6 +1676,9 @@ impl SegmentBuilder {
/// Does not update bounding boxes or char count.
fn append_ligature_tail(&mut self, tail: &str) {
self.text.push_str(tail);
+ if self.word_has {
+ self.cur_word.push_str(tail);
+ }
}
/// Returns true if the segment contains any characters that aren't dots or spaces.
@@ -1620,6 +1698,7 @@ impl SegmentBuilder {
/// Commit a pending space into the segment text.
fn commit_pending_space(&mut self) {
if self.pending_space {
+ self.break_word();
self.text.push(' ');
self.pending_space = false;
}
@@ -1631,6 +1710,7 @@ impl SegmentBuilder {
return;
}
+ self.break_word();
let trimmed = self.text.trim();
if !trimmed.is_empty() {
let width = self.vp_right - self.vp_left;
@@ -1669,10 +1749,11 @@ impl SegmentBuilder {
confidence: None,
link: None,
strike: false,
+ words: std::mem::take(&mut self.words),
});
}
- *self = Self::new();
+ *self = Self::new(self.emit_words);
}
}
diff --git a/crates/liteparse/src/lib.rs b/crates/liteparse/src/lib.rs
index 0efa0ec..688b23b 100644
--- a/crates/liteparse/src/lib.rs
+++ b/crates/liteparse/src/lib.rs
@@ -12,7 +12,7 @@ pub use font_db_resolver::FontDbResolver;
pub use glyph_resolver::{GLYPH_RESOLVER_FONT_SIZE, GlyphResolver};
pub use parser::{LiteParse, ParseResult, ScreenshotResult};
pub use search::{SearchOptions, search_items};
-pub use types::{ParsedPage, TextItem};
+pub use types::{ParsedPage, TextItem, WordBox};
// ── Modules with user-facing types (visible in docs) ───────────────────
pub mod config;
diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rs
index e8bfac6..183100f 100644
--- a/crates/liteparse/src/parser.rs
+++ b/crates/liteparse/src/parser.rs
@@ -171,6 +171,7 @@ impl LiteParse {
false, // render_images: image rasters not needed for complexity
false, // extract_links: irrelevant for complexity stats
self.glyph_resolver.as_deref(),
+ false, // emit_word_boxes: word boxes not needed for complexity stats
)?;
let t_extract = web_time::Instant::now();
log(&format!(
@@ -296,6 +297,7 @@ impl LiteParse {
self.config.extract_links
&& self.config.output_format == crate::config::OutputFormat::Markdown,
self.glyph_resolver.as_deref(),
+ self.config.emit_word_boxes,
)?;
let t_extract = web_time::Instant::now();
log(&format!(
diff --git a/crates/liteparse/src/types.rs b/crates/liteparse/src/types.rs
index 5717189..5ddf9f5 100644
--- a/crates/liteparse/src/types.rs
+++ b/crates/liteparse/src/types.rs
@@ -67,6 +67,27 @@ pub struct TextItem {
/// markdown emitter to wrap the text in `~~…~~`.
#[serde(skip_serializing_if = "std::ops::Not::not")]
pub strike: bool,
+ /// Per-word sub-boxes within this item, split on the inter-word spaces seen
+ /// during segment building. A segment groups several words together (it only
+ /// breaks at line/column boundaries), so this exposes the finer word-level
+ /// geometry needed for bbox attribution. Empty for items that produced no
+ /// word split (e.g. OCR-sourced or single-token items). Internal/attribution
+ /// use only — `#[serde(skip)]` keeps it out of the JSON output but it is
+ /// marshalled across the napi boundary.
+ #[serde(skip)]
+ pub words: Vec<WordBox>,
+}
+
+/// One word's bounding box within a `TextItem`, in the same viewport space
+/// (top-left origin, 72 DPI) as the parent item. `text` is the word's content
+/// with inter-word spaces excluded.
+#[derive(Debug, Clone, Default, Serialize)]
+pub struct WordBox {
+ pub text: String,
+ pub x: f32,
+ pub y: f32,
+ pub width: f32,
+ pub height: f32,
}
#[doc(hidden)]
diff --git a/packages/node/native.d.ts b/packages/node/native.d.ts
index d428c16..f9fe03b 100644
--- a/packages/node/native.d.ts
+++ b/packages/node/native.d.ts
@@ -56,6 +56,20 @@ export interface JsLiteParseConfig {
* take the first success — lower tail latency at the cost of extra load.
*/
ocrHedgeDelaysMs?: Array<number>
+ /**
+ * Emit per-word sub-boxes on each text item (`TextItem.words`). Default
+ * false. Word boxes roughly double the text-item payload, so enable only
+ * for word-level bbox attribution.
+ */
+ emitWordBoxes?: boolean
+}
+/** One word's sub-box within a `JsTextItem`, in the same viewport space. */
+export interface JsWordBox {
+ text: string
+ x: number
+ y: number
+ width: number
+ height: number
}
export interface JsTextItem {
text: string
@@ -68,6 +82,11 @@ export interface JsTextItem {
confidence?: number
/** Rotation in degrees (viewport space). Defaults to 0 when omitted. */
rotation?: number
+ /**
+ * Per-word sub-boxes for attribution. Empty for items with no word split
+ * (e.g. OCR-sourced or single-token items).
+ */
+ words: Array<JsWordBox>
}
/**
* A vector-graphic primitive supplied by an external extractor. `kind` selects
@@ -136,6 +155,21 @@ export interface JsScreenshotResult {
height: number
imageBuffer: Buffer
}
+export interface JsPageComplexityStats {
+ pageNumber: number
+ textLength: number
+ textCoverage: number
+ hasSubstantialImages: boolean
+ imageBlockCount: number
+ imageCoverage: number
+ largestImageCoverage: number
+ fullPageImage: boolean
+ uncoveredVectorArea?: number
+ isGarbled: boolean
+ pageArea: number
+ needsOcr: boolean
+ reasons: Array<string>
+}
/** Search text items for phrase matches, returning merged items with combined bounding boxes. */
export declare function searchItems(items: Array<JsTextItem>, phrase: string, caseSensitive?: boolean | undefined | null): Array<JsTextItem>
/** Main LiteParse parser class. */
@@ -157,6 +191,13 @@ export declare class LiteParse {
* font-recovery pipeline).
*/
parsePages(pages: Array<JsPageInput>): JsParseResult
+ /**
+ * Determine per-page complexity. Returns one entry per parsed page with
+ * signals (text coverage, images, garbled text, vector area) and a
+ * `needsOcr` verdict — a cheap pre-OCR check to decide whether a document
+ * needs advanced parsing. Accepts a file path (string) or raw PDF bytes.
+ */
+ isComplex(input: string | Buffer): Promise<Array<JsPageComplexityStats>>
/**
* Take screenshots of document pages. Returns PNG image buffers.
*
diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.ts
index b713c9c..9b0206c 100644
--- a/packages/node/src/lib.ts
+++ b/packages/node/src/lib.ts
@@ -51,6 +51,24 @@ export interface LiteParseConfig {
* OCR pod, at the cost of extra OCR-server load. HTTP OCR engine only.
*/
ocrHedgeDelaysMs: number[];
+ /**
+ * Emit per-word sub-boxes on each text item ({@link TextItem.words}).
+ * Default false. Word boxes roughly double the text-item payload (size + napi
+ * marshalling), so enable only when doing word-level bbox attribution.
+ */
+ emitWordBoxes: boolean;
+}
+
+/**
+ * One word's bounding box within a {@link TextItem}, in the same viewport space
+ * (top-left origin, 72 DPI). `text` excludes inter-word spaces.
+ */
+export interface WordBox {
+ text: string;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
}
export interface TextItem {
@@ -64,6 +82,13 @@ export interface TextItem {
confidence?: number;
/** Rotation in degrees (viewport space). Defaults to 0 when omitted. */
rotation?: number;
+ /**
+ * Per-word sub-boxes within this item. A text item groups several words
+ * together (breaking only at line/column boundaries), so this carries the
+ * finer word-level geometry for bbox attribution. Empty/undefined for items
+ * with no word split (e.g. OCR-sourced or single-token items).
+ */
+ words?: WordBox[];
}
/**
@@ -199,6 +224,7 @@ export class LiteParse {
numWorkers: userConfig.numWorkers,
ocrFailureFatal: userConfig.ocrFailureFatal,
ocrHedgeDelaysMs: userConfig.ocrHedgeDelaysMs,
+ emitWordBoxes: userConfig.emitWordBoxes,
};
this._native = new native.LiteParse(nativeConfig);
@@ -223,6 +249,7 @@ export class LiteParse {
numWorkers: resolved.numWorkers ?? 1,
ocrFailureFatal: resolved.ocrFailureFatal ?? true,
ocrHedgeDelaysMs: resolved.ocrHedgeDelaysMs ?? [],
+ emitWordBoxes: resolved.emitWordBoxes ?? false,
};
}
@@ -339,6 +366,8 @@ function toTextItem(item: NativeTextItem): TextItem {
fontName: item.fontName,
fontSize: item.fontSize,
confidence: item.confidence,
+ rotation: item.rotation,
+ words: item.words,
};
}
diff --git a/packages/node/src/native.ts b/packages/node/src/native.ts
index c313491..dd16ded 100644
--- a/packages/node/src/native.ts
+++ b/packages/node/src/native.ts
@@ -37,6 +37,15 @@ export interface LiteParseNativeConfig {
numWorkers?: number;
ocrFailureFatal?: boolean;
ocrHedgeDelaysMs?: number[];
+ emitWordBoxes?: boolean;
+}
+
+export interface NativeWordBox {
+ text: string;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
}
export interface NativeTextItem {
@@ -49,6 +58,7 @@ export interface NativeTextItem {
fontSize?: number;
confidence?: number;
rotation?: number;
+ words?: NativeWordBox[];
}
export interface NativeGraphic {
diff --git a/packages/python/liteparse/__init__.py b/packages/python/liteparse/__init__.py
index eee674a..3ccef61 100644
--- a/packages/python/liteparse/__init__.py
+++ b/packages/python/liteparse/__init__.py
@@ -6,6 +6,7 @@ from .types import (
ParseResult,
ParsedPage,
TextItem,
+ WordBox,
ScreenshotResult,
ParseError,
)
@@ -17,6 +18,7 @@ __all__ = [
"ParseResult",
"ParsedPage",
"TextItem",
+ "WordBox",
"ScreenshotResult",
"PageComplexityStats",
"ExtractedImage",
diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.py
index 68b47e6..823a9a8 100644
--- a/packages/python/liteparse/parser.py
+++ b/packages/python/liteparse/parser.py
@@ -15,6 +15,7 @@ from .types import (
ParseResult,
ScreenshotResult,
TextItem,
+ WordBox,
)
@@ -32,6 +33,17 @@ def _convert_native_result(native_result: Any) -> ParseResult:
font_name=item.font_name,
font_size=item.font_size,
confidence=item.confidence,
+ rotation=getattr(item, "rotation", 0.0),
+ words=[
+ WordBox(
+ text=w.text,
+ x=w.x,
+ y=w.y,
+ width=w.width,
+ height=w.height,
+ )
+ for w in getattr(item, "words", [])
+ ],
)
for item in native_page.text_items
]
@@ -93,6 +105,7 @@ class LiteParse:
extract_links: Optional[bool] = None,
ocr_failure_fatal: Optional[bool] = None,
ocr_hedge_delays_ms: Optional[List[int]] = None,
+ emit_word_boxes: Optional[bool] = None,
):
"""
Initialize LiteParse parser.
@@ -125,6 +138,10 @@ class LiteParse:
``[0, 5000, 10000]``) each attempt fires a duplicate request at
every delay and takes the first to succeed, cancelling the rest
— trades extra OCR-server load for lower tail latency.
+ emit_word_boxes: Emit per-word sub-boxes on each text item
+ (``TextItem.words``). Default False. Word boxes roughly double
+ the text-item payload, so enable only for word-level bbox
+ attribution.
"""
kwargs = {}
if ocr_enabled is not None:
@@ -161,6 +178,8 @@ class LiteParse:
kwargs["ocr_failure_fatal"] = ocr_failure_fatal
if ocr_hedge_delays_ms is not None:
kwargs["ocr_hedge_delays_ms"] = ocr_hedge_delays_ms
+ if emit_word_boxes is not None:
+ kwargs["emit_word_boxes"] = emit_word_boxes
self._native = _NativeLiteParse(**kwargs)
diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.py
index 57e8215..d85e8e9 100644
--- a/packages/python/liteparse/types.py
+++ b/packages/python/liteparse/types.py
@@ -6,6 +6,17 @@ from dataclasses import dataclass, field
from typing import Dict, Iterator, List, Optional
+@dataclass
+class WordBox:
+ """One word's bounding box within a :class:`TextItem`, in the same viewport
+ space (top-left origin, 72 DPI). ``text`` excludes inter-word spaces."""
+ text: str
+ x: float
+ y: float
+ width: float
+ height: float
+
+
@dataclass
class TextItem:
"""Individual text item extracted from a document."""
@@ -17,6 +28,10 @@ class TextItem:
font_name: Optional[str] = None
font_size: Optional[float] = None
confidence: Optional[float] = None
+ rotation: float = 0.0
+ #: Per-word sub-boxes. Empty unless the parser was configured with
+ #: ``emit_word_boxes=True``.
+ words: List[WordBox] = field(default_factory=list)
@dataclass