pdf_interpret/

util.rs

//! A number of utility methods.

use crate::{InterpreterWarning, WarningSinkFn};
use kurbo::{Affine, BezPath, PathEl, Rect};
use log::warn;
use pdf_syntax::object::Stream;
use pdf_syntax::object::stream::DecodeFailure;
use pdf_syntax::page::{Page, Rotation};
use siphasher::sip128::{Hasher128, SipHasher13};
use std::hash::Hash;
use std::ops::Sub;

pub(crate) fn decode_or_warn(stream: &Stream<'_>, sink: &WarningSinkFn) -> Option<Vec<u8>> {
    match stream.decoded() {
        Ok(data) => Some(data),
        Err(DecodeFailure::StreamTooLarge { observed, limit }) => {
            sink(InterpreterWarning::StreamTooLarge { observed, limit });
            None
        }
        Err(_) => None,
    }
}

pub(crate) trait OptionLog {
    fn warn_none(self, f: &str) -> Self;
}

impl<T> OptionLog for Option<T> {
    #[inline]
    fn warn_none(self, f: &str) -> Self {
        self.or_else(|| {
            warn!("{f}");

            None
        })
    }
}

const SCALAR_NEARLY_ZERO: f32 = 1.0 / (1 << 8) as f32;

/// A number of useful methods for f32 numbers.
pub trait Float32Ext: Sized + Sub<f32, Output = f32> + Copy + PartialOrd<f32> {
    /// Whether the number is approximately 0.
    fn is_nearly_zero(&self) -> bool {
        self.is_nearly_zero_within_tolerance(SCALAR_NEARLY_ZERO)
    }

    /// Whether the number is nearly equal to another number.
    fn is_nearly_equal(&self, other: f32) -> bool {
        (*self - other).is_nearly_zero()
    }

    /// Whether the number is nearly equal to another number.
    fn is_nearly_less_or_equal(&self, other: f32) -> bool {
        (*self - other).is_nearly_zero() || *self < other
    }

    /// Whether the number is nearly equal to another number.
    fn is_nearly_greater_or_equal(&self, other: f32) -> bool {
        (*self - other).is_nearly_zero() || *self > other
    }

    /// Whether the number is approximately 0, with a given tolerance.
    fn is_nearly_zero_within_tolerance(&self, tolerance: f32) -> bool;
}

impl Float32Ext for f32 {
    fn is_nearly_zero_within_tolerance(&self, tolerance: f32) -> bool {
        debug_assert!(tolerance >= 0.0, "tolerance must be non-negative");

        self.abs() <= tolerance
    }
}

/// A number of useful methods for f64 numbers.
pub trait Float64Ext: Sized + Sub<f64, Output = f64> + Copy + PartialOrd<f64> {
    /// Whether the number is approximately 0.
    fn is_nearly_zero(&self) -> bool {
        self.is_nearly_zero_within_tolerance(SCALAR_NEARLY_ZERO as f64)
    }

    /// Whether the number is nearly equal to another number.
    fn is_nearly_equal(&self, other: f64) -> bool {
        (*self - other).is_nearly_zero()
    }

    /// Whether the number is nearly equal to another number.
    fn is_nearly_less_or_equal(&self, other: f64) -> bool {
        (*self - other).is_nearly_zero() || *self < other
    }

    /// Whether the number is nearly equal to another number.
    fn is_nearly_greater_or_equal(&self, other: f64) -> bool {
        (*self - other).is_nearly_zero() || *self > other
    }

    /// Whether the number is approximately 0, with a given tolerance.
    fn is_nearly_zero_within_tolerance(&self, tolerance: f64) -> bool;
}

impl Float64Ext for f64 {
    fn is_nearly_zero_within_tolerance(&self, tolerance: f64) -> bool {
        debug_assert!(tolerance >= 0.0, "tolerance must be non-negative");

        self.abs() <= tolerance
    }
}

pub(crate) trait PointExt: Sized {
    fn x(&self) -> f32;
    fn y(&self) -> f32;

    fn nearly_same(&self, other: Self) -> bool {
        self.x().is_nearly_equal(other.x()) && self.y().is_nearly_equal(other.y())
    }
}

