Skip to main content

docling_pdf/render/
mod.rs

1//! The pure-Rust page renderer — phase 3 of retiring pdfium
2//! (docs/PDF_CONFORMANCE.md, "Retiring pdfium"): the raster of a page's
3//! vector content, text and images that the layout / TableFormer / OCR
4//! stages consume — the default renderer since phase 5 (docling-parse's
5//! renderer plugin draws them only under `DOCLING_RS_RENDERER=docling-parse`).
6//!
7//! It draws what docling-parse's `renderer<BLEND2D>` draws, in its frame:
8//! the page's crop box on a `ceil(width · scale)` × `ceil(height · scale)`
9//! white canvas (`resolve_canvas_size`), y down, the box mapped onto the
10//! whole canvas, `/Rotate` applied to the finished pixels; content-stream
11//! semantics as in [`content`]; fonts as in [`font`]; the anti-aliased
12//! rasterizer, strokes, masks, gradients and image blits are tiny-skia's.
13//! It is not byte-identical to that renderer — Blend2D's font engine,
14//! rasterizer and JIT compositor round differently — and the docling-parse
15//! shim stays the reference the PDF baselines are pinned to; this renderer
16//! is measured against it (`tests::against_the_docling_parse_shim`).
17
18pub mod color;
19pub mod content;
20pub mod font;
21pub mod function;
22pub mod geom;
23pub mod image;
24pub mod jbig2;
25pub mod jpx;
26pub mod objects;
27pub mod prepass;
28
29use std::rc::Rc;
30
31use ::image::RgbImage;
32use lopdf::Document;
33
34use crate::pdf_meta::PdfMeta;
35use geom::Mat;
36
37/// docling-parse's `pixels_for_extent`: `ceil(extent − 1e-6)`.
38pub fn pixels_for_extent(extent: f64) -> u32 {
39    ((extent - 1e-6).ceil().max(1.0)) as u32
40}
41
42/// An image the render could not draw as its pixels (#916): a placeholder
43/// block stands in for it (a codec that failed or is missing), or it was left
44/// out. `rect` is the image's device bounding box in the output bitmap's
45/// pixels (before `/Rotate` is applied to the page).
46#[derive(Debug, Clone, PartialEq)]
47pub struct Omission {
48    /// The image XObject's object id (`None` for an inline image).
49    pub object: Option<lopdf::ObjectId>,
50    /// `[x0, y0, x1, y1]`.
51    pub rect: [f64; 4],
52    /// Why, e.g. `JPEG not decoded (Corrupt("no SOI"))`.
53    pub reason: String,
54}
55
56/// A document's renderer: the per-document caches (fonts, CMYK table,
57/// decoded image samples) that its page renders share. The pipeline renders
58/// every page at two scales; hold one `Renderer` per document across both.
59pub struct Renderer<'a> {
60    meta: &'a PdfMeta,
61    shared: Rc<content::Shared>,
62}
63
64impl<'a> Renderer<'a> {
65    /// What the renders since the last call drew as a placeholder or left
66    /// out (#916).
67    pub fn take_omissions(&self) -> Vec<Omission> {
68        self.shared.take_omissions()
69    }
70
71    /// A renderer decoding its JPEGs for docling's bitmap hint (1.0 pixel per
72    /// PDF unit — the model-input renders).
73    pub fn new(meta: &'a PdfMeta) -> Renderer<'a> {
74        Renderer {
75            meta,
76            shared: Rc::new(content::Shared::default()),
77        }
78    }
79
80    /// A renderer with an explicit `bitmap_target_pixels_per_unit`: `0.0`
81    /// decodes every image at full size (the page rasters a caller keeps —
82    /// `render_pages`, the VLM input — where docling-parse is asked with 0.0
83    /// too).
84    pub fn with_bitmap_hint(meta: &'a PdfMeta, bitmap_hint: f64) -> Renderer<'a> {
85        Renderer {
86            meta,
87            shared: Rc::new(content::Shared::with_bitmap_hint(bitmap_hint)),
88        }
89    }
90
91    /// Render page `index` at `scale` pixels per point the way docling-parse
92    /// sizes its canvas (display orientation, `/Rotate` applied).
93    pub fn render_scaled(&self, index: usize, scale: f64) -> Option<RgbImage> {
94        let geom = self.meta.geometry(index)?;
95        let w = pixels_for_extent(f64::from(geom.width) * scale);
96        let h = pixels_for_extent(f64::from(geom.height) * scale);
97        self.render(index, w, h)
98    }
99
100    /// Render page `index` into exactly `width` × `height` display-frame
101    /// pixels (the crop box stretched onto the canvas, as every renderer
102    /// here does).
103    pub fn render(&self, index: usize, width: u32, height: u32) -> Option<RgbImage> {
104        self.render_with_hint(index, width, height, self.shared.bitmap_hint())
105    }
106
107    /// [`Renderer::render`] with an explicit `bitmap_target_pixels_per_unit`
108    /// for this one render: `1.0` decodes JPEGs the way docling's model
109    /// inputs are decoded, `0.0` at full size — what a bitmap kept for OCR
110    /// wants (the recognizer reads a scan's 300 dpi, not a quarter of it
111    /// blitted up; docling's own OCR runs on its hint-1.0 decode, the
112    /// deliberate deviation the pdfium raster of a scan already makes).
113    pub fn render_with_hint(
114        &self,
115        index: usize,
116        width: u32,
117        height: u32,
118        bitmap_hint: f64,
119    ) -> Option<RgbImage> {
120        if width == 0 || height == 0 || width > 1 << 15 || height > 1 << 15 {
121            return None;
122        }
123        let meta = self.meta;
124        let doc = meta.doc();
125        let pid = meta.page_id(index)?;
126        let page = doc.get_object(pid).ok()?.as_dict().ok()?;
127        let geom = meta.geometry(index)?;
128        let pb = crate::textparse::page_box(doc, pid);
129        // Draw in the unrotated frame; the canvas is transposed for 90°/270°.
130        let (cw, ch) = if geom.rotation == 90 || geom.rotation == 270 {
131            (height, width)
132        } else {
133            (width, height)
134        };
135        let sx = f64::from(cw) / f64::from(pb.w).max(1e-6);
136        let sy = f64::from(ch) / f64::from(pb.h).max(1e-6);
137        // user (x, y) → canvas ((x − l)·sx, H − (y − b)·sy)
138        let base = Mat::new(
139            sx,
140            0.0,
141            0.0,
142            -sy,
143            -f64::from(pb.l) * sx,
144            f64::from(ch) + f64::from(pb.b) * sy,
145        );
146
147        let content = doc.get_page_content(pid);
148        let resources = page_resources(doc, pid);
149        let mut interp = content::Interp::new(doc, cw, ch, self.shared.clone(), bitmap_hint)?;
150        crate::timing::timed("render.content", || {
151            interp.run_page(&content, resources, base);
152            interp.run_widgets(page, base);
153        });
154        let canvas = interp.into_canvas();
155        let rgb = crate::timing::timed("render.finish", || to_rgb(&canvas));
156        Some(rotate(rgb, geom.rotation))
157    }
158}
159
160/// One-off [`Renderer::render_scaled`] (no cache carried across pages).
161pub fn render_page(meta: &PdfMeta, index: usize, scale: f64) -> Option<RgbImage> {
162    Renderer::new(meta).render_scaled(index, scale)
163}
164
165/// One-off [`Renderer::render`].
166pub fn render_page_sized(
167    meta: &PdfMeta,
168    index: usize,
169    width: u32,
170    height: u32,
171) -> Option<RgbImage> {
172    Renderer::new(meta).render(index, width, height)
173}
174
175fn page_resources(doc: &Document, pid: lopdf::ObjectId) -> Option<&lopdf::Dictionary> {
176    doc.get_page_resources(pid).ok().and_then(|(inline, ids)| {
177        inline.or_else(|| ids.into_iter().find_map(|id| doc.get_dictionary(id).ok()))
178    })
179}
180
181/// Premultiplied RGBA over an opaque white canvas → RGB (the alpha is 255
182/// everywhere the canvas started white; a blend mode can only lower colour).
183fn to_rgb(pm: &tiny_skia::Pixmap) -> RgbImage {
184    let (w, h) = (pm.width(), pm.height());
185    let mut out = RgbImage::new(w, h);
186    let data = pm.data();
187    for (i, px) in out.pixels_mut().enumerate() {
188        let a = u32::from(data[i * 4 + 3]);
189        let un = |c: u8| -> u8 {
190            if a == 0 {
191                255
192            } else if a == 255 {
193                c
194            } else {
195                // Un-premultiply, then composite over white.
196                let c = u32::from(c);
197                (c + (255 - a)).min(255) as u8
198            }
199        };
200        *px = ::image::Rgb([un(data[i * 4]), un(data[i * 4 + 1]), un(data[i * 4 + 2])]);
201    }
202    out
203}
204
205/// Rotate the finished canvas clockwise by `/Rotate` degrees.
206fn rotate(img: RgbImage, rotation: u16) -> RgbImage {
207    match rotation {
208        90 => ::image::imageops::rotate90(&img),
209        180 => ::image::imageops::rotate180(&img),
210        270 => ::image::imageops::rotate270(&img),
211        _ => img,
212    }
213}
214
215#[cfg(test)]
216mod tests {
217    use super::*;
218
219    fn root() -> std::path::PathBuf {
220        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../..")
221    }
222
223    /// Every corpus page renders at scale 1.0 to the docling-parse canvas
224    /// size, with ink on it.
225    #[test]
226    fn renders_the_corpus() {
227        // Every PDF the snapshot corpus is generated from — the pdf fixtures,
228        // the scans, the LaTeX figure PDFs (matplotlib / TikZ vector art,
229        // where the renderer's biggest snapshot drifts were) and the ODF
230        // renders; `DOCLING_RS_SHIM_CORPUS=pdf` restricts it to the pdf dir.
231        let mut files = Vec::new();
232        for d in corpus_dirs() {
233            collect_pdfs(&root().join(d), &mut files);
234        }
235        files.sort();
236        assert!(!files.is_empty());
237        let check = |f: &std::path::Path| {
238            let bytes = std::fs::read(f).unwrap();
239            let Some(meta) = PdfMeta::open(&bytes) else {
240                return;
241            };
242            let renderer = Renderer::new(&meta);
243            for i in 0..meta.page_count().min(3) {
244                let g = meta.geometry(i).unwrap();
245                let img = renderer
246                    .render_scaled(i, 1.0)
247                    .unwrap_or_else(|| panic!("{}: page {} declined", f.display(), i + 1));
248                assert_eq!(
249                    img.width(),
250                    pixels_for_extent(f64::from(g.width)),
251                    "{}",
252                    f.display()
253                );
254                assert_eq!(
255                    img.height(),
256                    pixels_for_extent(f64::from(g.height)),
257                    "{}",
258                    f.display()
259                );
260                let dark = img.pixels().filter(|p| p[0] < 200).count();
261                assert!(dark > 0, "{} p{}: blank render", f.display(), i + 1);
262            }
263        };
264        // A minute of debug-build rendering serially; the files are
265        // independent, so a thread per core takes them off a shared queue
266        // (the crate has no rayon). A worker's panic is the test's.
267        let next = std::sync::atomic::AtomicUsize::new(0);
268        let workers = std::thread::available_parallelism().map_or(1, |n| n.get());
269        std::thread::scope(|s| {
270            let handles: Vec<_> = (0..workers.min(files.len()))
271                .map(|_| {
272                    s.spawn(|| loop {
273                        let i = next.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
274                        let Some(f) = files.get(i) else { break };
275                        check(f);
276                    })
277                })
278                .collect();
279            for h in handles {
280                if let Err(e) = h.join() {
281                    std::panic::resume_unwind(e);
282                }
283            }
284        });
285    }
286
287    /// Measure this renderer against the docling-parse shim on the corpus at
288    /// the two pipeline scales, when the shim is installed: prints per-file
289    /// mean absolute differences and asserts a loose bound so a regression
290    /// (a page gone blank, text drawn at the wrong size) fails the test.
291    #[test]
292    fn against_the_docling_parse_shim() {
293        // Tests run with CWD = the crate; point the loader at the repo's copy.
294        if std::env::var_os("DOCLING_PARSE_RENDER_LIB").is_none() {
295            let lib = root().join(".docling-parse/lib");
296            if lib.is_dir() {
297                std::env::set_var("DOCLING_PARSE_RENDER_LIB", &lib);
298            }
299        }
300        // The shim loads only when asked for by name (phase 5); no other test
301        // in this binary resolves the plugin, so the once-only load sees this.
302        std::env::set_var("DOCLING_RS_RENDERER", "docling-parse");
303        let Some(plugin) = crate::dparse_render::plugin() else {
304            eprintln!("docling-parse shim not installed — skipping the renderer comparison");
305            return;
306        };
307        let _ = plugin;
308        // Every PDF the snapshot corpus is generated from (the walk of
309        // `renders_the_corpus`), so the gate covers what the baselines see.
310        let mut files = Vec::new();
311        for d in corpus_dirs() {
312            collect_pdfs(&root().join(d), &mut files);
313        }
314        files.sort();
315        eprintln!("renderer vs shim: {} PDFs", files.len());
316        let mut worst = 0.0f64;
317        let mut total_mad = 0.0f64;
318        let mut n = 0usize;
319        for f in &files {
320            let bytes = std::fs::read(f).unwrap();
321            let Some(meta) = PdfMeta::open(&bytes) else {
322                eprintln!("{}: object model unreadable, skipped", f.display());
323                continue;
324            };
325            let renderer = Renderer::new(&meta);
326            let Some(dp) = crate::dparse_render::Doc::open_if_enabled(&bytes, None) else {
327                eprintln!("{}: the shim declined the file, skipped", f.display());
328                continue;
329            };
330            for i in 0..meta.page_count() {
331                for scale in [1.0f64, 2.0] {
332                    let Ok(want) = dp.render(i, scale, 1.0) else {
333                        continue;
334                    };
335                    let Some(got) = renderer.render(i, want.width(), want.height()) else {
336                        continue;
337                    };
338                    let mad = mean_abs_diff(&got, &want);
339                    worst = worst.max(mad);
340                    total_mad += mad;
341                    n += 1;
342                    eprintln!(
343                        "{} p{} @{scale}: mean |Δ| = {mad:.2}",
344                        f.file_name().unwrap().to_string_lossy(),
345                        i + 1
346                    );
347                }
348                dp.release_page(i);
349            }
350        }
351        if n > 0 {
352            eprintln!(
353                "renderer vs shim: {n} renders, mean |Δ| {:.2}, worst {worst:.2}",
354                total_mad / n as f64
355            );
356        }
357        // The corpus sits at mean |Δ| ≈ 1 / 255 per channel with the worst
358        // page (a photograph resampled through a different bilinear phase)
359        // under 6; a page past 10 is a drawing bug, not rounding.
360        assert!(
361            worst < 10.0,
362            "a render diverged from the shim (mean |Δ| {worst:.1})"
363        );
364        if n > 0 {
365            assert!(
366                total_mad / (n as f64) < 2.0,
367                "the corpus drifted from the shim"
368            );
369        }
370    }
371
372    /// The source directories of the snapshot corpus; `DOCLING_RS_SHIM_CORPUS=pdf`
373    /// restricts a run to the pdf fixtures.
374    fn corpus_dirs() -> &'static [&'static str] {
375        if std::env::var("DOCLING_RS_SHIM_CORPUS").as_deref() == Ok("pdf") {
376            &["tests/data/pdf/sources"]
377        } else {
378            &[
379                "tests/data/pdf/sources",
380                "tests/data/scanned/sources",
381                "tests/data/latex/sources",
382                "tests/data/odf/sources",
383            ]
384        }
385    }
386
387    fn collect_pdfs(dir: &std::path::Path, out: &mut Vec<std::path::PathBuf>) {
388        let Ok(rd) = std::fs::read_dir(dir) else {
389            return;
390        };
391        for e in rd.flatten() {
392            let p = e.path();
393            if p.is_dir() {
394                collect_pdfs(&p, out);
395            } else if p.extension().is_some_and(|e| e == "pdf") {
396                out.push(p);
397            }
398        }
399    }
400
401    fn mean_abs_diff(a: &RgbImage, b: &RgbImage) -> f64 {
402        if a.dimensions() != b.dimensions() {
403            return 255.0;
404        }
405        let sum: u64 = a
406            .as_raw()
407            .iter()
408            .zip(b.as_raw())
409            .map(|(x, y)| u64::from((i32::from(*x) - i32::from(*y)).unsigned_abs()))
410            .sum();
411        sum as f64 / a.as_raw().len().max(1) as f64
412    }
413}
414
415/// Synthetic pages, one drawing feature each: the frame mapping, `/Rotate`,
416/// the minimum stroke width, constant alpha, clips, images (XObject and
417/// inline), shadings, patterns, forms, widgets, text (fallback face and
418/// Type 3). Each asserts where the ink lands, not its exact coverage — the
419/// shim comparison above is the coverage oracle.
420#[cfg(test)]
421mod synthetic {
422    use super::*;
423    use lopdf::{dictionary, Dictionary, Object, Stream};
424
425    /// A one-page document: `media` box, `page_extra` merged into the page
426    /// dictionary (CropBox, Rotate, Annots), `resources`, `content`.
427    fn synth(
428        doc: &mut Document,
429        media: [f32; 4],
430        page_extra: Dictionary,
431        resources: Dictionary,
432        content: &str,
433    ) -> Vec<u8> {
434        synth_bytes(doc, media, page_extra, resources, content.as_bytes())
435    }
436
437    fn synth_bytes(
438        doc: &mut Document,
439        media: [f32; 4],
440        page_extra: Dictionary,
441        resources: Dictionary,
442        content: &[u8],
443    ) -> Vec<u8> {
444        let pages_id = doc.new_object_id();
445        let res_id = doc.add_object(resources);
446        let content_id = doc.add_object(Stream::new(Dictionary::new(), content.to_vec()));
447        let mut page = dictionary! {
448            "Type" => "Page",
449            "Parent" => Object::Reference(pages_id),
450            "MediaBox" => media.iter().map(|&v| Object::Real(v)).collect::<Vec<_>>(),
451            "Contents" => Object::Reference(content_id),
452            "Resources" => Object::Reference(res_id),
453        };
454        for (k, v) in page_extra.into_iter() {
455            page.set(k, v);
456        }
457        let page_id = doc.add_object(page);
458        doc.objects.insert(
459            pages_id,
460            Object::Dictionary(dictionary! {
461                "Type" => "Pages",
462                "Kids" => vec![Object::Reference(page_id)],
463                "Count" => 1,
464            }),
465        );
466        let catalog_id = doc.add_object(dictionary! {
467            "Type" => "Catalog",
468            "Pages" => Object::Reference(pages_id),
469        });
470        doc.trailer.set("Root", Object::Reference(catalog_id));
471        let mut out = Vec::new();
472        doc.save_to(&mut out).unwrap();
473        out
474    }
475
476    /// A 200 × 100 pt page with `content` and `resources`.
477    fn page(resources: Dictionary, content: &str) -> Vec<u8> {
478        let mut doc = Document::with_version("1.5");
479        synth(
480            &mut doc,
481            [0.0, 0.0, 200.0, 100.0],
482            Dictionary::new(),
483            resources,
484            content,
485        )
486    }
487
488    fn page_with_contents(contents: &[&[u8]]) -> Vec<u8> {
489        let mut doc = Document::with_version("1.5");
490        let streams = contents
491            .iter()
492            .map(|content| {
493                Object::Reference(doc.add_object(Stream::new(Dictionary::new(), content.to_vec())))
494            })
495            .collect::<Vec<_>>();
496        synth(
497            &mut doc,
498            [0.0, 0.0, 200.0, 100.0],
499            dictionary! { "Contents" => streams },
500            Dictionary::new(),
501            "",
502        )
503    }
504
505    fn render(bytes: &[u8]) -> RgbImage {
506        let meta = PdfMeta::open(bytes).expect("object model");
507        render_page(&meta, 0, 1.0).expect("render")
508    }
509
510    fn px(img: &RgbImage, x: u32, y: u32) -> [u8; 3] {
511        img.get_pixel(x, y).0
512    }
513
514    fn near(a: [u8; 3], b: [u8; 3], tol: i32) -> bool {
515        a.iter()
516            .zip(b)
517            .all(|(&x, y)| (i32::from(x) - i32::from(y)).abs() <= tol)
518    }
519
520    const WHITE: [u8; 3] = [255, 255, 255];
521    const RED: [u8; 3] = [255, 0, 0];
522
523    /// Ink (anything not white) inside a device rectangle.
524    fn ink_in(img: &RgbImage, x0: u32, y0: u32, x1: u32, y1: u32) -> usize {
525        let mut n = 0;
526        for y in y0..y1 {
527            for x in x0..x1 {
528                if px(img, x, y) != WHITE {
529                    n += 1;
530                }
531            }
532        }
533        n
534    }
535
536    #[test]
537    fn fills_land_in_the_docling_parse_frame() {
538        // A 200 × 100 page: canvas 200 × 100, y down, `re f` at (60, 10)
539        // 40 × 30 covers x 60..100, y 60..90.
540        let img = render(&page(Dictionary::new(), "1 0 0 rg 60 10 40 30 re f"));
541        assert_eq!((img.width(), img.height()), (200, 100));
542        assert_eq!(px(&img, 80, 75), RED);
543        assert_eq!(px(&img, 61, 61), RED);
544        assert_eq!(px(&img, 80, 55), WHITE);
545        assert_eq!(px(&img, 105, 75), WHITE);
546        assert_eq!(px(&img, 5, 5), WHITE);
547    }
548
549    #[test]
550    fn leading_comment_content_stream_does_not_hide_later_streams() {
551        let bytes = page_with_contents(&[
552            b"% CANON_PFINF_TYPE2_TEXTOFF\n",
553            b"1 0 0 rg 60 10 40 30 re f",
554        ]);
555        let img = render(&bytes);
556        assert_eq!(px(&img, 80, 75), RED);
557    }
558
559    #[test]
560    fn crop_box_is_the_canvas() {
561        // CropBox [50 0 150 100] → a 100 × 100 canvas; the rectangle at
562        // x 60..100 lands at canvas x 10..50.
563        let mut doc = Document::with_version("1.5");
564        let bytes = synth(
565            &mut doc,
566            [0.0, 0.0, 200.0, 100.0],
567            dictionary! { "CropBox" => vec![50.into(), 0.into(), 150.into(), 100.into()] },
568            Dictionary::new(),
569            "1 0 0 rg 60 10 40 30 re f",
570        );
571        let img = render(&bytes);
572        assert_eq!((img.width(), img.height()), (100, 100));
573        assert_eq!(px(&img, 30, 75), RED);
574        assert_eq!(px(&img, 5, 75), WHITE);
575        assert_eq!(px(&img, 55, 75), WHITE);
576    }
577
578    #[test]
579    fn rotate_transposes_the_canvas() {
580        // /Rotate 90: the display canvas is 100 × 200 and the page's
581        // bottom-left corner shows top-left.
582        let mut doc = Document::with_version("1.5");
583        let bytes = synth(
584            &mut doc,
585            [0.0, 0.0, 200.0, 100.0],
586            dictionary! { "Rotate" => 90 },
587            Dictionary::new(),
588            "1 0 0 rg 0 0 40 20 re f",
589        );
590        let img = render(&bytes);
591        assert_eq!((img.width(), img.height()), (100, 200));
592        assert_eq!(px(&img, 10, 20), RED);
593        assert_eq!(px(&img, 10, 45), WHITE);
594        assert_eq!(px(&img, 90, 190), WHITE);
595        let meta = PdfMeta::open(&bytes).unwrap();
596        let sized = render_page_sized(&meta, 0, 50, 100).unwrap();
597        assert_eq!((sized.width(), sized.height()), (50, 100));
598        assert_eq!(px(&sized, 5, 10), RED);
599    }
600
601    #[test]
602    fn hairline_strokes_are_one_pixel_wide() {
603        // `0 w` is a hairline in PDF; docling-parse draws it at one pixel.
604        let img = render(&page(Dictionary::new(), "0 w 10 50.5 m 190 50.5 l S"));
605        assert!(ink_in(&img, 100, 49, 101, 51) >= 1);
606        assert_eq!(ink_in(&img, 100, 40, 101, 48), 0);
607        assert_eq!(ink_in(&img, 100, 52, 101, 60), 0);
608        // A 4-pt line is four pixels tall.
609        let img = render(&page(Dictionary::new(), "4 w 10 50 m 190 50 l S"));
610        assert!(ink_in(&img, 100, 44, 101, 56) >= 4);
611        assert_eq!(ink_in(&img, 100, 40, 101, 47), 0);
612    }
613
614    #[test]
615    fn constant_alpha_blends_over_white() {
616        let res = dictionary! {
617            "ExtGState" => dictionary! {
618                "GS" => dictionary! { "ca" => 0.5, "CA" => 0.25 },
619            },
620        };
621        let img = render(&page(res, "/GS gs 0 g 20 20 160 60 re f"));
622        let p = px(&img, 100, 50);
623        assert!(near(p, [128, 128, 128], 2), "{p:?}");
624    }
625
626    #[test]
627    fn rect_clip_cuts_the_fill() {
628        let img = render(&page(
629            Dictionary::new(),
630            "q 0 0 100 100 re W n 0 0 1 rg 0 0 200 100 re f Q 0 0 200 10 re f",
631        ));
632        assert_eq!(px(&img, 50, 50), [0, 0, 255]);
633        assert_eq!(px(&img, 150, 50), WHITE);
634        // The clip ends with Q: the bottom strip is black across the page.
635        assert_eq!(px(&img, 150, 95), [0, 0, 0]);
636    }
637
638    #[test]
639    fn shape_clip_follows_the_path() {
640        // A triangle clip: the fill shows inside the triangle only.
641        let img = render(&page(
642            Dictionary::new(),
643            "q 0 0 m 200 0 l 100 100 l h W n 0 1 0 rg 0 0 200 100 re f Q",
644        ));
645        assert_eq!(px(&img, 100, 50), [0, 255, 0]);
646        assert_eq!(px(&img, 100, 90), [0, 255, 0]);
647        assert_eq!(px(&img, 5, 5), WHITE);
648        assert_eq!(px(&img, 195, 5), WHITE);
649    }
650
651    #[test]
652    fn image_xobject_is_blitted_with_its_orientation() {
653        // 2 × 2 RGB: red green / blue black, first row at the top.
654        let data = vec![255, 0, 0, 0, 255, 0, 0, 0, 255, 0, 0, 0];
655        let mut doc = Document::with_version("1.5");
656        let im = doc.add_object(Stream::new(
657            dictionary! {
658                "Type" => "XObject", "Subtype" => "Image",
659                "Width" => 2, "Height" => 2, "BitsPerComponent" => 8,
660                "ColorSpace" => "DeviceRGB",
661            },
662            data,
663        ));
664        let bytes = synth(
665            &mut doc,
666            [0.0, 0.0, 200.0, 100.0],
667            Dictionary::new(),
668            dictionary! { "XObject" => dictionary! { "Im0" => Object::Reference(im) } },
669            "q 200 0 0 100 0 0 cm /Im0 Do Q",
670        );
671        let img = render(&bytes);
672        // Bilinear sampling at the quadrant centres: the source colours
673        // within tiny-skia's fixed-point rounding.
674        assert!(near(px(&img, 50, 25), RED, 6));
675        assert!(near(px(&img, 150, 25), [0, 255, 0], 6));
676        assert!(near(px(&img, 50, 75), [0, 0, 255], 6));
677        assert!(near(px(&img, 150, 75), [0, 0, 0], 6));
678    }
679
680    #[test]
681    fn inline_image_and_stencil_mask() {
682        // A 1 × 1 gray inline image over the left half, a 2 × 1 stencil
683        // (bit 0 paints) in the fill colour over the right half.
684        let mut content = b"q 100 0 0 100 0 0 cm BI /W 1 /H 1 /CS /G /BPC 8 ID ".to_vec();
685        content.push(0x80);
686        content.extend_from_slice(
687            b" EI Q q 1 0 0 rg 100 0 0 100 100 0 cm BI /W 2 /H 1 /IM true /D [0 1] ID ",
688        );
689        content.push(0x40);
690        content.extend_from_slice(b" EI Q");
691        let mut doc = Document::with_version("1.5");
692        let bytes = synth_bytes(
693            &mut doc,
694            [0.0, 0.0, 200.0, 100.0],
695            Dictionary::new(),
696            Dictionary::new(),
697            &content,
698        );
699        let img = render(&bytes);
700        assert!(near(px(&img, 50, 50), [128, 128, 128], 1));
701        assert_eq!(px(&img, 125, 50), RED);
702        assert_eq!(px(&img, 175, 50), WHITE);
703    }
704
705    #[test]
706    fn axial_shading_interpolates() {
707        let res = dictionary! {
708            "Shading" => dictionary! {
709                "Sh" => dictionary! {
710                    "ShadingType" => 2, "ColorSpace" => "DeviceGray",
711                    "Coords" => vec![0.into(), 0.into(), 200.into(), 0.into()],
712                    "Function" => dictionary! {
713                        "FunctionType" => 2, "Domain" => vec![0.into(), 1.into()],
714                        "C0" => vec![0.into()], "C1" => vec![1.into()], "N" => 1,
715                    },
716                    "Extend" => vec![true.into(), true.into()],
717                },
718            },
719        };
720        let img = render(&page(res, "/Sh sh"));
721        assert!(px(&img, 5, 50)[0] < 40);
722        assert!(px(&img, 195, 50)[0] > 215);
723        assert!(near(px(&img, 100, 50), [128, 128, 128], 12));
724        // The same shading as a fill pattern, clipped by the path.
725        let res = dictionary! {
726            "Pattern" => dictionary! {
727                "P" => dictionary! {
728                    "PatternType" => 2,
729                    "Shading" => dictionary! {
730                        "ShadingType" => 2, "ColorSpace" => "DeviceGray",
731                        "Coords" => vec![0.into(), 0.into(), 200.into(), 0.into()],
732                        "Function" => dictionary! {
733                            "FunctionType" => 2, "Domain" => vec![0.into(), 1.into()],
734                            "C0" => vec![0.into()], "C1" => vec![1.into()], "N" => 1,
735                        },
736                    },
737                },
738            },
739        };
740        let img = render(&page(res, "/Pattern cs /P scn 0 0 100 100 re f"));
741        assert!(px(&img, 5, 50)[0] < 40);
742        assert!(near(px(&img, 50, 50), [64, 64, 64], 12));
743        assert_eq!(px(&img, 150, 50), WHITE);
744    }
745
746    #[test]
747    fn tiling_pattern_repeats_its_cell() {
748        // A 20 × 20 cell with a 10 × 10 black square: half the area inked.
749        let mut doc = Document::with_version("1.5");
750        let pat = doc.add_object(Stream::new(
751            dictionary! {
752                "PatternType" => 1, "PaintType" => 1, "TilingType" => 1,
753                "BBox" => vec![0.into(), 0.into(), 20.into(), 20.into()],
754                "XStep" => 20, "YStep" => 20, "Resources" => Dictionary::new(),
755            },
756            b"0 g 0 0 10 10 re f".to_vec(),
757        ));
758        let bytes = synth(
759            &mut doc,
760            [0.0, 0.0, 200.0, 100.0],
761            Dictionary::new(),
762            dictionary! { "Pattern" => dictionary! { "P" => Object::Reference(pat) } },
763            "/Pattern cs /P scn 0 0 200 100 re f",
764        );
765        let img = render(&bytes);
766        let inked = ink_in(&img, 0, 0, 200, 100);
767        assert!((4000..=6500).contains(&inked), "{inked}");
768        // The cell at the origin: its square covers x 0..10, y 90..100.
769        assert_eq!(px(&img, 5, 95), [0, 0, 0]);
770        assert_eq!(px(&img, 15, 85), WHITE);
771    }
772
773    #[test]
774    fn form_xobject_matrix_and_bbox() {
775        // The form fills far beyond its BBox; only the BBox, moved by the
776        // Matrix to x 100..150 / y 0..50, shows.
777        let mut doc = Document::with_version("1.5");
778        let fx = doc.add_object(Stream::new(
779            dictionary! {
780                "Type" => "XObject", "Subtype" => "Form",
781                "BBox" => vec![0.into(), 0.into(), 50.into(), 50.into()],
782                "Matrix" => vec![1.into(), 0.into(), 0.into(), 1.into(), 100.into(), 0.into()],
783            },
784            b"1 0 0 rg -500 -500 1000 1000 re f".to_vec(),
785        ));
786        let bytes = synth(
787            &mut doc,
788            [0.0, 0.0, 200.0, 100.0],
789            Dictionary::new(),
790            dictionary! { "XObject" => dictionary! { "Fx" => Object::Reference(fx) } },
791            "/Fx Do",
792        );
793        let img = render(&bytes);
794        assert_eq!(px(&img, 125, 75), RED);
795        assert_eq!(px(&img, 75, 75), WHITE);
796        assert_eq!(px(&img, 125, 25), WHITE);
797        assert_eq!(px(&img, 175, 75), WHITE);
798    }
799
800    #[test]
801    fn transparency_group_alpha_reaches_its_contents() {
802        // docling-parse pushes the group's `ca` down onto the contents.
803        let mut doc = Document::with_version("1.5");
804        let fx = doc.add_object(Stream::new(
805            dictionary! {
806                "Type" => "XObject", "Subtype" => "Form",
807                "BBox" => vec![0.into(), 0.into(), 200.into(), 100.into()],
808                "Group" => dictionary! { "S" => "Transparency", "CS" => "DeviceRGB" },
809            },
810            b"0 g 0 0 200 100 re f".to_vec(),
811        ));
812        let bytes = synth(
813            &mut doc,
814            [0.0, 0.0, 200.0, 100.0],
815            Dictionary::new(),
816            dictionary! {
817                "XObject" => dictionary! { "Fx" => Object::Reference(fx) },
818                "ExtGState" => dictionary! { "GS" => dictionary! { "ca" => 0.5 } },
819            },
820            "/GS gs /Fx Do",
821        );
822        let img = render(&bytes);
823        assert!(near(px(&img, 100, 50), [128, 128, 128], 2));
824    }
825
826    #[test]
827    fn widgets_draw_their_appearance_unless_hidden() {
828        let mut doc = Document::with_version("1.5");
829        let ap = doc.add_object(Stream::new(
830            dictionary! {
831                "Type" => "XObject", "Subtype" => "Form",
832                "BBox" => vec![0.into(), 0.into(), 10.into(), 10.into()],
833            },
834            b"1 0 0 rg 0 0 10 10 re f".to_vec(),
835        ));
836        let widget = |x0: i64, flags: i64, subtype: &str| -> Object {
837            Object::Dictionary(dictionary! {
838                "Type" => "Annot", "Subtype" => subtype, "F" => flags,
839                "Rect" => vec![x0.into(), 20.into(), (x0 + 40).into(), 60.into()],
840                "AP" => dictionary! { "N" => Object::Reference(ap) },
841            })
842        };
843        let bytes = synth(
844            &mut doc,
845            [0.0, 0.0, 200.0, 100.0],
846            dictionary! {
847                "Annots" => vec![
848                    widget(10, 4, "Widget"),
849                    widget(60, 2, "Widget"),
850                    widget(110, 4, "Square"),
851                ],
852            },
853            Dictionary::new(),
854            "",
855        );
856        let img = render(&bytes);
857        // The visible widget: BBox 10 × 10 fitted to the 40 × 40 Rect.
858        assert_eq!(px(&img, 30, 60), RED);
859        assert_eq!(px(&img, 12, 42), RED);
860        assert_eq!(px(&img, 48, 78), RED);
861        assert_eq!(px(&img, 30, 30), WHITE);
862        // Hidden, and a non-Widget annotation: not drawn.
863        assert_eq!(px(&img, 80, 60), WHITE);
864        assert_eq!(px(&img, 130, 60), WHITE);
865    }
866
867    #[test]
868    fn text_paints_glyphs_from_a_fallback_face() {
869        let style = font::fallback::style_for("Helvetica", None, None);
870        if font::fallback::face(style).is_none() {
871            eprintln!("no fallback fonts on this host — skipping");
872            return;
873        }
874        let res = dictionary! {
875            "Font" => dictionary! {
876                "F1" => dictionary! {
877                    "Type" => "Font", "Subtype" => "Type1", "BaseFont" => "Helvetica",
878                },
879            },
880        };
881        let img = render(&page(res.clone(), "BT /F1 40 Tf 20 30 Td (HELLO) Tj ET"));
882        // Cap height ~0.72 em: ink between y 100−30−29 and the baseline.
883        assert!(ink_in(&img, 20, 40, 160, 70) > 200);
884        assert_eq!(ink_in(&img, 0, 0, 200, 35), 0);
885        assert_eq!(ink_in(&img, 0, 75, 200, 100), 0);
886        // Render mode 3 (invisible) draws nothing; a `Tz` of 50 % halves
887        // the advance so the word ends earlier.
888        let img = render(&page(
889            res.clone(),
890            "BT 3 Tr /F1 40 Tf 20 30 Td (HELLO) Tj ET",
891        ));
892        assert_eq!(ink_in(&img, 0, 0, 200, 100), 0);
893        let wide = render(&page(res.clone(), "BT /F1 40 Tf 20 30 Td (HHHH) Tj ET"));
894        let narrow = render(&page(res, "BT /F1 40 Tf 50 Tz 20 30 Td (HHHH) Tj ET"));
895        let right = |img: &RgbImage| {
896            (0..200)
897                .rev()
898                .find(|&x| ink_in(img, x, 0, x + 1, 100) > 0)
899                .unwrap()
900        };
901        assert!(right(&wide) > right(&narrow) + 30);
902    }
903
904    #[test]
905    fn type3_glyphs_run_their_procedures() {
906        let mut doc = Document::with_version("1.5");
907        let square = doc.add_object(Stream::new(
908            Dictionary::new(),
909            b"1000 0 0 0 750 750 d1 0 0 750 750 re f".to_vec(),
910        ));
911        let font = doc.add_object(dictionary! {
912            "Type" => "Font", "Subtype" => "Type3",
913            "FontBBox" => vec![0.into(), 0.into(), 750.into(), 750.into()],
914            "FontMatrix" => vec![0.001.into(), 0.into(), 0.into(), 0.001.into(), 0.into(), 0.into()],
915            "CharProcs" => dictionary! { "square" => Object::Reference(square) },
916            "Encoding" => dictionary! {
917                "Type" => "Encoding",
918                "Differences" => vec![97.into(), Object::Name(b"square".to_vec())],
919            },
920            "FirstChar" => 97, "LastChar" => 97, "Widths" => vec![1000.into()],
921            "Resources" => Dictionary::new(),
922        });
923        let bytes = synth(
924            &mut doc,
925            [0.0, 0.0, 200.0, 100.0],
926            Dictionary::new(),
927            dictionary! { "Font" => dictionary! { "F1" => Object::Reference(font) } },
928            "BT /F1 40 Tf 20 20 Td 0 0 1 rg (aa) Tj ET",
929        );
930        let img = render(&bytes);
931        // Two 30 × 30 squares 40 pt apart: x 20..50 and 60..90, y 50..80.
932        assert_eq!(px(&img, 35, 65), [0, 0, 255]);
933        assert_eq!(px(&img, 75, 65), [0, 0, 255]);
934        assert_eq!(px(&img, 55, 65), WHITE);
935        assert_eq!(px(&img, 105, 65), WHITE);
936        assert_eq!(px(&img, 35, 45), WHITE);
937    }
938
939    #[test]
940    fn cmyk_follows_the_docling_parse_model() {
941        // docling-parse's CMYK model: pure K is (35, 31, 32), not black.
942        let img = render(&page(Dictionary::new(), "0 0 0 1 k 0 0 200 100 re f"));
943        assert_eq!(px(&img, 100, 50), [35, 31, 32]);
944    }
945
946    #[test]
947    fn a_renderer_reuses_its_caches_across_renders() {
948        // Two sizes of the same page through one Renderer: identical to
949        // one-off renders (the image store and font cache change nothing).
950        let data: Vec<u8> = (0..64 * 64 * 3).map(|i| (i % 251) as u8).collect();
951        let mut doc = Document::with_version("1.5");
952        let im = doc.add_object(Stream::new(
953            dictionary! {
954                "Type" => "XObject", "Subtype" => "Image",
955                "Width" => 64, "Height" => 64, "BitsPerComponent" => 8,
956                "ColorSpace" => "DeviceRGB",
957            },
958            data,
959        ));
960        let bytes = synth(
961            &mut doc,
962            [0.0, 0.0, 200.0, 100.0],
963            Dictionary::new(),
964            dictionary! { "XObject" => dictionary! { "Im0" => Object::Reference(im) } },
965            "q 100 0 0 50 50 25 cm /Im0 Do Q q 20 0 0 20 0 0 cm /Im0 Do Q",
966        );
967        let meta = PdfMeta::open(&bytes).unwrap();
968        let r = Renderer::new(&meta);
969        let a1 = r.render(0, 200, 100).unwrap();
970        let a2 = r.render(0, 400, 200).unwrap();
971        let a3 = r.render(0, 200, 100).unwrap();
972        assert_eq!(
973            a1.as_raw(),
974            render_page_sized(&meta, 0, 200, 100).unwrap().as_raw()
975        );
976        assert_eq!(
977            a2.as_raw(),
978            render_page_sized(&meta, 0, 400, 200).unwrap().as_raw()
979        );
980        assert_eq!(a1.as_raw(), a3.as_raw());
981    }
982
983    /// #598: a `JPXDecode` image draws its pixels, not a mid-gray block. The
984    /// fixture is a lossless 12 × 9 gray gradient (`(x·21 + y·3) mod 256`):
985    /// dark at the left edge, bright at the right; with alpha from the
986    /// codestream only under `/SMaskInData`.
987    #[test]
988    fn jpx_image_renders_its_pixels() {
989        let jp2 = std::fs::read(
990            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/data/jpx/gray_12x9.jp2"),
991        )
992        .unwrap();
993        let mut doc = Document::with_version("1.5");
994        let im = doc.add_object(Stream::new(
995            dictionary! {
996                "Type" => "XObject", "Subtype" => "Image",
997                "Width" => 12, "Height" => 9,
998                "ColorSpace" => "DeviceGray", "BitsPerComponent" => 8,
999                "Filter" => "JPXDecode",
1000            },
1001            jp2.clone(),
1002        ));
1003        let bytes = synth(
1004            &mut doc,
1005            [0.0, 0.0, 200.0, 100.0],
1006            Dictionary::new(),
1007            dictionary! { "XObject" => dictionary! { "Im0" => Object::Reference(im) } },
1008            "q 120 0 0 90 40 5 cm /Im0 Do Q",
1009        );
1010        let img = render(&bytes);
1011        // Image column 0 (codes 0–24) lands at device x 40–50, column 11
1012        // (codes 231–255) at x 150–160; the row at device y 50 is image row 4.
1013        let left = px(&img, 45, 50);
1014        let right = px(&img, 155, 50);
1015        assert!(left[0] < 40 && left == [left[0]; 3], "left pixel {left:?}");
1016        assert!(
1017            right[0] > 215 && right == [right[0]; 3],
1018            "right pixel {right:?}"
1019        );
1020        assert_eq!(px(&img, 20, 50), WHITE, "outside the image stays white");
1021
1022        // The RGBA fixture: alpha is ignored without `/SMaskInData` (an
1023        // opaque blit) and honoured with it (the x = 0 column is fully
1024        // transparent, so the page shows through).
1025        let rgba = std::fs::read(
1026            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/data/jpx/rgba_8x6.jp2"),
1027        )
1028        .unwrap();
1029        for (smask_in_data, transparent_left) in [(0, false), (1, true)] {
1030            let mut doc = Document::with_version("1.5");
1031            let im = doc.add_object(Stream::new(
1032                dictionary! {
1033                    "Type" => "XObject", "Subtype" => "Image",
1034                    "Width" => 8, "Height" => 6,
1035                    "ColorSpace" => "DeviceRGB", "BitsPerComponent" => 8,
1036                    "Filter" => "JPXDecode", "SMaskInData" => smask_in_data,
1037                },
1038                rgba.clone(),
1039            ));
1040            let bytes = synth(
1041                &mut doc,
1042                [0.0, 0.0, 200.0, 100.0],
1043                Dictionary::new(),
1044                dictionary! { "XObject" => dictionary! { "Im0" => Object::Reference(im) } },
1045                "q 160 0 0 60 20 20 cm /Im0 Do Q",
1046            );
1047            let img = render(&bytes);
1048            // Image column 0 → device x 20–40: colour (0, y·40, 128), alpha 0
1049            // (the bilinear blit lets a sliver of column 1, alpha 36, in).
1050            let p = px(&img, 30, 50);
1051            if transparent_left {
1052                assert!(near(p, WHITE, 3), "SMaskInData {smask_in_data}: {p:?}");
1053            } else {
1054                assert!(
1055                    p != WHITE && p[2] > 100,
1056                    "SMaskInData {smask_in_data}: {p:?}"
1057                );
1058            }
1059        }
1060    }
1061
1062    /// A JBIG2 fixture (`tests/data/jbig2`) and its reference bitmap as the
1063    /// packed 1-bit samples the filter would output (0 = black).
1064    fn jbig2_fixture(name: &str) -> Vec<u8> {
1065        std::fs::read(
1066            std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
1067                .join("tests/data/jbig2")
1068                .join(name),
1069        )
1070        .unwrap()
1071    }
1072
1073    fn jbig2_reference(name: &str) -> (usize, usize, Vec<u8>) {
1074        let img = ::image::load_from_memory(&jbig2_fixture(name))
1075            .unwrap()
1076            .to_luma8();
1077        let (w, h) = (img.width() as usize, img.height() as usize);
1078        let stride = w.div_ceil(8);
1079        let mut out = vec![0xffu8; stride * h];
1080        for (y, row) in img.rows().enumerate() {
1081            for (x, p) in row.enumerate() {
1082                if p.0[0] < 128 {
1083                    out[y * stride + x / 8] &= !(0x80 >> (x % 8));
1084                }
1085            }
1086        }
1087        (w, h, out)
1088    }
1089
1090    /// One page drawing `image` (an image XObject stream) over the whole of
1091    /// a 440 × 180 pt page, at `scale` px/pt.
1092    fn page_with_image(stream: Stream, content: &str) -> RgbImage {
1093        let mut doc = Document::with_version("1.5");
1094        let im = doc.add_object(stream);
1095        let bytes = synth(
1096            &mut doc,
1097            [0.0, 0.0, 440.0, 180.0],
1098            Dictionary::new(),
1099            dictionary! { "XObject" => dictionary! { "Im0" => Object::Reference(im) } },
1100            content,
1101        );
1102        render(&bytes)
1103    }
1104
1105    fn non_white_share(img: &RgbImage) -> f64 {
1106        let n = img.pixels().filter(|p| p.0 != WHITE).count();
1107        n as f64 / (img.width() as f64 * img.height() as f64)
1108    }
1109
1110    /// #811: a JBIG2 `/ImageMask` stencil draws its pixels — the same page
1111    /// as the Flate and CCITT G4 (`/K -1`, the very same T.6 bytes)
1112    /// controls, pixel for pixel — where it used to draw nothing at all,
1113    /// leaving a scanned page's text out of the render.
1114    #[test]
1115    fn jbig2_stencil_renders_like_its_flate_and_ccitt_twins() {
1116        let (w, h, bits) = jbig2_reference("generic_mmr.png");
1117        let content = "q 0 0 0 rg 326 0 0 218 57 -19 cm /Im0 Do Q";
1118        let mask = |filter: Dictionary, data: Vec<u8>| {
1119            let mut d = dictionary! {
1120                "Type" => "XObject", "Subtype" => "Image",
1121                "Width" => w as i64, "Height" => h as i64,
1122                "ImageMask" => true,
1123            };
1124            for (k, v) in filter.into_iter() {
1125                d.set(k, v);
1126            }
1127            Stream::new(d, data)
1128        };
1129        let flate = page_with_image(mask(Dictionary::new(), bits.clone()), content);
1130        let jbig2 = page_with_image(
1131            mask(
1132                dictionary! { "Filter" => "JBIG2Decode" },
1133                jbig2_fixture("generic_mmr.jbig2"),
1134            ),
1135            content,
1136        );
1137        let ccitt = page_with_image(
1138            mask(
1139                dictionary! {
1140                    "Filter" => "CCITTFaxDecode",
1141                    "DecodeParms" => dictionary! { "K" => -1, "Columns" => w as i64, "Rows" => h as i64 },
1142                },
1143                jbig2_fixture("generic_mmr.g4"),
1144            ),
1145            content,
1146        );
1147        let share = non_white_share(&flate);
1148        assert!(share > 0.05 && share < 0.95, "control share {share}");
1149        assert_eq!(jbig2.as_raw(), flate.as_raw(), "JBIG2 stencil vs Flate");
1150        assert_eq!(ccitt.as_raw(), flate.as_raw(), "CCITT stencil vs Flate");
1151    }
1152
1153    /// A 1-bit `DeviceGray` JBIG2 image (not a stencil) and one whose
1154    /// symbol dictionary sits in `/JBIG2Globals` both draw their pixels,
1155    /// pixel-identical to the Flate image of the reference bitmap.
1156    #[test]
1157    fn jbig2_gray_image_and_globals_render_their_pixels() {
1158        let content = "q 326 0 0 218 57 -19 cm /Im0 Do Q";
1159        let gray = |w: usize, h: usize, extra: Dictionary, data: Vec<u8>| {
1160            let mut d = dictionary! {
1161                "Type" => "XObject", "Subtype" => "Image",
1162                "Width" => w as i64, "Height" => h as i64,
1163                "ColorSpace" => "DeviceGray", "BitsPerComponent" => 1,
1164            };
1165            for (k, v) in extra.into_iter() {
1166                d.set(k, v);
1167            }
1168            Stream::new(d, data)
1169        };
1170        let (w, h, bits) = jbig2_reference("generic_mmr.png");
1171        let flate = page_with_image(gray(w, h, Dictionary::new(), bits), content);
1172        let jbig2 = page_with_image(
1173            gray(
1174                w,
1175                h,
1176                dictionary! { "Filter" => "JBIG2Decode" },
1177                jbig2_fixture("generic_mmr.jbig2"),
1178            ),
1179            content,
1180        );
1181        assert!(non_white_share(&flate) > 0.05);
1182        assert_eq!(jbig2.as_raw(), flate.as_raw(), "JBIG2 gray vs Flate");
1183
1184        // The text region's symbols come from the globals stream.
1185        let (w, h, bits) = jbig2_reference("symbol_global.png");
1186        let flate = page_with_image(gray(w, h, Dictionary::new(), bits), content);
1187        let mut doc = Document::with_version("1.5");
1188        let globals = doc.add_object(Stream::new(
1189            Dictionary::new(),
1190            jbig2_fixture("symbol_global.globals.jbig2"),
1191        ));
1192        let im = doc.add_object(gray(
1193            w,
1194            h,
1195            dictionary! {
1196                "Filter" => "JBIG2Decode",
1197                "DecodeParms" => dictionary! { "JBIG2Globals" => Object::Reference(globals) },
1198            },
1199            jbig2_fixture("symbol_global.jbig2"),
1200        ));
1201        let bytes = synth(
1202            &mut doc,
1203            [0.0, 0.0, 440.0, 180.0],
1204            Dictionary::new(),
1205            dictionary! { "XObject" => dictionary! { "Im0" => Object::Reference(im) } },
1206            content,
1207        );
1208        let with_globals = render(&bytes);
1209        assert!(non_white_share(&flate) > 0.02);
1210        assert_eq!(
1211            with_globals.as_raw(),
1212            flate.as_raw(),
1213            "JBIG2 + globals vs Flate"
1214        );
1215    }
1216
1217    /// A JBIG2 stream no decoder can read draws the documented mid-gray
1218    /// placeholder — for a stencil too (#811: a stencil used to draw
1219    /// nothing, so the page gave no sign that an image was missing).
1220    #[test]
1221    fn undecodable_jbig2_draws_the_placeholder_even_as_a_stencil() {
1222        let content = "q 0 0 0 rg 200 0 0 100 120 40 cm /Im0 Do Q";
1223        for is_mask in [true, false] {
1224            let mut d = dictionary! {
1225                "Type" => "XObject", "Subtype" => "Image",
1226                "Width" => 20, "Height" => 10, "Filter" => "JBIG2Decode",
1227            };
1228            if is_mask {
1229                d.set("ImageMask", true);
1230            } else {
1231                d.set("ColorSpace", "DeviceGray");
1232                d.set("BitsPerComponent", 1);
1233            }
1234            let img = page_with_image(Stream::new(d, b"not a JBIG2 stream".to_vec()), content);
1235            let inside = px(&img, 220, 90);
1236            assert!(
1237                near(inside, [128, 128, 128], 2),
1238                "mask {is_mask}: inside the image {inside:?}"
1239            );
1240            assert_eq!(
1241                px(&img, 50, 90),
1242                WHITE,
1243                "mask {is_mask}: outside stays white"
1244            );
1245        }
1246    }
1247}