pdf-untangle 0.3.0

Untangle garbled PDF text: layout-aware extraction that reconstructs reading order, strips page furniture, and splits documents into structured, citable sections
Documentation
//! Layer 1 — PDF → positioned text runs.
//!
//! Backends are pluggable behind [`TextSource`] so Layers 2–3 never know which
//! extraction engine produced the runs. Two ship today, each behind a cargo
//! feature:
//!
//! - **`backend-pdfium`** — Google PDFium via the `pdfium-render` crate. Best
//!   extraction quality: true per-object bounding boxes, font names, weight
//!   and italic flags. Requires the native `libpdfium` library at *runtime*
//!   (it is loaded dynamically; nothing extra is needed at build time). The
//!   library is located via the `PDFIUM_DYNAMIC_LIB_PATH` environment
//!   variable, then a `.pdfium/` directory under the current directory, then
//!   the system library path. See the README dev section and
//!   `scripts/fetch-pdfium.sh` for obtaining a prebuilt library.
//! - **`backend-pure`** — pure Rust via the `pdf-extract` crate (built on
//!   `lopdf`). Zero native dependencies. Yields real positions and font
//!   sizes, but the underlying API does not expose font names or style
//!   flags, so [`TextRun::bold`]/[`TextRun::italic`] are always `false` and
//!   [`TextRun::font`] is always `None` from this backend. Bounding-box
//!   heights are approximated from the font size.
//!
//! [`runs`] dispatches to the default backend. When both features are
//! enabled, PDFium is preferred at runtime if its library loads, with a
//! logged fallback to the pure backend otherwise (see [`runs_with_backend`]).

use anyhow::Result;
use serde::Serialize;

#[cfg(feature = "backend-pdfium")]
pub mod pdfium;
#[cfg(feature = "backend-pure")]
pub mod pure;

/// One run of text as placed on a page: contiguous glyphs sharing position
/// and style. The atom Layer 2 works from.
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct TextRun {
    /// The run's text, decoded to Unicode.
    pub text: String,
    /// Page-space bounding box, points, origin bottom-left: (x0, y0, x1, y1).
    pub bbox: (f32, f32, f32, f32),
    /// Effective (rendered) font size in points, i.e. the nominal `Tf` size
    /// combined with any text-matrix scaling.
    pub font_size: f32,
    /// Bold flag. Backend-dependent: PDFium reports it from font weight and
    /// name; the pure backend cannot see it and always reports `false`.
    pub bold: bool,
    /// Italic flag. Backend-dependent, like [`TextRun::bold`].
    pub italic: bool,
    /// Font name (e.g. `"TimesNewRomanPS-BoldMT"`), when the backend exposes
    /// it. `None` from the pure backend.
    pub font: Option<String>,
    /// 0-based page index this run belongs to.
    pub page: usize,
}

/// A page's dimensions plus every run on it, in source (not reading) order.
#[derive(Debug, Clone, Serialize)]
pub struct PageRuns {
    /// Page width in points.
    pub width: f32,
    /// Page height in points.
    pub height: f32,
    /// Every text run on the page, in the order the PDF emits them.
    pub runs: Vec<TextRun>,
}

/// An extraction backend: opens PDF bytes and yields per-page runs.
pub trait TextSource {
    /// Extract every page's positioned text runs from `pdf_bytes`.
    fn pages(&self, pdf_bytes: &[u8]) -> Result<Vec<PageRuns>>;
}

/// Which extraction backend produced a set of runs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum Backend {
    /// Google PDFium via `pdfium-render` (`backend-pdfium` feature).
    Pdfium,
    /// Pure Rust via `pdf-extract`/`lopdf` (`backend-pure` feature).
    Pure,
}

impl Backend {
    /// Short stable name, e.g. for logs and `--json` output.
    pub fn name(self) -> &'static str {
        match self {
            Backend::Pdfium => "pdfium",
            Backend::Pure => "pure",
        }
    }
}

impl std::fmt::Display for Backend {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.name())
    }
}

/// Extract positioned runs from PDF bytes with the default backend.
///
/// Equivalent to [`runs_with_backend`] but discards the backend tag.
pub fn runs(pdf_bytes: &[u8]) -> Result<Vec<PageRuns>> {
    runs_with_backend(pdf_bytes).map(|(pages, _)| pages)
}

