pdf2-render 1.8.0

Rasteriser for the pdf2 crate: paths, clips, images, text, fonts, shadings and patterns, with a report of what it cannot draw.
Documentation
//! `/JBIG2Decode` (7.4.7): bi-level scans, behind the `jbig2` feature.
//!
//! The two pdf.js pages are the same 399×400 crop of scanned text, encoded twice:
//! `bitmap-composite-and-xnor.pdf` carries its segments inline, and
//! `bitmap-p32-eof.pdf` keeps them in a `/JBIG2Globals` stream — which is the
//! clause's separate-segments case and the reason a page wired only to
//! `Page::new_embedded(data, None, …)` fails on it.
//!
//! What is proven here: both pages paint, the globals page is not blank, the two
//! decode to the **same pixels** (so the shared dictionaries are really applied),
//! and the sense is ink on white rather than its negative — `hayro-jbig2` reports
//! `black` while a 1-bit PDF sample is 1 for white.

#![cfg(feature = "jbig2")]

use std::path::{Path, PathBuf};

use pdf2::Document;
use pdf2_render::{RenderOptions, RenderedPage, render_page_number};

fn corpus(name: &str) -> Vec<u8> {
    let path: PathBuf = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../corpus/tier-a")
        .join(name);
    std::fs::read(&path).unwrap_or_else(|error| panic!("{}: {error}", path.display()))
}

fn render(name: &str) -> RenderedPage {
    let document = Document::open(corpus(name)).expect("open");
    render_page_number(&document, 0, &RenderOptions::default()).expect("render")
}

/// Black and white counts for a rendered page.
fn ink(rendered: &RenderedPage) -> (usize, usize) {
    let mut black = 0;
    let mut white = 0;
    for y in 0..rendered.canvas.height() {
        for x in 0..rendered.canvas.width() {
            match rendered.canvas.pixel(x, y) {
                Some([0, 0, 0, 255]) => black += 1,
                Some([255, 255, 255, 255]) => white += 1,
                Some(other) => panic!("a bi-level page painted {other:?}"),
                None => panic!("({x}, {y}) is outside the canvas"),
            }
        }
    }
    (black, white)
}

#[test]
fn the_inline_page_paints_ink_on_white() {
    let rendered = render("bitmap-composite-and-xnor.pdf");
    assert_eq!(
        rendered.report.to_string(),
        "all operators supported",
        "the image draws instead of being reported: {}",
        rendered.report
    );
    let (black, white) = ink(&rendered);
    assert_eq!(black + white, 399 * 400, "every pixel is one of the two");
    assert!(black > 5_000, "the page has ink: {black} black pixels");
    assert!(
        white > black * 4,
        "the sense is ink on white, not the negative: {black} black against {white} white"
    );
}

#[test]
fn the_globals_page_paints_the_same_pixels() {
    let inline = render("bitmap-composite-and-xnor.pdf");
    let globals = render("bitmap-p32-eof.pdf");
    assert_eq!(
        globals.report.to_string(),
        "all operators supported",
        "the globals page draws: {}",
        globals.report
    );
    let (black, white) = ink(&globals);
    assert!(black > 5_000, "the globals page is not blank: {black}");
    assert!(white > black * 4, "and it is ink on white too");
    // The pair is one image encoded two ways, so the shared dictionaries must
    // produce the same raster: a page that ignored `/JBIG2Globals` could still
    // paint something, but not this.
    for y in 0..inline.canvas.height() {
        for x in 0..inline.canvas.width() {
            assert_eq!(
                inline.canvas.pixel(x, y),
                globals.canvas.pixel(x, y),
                "the two encodings disagree at ({x}, {y})"
            );
        }
    }
}

/// A `P4` (binary) PBM, as `corpus/reference/` stores the reference rasters.
///
/// The committed form is PBM rather than the upstream PNG because this crate has
/// no PNG *decoder* — `src/png.rs` only writes — and the rasters are 1-bit, so P4
/// loses nothing. Bit `1` is black, which is the PDF sample value 0.
struct Pbm {
    width: u32,
    height: u32,
    black: Vec<bool>,
}

