Skip to main content

pdf_textlayer/
lib.rs

1//! Add an invisible, searchable text layer to a PDF.
2//!
3//! Give the writer a PDF and the OCR boxes for its pages. Each box is drawn
4//! at its location in text render mode 3, so the page looks the same and
5//! becomes selectable and searchable.
6//!
7//! * Pages without drawable boxes are left as they are.
8//! * A box that lands on a word the page already contains is skipped, so a
9//!   page that mixes native text and a scan is not indexed twice.
10//! * Boxes are given in the upright view of the page. Pages with a `/Rotate`
11//!   entry and boxes with their own rotation are placed along the text
12//!   direction.
13//!
14//! ```no_run
15//! use pdf_textlayer::{Options, ParsedPage, TextBox, write_text_layer};
16//!
17//! let pages = vec![ParsedPage {
18//!     page_number: 1,
19//!     boxes: vec![TextBox::new("Hello world", 72.0, 100.0, 120.0, 12.0)],
20//! }];
21//!
22//! let stats = write_text_layer("scan.pdf", &pages, "searchable.pdf", &Options::default())?;
23//! assert_eq!(stats.items_drawn, 1);
24//! # Ok::<(), pdf_textlayer::Error>(())
25//! ```
26//!
27//! OCR JSON from a supported tool goes through an [`Adapter`]:
28//!
29//! ```no_run
30//! use pdf_textlayer::{Adapter, Options, make_searchable_pdf};
31//!
32//! let stats = make_searchable_pdf("scan.pdf", "parsed.json", "searchable.pdf", Adapter::Liteparse, &Options::default())?;
33//! # Ok::<(), pdf_textlayer::Error>(())
34//! ```
35
36pub mod adapters;
37#[cfg(feature = "cli")]
38pub mod cli;
39mod geometry;
40mod metrics;
41mod metrics_data;
42mod native_text;
43mod overlay;
44mod overlay_font;
45
46use std::fs::File;
47use std::io::BufWriter;
48use std::path::Path;
49
50use lopdf::Document;
51
52pub use adapters::Adapter;
53pub use metrics::FontMetrics;
54
55/// One piece of OCR text to draw, in PDF points.
56///
57/// The origin is the top-left of the page as displayed, x to the right and
58/// y down. `(x, y)` is the top-left corner of the axis-aligned box.
59#[derive(Debug, Clone, PartialEq)]
60pub struct TextBox {
61    pub text: String,
62    pub x: f64,
63    pub y: f64,
64    pub width: f64,
65    pub height: f64,
66    /// OCR confidence from 0 to 1.
67    pub confidence: f64,
68    /// Text direction in degrees counter-clockwise. Values snap to 0, 90,
69    /// 180, or 270.
70    pub rotation: f64,
71}
72
73impl TextBox {
74    /// A horizontal box with full confidence.
75    pub fn new(text: impl Into<String>, x: f64, y: f64, width: f64, height: f64) -> TextBox {
76        TextBox {
77            text: text.into(),
78            x,
79            y,
80            width,
81            height,
82            confidence: 1.0,
83            rotation: 0.0,
84        }
85    }
86}
87
88/// The OCR boxes of one page.
89#[derive(Debug, Clone, PartialEq)]
90pub struct ParsedPage {
91    /// 1-indexed page of the input PDF that receives the boxes.
92    pub page_number: u32,
93    pub boxes: Vec<TextBox>,
94}
95
96/// Drawing options.
97#[derive(Debug, Clone, PartialEq)]
98pub struct Options {
99    /// Drop boxes whose confidence is below this. `0.0` keeps everything.
100    pub min_confidence: f64,
101    /// The width table that sizes each run.
102    pub font: FontMetrics,
103    /// Replace characters that cannot be drawn with `?`. When false, a box
104    /// that contains one is dropped instead.
105    pub sanitize_unsupported: bool,
106}
107
108impl Default for Options {
109    fn default() -> Options {
110        Options {
111            min_confidence: 0.0,
112            font: FontMetrics::default(),
113            sanitize_unsupported: true,
114        }
115    }
116}
117
118/// What a pass wrote.
119#[derive(Debug, Clone, PartialEq, Eq)]
120pub struct Stats {
121    /// Pages in the document.
122    pub pages: usize,
123    /// 1-indexed pages that received a text layer, in page order.
124    pub ocr_pages: Vec<u32>,
125    /// Boxes drawn across all pages.
126    pub items_drawn: usize,
127}
128
129#[derive(Debug, thiserror::Error)]
130pub enum Error {
131    #[error("{path}: {source}")]
132    Io {
133        path: String,
134        #[source]
135        source: std::io::Error,
136    },
137    #[error("not a readable PDF: {0}")]
138    Pdf(#[from] lopdf::Error),
139    #[error("encrypted PDFs are not supported")]
140    Encrypted,
141    #[error("not valid JSON: {0}")]
142    Json(#[from] serde_json::Error),
143    #[error("unknown adapter {0:?}: expected 'liteparse'")]
144    UnknownAdapter(String),
145    #[error("unknown font {0:?}: expected 'helv', 'tiro', or 'cour'")]
146    UnknownFont(String),
147}
148
149/// Draw a text layer onto the PDF at `input` and save it to `output`.
150///
151/// `output` is overwritten if it exists. Nothing is written when the input
152/// cannot be read.
153pub fn write_text_layer(
154    input: impl AsRef<Path>,
155    pages: &[ParsedPage],
156    output: impl AsRef<Path>,
157    options: &Options,
158) -> Result<Stats, Error> {
159    let input = input.as_ref();
160    let output = output.as_ref();
161    let pdf = std::fs::read(input).map_err(|source| io_error(input, source))?;
162    let (mut document, stats) = overlay_document(&pdf, pages, options)?;
163
164    // The input bytes are no longer needed; the document owns its own copy.
165    drop(pdf);
166
167    let mut file = BufWriter::new(File::create(output).map_err(|source| io_error(output, source))?);
168    document.save_to(&mut file).map_err(|source| io_error(output, source))?;
169    file.into_inner()
170        .map_err(|error| io_error(output, error.into_error()))?;
171
172    Ok(stats)
173}
174
175/// Read the OCR JSON at `source` with `adapter`, draw its boxes onto the PDF
176/// at `input`, and save the result to `output`.
177pub fn make_searchable_pdf(
178    input: impl AsRef<Path>,
179    source: impl AsRef<Path>,
180    output: impl AsRef<Path>,
181    adapter: Adapter,
182    options: &Options,
183) -> Result<Stats, Error> {
184    let pages = adapter.parse_file(source)?;
185    write_text_layer(input, &pages, output, options)
186}
187
188/// Draw a text layer onto a PDF held in memory and return the new PDF.
189pub fn add_text_layer(pdf: &[u8], pages: &[ParsedPage], options: &Options) -> Result<(Vec<u8>, Stats), Error> {
190    let (mut document, stats) = overlay_document(pdf, pages, options)?;
191    let mut output = Vec::with_capacity(pdf.len() + pdf.len() / 8);
192    document
193        .save_to(&mut output)
194        .map_err(|source| io_error(Path::new("<memory>"), source))?;
195
196    Ok((output, stats))
197}
198
199fn overlay_document(pdf: &[u8], pages: &[ParsedPage], options: &Options) -> Result<(Document, Stats), Error> {
200    let mut document = Document::load_mem(pdf)?;
201
202    // An encrypted file is rejected even when it opens without a password:
203    // saving it decrypted would silently drop the owner's restrictions.
204    if document.trailer.has(b"Encrypt") || document.was_encrypted() {
205        return Err(Error::Encrypted);
206    }
207
208    // A file whose page tree cannot be found must not be saved back empty.
209    document.catalog()?;
210
211    let stats = overlay::Overlay::new(&mut document, options).run(&mut document, pages)?;
212
213    Ok((document, stats))
214}
215
216pub(crate) fn io_error(path: &Path, source: std::io::Error) -> Error {
217    Error::Io {
218        path: path.display().to_string(),
219        source,
220    }
221}