html_to_markdown_rs/hocr/
extractor.rs

1//! hOCR element extraction
2//!
3//! Extracts structured hOCR elements from HTML DOM.
4
5use super::parser::parse_properties;
6use super::types::{HocrElement, HocrElementType, HocrMetadata};
7
8/// Extract complete hOCR document structure from HTML DOM
9///
10/// Parses an HTML document containing hOCR annotations and extracts all hOCR elements
11/// along with document metadata.
12///
13/// # Arguments
14///
15/// * `dom` - The parsed HTML DOM (from tl parser)
16/// * `debug` - Enable debug logging for property parsing
17///
18/// # Returns
19///
20/// A tuple containing:
21/// * `Vec<HocrElement>` - All top-level hOCR elements with their full hierarchies
22/// * `HocrMetadata` - Document metadata from `<head>` meta tags
23///
24/// # hOCR 1.2 Compliance
25///
26/// Supports all 40 element types:
27/// - Logical structure (12): ocr_title, ocr_chapter, ocr_section, ocr_par, etc.
28/// - Typesetting (6): ocr_page, ocr_carea, ocr_line, etc.
29/// - Float elements (13): ocr_image, ocr_table, ocr_math, etc.
30/// - Inline elements (6): ocr_dropcap, ocr_glyph, etc.
31/// - Engine-specific (3): ocrx_block, ocrx_line, ocrx_word
32///
33/// Extracts all 20+ properties from title attributes (bbox, x_wconf, baseline, order, etc.)
34/// and all 5 metadata fields (ocr-system, ocr-capabilities, ocr-langs, etc.)
35///
36/// # Example
37///
38/// ```rust
39/// use html_to_markdown_rs::hocr::extract_hocr_document;
40///
41/// let html = r#"<div class="ocr_page" title="bbox 0 0 1000 1500">
42///     <p class="ocr_par" title="bbox 100 100 900 200">
43///         <span class="ocrx_word" title="bbox 100 100 150 130; x_wconf 95">Hello</span>
44///     </p>
45/// </div>"#;
46/// let dom = tl::parse(html, tl::ParserOptions::default()).unwrap();
47/// let (elements, metadata) = extract_hocr_document(&dom, false);
48/// ```
49pub fn extract_hocr_document(dom: &tl::VDom, debug: bool) -> (Vec<HocrElement>, HocrMetadata) {
50    let parser = dom.parser();
51    let mut elements = Vec::new();
52    let metadata = extract_metadata(dom);
53
54    // Recursively search for hOCR elements starting from root
55    for child_handle in dom.children().iter() {
56        collect_hocr_elements(child_handle, parser, &mut elements, debug);
57    }
58
59    (elements, metadata)
60}
61
62/// Recursively collect hOCR elements from DOM tree
63fn collect_hocr_elements(
64    node_handle: &tl::NodeHandle,
65    parser: &tl::Parser,
66    elements: &mut Vec<HocrElement>,
67    debug: bool,
68) {
69    // Try to extract as hOCR element
70    if let Some(element) = extract_element(node_handle, parser, debug) {
71        elements.push(element);
72    } else if let Some(tl::Node::Tag(tag)) = node_handle.get(parser) {
73        // Not an hOCR element, but continue searching in children
74        let children = tag.children();
75        for child_handle in children.top().iter() {
76            collect_hocr_elements(child_handle, parser, elements, debug);
77        }
78    }
79}
80
81/// Extract hOCR metadata from HTML head (or from orphaned meta tags after sanitization)
82fn extract_metadata(dom: &tl::VDom) -> HocrMetadata {
83    let mut metadata = HocrMetadata::default();
84    let parser = dom.parser();
85
86    // Helper function to extract metadata from a single meta tag
87    fn extract_from_meta_tag(meta_tag: &tl::HTMLTag, metadata: &mut HocrMetadata) {
88        let attrs = meta_tag.attributes();
89        if let (Some(name), Some(content)) = (attrs.get("name").flatten(), attrs.get("content").flatten()) {
90            let name_str = name.as_utf8_str();
91            let content_str = content.as_utf8_str().to_string();
92
93            match name_str.as_ref() {
94                "ocr-system" => metadata.ocr_system = Some(content_str),
95                "ocr-capabilities" => {
96                    metadata.ocr_capabilities = content_str.split_whitespace().map(|s| s.to_string()).collect();
97                }
98                "ocr-number-of-pages" => {
99                    metadata.ocr_number_of_pages = content_str.parse().ok();
100                }
101                "ocr-langs" => {
102                    metadata.ocr_langs = content_str.split_whitespace().map(|s| s.to_string()).collect();
103                }
104                "ocr-scripts" => {
105                    metadata.ocr_scripts = content_str.split_whitespace().map(|s| s.to_string()).collect();
106                }
107                _ => {}
108            }
109        }
110    }
111
112    // Recursively search for meta tags (either inside head or as orphans after sanitization)
113    fn find_meta_tags<'a>(node_handle: &tl::NodeHandle, parser: &'a tl::Parser<'a>, metadata: &mut HocrMetadata) {
114        if let Some(tl::Node::Tag(tag)) = node_handle.get(parser) {
115            let tag_name = tag.name().as_utf8_str();
116
117            // Extract from meta tags directly (handles both meta inside head and orphaned meta)
118            if tag_name == "meta" {
119                extract_from_meta_tag(tag, metadata);
120            }
121
122            // Recursively search children
123            let children = tag.children();
124            for child_handle in children.top().iter() {
125                find_meta_tags(child_handle, parser, metadata);
126            }
127        }
128    }
129
130    // Search from root
131    for child_handle in dom.children().iter() {
132        find_meta_tags(child_handle, parser, &mut metadata);
133    }
134
135    metadata
136}
137
138/// Extract a single hOCR element and its children
139fn extract_element(node_handle: &tl::NodeHandle, parser: &tl::Parser, debug: bool) -> Option<HocrElement> {
140    if let Some(tl::Node::Tag(tag)) = node_handle.get(parser) {
141        let attrs = tag.attributes();
142        let class_attr = attrs.get("class").flatten()?;
143        let classes = class_attr.as_utf8_str();
144
145        // Find hOCR element type from classes
146        let element_type = classes.split_whitespace().find_map(HocrElementType::from_class)?;
147
148        // Parse properties from title attribute
149        let properties = if let Some(title) = attrs.get("title").flatten() {
150            parse_properties(&title.as_utf8_str(), debug)
151        } else {
152            Default::default()
153        };
154
155        // Extract text content and children
156        let mut text = String::new();
157        let mut children = Vec::new();
158
159        let tag_children = tag.children();
160        for child_handle in tag_children.top().iter() {
161            if let Some(tl::Node::Raw(bytes)) = child_handle.get(parser) {
162                text.push_str(&bytes.as_utf8_str());
163            } else if let Some(child_element) = extract_element(child_handle, parser, debug) {
164                children.push(child_element);
165            }
166        }
167
168        Some(HocrElement {
169            element_type,
170            properties,
171            text: text.trim().to_string(),
172            children,
173        })
174    } else {
175        None
176    }
177}
178
179#[cfg(test)]
180mod tests {
181    use super::*;
182
183    #[test]
184    fn test_extract_simple_word() {
185        let html = r#"<span class="ocrx_word" title="bbox 100 50 150 80; x_wconf 95">Hello</span>"#;
186        let dom = tl::parse(html, tl::ParserOptions::default()).unwrap();
187        let parser = dom.parser();
188
189        let element = extract_element(&dom.children()[0], parser, false).unwrap();
190        assert!(matches!(element.element_type, HocrElementType::OcrxWord));
191        assert_eq!(element.text, "Hello");
192        assert!(element.properties.bbox.is_some());
193        assert_eq!(element.properties.x_wconf, Some(95.0));
194    }
195
196    #[test]
197    fn test_extract_paragraph() {
198        let html = r#"<p class="ocr_par" title="bbox 0 0 200 100">
199            <span class="ocrx_word" title="bbox 10 10 50 30; x_wconf 90">First</span>
200            <span class="ocrx_word" title="bbox 60 10 100 30; x_wconf 92">Word</span>
201        </p>"#;
202        let dom = tl::parse(html, tl::ParserOptions::default()).unwrap();
203        let parser = dom.parser();
204
205        let element = extract_element(&dom.children()[0], parser, false).unwrap();
206        assert!(matches!(element.element_type, HocrElementType::OcrPar));
207        assert_eq!(element.children.len(), 2);
208        assert!(matches!(element.children[0].element_type, HocrElementType::OcrxWord));
209    }
210
211    #[test]
212    fn test_extract_metadata() {
213        let html = r#"<!DOCTYPE html>
214<html>
215<head>
216<meta name="ocr-system" content="tesseract 4.1.1" />
217<meta name="ocr-capabilities" content="ocr_page ocr_carea ocr_par ocr_line ocrx_word" />
218<meta name="ocr-number-of-pages" content="5" />
219</head>
220<body>
221<div class="ocr_page"></div>
222</body>
223</html>"#;
224        let dom = tl::parse(html, tl::ParserOptions::default()).unwrap();
225        let (_, metadata) = extract_hocr_document(&dom, false);
226
227        assert_eq!(metadata.ocr_system, Some("tesseract 4.1.1".to_string()));
228        assert!(metadata.ocr_capabilities.contains(&"ocr_page".to_string()));
229        assert_eq!(metadata.ocr_number_of_pages, Some(5));
230    }
231}
html_to_markdown_rs/hocr/extractor.rs

html_to_markdown_rs/hocr/
extractor.rs
