Skip to main content

docling_pdf/
embedded.rs

1//! Embedded images as picture images (#1007, docling#5143's
2//! `use_embedded_picture_images`): when a picture region holds exactly one
3//! image XObject and nothing else draws over it, the picture's image is that
4//! bitmap at its native resolution instead of a crop of the page render.
5//!
6//! [`page_images`] walks a page's content stream once — the CTM, the clip,
7//! ExtGState transparency, paths, shadings, forms, image XObjects and inline
8//! images; text is left to the page's text cells — and lists every image
9//! placement in top-left page points, with the decoded pixels attached only
10//! to the ones that are *safe* to hand out as they are:
11//!
12//! * nothing is painted after the image over its area (a later path,
13//!   shading, image or Widget appearance would change what the page shows);
14//! * it is opaque and composited plainly — no `/SMask`, `/Mask`,
15//!   `/ImageMask`, `/SMaskInData`, no ExtGState soft mask, constant alpha
16//!   below 1 or blend mode;
17//! * it is drawn upright (an axis-aligned CTM, neither mirrored nor
18//!   rotated: the bitmap's rows are the picture's rows) and not cut by the
19//!   clip;
20//! * it decodes (no placeholder block).
21//!
22//! [`match_region`] then applies docling's matching rule: the region and one
23//! image's box must each cover ≥ 0.8 of the other (mutual
24//! intersection-over-self), no second image may overlap it, and no text
25//! cell may either. Anything uncertain returns `None` and the caller keeps
26//! the rendered crop — the fallback is always the picture docling's default
27//! produces. Upstream checks text and vector content painted *anywhere* over
28//! the image; the walk here only rejects content painted *after* it (an
29//! opaque image hides whatever lies beneath), so a page background or a
30//! frame drawn first no longer forces the crop — a deliberate, documented
31//! widening (`docs/MIGRATION.md`).
32//!
33//! Pages with `/Rotate` yield no placements (the bitmap would have to be
34//! turned with the page): their pictures stay render crops.
35
36use image::RgbImage;
37use lopdf::{Dictionary, Document, Object};
38
39use crate::pdf_meta::PdfMeta;
40use crate::pdfium_backend::TextCell;
41use crate::render::geom::{Box2, Mat};
42use crate::render::objects::{
43    as_dict, as_stream, get, get_bool2, get_int, get_name, name, num, nums, resource,
44};
45
46/// docling's `overlap_threshold`: the region and the image must each cover
47/// this share of the other.
48const OVERLAP: f32 = 0.8;
49/// The share of an image's box the clip must leave visible for the bitmap
50/// to still be what the page shows (anti-aliased clip edges, rounding).
51const CLIP_KEEP: f64 = 0.99;
52const MAX_OPS: usize = 2_000_000;
53const MAX_DEPTH: usize = 12;
54/// Decoded pixels kept per page (≈ 256 MiB of RGB): a page of scans past it
55/// keeps its crops.
56const MAX_PIXELS: u64 = 90_000_000;
57
58/// One image placement on a page.
59#[derive(Clone)]
60pub struct EmbeddedImage {
61    /// `[l, t, r, b]` in top-left page points (the frame regions and text
62    /// cells use).
63    pub bbox: [f32; 4],
64    /// The bitmap at native resolution when the placement is safe to hand
65    /// out as the picture (see the module docs); `None` otherwise — the
66    /// placement still counts for the "exactly one image" and "no other
67    /// image overlaps" rules.
68    pub image: Option<RgbImage>,
69}
70
71impl std::fmt::Debug for EmbeddedImage {
72    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
73        f.debug_struct("EmbeddedImage")
74            .field("bbox", &self.bbox)
75            .field("image", &self.image.as_ref().map(|i| i.dimensions()))
76            .finish()
77    }
78}
79
80#[derive(Clone)]
81struct State {
82    ctm: Mat,
83    /// The clip's bounding box in page space.
84    clip: Box2,
85    /// The clip is not exactly [`Self::clip`] (a non-rectangular path, a
86    /// rotated rectangle, text clipping).
87    clip_complex: bool,
88    /// An ExtGState soft mask, constant fill alpha below 1 or a blend mode.
89    tainted: bool,
90    text_clip: bool,
91}
92
93enum Paint {
94    /// An image placement: its page box, and the stream + resources to
95    /// decode it from when it is safe.
96    Image {
97        bbox: Box2,
98        decodable: Option<(lopdf::Stream, Option<Dictionary>)>,
99    },
100    /// Anything else that puts ink on the page (clipped to the clip box).
101    Mark(Box2),
102}
103
104struct Walk<'a> {
105    doc: &'a Document,
106    ops: usize,
107    paints: Vec<Paint>,
108}
109
110/// Every image placement of page `index` (0-based), the safe ones decoded.
111/// Empty for a rotated page or one lopdf cannot read.
112pub fn page_images(meta: &PdfMeta, index: usize) -> Vec<EmbeddedImage> {
113    let Some(geom) = meta.geometry(index) else {
114        return Vec::new();
115    };
116    if geom.rotation != 0 {
117        return Vec::new();
118    }
119    let doc = meta.doc();
120    let Some(pid) = meta.page_id(index) else {
121        return Vec::new();
122    };
123    let pb = crate::textparse::page_box(doc, pid);
124    let (l, b, w, h) = (
125        f64::from(pb.l),
126        f64::from(pb.b),
127        f64::from(pb.w),
128        f64::from(pb.h),
129    );
130    // user (x, y) → top-left page points (x − l, h − (y − b)).
131    let base = Mat::new(1.0, 0.0, 0.0, -1.0, -l, h + b);
132    let page_box = Box2::new(0.0, 0.0, w, h);
133    let resources = page_resources(doc, pid).cloned();
134    let content = doc.get_page_content(pid);
135    let mut walk = Walk {
136        doc,
137        ops: 0,
138        paints: Vec::new(),
139    };
140    let st = State {
141        ctm: base,
142        clip: page_box,
143        clip_complex: false,
144        tainted: false,
145        text_clip: false,
146    };
147    walk.run(&content, resources.as_ref(), st, 0);
148    if let Ok(page) = doc.get_dictionary(pid) {
149        walk.widgets(page, base);
150    }
151    walk.finish()
152}
153
154/// The placement `region` (`[l, t, r, b]`, top-left page points) is a
155/// picture of, by docling's rule — `None` unless exactly one image matches
156/// it, that image is safe, and no other image or text cell overlaps it.
157pub fn match_region<'a>(
158    images: &'a [EmbeddedImage],
159    cells: &[TextCell],
160    region: [f32; 4],
161) -> Option<&'a RgbImage> {
162    let mut found = None;
163    for (i, im) in images.iter().enumerate() {
164        if ios(region, im.bbox) >= OVERLAP && ios(im.bbox, region) >= OVERLAP {
165            if found.is_some() {
166                return None;
167            }
168            found = Some(i);
169        }
170    }
171    let i = found?;
172    let cand = &images[i];
173    let image = cand.image.as_ref()?;
174    let overlaps_other = images
175        .iter()
176        .enumerate()
177        .any(|(j, o)| j != i && overlap(cand.bbox, o.bbox) > 0.0);
178    let overlaps_text = cells
179        .iter()
180        .filter(|c| !c.text.trim().is_empty())
181        .any(|c| overlap(cand.bbox, [c.l, c.t, c.r, c.b]) > 0.0);
182    (!overlaps_other && !overlaps_text).then_some(image)
183}
184
185fn overlap(a: [f32; 4], b: [f32; 4]) -> f32 {
186    let w = a[2].min(b[2]) - a[0].max(b[0]);
187    let h = a[3].min(b[3]) - a[1].max(b[1]);
188    if w > 0.0 && h > 0.0 {
189        w * h
190    } else {
191        0.0
192    }
193}
194
195/// docling's `intersection_over_self`: the share of `a` that `b` covers.
196fn ios(a: [f32; 4], b: [f32; 4]) -> f32 {
197    let area = (a[2] - a[0]).max(0.0) * (a[3] - a[1]).max(0.0);
198    if area <= 0.0 {
199        0.0
200    } else {
201        overlap(a, b) / area
202    }
203}
204
205fn page_resources(doc: &Document, pid: lopdf::ObjectId) -> Option<&Dictionary> {
206    crate::textparse::page_res(doc, pid)
207}
208
209fn boxes_overlap(a: Box2, b: Box2) -> bool {
210    !a.intersect(b).is_empty()
211}
212
213fn area(b: Box2) -> f64 {
214    b.width() * b.height()
215}
216
217/// An axis-aligned transform (no rotation or shear).
218fn axis_aligned(m: Mat) -> bool {
219    let s = m.max_scale().max(1e-9);
220    m.b.abs() <= 1e-6 * s && m.c.abs() <= 1e-6 * s
221}
222
223impl Walk<'_> {
224    fn finish(self) -> Vec<EmbeddedImage> {
225        let mut out = Vec::new();
226        let mut pixels = 0u64;
227        for (i, p) in self.paints.iter().enumerate() {
228            let Paint::Image { bbox, decodable } = p else {
229                continue;
230            };
231            let painted_over = self.paints[i + 1..].iter().any(|q| match q {
232                Paint::Image { bbox: o, .. } | Paint::Mark(o) => boxes_overlap(*bbox, *o),
233            });
234            let image = match decodable {
235                Some((stream, res)) if !painted_over => {
236                    decode(self.doc, stream, res.as_ref(), &mut pixels)
237                }
238                _ => None,
239            };
240            out.push(EmbeddedImage {
241                bbox: [
242                    bbox.x0 as f32,
243                    bbox.y0 as f32,
244                    bbox.x1 as f32,
245                    bbox.y1 as f32,
246                ],
247                image,
248            });
249        }
250        out
251    }
252
253    fn mark(&mut self, st: &State, b: Box2) {
254        let b = b.intersect(st.clip);
255        if !b.is_empty() {
256            self.paints.push(Paint::Mark(b));
257        }
258    }
259
260    fn run(&mut self, content: &[u8], res: Option<&Dictionary>, init: State, depth: usize) {
261        if depth > MAX_DEPTH {
262            return;
263        }
264        let doc = self.doc;
265        let prepared = crate::render::prepass::prepare(content, doc, res);
266        let Ok(ops) = lopdf::content::Content::decode(&prepared.content) else {
267            return;
268        };
269        let mut stack: Vec<State> = Vec::new();
270        let mut st = init;
271        // The current path's user-space points, and whether it is one `re`.
272        let mut pts: Vec<(f64, f64)> = Vec::new();
273        let mut rects = 0usize;
274        let mut other_segments = false;
275        let mut pending_clip = false;
276        let mut line_width = 1.0f64;
277        let mut render_mode = 0i64;
278        for op in &ops.operations {
279            self.ops += 1;
280            if self.ops > MAX_OPS {
281                return;
282            }
283            let args = &op.operands;
284            let n = |i: usize| args.get(i).and_then(num).unwrap_or(0.0);
285            match op.operator.as_str() {
286                "q" => {
287                    stack.push(st.clone());
288                    if stack.len() > 64 {
289                        stack.remove(0);
290                    }
291                }
292                "Q" => {
293                    if let Some(s) = stack.pop() {
294                        st = s;
295                    }
296                }
297                "cm" if args.len() >= 6 => {
298                    let v: Vec<f64> = (0..6).map(n).collect();
299                    if let Some(m) = Mat::from_slice(&v) {
300                        st.ctm = m.then(st.ctm);
301                    }
302                }
303                "w" => line_width = n(0).abs(),
304                "gs" => {
305                    if let Some(gs) = args
306                        .first()
307                        .and_then(name)
308                        .and_then(|nm| resource(doc, res, b"ExtGState", nm))
309                        .and_then(|o| as_dict(doc, o))
310                    {
311                        if let Some(lw) = get(doc, gs, b"LW").and_then(num) {
312                            line_width = lw.abs();
313                        }
314                        let smask = get(doc, gs, b"SMask")
315                            .is_some_and(|o| !matches!(o, Object::Name(n) if n == b"None"));
316                        let alpha = get(doc, gs, b"ca").and_then(num).is_some_and(|a| a < 1.0);
317                        let blend = get(doc, gs, b"BM").is_some_and(|o| {
318                            let nm = match o {
319                                Object::Name(n) => Some(n.as_slice()),
320                                Object::Array(a) => a.first().and_then(name),
321                                _ => None,
322                            };
323                            !matches!(nm, Some(b"Normal" | b"Compatible"))
324                        });
325                        if smask || alpha || blend {
326                            st.tainted = true;
327                        }
328                    }
329                }
330                "m" | "l" if args.len() >= 2 => {
331                    pts.push((n(0), n(1)));
332                    other_segments = true;
333                }
334                "c" if args.len() >= 6 => {
335                    pts.extend([(n(0), n(1)), (n(2), n(3)), (n(4), n(5))]);
336                    other_segments = true;
337                }
338                "v" | "y" if args.len() >= 4 => {
339                    pts.extend([(n(0), n(1)), (n(2), n(3))]);
340                    other_segments = true;
341                }
342                "re" if args.len() >= 4 => {
343                    let (x, y, w, h) = (n(0), n(1), n(2), n(3));
344                    pts.extend([(x, y), (x + w, y + h)]);
345                    rects += 1;
346                }
347                "h" => {}
348                "W" | "W*" => pending_clip = true,
349                "S" | "s" | "f" | "F" | "f*" | "B" | "B*" | "b" | "b*" | "n" => {
350                    let bbox = path_box(&pts, st.ctm);
351                    if op.operator != "n" {
352                        if let Some(b) = bbox {
353                            let stroked =
354                                matches!(op.operator.as_str(), "S" | "s" | "B" | "B*" | "b" | "b*");
355                            // A stroke reaches half its width past the path
356                            // (and at least a hairline's pixel).
357                            let pad = if stroked {
358                                (line_width * st.ctm.max_scale() / 2.0).max(0.5)
359                            } else {
360                                0.0
361                            };
362                            let b = Box2::new(b.x0 - pad, b.y0 - pad, b.x1 + pad, b.y1 + pad);
363                            self.mark(&st, b);
364                        }
365                    }
366                    if pending_clip {
367                        match bbox {
368                            Some(b) => {
369                                st.clip = st.clip.intersect(b);
370                                if other_segments || rects != 1 || !axis_aligned(st.ctm) {
371                                    st.clip_complex = true;
372                                }
373                            }
374                            None => st.clip = Box2::new(0.0, 0.0, 0.0, 0.0),
375                        }
376                    }
377                    pts.clear();
378                    rects = 0;
379                    other_segments = false;
380                    pending_clip = false;
381                }
382                "Tr" => render_mode = n(0) as i64,
383                "Tj" | "TJ" | "'" | "\"" if render_mode >= 4 => {
384                    // Clipping text: what follows is cut to glyph shapes.
385                    st.text_clip = true;
386                }
387                "ET" if st.text_clip => {
388                    st.clip_complex = true;
389                    st.text_clip = false;
390                }
391                "Do" => {
392                    let Some(xobj) = args
393                        .first()
394                        .and_then(name)
395                        .and_then(|nm| resource(doc, res, b"XObject", nm))
396                    else {
397                        continue;
398                    };
399                    let Some(stream) = as_stream(doc, xobj) else {
400                        continue;
401                    };
402                    let is_image = match get_name(doc, &stream.dict, b"Subtype") {
403                        Some(b"Image") => true,
404                        Some(b"Form") => false,
405                        Some(b"PS") => continue,
406                        _ if stream.dict.has(b"BBox") => false,
407                        _ if stream.dict.has(b"Width") => true,
408                        _ => continue,
409                    };
410                    if is_image {
411                        self.image(stream, res, &st);
412                    } else {
413                        self.form(stream, res, &st, depth + 1);
414                    }
415                }
416                "BIX" => {
417                    if let Some(s) = args
418                        .first()
419                        .and_then(crate::render::prepass::inline_index)
420                        .and_then(|i| prepared.inline.get(i))
421                    {
422                        let s = s.clone();
423                        self.image(&s, res, &st);
424                    }
425                }
426                // A shading fills the whole clip.
427                "sh" => {
428                    let clip = st.clip;
429                    self.mark(&st, clip);
430                }
431                _ => {}
432            }
433        }
434    }
435
436    fn image(&mut self, stream: &lopdf::Stream, res: Option<&Dictionary>, st: &State) {
437        let doc = self.doc;
438        let (x0, y0, x1, y1) = st.ctm.unit_bbox();
439        let bbox = Box2::new(x0, y0, x1, y1);
440        if bbox.intersect(st.clip).is_empty() {
441            return;
442        }
443        let d = &stream.dict;
444        let m = st.ctm;
445        // Upright in the top-left frame: x grows right, the bitmap's first
446        // row (unit-square y = 1) is on top.
447        let upright = axis_aligned(m) && m.a > 0.0 && m.d < 0.0;
448        let plain = !st.tainted
449            && !get_bool2(doc, d, b"ImageMask", b"IM").unwrap_or(false)
450            && !d.has(b"SMask")
451            && !d.has(b"Mask")
452            && get_int(doc, d, b"SMaskInData").unwrap_or(0) == 0;
453        let unclipped = !st.clip_complex && area(bbox.intersect(st.clip)) >= CLIP_KEEP * area(bbox);
454        let decodable = (upright && plain && unclipped).then(|| (stream.clone(), res.cloned()));
455        self.paints.push(Paint::Image { bbox, decodable });
456    }
457
458    fn form(&mut self, stream: &lopdf::Stream, res: Option<&Dictionary>, st: &State, depth: usize) {
459        let doc = self.doc;
460        let matrix = get(doc, &stream.dict, b"Matrix")
461            .and_then(|o| nums(doc, o))
462            .and_then(|v| Mat::from_slice(&v))
463            .unwrap_or(Mat::IDENTITY);
464        let mut inner = st.clone();
465        inner.ctm = matrix.then(st.ctm);
466        if let Some(b) = get(doc, &stream.dict, b"BBox")
467            .and_then(|o| nums(doc, o))
468            .filter(|b| b.len() == 4)
469        {
470            let clip = Box2::new(b[0], b[1], b[2], b[3]).transformed(inner.ctm);
471            inner.clip = inner.clip.intersect(clip);
472            if !axis_aligned(inner.ctm) {
473                inner.clip_complex = true;
474            }
475        }
476        let own = get(doc, &stream.dict, b"Resources")
477            .and_then(|o| as_dict(doc, o))
478            .cloned();
479        let Ok(content) = stream.decompressed_content() else {
480            // Undecodable form content: assume it inks its whole box.
481            let clip = inner.clip;
482            self.mark(&inner, clip);
483            return;
484        };
485        let res = own.as_ref().or(res);
486        self.run(&content, res, inner, depth);
487    }
488
489    /// The Widget annotations the renderer draws over the page: their
490    /// rectangles count as paint.
491    fn widgets(&mut self, page: &Dictionary, base: Mat) {
492        let doc = self.doc;
493        let Some(Object::Array(annots)) = get(doc, page, b"Annots") else {
494            return;
495        };
496        let st = State {
497            ctm: base,
498            clip: Box2::new(f64::MIN, f64::MIN, f64::MAX, f64::MAX),
499            clip_complex: false,
500            tainted: false,
501            text_clip: false,
502        };
503        for a in annots {
504            let Some(ad) = as_dict(doc, a) else { continue };
505            if get_name(doc, ad, b"Subtype") != Some(b"Widget") || !ad.has(b"AP") {
506                continue;
507            }
508            if let Some(r) = get(doc, ad, b"Rect")
509                .and_then(|o| nums(doc, o))
510                .filter(|r| r.len() == 4)
511            {
512                self.mark(&st, Box2::new(r[0], r[1], r[2], r[3]).transformed(base));
513            }
514        }
515    }
516}
517
518fn path_box(pts: &[(f64, f64)], ctm: Mat) -> Option<Box2> {
519    let mut it = pts.iter().map(|&(x, y)| ctm.apply(x, y));
520    let (x, y) = it.next()?;
521    let mut b = Box2::new(x, y, x, y);
522    for (x, y) in it {
523        b.x0 = b.x0.min(x);
524        b.y0 = b.y0.min(y);
525        b.x1 = b.x1.max(x);
526        b.y1 = b.y1.max(y);
527    }
528    Some(b)
529}
530
531/// The image's samples as an RGB bitmap at native size; `None` when it does
532/// not decode, comes out a placeholder, or the page's pixel budget is spent.
533fn decode(
534    doc: &Document,
535    stream: &lopdf::Stream,
536    res: Option<&Dictionary>,
537    pixels: &mut u64,
538) -> Option<RgbImage> {
539    let (w, h) = crate::render::image::declared_size(doc, &stream.dict)?;
540    let n = (w.max(0) as u64).saturating_mul(h.max(0) as u64);
541    if *pixels + n > MAX_PIXELS {
542        return None;
543    }
544    let loaded = crate::render::image::load(doc, stream, res, 0).ok()?;
545    if loaded.placeholder_reason().is_some() {
546        return None;
547    }
548    let mut cmyk = crate::render::color::CmykCache::default();
549    let dec = crate::render::image::rasterize(&loaded, [0, 0, 0], None, &mut cmyk).ok()?;
550    let pm = &dec.pixmap;
551    *pixels += u64::from(pm.width()) * u64::from(pm.height());
552    let data = pm.data();
553    let mut out = RgbImage::new(pm.width(), pm.height());
554    for (i, px) in out.pixels_mut().enumerate() {
555        let p = &data[i * 4..i * 4 + 4];
556        if p[3] != 255 {
557            // Not opaque after all (a colour key the dictionary did not
558            // announce): the render is what the page shows.
559            return None;
560        }
561        *px = image::Rgb([p[0], p[1], p[2]]);
562    }
563    Some(out)
564}
565
566#[cfg(test)]
567mod tests {
568    use super::*;
569    use lopdf::{dictionary, Stream};
570
571    fn root() -> std::path::PathBuf {
572        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../..")
573    }
574
575    /// Page 1 of `bytes` through the real page walk with the option on: its
576    /// text cells and image placements.
577    fn walk_first_page(bytes: &[u8]) -> crate::pdfium_backend::PdfPage {
578        let mut out = None;
579        crate::pdfium_backend::walk_pages::<crate::PdfError, _>(
580            bytes,
581            None,
582            false,
583            true,
584            Some((0, 0)),
585            crate::pdfium_backend::BitmapRender::OnDemand,
586            crate::pdfium_backend::TextOptions {
587                embedded_pictures: true,
588                ..Default::default()
589            },
590            |_, _, page| {
591                out = Some(page);
592                Ok(())
593            },
594        )
595        .unwrap();
596        out.expect("one page")
597    }
598
599    fn fixture(name: &str) -> crate::pdfium_backend::PdfPage {
600        let bytes = std::fs::read(root().join("tests/data/pdf/sources").join(name)).unwrap();
601        walk_first_page(&bytes)
602    }
603
604    /// docling's `test_extract_single_embedded_image`: the one bitmap of
605    /// `picture_classification.pdf` page 1 comes out at its native 768 × 474.
606    #[test]
607    fn extracts_the_single_embedded_image() {
608        let page = fixture("picture_classification.pdf");
609        assert_eq!(page.embedded_images.len(), 1, "{:?}", page.embedded_images);
610        let bbox = page.embedded_images[0].bbox;
611        let img = match_region(&page.embedded_images, &page.cells, bbox).expect("safe image");
612        assert_eq!(img.dimensions(), (768, 474));
613        // A layout box a little off the image still matches (≥ 0.8 both ways)…
614        let loose = [bbox[0] - 8.0, bbox[1] - 8.0, bbox[2] + 4.0, bbox[3] + 4.0];
615        assert!(match_region(&page.embedded_images, &page.cells, loose).is_some());
616        // …one twice the image's size does not.
617        let h = bbox[3] - bbox[1];
618        let big = [bbox[0], bbox[1] - h, bbox[2], bbox[3]];
619        assert!(match_region(&page.embedded_images, &page.cells, big).is_none());
620    }
621
622    /// docling's `test_reject_embedded_image_with_overlapping_page_content`:
623    /// `amt_handbook_sample.pdf`'s first bitmap shares its box with others.
624    #[test]
625    fn rejects_an_image_with_overlapping_page_content() {
626        let page = fixture("amt_handbook_sample.pdf");
627        let first = page.embedded_images.first().expect("bitmaps").bbox;
628        assert!(match_region(&page.embedded_images, &page.cells, first).is_none());
629    }
630
631    /// The walk lists nothing unless asked (the option is off by default).
632    #[test]
633    fn walk_collects_nothing_by_default() {
634        let bytes = std::fs::read(root().join("tests/data/pdf/sources/picture_classification.pdf"))
635            .unwrap();
636        let mut n = None;
637        crate::pdfium_backend::walk_pages::<crate::PdfError, _>(
638            &bytes,
639            None,
640            false,
641            true,
642            Some((0, 0)),
643            crate::pdfium_backend::BitmapRender::OnDemand,
644            crate::pdfium_backend::TextOptions::default(),
645            |_, _, page| {
646                n = Some(page.embedded_images.len());
647                Ok(())
648            },
649        )
650        .unwrap();
651        assert_eq!(n, Some(0));
652    }
653
654    /// A 400 × 300 pt page drawing a 4 × 2 RGB image XObject (`/Im0`, plus
655    /// `/Im1`, and `extra` merged into `/Im0`'s dictionary) with `content`.
656    fn synth(content: &str, extra: lopdf::Dictionary, gs: lopdf::Dictionary) -> Vec<u8> {
657        let mut doc = lopdf::Document::with_version("1.5");
658        let image = |extra: lopdf::Dictionary| {
659            let mut d = dictionary! {
660                "Type" => "XObject", "Subtype" => "Image",
661                "Width" => 4, "Height" => 2,
662                "ColorSpace" => "DeviceRGB", "BitsPerComponent" => 8,
663            };
664            for (k, v) in extra.into_iter() {
665                d.set(k, v);
666            }
667            let px: Vec<u8> = (0..8u8).flat_map(|i| [i * 30, 255 - i * 30, 100]).collect();
668            Stream::new(d, px)
669        };
670        let im0 = doc.add_object(image(extra));
671        let im1 = doc.add_object(image(lopdf::Dictionary::new()));
672        let pages_id = doc.new_object_id();
673        let content_id = doc.add_object(Stream::new(dictionary! {}, content.as_bytes().to_vec()));
674        let res = dictionary! {
675            "XObject" => dictionary! {
676                "Im0" => Object::Reference(im0),
677                "Im1" => Object::Reference(im1),
678            },
679            "ExtGState" => dictionary! { "G0" => gs },
680        };
681        let page_id = doc.add_object(dictionary! {
682            "Type" => "Page",
683            "Parent" => Object::Reference(pages_id),
684            "MediaBox" => vec![0.into(), 0.into(), 400.into(), 300.into()],
685            "Contents" => Object::Reference(content_id),
686            "Resources" => res,
687        });
688        doc.objects.insert(
689            pages_id,
690            Object::Dictionary(dictionary! {
691                "Type" => "Pages", "Kids" => vec![Object::Reference(page_id)], "Count" => 1,
692            }),
693        );
694        let catalog = doc.add_object(dictionary! {
695            "Type" => "Catalog", "Pages" => Object::Reference(pages_id),
696        });
697        doc.trailer.set("Root", Object::Reference(catalog));
698        let mut out = Vec::new();
699        doc.save_to(&mut out).unwrap();
700        out
701    }
702
703    /// The image `content` places at 100 × 50 pt from (50, 150) (top-left
704    /// frame: x 50–150, y 100–150), as `match_region` hands it out.
705    fn matched(content: &str, extra: lopdf::Dictionary, gs: lopdf::Dictionary) -> Option<RgbImage> {
706        let page = walk_first_page(&synth(content, extra, gs));
707        match_region(
708            &page.embedded_images,
709            &page.cells,
710            [50.0, 100.0, 150.0, 150.0],
711        )
712        .cloned()
713    }
714
715    const DRAW: &str = "q 100 0 0 50 50 150 cm /Im0 Do Q";
716
717    fn none() -> lopdf::Dictionary {
718        lopdf::Dictionary::new()
719    }
720
721    #[test]
722    fn a_plain_image_comes_out_at_native_size_with_its_pixels() {
723        let img = matched(DRAW, none(), none()).expect("matched");
724        assert_eq!(img.dimensions(), (4, 2));
725        assert_eq!(img.get_pixel(0, 0).0, [0, 255, 100]);
726        assert_eq!(img.get_pixel(3, 1).0, [210, 45, 100]);
727    }
728
729    #[test]
730    fn content_painted_beneath_does_not_matter_but_over_it_does() {
731        let under = format!("1 0 0 rg 0 0 400 300 re f {DRAW}");
732        assert!(matched(&under, none(), none()).is_some());
733        let over = format!("{DRAW} 0 0 1 rg 60 160 10 10 re f");
734        assert!(matched(&over, none(), none()).is_none());
735        let stroke = format!("{DRAW} 0 0 m 400 300 l S");
736        assert!(matched(&stroke, none(), none()).is_none());
737        // Ink painted after, but elsewhere on the page, is fine.
738        let beside = format!("{DRAW} 300 10 20 20 re f");
739        assert!(matched(&beside, none(), none()).is_some());
740        // A clip-only path paints nothing.
741        let clip = format!("q 0 0 400 300 re W n {DRAW} Q");
742        assert!(matched(&clip, none(), none()).is_some());
743    }
744
745    #[test]
746    fn a_second_overlapping_image_makes_the_match_ambiguous() {
747        let two = format!("{DRAW} q 20 0 0 20 140 140 cm /Im1 Do Q");
748        assert!(matched(&two, none(), none()).is_none());
749        // Drawn first, beneath ours: still a second image in the box.
750        let first = format!("q 20 0 0 20 140 140 cm /Im1 Do Q {DRAW}");
751        assert!(matched(&first, none(), none()).is_none());
752    }
753
754    #[test]
755    fn rotated_mirrored_or_clipped_placements_keep_the_crop() {
756        // Mirrored horizontally (same box).
757        assert!(matched("q -100 0 0 50 150 150 cm /Im0 Do Q", none(), none()).is_none());
758        // Upside down.
759        assert!(matched("q 100 0 0 -50 50 200 cm /Im0 Do Q", none(), none()).is_none());
760        // Cut by a rectangle clip.
761        let cut = format!("q 50 150 60 50 re W n {DRAW} Q");
762        assert!(matched(&cut, none(), none()).is_none());
763        // A non-rectangular clip.
764        let tri = format!("q 0 0 m 400 0 l 0 300 l h W n {DRAW} Q");
765        assert!(matched(&tri, none(), none()).is_none());
766    }
767
768    #[test]
769    fn masked_or_transparent_images_keep_the_crop() {
770        let mut smask = lopdf::Dictionary::new();
771        smask.set("SMask", Object::Reference((99, 0)));
772        assert!(matched(DRAW, smask, none()).is_none());
773        let alpha = dictionary! { "Type" => "ExtGState", "ca" => 0.5 };
774        let draw = format!("/G0 gs {DRAW}");
775        assert!(matched(&draw, none(), alpha).is_none());
776        let multiply = dictionary! { "Type" => "ExtGState", "BM" => "Multiply" };
777        assert!(matched(&draw, none(), multiply).is_none());
778        let normal = dictionary! { "Type" => "ExtGState", "BM" => "Normal", "ca" => 1 };
779        assert!(matched(&draw, none(), normal).is_some());
780    }
781
782    #[test]
783    fn a_rotated_page_lists_no_placements() {
784        let bytes = synth(DRAW, none(), none());
785        let mut doc = lopdf::Document::load_mem(&bytes).unwrap();
786        let pid = *doc.get_pages().values().next().unwrap();
787        doc.get_dictionary_mut(pid).unwrap().set("Rotate", 90);
788        let mut out = Vec::new();
789        doc.save_to(&mut out).unwrap();
790        assert!(walk_first_page(&out).embedded_images.is_empty());
791    }
792
793    #[test]
794    fn text_over_the_image_keeps_the_crop() {
795        let im = EmbeddedImage {
796            bbox: [50.0, 50.0, 150.0, 100.0],
797            image: Some(RgbImage::new(4, 2)),
798        };
799        let cell = |text: &str| TextCell {
800            text: text.into(),
801            l: 60.0,
802            t: 60.0,
803            r: 90.0,
804            b: 70.0,
805        };
806        let region = [50.0, 50.0, 150.0, 100.0];
807        assert!(match_region(std::slice::from_ref(&im), &[cell("label")], region).is_none());
808        assert!(match_region(std::slice::from_ref(&im), &[cell("  ")], region).is_some());
809    }
810}