/// Extract positioned runs and report which backend produced them.
///
/// Dispatch rules:
/// - Both backend features enabled: prefer PDFium when its native library
///   loads; otherwise log a warning and fall back to the pure backend.
/// - One feature enabled: use it (PDFium returns an error if its library
///   cannot be loaded).
/// - No backend feature enabled: always returns an error.
#[allow(unreachable_code)]
// `return` keeps each feature-gated block self-contained; with only one
// backend compiled in, the "last" block clippy sees varies by feature set.
#[allow(clippy::needless_return)]
pub fn runs_with_backend(pdf_bytes: &[u8]) -> Result<(Vec<PageRuns>, Backend)> {
    #[cfg(feature = "backend-pdfium")]
    {
        match pdfium::PdfiumSource::new() {
            Ok(source) => {
                log::info!("extracting with the pdfium backend");
                return source.pages(pdf_bytes).map(|p| (p, Backend::Pdfium));
            }
            #[cfg(feature = "backend-pure")]
            Err(e) => {
                log::warn!("pdfium library unavailable ({e:#}); falling back to pure backend");
            }
            #[cfg(not(feature = "backend-pure"))]
            Err(e) => {
                return Err(e.context(
                    "pdfium library not found; set PDFIUM_DYNAMIC_LIB_PATH or run \
                     scripts/fetch-pdfium.sh (see README)",
                ));
            }
        }
    }
    #[cfg(feature = "backend-pure")]
    {
        log::info!("extracting with the pure backend");
        return pure::PureSource
            .pages(pdf_bytes)
            .map(|p| (p, Backend::Pure));
    }
    #[cfg(not(any(feature = "backend-pdfium", feature = "backend-pure")))]
    {
        let _ = pdf_bytes;
        anyhow::bail!(
            "no extraction backend compiled in: enable the `backend-pdfium` and/or \
             `backend-pure` cargo feature"
        )
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn backend_names_are_stable() {
        assert_eq!(Backend::Pdfium.name(), "pdfium");
        assert_eq!(Backend::Pure.name(), "pure");
        assert_eq!(Backend::Pdfium.to_string(), "pdfium");
        assert_eq!(serde_json::to_string(&Backend::Pure).unwrap(), "\"pure\"");
    }

    #[test]
    fn text_run_serializes_for_inspect_json() {
        let run = TextRun {
            text: "§ 2051. Definitions.".into(),
            bbox: (72.0, 700.5, 210.0, 712.0),
            font_size: 11.5,
            bold: true,
            italic: false,
            font: Some("TimesNewRomanPS-BoldMT".into()),
            page: 0,
        };
        let v: serde_json::Value = serde_json::to_value(&run).unwrap();
        assert_eq!(v["text"], "§ 2051. Definitions.");
        assert_eq!(v["bbox"][0], 72.0);
        assert_eq!(v["bold"], true);
        assert_eq!(v["font"], "TimesNewRomanPS-BoldMT");
    }

    #[cfg(not(any(feature = "backend-pdfium", feature = "backend-pure")))]
    #[test]
    fn runs_errors_without_a_backend() {
        let err = runs(b"%PDF-1.7 not really").unwrap_err();
        assert!(err.to_string().contains("no extraction backend"));
    }

    #[cfg(feature = "backend-pure")]
    #[test]
    fn pure_backend_rejects_garbage_bytes() {
        assert!(pure::PureSource.pages(b"this is not a pdf").is_err());
    }

    /// A tiny but complete single-page PDF ("Hello Untangle" in Helvetica 12).
    #[cfg(feature = "backend-pure")]
    fn minimal_pdf() -> Vec<u8> {
        let mut pdf = Vec::new();
        let mut offsets = Vec::new();
        let header = b"%PDF-1.4\n";
        pdf.extend_from_slice(header);
        let objects: Vec<String> = vec![
            "1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n".into(),
            "2 0 obj\n<< /Type /Pages /Kids [3 0 R] /Count 1 >>\nendobj\n".into(),
            "3 0 obj\n<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] \
             /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>\nendobj\n"
                .into(),
            "4 0 obj\n<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>\nendobj\n".into(),
            {
                let stream = "BT /F1 12 Tf 72 720 Td (Hello Untangle) Tj ET";
                format!(
                    "5 0 obj\n<< /Length {} >>\nstream\n{}\nendstream\nendobj\n",
                    stream.len(),
                    stream
                )
            },
        ];
        for obj in &objects {
            offsets.push(pdf.len());
            pdf.extend_from_slice(obj.as_bytes());
        }
        let xref_at = pdf.len();
        pdf.extend_from_slice(format!("xref\n0 {}\n", objects.len() + 1).as_bytes());
        pdf.extend_from_slice(b"0000000000 65535 f \n");
        for off in &offsets {
            pdf.extend_from_slice(format!("{off:010} 00000 n \n").as_bytes());
        }
        pdf.extend_from_slice(
            format!(
                "trailer\n<< /Size {} /Root 1 0 R >>\nstartxref\n{}\n%%EOF\n",
                objects.len() + 1,
                xref_at
            )
            .as_bytes(),
        );
        pdf
    }

    #[cfg(feature = "backend-pure")]
    #[test]
    fn pure_backend_extracts_positioned_text() {
        let pages = pure::PureSource.pages(&minimal_pdf()).unwrap();
        assert_eq!(pages.len(), 1);
        assert_eq!(pages[0].width, 612.0);
        assert_eq!(pages[0].height, 792.0);
        let text: String = pages[0].runs.iter().map(|r| r.text.as_str()).collect();
        assert!(text.contains("Hello Untangle"), "got: {text:?}");
        let run = &pages[0].runs[0];
        assert!((run.bbox.0 - 72.0).abs() < 1.0, "x0 was {}", run.bbox.0);
        assert!((run.bbox.1 - 720.0).abs() < 6.0, "y0 was {}", run.bbox.1);
        assert!((run.font_size - 12.0).abs() < 0.01);
        assert_eq!(run.page, 0);
    }

    #[cfg(feature = "backend-pure")]
    #[test]
    fn runs_dispatches_to_a_real_backend() {
        // With backend-pure enabled (alone or with an unloadable pdfium),
        // `runs` must produce pages rather than the "not implemented" error.
        let (pages, backend) = runs_with_backend(&minimal_pdf()).unwrap();
        assert_eq!(pages.len(), 1);
        assert!(matches!(backend, Backend::Pdfium | Backend::Pure));
    }
}