impl PointExt for kurbo::Point {
    fn x(&self) -> f32 {
        self.x as f32
    }

    fn y(&self) -> f32 {
        self.y as f32
    }
}

/// Calculate a 128-bit siphash of a value.
pub(crate) fn hash128<T: Hash + ?Sized>(value: &T) -> u128 {
    let mut state = SipHasher13::new();
    value.hash(&mut state);
    state.finish128().as_u128()
}

pub(crate) trait BezPathExt {
    fn fast_bounding_box(&self) -> Rect;
}

impl BezPathExt for BezPath {
    fn fast_bounding_box(&self) -> Rect {
        let mut min_x = f64::INFINITY;
        let mut min_y = f64::INFINITY;
        let mut max_x = f64::NEG_INFINITY;
        let mut max_y = f64::NEG_INFINITY;

        let mut include = |x: f64, y: f64| {
            min_x = min_x.min(x);
            min_y = min_y.min(y);
            max_x = max_x.max(x);
            max_y = max_y.max(y);
        };

        for el in self.elements() {
            match *el {
                PathEl::MoveTo(p) | PathEl::LineTo(p) => include(p.x, p.y),
                PathEl::QuadTo(p1, p2) => {
                    include(p1.x, p1.y);
                    include(p2.x, p2.y);
                }
                PathEl::CurveTo(p1, p2, p3) => {
                    include(p1.x, p1.y);
                    include(p2.x, p2.y);
                    include(p3.x, p3.y);
                }
                PathEl::ClosePath => {}
            }
        }

        if min_x > max_x {
            Rect::ZERO
        } else {
            Rect::new(min_x, min_y, max_x, max_y)
        }
    }
}

/// Extension methods for rectangles.
pub trait RectExt {
    /// Convert the rectangle to a `kurbo` rectangle.
    fn to_kurbo(&self) -> Rect;
}

impl RectExt for pdf_syntax::object::Rect {
    fn to_kurbo(&self) -> Rect {
        Rect::new(self.x0, self.y0, self.x1, self.y1)
    }
}

// Note: Keep in sync with `pdf-interpret-write`.
/// Extension methods for PDF pages.
pub trait PageExt {
    /// Return the initial transform that should be applied when rendering. This accounts for a
    /// number of factors, such as the mismatch between PDF's y-up and most renderers' y-down
    /// coordinate system, the rotation of the page and the offset of the crop box.
    fn initial_transform(&self, invert_y: bool) -> Affine;
}

impl PageExt for Page<'_> {
    fn initial_transform(&self, invert_y: bool) -> Affine {
        // Use the raw CropBox origin for the coordinate-system translation.
        // MuPDF maps (CropBox.x0, CropBox.y0) → canvas (0, 0).  For normal
        // PDFs (CropBox ⊆ MediaBox) intersected_crop_box and crop_box share
        // the same origin, so there is no change.  For unusual documents where
        // CropBox extends beyond MediaBox (e.g. gen-802: CropBox=[0,0,684,864]
        // but MediaBox=[36,36,648,828]) the intersected origin was (36,36),
        // producing a 75-pixel content offset vs MuPDF. (#544 follow-up)
        let crop_box = self.crop_box();
        let (_, base_height) = self.base_dimensions();
        let (width, height) = self.render_dimensions();

        let horizontal_t =
            Affine::rotate(90.0_f64.to_radians()) * Affine::translate((0.0, -width as f64));
        let flipped_horizontal_t =
            Affine::translate((0.0, height as f64)) * Affine::rotate(-90.0_f64.to_radians());

        let rotation_transform = match self.rotation() {
            Rotation::None => Affine::IDENTITY,
            Rotation::Horizontal => {
                if invert_y {
                    horizontal_t
                } else {
                    flipped_horizontal_t
                }
            }
            Rotation::Flipped => {
                Affine::scale(-1.0) * Affine::translate((-width as f64, -height as f64))
            }
            Rotation::FlippedHorizontal => {
                if invert_y {
                    flipped_horizontal_t
                } else {
                    horizontal_t
                }
            }
        };

        let inversion_transform = if invert_y {
            Affine::new([1.0, 0.0, 0.0, -1.0, 0.0, base_height as f64])
        } else {
            Affine::IDENTITY
        };

        rotation_transform * inversion_transform * Affine::translate((-crop_box.x0, -crop_box.y0))
    }
}

