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    doc.get_page_resources(pid).ok().and_then(|(inline, ids)| {
207        inline.or_else(|| ids.into_iter().find_map(|id| doc.get_dictionary(id).ok()))
208    })
209}
210
211fn boxes_overlap(a: Box2, b: Box2) -> bool {
212    !a.intersect(b).is_empty()
213}
214
215fn area(b: Box2) -> f64 {
216    b.width() * b.height()
217}
218
219/// An axis-aligned transform (no rotation or shear).
220fn axis_aligned(m: Mat) -> bool {
221    let s = m.max_scale().max(1e-9);
222    m.b.abs() <= 1e-6 * s && m.c.abs() <= 1e-6 * s
223}
224
225impl Walk<'_> {
226    fn finish(self) -> Vec<EmbeddedImage> {
227        let mut out = Vec::new();
228        let mut pixels = 0u64;
229        for (i, p) in self.paints.iter().enumerate() {
230            let Paint::Image { bbox, decodable } = p else {
231                continue;
232            };
233            let painted_over = self.paints[i + 1..].iter().any(|q| match q {
234                Paint::Image { bbox: o, .. } | Paint::Mark(o) => boxes_overlap(*bbox, *o),
235            });
236            let image = match decodable {
237                Some((stream, res)) if !painted_over => {
238                    decode(self.doc, stream, res.as_ref(), &mut pixels)
239                }
240                _ => None,
241            };
242            out.push(EmbeddedImage {
243                bbox: [
244                    bbox.x0 as f32,
245                    bbox.y0 as f32,
246                    bbox.x1 as f32,
247                    bbox.y1 as f32,
248                ],
249                image,
250            });
251        }
252        out
253    }
254
255    fn mark(&mut self, st: &State, b: Box2) {
256        let b = b.intersect(st.clip);
257        if !b.is_empty() {
258            self.paints.push(Paint::Mark(b));
259        }
260    }
261
262    fn run(&mut self, content: &[u8], res: Option<&Dictionary>, init: State, depth: usize) {
263        if depth > MAX_DEPTH {
264            return;
265        }
266        let doc = self.doc;
267        let prepared = crate::render::prepass::prepare(content, doc, res);
268        let Ok(ops) = lopdf::content::Content::decode(&prepared.content) else {
269            return;
270        };
271        let mut stack: Vec<State> = Vec::new();
272        let mut st = init;
273        // The current path's user-space points, and whether it is one `re`.
274        let mut pts: Vec<(f64, f64)> = Vec::new();
275        let mut rects = 0usize;
276        let mut other_segments = false;
277        let mut pending_clip = false;
278        let mut line_width = 1.0f64;
279        let mut render_mode = 0i64;
280        for op in &ops.operations {
281            self.ops += 1;
282            if self.ops > MAX_OPS {
283                return;
284            }
285            let args = &op.operands;
286            let n = |i: usize| args.get(i).and_then(num).unwrap_or(0.0);
287            match op.operator.as_str() {
288                "q" => {
289                    stack.push(st.clone());
290                    if stack.len() > 64 {
291                        stack.remove(0);
292                    }
293                }
294                "Q" => {
295                    if let Some(s) = stack.pop() {
296                        st = s;
297                    }
298                }
299                "cm" if args.len() >= 6 => {
300                    let v: Vec<f64> = (0..6).map(n).collect();
301                    if let Some(m) = Mat::from_slice(&v) {
302                        st.ctm = m.then(st.ctm);
303                    }
304                }
305                "w" => line_width = n(0).abs(),
306                "gs" => {
307                    if let Some(gs) = args
308                        .first()
309                        .and_then(name)
310                        .and_then(|nm| resource(doc, res, b"ExtGState", nm))
311                        .and_then(|o| as_dict(doc, o))
312                    {
313                        if let Some(lw) = get(doc, gs, b"LW").and_then(num) {
314                            line_width = lw.abs();
315                        }
316                        let smask = get(doc, gs, b"SMask")
317                            .is_some_and(|o| !matches!(o, Object::Name(n) if n == b"None"));
318                        let alpha = get(doc, gs, b"ca").and_then(num).is_some_and(|a| a < 1.0);
319                        let blend = get(doc, gs, b"BM").is_some_and(|o| {
320                            let nm = match o {
321                                Object::Name(n) => Some(n.as_slice()),
322                                Object::Array(a) => a.first().and_then(name),
323                                _ => None,
324                            };
325                            !matches!(nm, Some(b"Normal" | b"Compatible"))
326                        });
327                        if smask || alpha || blend {
328                            st.tainted = true;
329                        }
330                    }
331                }
332                "m" | "l" if args.len() >= 2 => {
333                    pts.push((n(0), n(1)));
334                    other_segments = true;
335                }
336                "c" if args.len() >= 6 => {
337                    pts.extend([(n(0), n(1)), (n(2), n(3)), (n(4), n(5))]);
338                    other_segments = true;
339                }
340                "v" | "y" if args.len() >= 4 => {
341                    pts.extend([(n(0), n(1)), (n(2), n(3))]);
342                    other_segments = true;
343                }
344                "re" if args.len() >= 4 => {
345                    let (x, y, w, h) = (n(0), n(1), n(2), n(3));
346                    pts.extend([(x, y), (x + w, y + h)]);
347                    rects += 1;
348                }
349                "h" => {}
350                "W" | "W*" => pending_clip = true,
351                "S" | "s" | "f" | "F" | "f*" | "B" | "B*" | "b" | "b*" | "n" => {
352                    let bbox = path_box(&pts, st.ctm);
353                    if op.operator != "n" {
354                        if let Some(b) = bbox {
355                            let stroked =
356                                matches!(op.operator.as_str(), "S" | "s" | "B" | "B*" | "b" | "b*");
357                            // A stroke reaches half its width past the path
358                            // (and at least a hairline's pixel).
359                            let pad = if stroked {
360                                (line_width * st.ctm.max_scale() / 2.0).max(0.5)
361                            } else {
362                                0.0
363                            };
364                            let b = Box2::new(b.x0 - pad, b.y0 - pad, b.x1 + pad, b.y1 + pad);
365                            self.mark(&st, b);
366                        }
367                    }
368                    if pending_clip {
369                        match bbox {
370                            Some(b) => {
371                                st.clip = st.clip.intersect(b);
372                                if other_segments || rects != 1 || !axis_aligned(st.ctm) {
373                                    st.clip_complex = true;
374                                }
375                            }
376                            None => st.clip = Box2::new(0.0, 0.0, 0.0, 0.0),
377                        }
378                    }
379                    pts.clear();
380                    rects = 0;
381                    other_segments = false;
382                    pending_clip = false;
383                }
384                "Tr" => render_mode = n(0) as i64,
385                "Tj" | "TJ" | "'" | "\"" if render_mode >= 4 => {
386                    // Clipping text: what follows is cut to glyph shapes.
387                    st.text_clip = true;
388                }
389                "ET" if st.text_clip => {
390                    st.clip_complex = true;
391                    st.text_clip = false;
392                }
393                "Do" => {
394                    let Some(xobj) = args
395                        .first()
396                        .and_then(name)
397                        .and_then(|nm| resource(doc, res, b"XObject", nm))
398                    else {
399                        continue;
400                    };
401                    let Some(stream) = as_stream(doc, xobj) else {
402                        continue;
403                    };
404                    let is_image = match get_name(doc, &stream.dict, b"Subtype") {
405                        Some(b"Image") => true,
406                        Some(b"Form") => false,
407                        Some(b"PS") => continue,
408                        _ if stream.dict.has(b"BBox") => false,
409                        _ if stream.dict.has(b"Width") => true,
410                        _ => continue,
411                    };
412                    if is_image {
413                        self.image(stream, res, &st);
414                    } else {
415                        self.form(stream, res, &st, depth + 1);
416                    }
417                }
418                "BIX" => {
419                    if let Some(s) = args
420                        .first()
421                        .and_then(crate::render::prepass::inline_index)
422                        .and_then(|i| prepared.inline.get(i))
423                    {
424                        let s = s.clone();
425                        self.image(&s, res, &st);
426                    }
427                }
428                // A shading fills the whole clip.
429                "sh" => {
430                    let clip = st.clip;
431                    self.mark(&st, clip);
432                }
433                _ => {}
434            }
435        }
436    }
437
438    fn image(&mut self, stream: &lopdf::Stream, res: Option<&Dictionary>, st: &State) {
439        let doc = self.doc;
440        let (x0, y0, x1, y1) = st.ctm.unit_bbox();
441        let bbox = Box2::new(x0, y0, x1, y1);
442        if bbox.intersect(st.clip).is_empty() {
443            return;
444        }
445        let d = &stream.dict;
446        let m = st.ctm;
447        // Upright in the top-left frame: x grows right, the bitmap's first
448        // row (unit-square y = 1) is on top.
449        let upright = axis_aligned(m) && m.a > 0.0 && m.d < 0.0;
450        let plain = !st.tainted
451            && !get_bool2(doc, d, b"ImageMask", b"IM").unwrap_or(false)
452            && !d.has(b"SMask")
453            && !d.has(b"Mask")
454            && get_int(doc, d, b"SMaskInData").unwrap_or(0) == 0;
455        let unclipped = !st.clip_complex && area(bbox.intersect(st.clip)) >= CLIP_KEEP * area(bbox);
456        let decodable = (upright && plain && unclipped).then(|| (stream.clone(), res.cloned()));
457        self.paints.push(Paint::Image { bbox, decodable });
458    }
459
460    fn form(&mut self, stream: &lopdf::Stream, res: Option<&Dictionary>, st: &State, depth: usize) {
461        let doc = self.doc;
462        let matrix = get(doc, &stream.dict, b"Matrix")
463            .and_then(|o| nums(doc, o))
464            .and_then(|v| Mat::from_slice(&v))
465            .unwrap_or(Mat::IDENTITY);
466        let mut inner = st.clone();
467        inner.ctm = matrix.then(st.ctm);
468        if let Some(b) = get(doc, &stream.dict, b"BBox")
469            .and_then(|o| nums(doc, o))
470            .filter(|b| b.len() == 4)
471        {
472            let clip = Box2::new(b[0], b[1], b[2], b[3]).transformed(inner.ctm);
473            inner.clip = inner.clip.intersect(clip);
474            if !axis_aligned(inner.ctm) {
475                inner.clip_complex = true;
476            }
477        }
478        let own = get(doc, &stream.dict, b"Resources")
479            .and_then(|o| as_dict(doc, o))
480            .cloned();
481        let Ok(content) = stream.decompressed_content() else {
482            // Undecodable form content: assume it inks its whole box.
483            let clip = inner.clip;
484            self.mark(&inner, clip);
485            return;
486        };
487        let res = own.as_ref().or(res);
488        self.run(&content, res, inner, depth);
489    }
490
491    /// The Widget annotations the renderer draws over the page: their
492    /// rectangles count as paint.
493    fn widgets(&mut self, page: &Dictionary, base: Mat) {
494        let doc = self.doc;
495        let Some(Object::Array(annots)) = get(doc, page, b"Annots") else {
496            return;
497        };
498        let st = State {
499            ctm: base,
500            clip: Box2::new(f64::MIN, f64::MIN, f64::MAX, f64::MAX),
501            clip_complex: false,
502            tainted: false,
503            text_clip: false,
504        };
505        for a in annots {
506            let Some(ad) = as_dict(doc, a) else { continue };
507            if get_name(doc, ad, b"Subtype") != Some(b"Widget") || !ad.has(b"AP") {
508                continue;
509            }
510            if let Some(r) = get(doc, ad, b"Rect")
511                .and_then(|o| nums(doc, o))
512                .filter(|r| r.len() == 4)
513            {
514                self.mark(&st, Box2::new(r[0], r[1], r[2], r[3]).transformed(base));
515            }
516        }
517    }
518}
519
520fn path_box(pts: &[(f64, f64)], ctm: Mat) -> Option<Box2> {
521    let mut it = pts.iter().map(|&(x, y)| ctm.apply(x, y));
522    let (x, y) = it.next()?;
523    let mut b = Box2::new(x, y, x, y);
524    for (x, y) in it {
525        b.x0 = b.x0.min(x);
526        b.y0 = b.y0.min(y);
527        b.x1 = b.x1.max(x);
528        b.y1 = b.y1.max(y);
529    }
530    Some(b)
531}
532
533/// The image's samples as an RGB bitmap at native size; `None` when it does
534/// not decode, comes out a placeholder, or the page's pixel budget is spent.
535fn decode(
536    doc: &Document,
537    stream: &lopdf::Stream,
538    res: Option<&Dictionary>,
539    pixels: &mut u64,
540) -> Option<RgbImage> {
541    let (w, h) = crate::render::image::declared_size(doc, &stream.dict)?;
542    let n = (w.max(0) as u64).saturating_mul(h.max(0) as u64);
543    if *pixels + n > MAX_PIXELS {
544        return None;
545    }
546    let loaded = crate::render::image::load(doc, stream, res, 0).ok()?;
547    if loaded.placeholder_reason().is_some() {
548        return None;
549    }
550    let mut cmyk = crate::render::color::CmykCache::default();
551    let dec = crate::render::image::rasterize(&loaded, [0, 0, 0], None, &mut cmyk).ok()?;
552    let pm = &dec.pixmap;
553    *pixels += u64::from(pm.width()) * u64::from(pm.height());
554    let data = pm.data();
555    let mut out = RgbImage::new(pm.width(), pm.height());
556    for (i, px) in out.pixels_mut().enumerate() {
557        let p = &data[i * 4..i * 4 + 4];
558        if p[3] != 255 {
559            // Not opaque after all (a colour key the dictionary did not
560            // announce): the render is what the page shows.
561            return None;
562        }
563        *px = image::Rgb([p[0], p[1], p[2]]);
564    }
565    Some(out)
566}
567
568#[cfg(test)]
569mod tests {
570    use super::*;
571    use lopdf::{dictionary, Stream};
572
573    fn root() -> std::path::PathBuf {
574        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../..")
575    }
576
577    /// Page 1 of `bytes` through the real page walk with the option on: its
578    /// text cells and image placements.
579    fn walk_first_page(bytes: &[u8]) -> crate::pdfium_backend::PdfPage {
580        let mut out = None;
581        crate::pdfium_backend::walk_pages::<crate::PdfError, _>(
582            bytes,
583            None,
584            false,
585            true,
586            Some((0, 0)),
587            crate::pdfium_backend::BitmapRender::OnDemand,
588            crate::pdfium_backend::TextOptions {
589                embedded_pictures: true,
590                ..Default::default()
591            },
592            |_, _, page| {
593                out = Some(page);
594                Ok(())
595            },
596        )
597        .unwrap();
598        out.expect("one page")
599    }
600
601    fn fixture(name: &str) -> crate::pdfium_backend::PdfPage {
602        let bytes = std::fs::read(root().join("tests/data/pdf/sources").join(name)).unwrap();
603        walk_first_page(&bytes)
604    }
605
606    /// docling's `test_extract_single_embedded_image`: the one bitmap of
607    /// `picture_classification.pdf` page 1 comes out at its native 768 × 474.
608    #[test]
609    fn extracts_the_single_embedded_image() {
610        let page = fixture("picture_classification.pdf");
611        assert_eq!(page.embedded_images.len(), 1, "{:?}", page.embedded_images);
612        let bbox = page.embedded_images[0].bbox;
613        let img = match_region(&page.embedded_images, &page.cells, bbox).expect("safe image");
614        assert_eq!(img.dimensions(), (768, 474));
615        // A layout box a little off the image still matches (≥ 0.8 both ways)…
616        let loose = [bbox[0] - 8.0, bbox[1] - 8.0, bbox[2] + 4.0, bbox[3] + 4.0];
617        assert!(match_region(&page.embedded_images, &page.cells, loose).is_some());
618        // …one twice the image's size does not.
619        let h = bbox[3] - bbox[1];
620        let big = [bbox[0], bbox[1] - h, bbox[2], bbox[3]];
621        assert!(match_region(&page.embedded_images, &page.cells, big).is_none());
622    }
623
624    /// docling's `test_reject_embedded_image_with_overlapping_page_content`:
625    /// `amt_handbook_sample.pdf`'s first bitmap shares its box with others.
626    #[test]
627    fn rejects_an_image_with_overlapping_page_content() {
628        let page = fixture("amt_handbook_sample.pdf");
629        let first = page.embedded_images.first().expect("bitmaps").bbox;
630        assert!(match_region(&page.embedded_images, &page.cells, first).is_none());
631    }
632
633    /// The walk lists nothing unless asked (the option is off by default).
634    #[test]
635    fn walk_collects_nothing_by_default() {
636        let bytes = std::fs::read(root().join("tests/data/pdf/sources/picture_classification.pdf"))
637            .unwrap();
638        let mut n = None;
639        crate::pdfium_backend::walk_pages::<crate::PdfError, _>(
640            &bytes,
641            None,
642            false,
643            true,
644            Some((0, 0)),
645            crate::pdfium_backend::BitmapRender::OnDemand,
646            crate::pdfium_backend::TextOptions::default(),
647            |_, _, page| {
648                n = Some(page.embedded_images.len());
649                Ok(())
650            },
651        )
652        .unwrap();
653        assert_eq!(n, Some(0));
654    }
655
656    /// A 400 × 300 pt page drawing a 4 × 2 RGB image XObject (`/Im0`, plus
657    /// `/Im1`, and `extra` merged into `/Im0`'s dictionary) with `content`.
658    fn synth(content: &str, extra: lopdf::Dictionary, gs: lopdf::Dictionary) -> Vec<u8> {
659        let mut doc = lopdf::Document::with_version("1.5");
660        let image = |extra: lopdf::Dictionary| {
661            let mut d = dictionary! {
662                "Type" => "XObject", "Subtype" => "Image",
663                "Width" => 4, "Height" => 2,
664                "ColorSpace" => "DeviceRGB", "BitsPerComponent" => 8,
665            };
666            for (k, v) in extra.into_iter() {
667                d.set(k, v);
668            }
669            let px: Vec<u8> = (0..8u8).flat_map(|i| [i * 30, 255 - i * 30, 100]).collect();
670            Stream::new(d, px)
671        };
672        let im0 = doc.add_object(image(extra));
673        let im1 = doc.add_object(image(lopdf::Dictionary::new()));
674        let pages_id = doc.new_object_id();
675        let content_id = doc.add_object(Stream::new(dictionary! {}, content.as_bytes().to_vec()));
676        let res = dictionary! {
677            "XObject" => dictionary! {
678                "Im0" => Object::Reference(im0),
679                "Im1" => Object::Reference(im1),
680            },
681            "ExtGState" => dictionary! { "G0" => gs },
682        };
683        let page_id = doc.add_object(dictionary! {
684            "Type" => "Page",
685            "Parent" => Object::Reference(pages_id),
686            "MediaBox" => vec![0.into(), 0.into(), 400.into(), 300.into()],
687            "Contents" => Object::Reference(content_id),
688            "Resources" => res,
689        });
690        doc.objects.insert(
691            pages_id,
692            Object::Dictionary(dictionary! {
693                "Type" => "Pages", "Kids" => vec![Object::Reference(page_id)], "Count" => 1,
694            }),
695        );
696        let catalog = doc.add_object(dictionary! {
697            "Type" => "Catalog", "Pages" => Object::Reference(pages_id),
698        });
699        doc.trailer.set("Root", Object::Reference(catalog));
700        let mut out = Vec::new();
701        doc.save_to(&mut out).unwrap();
702        out
703    }
704
705    /// The image `content` places at 100 × 50 pt from (50, 150) (top-left
706    /// frame: x 50–150, y 100–150), as `match_region` hands it out.
707    fn matched(content: &str, extra: lopdf::Dictionary, gs: lopdf::Dictionary) -> Option<RgbImage> {
708        let page = walk_first_page(&synth(content, extra, gs));
709        match_region(
710            &page.embedded_images,
711            &page.cells,
712            [50.0, 100.0, 150.0, 150.0],
713        )
714        .cloned()
715    }
716
717    const DRAW: &str = "q 100 0 0 50 50 150 cm /Im0 Do Q";
718
719    fn none() -> lopdf::Dictionary {
720        lopdf::Dictionary::new()
721    }
722
723    #[test]
724    fn a_plain_image_comes_out_at_native_size_with_its_pixels() {
725        let img = matched(DRAW, none(), none()).expect("matched");
726        assert_eq!(img.dimensions(), (4, 2));
727        assert_eq!(img.get_pixel(0, 0).0, [0, 255, 100]);
728        assert_eq!(img.get_pixel(3, 1).0, [210, 45, 100]);
729    }
730
731    #[test]
732    fn content_painted_beneath_does_not_matter_but_over_it_does() {
733        let under = format!("1 0 0 rg 0 0 400 300 re f {DRAW}");
734        assert!(matched(&under, none(), none()).is_some());
735        let over = format!("{DRAW} 0 0 1 rg 60 160 10 10 re f");
736        assert!(matched(&over, none(), none()).is_none());
737        let stroke = format!("{DRAW} 0 0 m 400 300 l S");
738        assert!(matched(&stroke, none(), none()).is_none());
739        // Ink painted after, but elsewhere on the page, is fine.
740        let beside = format!("{DRAW} 300 10 20 20 re f");
741        assert!(matched(&beside, none(), none()).is_some());
742        // A clip-only path paints nothing.
743        let clip = format!("q 0 0 400 300 re W n {DRAW} Q");
744        assert!(matched(&clip, none(), none()).is_some());
745    }
746
747    #[test]
748    fn a_second_overlapping_image_makes_the_match_ambiguous() {
749        let two = format!("{DRAW} q 20 0 0 20 140 140 cm /Im1 Do Q");
750        assert!(matched(&two, none(), none()).is_none());
751        // Drawn first, beneath ours: still a second image in the box.
752        let first = format!("q 20 0 0 20 140 140 cm /Im1 Do Q {DRAW}");
753        assert!(matched(&first, none(), none()).is_none());
754    }
755
756    #[test]
757    fn rotated_mirrored_or_clipped_placements_keep_the_crop() {
758        // Mirrored horizontally (same box).
759        assert!(matched("q -100 0 0 50 150 150 cm /Im0 Do Q", none(), none()).is_none());
760        // Upside down.
761        assert!(matched("q 100 0 0 -50 50 200 cm /Im0 Do Q", none(), none()).is_none());
762        // Cut by a rectangle clip.
763        let cut = format!("q 50 150 60 50 re W n {DRAW} Q");
764        assert!(matched(&cut, none(), none()).is_none());
765        // A non-rectangular clip.
766        let tri = format!("q 0 0 m 400 0 l 0 300 l h W n {DRAW} Q");
767        assert!(matched(&tri, none(), none()).is_none());
768    }
769
770    #[test]
771    fn masked_or_transparent_images_keep_the_crop() {
772        let mut smask = lopdf::Dictionary::new();
773        smask.set("SMask", Object::Reference((99, 0)));
774        assert!(matched(DRAW, smask, none()).is_none());
775        let alpha = dictionary! { "Type" => "ExtGState", "ca" => 0.5 };
776        let draw = format!("/G0 gs {DRAW}");
777        assert!(matched(&draw, none(), alpha).is_none());
778        let multiply = dictionary! { "Type" => "ExtGState", "BM" => "Multiply" };
779        assert!(matched(&draw, none(), multiply).is_none());
780        let normal = dictionary! { "Type" => "ExtGState", "BM" => "Normal", "ca" => 1 };
781        assert!(matched(&draw, none(), normal).is_some());
782    }
783
784    #[test]
785    fn a_rotated_page_lists_no_placements() {
786        let bytes = synth(DRAW, none(), none());
787        let mut doc = lopdf::Document::load_mem(&bytes).unwrap();
788        let pid = *doc.get_pages().values().next().unwrap();
789        doc.get_dictionary_mut(pid).unwrap().set("Rotate", 90);
790        let mut out = Vec::new();
791        doc.save_to(&mut out).unwrap();
792        assert!(walk_first_page(&out).embedded_images.is_empty());
793    }
794
795    #[test]
796    fn text_over_the_image_keeps_the_crop() {
797        let im = EmbeddedImage {
798            bbox: [50.0, 50.0, 150.0, 100.0],
799            image: Some(RgbImage::new(4, 2)),
800        };
801        let cell = |text: &str| TextCell {
802            text: text.into(),
803            l: 60.0,
804            t: 60.0,
805            r: 90.0,
806            b: 70.0,
807        };
808        let region = [50.0, 50.0, 150.0, 100.0];
809        assert!(match_region(std::slice::from_ref(&im), &[cell("label")], region).is_none());
810        assert!(match_region(std::slice::from_ref(&im), &[cell("  ")], region).is_some());
811    }
812}