Skip to main content

pdf_textlayer/
adapters.rs

1//! Turn an OCR tool's JSON into [`ParsedPage`]s.
2//!
3//! Each source is one [`Adapter`] variant. Adding a source means adding a
4//! variant, its name in [`Adapter::from_name`], and a parse function.
5
6use std::fmt;
7use std::path::Path;
8use std::str::FromStr;
9
10use serde_json::{Map, Value};
11
12use crate::{Error, ParsedPage, TextBox};
13
14/// A JSON format the writer can read OCR boxes from.
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
16pub enum Adapter {
17    /// [LiteParse](https://github.com/run-llama/liteparse) `lit parse --format json`.
18    ///
19    /// Reads `pages[].text_items[]` whose `font_name` is `"OCR"`; native-text
20    /// items keep their real font name and are skipped. `rotation` is read when
21    /// present (`--extract-text-metadata`). The 0.1 field names `textItems` and
22    /// `fontName` are still accepted.
23    #[default]
24    Liteparse,
25}
26
27impl Adapter {
28    /// Every adapter, in the order the CLI lists them.
29    pub const ALL: [Adapter; 1] = [Adapter::Liteparse];
30
31    /// The name used by `--from` and the language packages.
32    pub fn name(self) -> &'static str {
33        match self {
34            Adapter::Liteparse => "liteparse",
35        }
36    }
37
38    /// Resolve an adapter by name, ignoring case.
39    pub fn from_name(name: &str) -> Option<Adapter> {
40        Adapter::ALL
41            .into_iter()
42            .find(|adapter| adapter.name().eq_ignore_ascii_case(name))
43    }
44
45    /// The pages of `document` that carry OCR boxes, in document order.
46    ///
47    /// Pages without OCR boxes are omitted. Malformed pages and items are
48    /// skipped rather than rejected, so one bad entry does not cost the rest.
49    pub fn parse(self, document: &Value) -> Vec<ParsedPage> {
50        match self {
51            Adapter::Liteparse => liteparse(document),
52        }
53    }
54
55    /// Parse a JSON document held in memory.
56    pub fn parse_str(self, json: &str) -> Result<Vec<ParsedPage>, Error> {
57        Ok(self.parse(&serde_json::from_str(json)?))
58    }
59
60    /// Parse the JSON file at `path`.
61    pub fn parse_file(self, path: impl AsRef<Path>) -> Result<Vec<ParsedPage>, Error> {
62        let path = path.as_ref();
63        let json = std::fs::read_to_string(path).map_err(|source| crate::io_error(path, source))?;
64        self.parse_str(&json)
65    }
66}
67
68impl fmt::Display for Adapter {
69    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
70        formatter.write_str(self.name())
71    }
72}
73
74impl FromStr for Adapter {
75    type Err = Error;
76
77    fn from_str(name: &str) -> Result<Adapter, Error> {
78        Adapter::from_name(name).ok_or_else(|| Error::UnknownAdapter(name.to_string()))
79    }
80}
81
82/// `font_name` that LiteParse gives text it read with OCR.
83const LITEPARSE_OCR_FONT: &str = "OCR";
84
85fn liteparse(document: &Value) -> Vec<ParsedPage> {
86    let Some(pages) = document.get("pages").and_then(Value::as_array) else {
87        return Vec::new();
88    };
89
90    pages
91        .iter()
92        .filter_map(|page| {
93            let page = page.as_object()?;
94            let page_number = u32::try_from(page.get("page")?.as_u64()?).ok()?;
95            let items = if page.contains_key("text_items") {
96                page.get("text_items")
97            } else {
98                page.get("textItems")
99            };
100            let boxes: Vec<TextBox> = items
101                .and_then(Value::as_array)
102                .into_iter()
103                .flatten()
104                .filter_map(|item| liteparse_box(item.as_object()?))
105                .collect();
106
107            (!boxes.is_empty()).then_some(ParsedPage { page_number, boxes })
108        })
109        .collect()
110}
111
112/// One drawable OCR box, or `None` when the item should be skipped.
113fn liteparse_box(item: &Map<String, Value>) -> Option<TextBox> {
114    if first_present(item, &["font_name", "fontName"])?.as_str()? != LITEPARSE_OCR_FONT {
115        return None;
116    }
117
118    let text = item.get("text").and_then(Value::as_str).unwrap_or("").trim();
119    let width = optional_number(item, "width")?.unwrap_or(0.0);
120    let height = optional_number(item, "height")?.unwrap_or(0.0);
121    if text.is_empty() || width <= 0.0 || height <= 0.0 {
122        return None;
123    }
124
125    Some(TextBox {
126        text: text.to_string(),
127        x: item.get("x")?.as_f64()?,
128        y: item.get("y")?.as_f64()?,
129        width,
130        height,
131        confidence: optional_number(item, "confidence")?.unwrap_or(1.0),
132        rotation: optional_number(item, "rotation")?.unwrap_or(0.0),
133    })
134}
135
136/// The first of `keys` that is present and not null.
137fn first_present<'a>(item: &'a Map<String, Value>, keys: &[&str]) -> Option<&'a Value> {
138    keys.iter()
139        .filter_map(|key| item.get(*key))
140        .find(|value| !value.is_null())
141}
142
143/// `Some(None)` when `key` is missing or null, `None` when it is not a number.
144fn optional_number(item: &Map<String, Value>, key: &str) -> Option<Option<f64>> {
145    match item.get(key) {
146        None | Some(Value::Null) => Some(None),
147        Some(value) => value.as_f64().map(Some),
148    }
149}
150
151#[cfg(test)]
152mod tests {
153    use serde_json::json;
154
155    use super::*;
156
157    fn item(text: &str, font_name: &str) -> Value {
158        json!({"text": text, "x": 10.0, "y": 20.0, "width": 30.0, "height": 8.0, "font_name": font_name})
159    }
160
161    #[test]
162    fn keeps_only_ocr_items_and_pages_that_have_them() {
163        let document = json!({"pages": [
164            {"page": 1, "text_items": [item("native", "Helvetica"), item(" scanned ", "OCR")]},
165            {"page": 2, "text_items": [item("native only", "Times")]},
166            {"page": 3, "text_items": []},
167        ]});
168
169        let pages = Adapter::Liteparse.parse(&document);
170
171        assert_eq!(
172            pages,
173            vec![ParsedPage {
174                page_number: 1,
175                boxes: vec![TextBox::new("scanned", 10.0, 20.0, 30.0, 8.0)],
176            }]
177        );
178    }
179
180    #[test]
181    fn reads_confidence_and_rotation_and_defaults_them_when_missing() {
182        let document = json!({"pages": [{"page": 4, "text_items": [
183            {"text": "a", "x": 1, "y": 2, "width": 3, "height": 4, "font_name": "OCR",
184             "confidence": 0.25, "rotation": 90},
185            {"text": "b", "x": 1, "y": 2, "width": 3, "height": 4, "font_name": "OCR",
186             "confidence": null},
187        ]}]});
188
189        let boxes = &Adapter::Liteparse.parse(&document)[0].boxes;
190
191        assert_eq!((boxes[0].confidence, boxes[0].rotation), (0.25, 90.0));
192        assert_eq!((boxes[1].confidence, boxes[1].rotation), (1.0, 0.0));
193    }
194
195    #[test]
196    fn accepts_the_camel_case_field_names() {
197        let document = json!({"pages": [{"page": 1, "textItems": [
198            {"text": "old", "x": 1, "y": 2, "width": 3, "height": 4, "fontName": "OCR"},
199        ]}]});
200
201        assert_eq!(Adapter::Liteparse.parse(&document)[0].boxes[0].text, "old");
202    }
203
204    #[test]
205    fn skips_malformed_pages_and_items() {
206        let document = json!({"pages": [
207            "not a page",
208            {"page": "1", "text_items": [item("string page number", "OCR")]},
209            {"page": -1, "text_items": [item("negative page", "OCR")]},
210            {"page": 2, "text_items": [
211                7,
212                {"text": "no x", "y": 2, "width": 3, "height": 4, "font_name": "OCR"},
213                {"text": "zero width", "x": 1, "y": 2, "width": 0, "height": 4, "font_name": "OCR"},
214                {"text": "no height", "x": 1, "y": 2, "width": 3, "font_name": "OCR"},
215                {"text": "bad confidence", "x": 1, "y": 2, "width": 3, "height": 4, "font_name": "OCR",
216                 "confidence": "high"},
217                {"text": "   ", "x": 1, "y": 2, "width": 3, "height": 4, "font_name": "OCR"},
218                {"x": 1, "y": 2, "width": 3, "height": 4, "font_name": "OCR"},
219                item("kept", "OCR"),
220            ]},
221        ]});
222
223        let pages = Adapter::Liteparse.parse(&document);
224
225        assert_eq!(pages.len(), 1);
226        assert_eq!(pages[0].page_number, 2);
227        assert_eq!(pages[0].boxes.len(), 1);
228        assert_eq!(pages[0].boxes[0].text, "kept");
229    }
230
231    #[test]
232    fn a_document_without_pages_has_no_boxes() {
233        assert!(Adapter::Liteparse.parse(&json!({})).is_empty());
234        assert!(Adapter::Liteparse.parse(&json!({"pages": {"1": []}})).is_empty());
235        assert!(matches!(Adapter::Liteparse.parse_str("{"), Err(Error::Json(_))));
236    }
237
238    #[test]
239    fn names_resolve_ignoring_case() {
240        assert_eq!("LiteParse".parse::<Adapter>().unwrap(), Adapter::Liteparse);
241        assert!(matches!("textract".parse::<Adapter>(), Err(Error::UnknownAdapter(name)) if name == "textract"));
242    }
243}