/// The slots where PDFDocEncoding (PDF 32000-1 Annex D.2) does not agree with
/// Latin-1: `0x18`-`0x1F`, `0x7F`, and `0x80`-`0xA0`. Every other byte is its
/// own code point, which is why only this much of the table is carried.
///
/// `None` is an undefined slot. The specification says a conforming writer
/// produces none, so a string carrying one is malformed, and the alternative
/// -- emitting the C1 control the byte names in Latin-1 -- is exactly the
/// class of code point this change exists to keep out of the text.
const PDF_DOC_ENCODING_DIVERGENCES: [(u8, Option<char>); 42] = [
    (0x18, Some('\u{02D8}')), // breve
    (0x19, Some('\u{02C7}')), // caron
    (0x1A, Some('\u{02C6}')), // circumflex
    (0x1B, Some('\u{02D9}')), // dotaccent
    (0x1C, Some('\u{02DD}')), // hungarumlaut
    (0x1D, Some('\u{02DB}')), // ogonek
    (0x1E, Some('\u{02DA}')), // ring
    (0x1F, Some('\u{02DC}')), // tilde
    (0x7F, None),
    (0x80, Some('\u{2022}')), // bullet
    (0x81, Some('\u{2020}')), // dagger
    (0x82, Some('\u{2021}')), // daggerdbl
    (0x83, Some('\u{2026}')), // ellipsis
    (0x84, Some('\u{2014}')), // emdash
    (0x85, Some('\u{2013}')), // endash
    (0x86, Some('\u{0192}')), // florin
    (0x87, Some('\u{2044}')), // fraction
    (0x88, Some('\u{2039}')), // guilsinglleft
    (0x89, Some('\u{203A}')), // guilsinglright
    (0x8A, Some('\u{2212}')), // minus
    (0x8B, Some('\u{2030}')), // perthousand
    (0x8C, Some('\u{201E}')), // quotedblbase
    (0x8D, Some('\u{201C}')), // quotedblleft
    (0x8E, Some('\u{201D}')), // quotedblright
    (0x8F, Some('\u{2018}')), // quoteleft
    (0x90, Some('\u{2019}')), // quoteright
    (0x91, Some('\u{201A}')), // quotesinglbase
    (0x92, Some('\u{2122}')), // trademark
    (0x93, Some('\u{FB01}')), // fi
    (0x94, Some('\u{FB02}')), // fl
    (0x95, Some('\u{0141}')), // Lslash
    (0x96, Some('\u{0152}')), // OE
    (0x97, Some('\u{0160}')), // Scaron
    (0x98, Some('\u{0178}')), // Ydieresis
    (0x99, Some('\u{017D}')), // Zcaron
    (0x9A, Some('\u{0131}')), // dotlessi
    (0x9B, Some('\u{0142}')), // lslash
    (0x9C, Some('\u{0153}')), // oe
    (0x9D, Some('\u{0161}')), // scaron
    (0x9E, Some('\u{017E}')), // zcaron
    (0x9F, None),
    (0xA0, Some('\u{20AC}')), // Euro
];

/// The character a PDFDocEncoding byte stands for, or `None` for the three
/// undefined slots (`0x7F`, `0x9F`, `0xAD`).
fn pdf_doc_encoding(byte: u8) -> Option<char> {
    if byte == 0xAD {
        return None;
    }
    match PDF_DOC_ENCODING_DIVERGENCES
        .iter()
        .find(|(code, _)| *code == byte)
    {
        Some((_, mapped)) => *mapped,
        None => Some(byte as char),
    }
}