impl Pbm {
    fn parse(bytes: &[u8]) -> Self {
        let mut fields = Vec::new();
        let mut at = 0;
        // `P4`, then width, then height, each separated by whitespace.
        while fields.len() < 3 {
            while at < bytes.len() && bytes[at].is_ascii_whitespace() {
                at += 1;
            }
            let start = at;
            while at < bytes.len() && !bytes[at].is_ascii_whitespace() {
                at += 1;
            }
            fields.push(String::from_utf8_lossy(&bytes[start..at]).into_owned());
        }
        assert_eq!(fields[0], "P4", "the reference is a binary PBM");
        let width: u32 = fields[1].parse().expect("PBM width");
        let height: u32 = fields[2].parse().expect("PBM height");
        at += 1; // the single whitespace byte after the height
        let stride = (width as usize).div_ceil(8);
        assert_eq!(
            bytes.len() - at,
            stride * height as usize,
            "the PBM body is width × height bits"
        );
        let mut black = Vec::with_capacity(width as usize * height as usize);
        for row in 0..height as usize {
            for column in 0..width as usize {
                let byte = bytes[at + row * stride + column / 8];
                black.push((byte >> (7 - column % 8)) & 1 == 1);
            }
        }
        Self {
            width,
            height,
            black,
        }
    }

    fn at(&self, x: u32, y: u32) -> bool {
        self.black[y as usize * self.width as usize + x as usize]
    }
}

fn reference() -> Pbm {
    let path: PathBuf = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../corpus/reference/bitmap-composite-and-xnor.pbm");
    let bytes = std::fs::read(&path).unwrap_or_else(|error| {
        panic!(
            "{}: {error} — the reference rasters live in corpus/reference/",
            path.display()
        )
    });
    Pbm::parse(&bytes)
}

#[test]
fn our_raster_matches_the_reference_exactly() {
    // pdfium's own expected raster for this page, committed under `corpus/reference/`
    // (see the README there): a fourth implementation's answer, which is what the
    // engine-agreement argument could not provide.
    //
    // This test began life pinning a **19 553 pixel** difference (mean |Δ| 31.24 of
    // 255) and the search it forced found the cause in the sink rather than the
    // decoder: `Rows` packed the pixels as one continuous bit stream while a 1-bit
    // PDF image is row-aligned to a byte, so with a width of 399 every row drifted
    // by one bit. hayro's own output was byte-exact all along — decoded straight
    // from the stream it reports 10 950 black, the reference's count — and with the
    // sink fixed the two rasters agree to the pixel, which is what is asserted here
    // so the alignment cannot regress.
    let reference = reference();
    assert_eq!((reference.width, reference.height), (399, 400));
    let dark = reference.black.iter().filter(|black| **black).count();
    assert_eq!(dark, 10_950, "the reference raster is intact");

    let rendered = render("bitmap-composite-and-xnor.pdf");
    assert_eq!(
        (rendered.canvas.width(), rendered.canvas.height()),
        (reference.width, reference.height),
        "the page and the reference are the same size"
    );

    let mut flipped = 0_u64;
    let mut columns = vec![0_u64; reference.width as usize];
    for y in 0..reference.height {
        for x in 0..reference.width {
            let Some(pixel) = rendered.canvas.pixel(x, y) else {
                panic!("({x}, {y}) is outside the canvas");
            };
            let ours_black = pixel[..3] == [0, 0, 0];
            if ours_black != reference.at(x, y) {
                flipped += 1;
                columns[x as usize] += 1;
            }
        }
    }
    let (busiest, count) = columns
        .iter()
        .enumerate()
        .max_by_key(|(_, count)| **count)
        .map(|(column, count)| (column as u32, *count))
        .expect("a column");
    assert_eq!(
        flipped, 0,
        "the raster matches pdfium's reference (busiest column x = {busiest} with {count} flips)"
    );
}

#[test]
fn a_scan_that_states_decode_1_0_is_inverted() {
    // `/Decode` remaps the samples before the colour space sees them (8.9.5.2), and a
    // 1-bit scan is where a writer states `[1 0]`: 1 becomes black and 0 white. The
    // CCITT and DCT paths applied it from the start; the JBIG2 path did not, so such
    // a page drew as its negative — white ink on black, which is what a "black page"
    // in a viewer usually is.
    //
    // The fixture is the corpus page with its colour space swapped for the array, in
    // place: the replacement is the same length, so the xref stays valid and no file
    // is committed for a one-line dict change.
    let mut bytes = corpus("bitmap-composite-and-xnor.pdf");
    let needle = b"/ColorSpace /DeviceGray";
    let replacement = b"/Decode [1 0]          ";
    assert_eq!(needle.len(), replacement.len());
    let at = bytes
        .windows(needle.len())
        .position(|window| window == needle)
        .expect("the image dictionary names its colour space");
    bytes[at..at + needle.len()].copy_from_slice(replacement);

    let document = Document::open(bytes).expect("open the patched page");
    let rendered = render_page_number(&document, 0, &RenderOptions::default()).expect("render");
    assert_eq!(
        rendered.report.to_string(),
        "all operators supported",
        "the inverted page draws: {}",
        rendered.report
    );
    let (black, white) = ink(&rendered);
    assert_eq!(
        (black, white),
        (148_650, 10_950),
        "every sample is inverted, not ignored"
    );
}