/// Decode a PDF text string (PDF 32000-1 §7.9.2.2, PDF 2.0 §7.9.2.2) into
/// Rust's `String`.
///
/// Three encodings, told apart by a byte-order mark: UTF-16BE behind `FE FF`,
/// UTF-8 behind `EF BB BF` (PDF 2.0), and PDFDocEncoding otherwise.
/// PDFDocEncoding is Latin-1 over most of its range and diverges in
/// `0x18`-`0x1F`, `0x7F` and `0x80`-`0xA0`, where reading it as Latin-1 turns
/// per-mille into the C1 control U+008B -- one of the code points this change
/// exists to keep out of extracted text. Those slots are in
/// [`PDF_DOC_ENCODING_DIVERGENCES`]; an undefined one drops its byte rather
/// than inventing a character for it.
///
/// An empty result is a result. `/ActualText ()` says this sequence stands for
/// no characters at all, which is how a producer suppresses decorative text,
/// and answering `None` there would hand the glyphs back instead. `None` means
/// only that the bytes did not decode.
pub(crate) fn decode_text_string(bytes: &[u8]) -> Option<String> {
    if let Some(rest) = bytes.strip_prefix(&[0xFE, 0xFF]) {
        let units: Vec<u16> = rest
            .chunks_exact(2)
            .map(|pair| u16::from_be_bytes([pair[0], pair[1]]))
            .collect();
        return String::from_utf16(&units).ok();
    }

    if let Some(rest) = bytes.strip_prefix(&[0xEF, 0xBB, 0xBF]) {
        return std::str::from_utf8(rest).ok().map(str::to_string);
    }

    Some(bytes.iter().copied().filter_map(pdf_doc_encoding).collect())
}

#[cfg(test)]
mod decode_text_string_tests {
    use super::decode_text_string;

    #[test]
    fn utf16be_behind_the_mark() {
        assert_eq!(
            decode_text_string(&[0xFE, 0xFF, 0x00, 0x41, 0x00, 0x42, 0x00, 0x43]),
            Some("ABC".to_string())
        );
    }

    #[test]
    fn pdf_doc_encoding_without_one() {
        assert_eq!(decode_text_string(b"Caf\xe9"), Some("Café".to_string()));
    }

    /// The slots where PDFDocEncoding is not Latin-1. Read as Latin-1 these
    /// are the C1 controls and a no-break space, which is the class of code
    /// point this change exists to keep out of the text.
    #[test]
    fn the_slots_where_it_is_not_latin1() {
        assert_eq!(decode_text_string(b"\x8b"), Some("\u{2030}".to_string()));
        assert_eq!(
            decode_text_string(b"\x93\x94"),
            Some("\u{FB01}\u{FB02}".to_string())
        );
        assert_eq!(decode_text_string(b"\xa0"), Some("\u{20AC}".to_string()));
        assert_eq!(decode_text_string(b"\x1a"), Some("\u{02C6}".to_string()));
    }

    /// The three undefined slots. A conforming writer produces none of them,
    /// and the byte is dropped rather than read as the control it would be in
    /// Latin-1.
    #[test]
    fn an_undefined_slot_drops_its_byte() {
        assert_eq!(
            decode_text_string(b"A\x7fB\x9fC\xadD"),
            Some("ABCD".to_string())
        );
        assert_eq!(decode_text_string(b"\x7f"), Some(String::new()));
    }

    /// PDF 2.0 allows a UTF-8 text string behind its own mark.
    #[test]
    fn utf8_behind_its_mark() {
        assert_eq!(
            decode_text_string(&[0xEF, 0xBB, 0xBF, 0xC3, 0xA9, 0x41]),
            Some("éA".to_string())
        );
        assert_eq!(decode_text_string(&[0xEF, 0xBB, 0xBF, 0xFF]), None);
    }

    /// An empty string decoded successfully, and that is not the same answer
    /// as "these bytes are not a string". `/ActualText ()` says the sequence
    /// stands for nothing, which is a producer suppressing decorative text.
    #[test]
    fn an_empty_replacement_is_still_a_replacement() {
        assert_eq!(decode_text_string(b""), Some(String::new()));
        assert_eq!(decode_text_string(&[0xFE, 0xFF]), Some(String::new()));
        assert_eq!(decode_text_string(&[0xEF, 0xBB, 0xBF]), Some(String::new()));
    }

    #[test]
    fn an_unpaired_surrogate_is_refused_rather_than_mangled() {
        assert_eq!(decode_text_string(&[0xFE, 0xFF, 0xD8, 0x00]), None);
    }
}