Skip to main content

docling_pdf/render/
image.rs

1//! Image XObjects and inline images → premultiplied RGBA pixmaps
2//! (ISO 32000-1, 8.9): every bit depth, the colour spaces of [`super::color`],
3//! `/Decode` ranges, stencil masks painted in the fill colour, `/SMask` soft
4//! masks, stencil and colour-key `/Mask`s. The sample data comes through the
5//! raster's filter chain, its libjpeg-exact JPEG decoder and its CCITT
6//! decoder, JPEG 2000 through [`super::jpx`] (#598) and JBIG2 through
7//! [`super::jbig2`] (#811). An image no decoder can read comes out as a
8//! mid-gray block (the picture the layout model should see is "a
9//! picture") — a stencil mask too, which used to draw nothing at all.
10//!
11//! Loading ([`load`]: filters, codec, colour space, alpha plane) is separate
12//! from rasterizing ([`rasterize`]: the RGBA pixmap for one destination
13//! size) so a document-wide cache can decode a scan once and blit it at the
14//! pipeline's several scales. Like docling-parse (`build_bitmap_image`), an
15//! image several times larger than its destination is box-averaged down by
16//! an integer factor before the blit, so a 5000-pixel-wide scan drawn 600
17//! pixels wide costs 600 columns.
18
19use std::collections::HashMap;
20
21use lopdf::{Dictionary, Document, Object};
22use tiny_skia::Pixmap;
23
24use super::color::{to_u8, CmykCache, ColorSpace};
25use super::objects::{as_stream, get2, get_bool, get_bool2, get_int, get_int2, nums};
26use super::{jbig2, jpx};
27use crate::raster::{fax, filters, jpeg};
28
29pub struct DecodedImage {
30    pub pixmap: Pixmap,
31    /// Source size before any reduction (the unit square maps to it).
32    pub src_width: u32,
33    pub src_height: u32,
34}
35
36/// Raw samples: rows of `bpc`-bit components, byte-aligned per row.
37struct Samples {
38    width: usize,
39    height: usize,
40    bpc: u32,
41    ncomp: usize,
42    data: Vec<u8>,
43    stride: usize,
44    /// A four-component JPEG with an Adobe APP14 marker.
45    adobe: bool,
46    /// An opacity channel the codec carried inside the image data (a JPX
47    /// codestream's alpha under `/SMaskInData`, #598), at the image size.
48    inline_alpha: Option<Vec<u8>>,
49}
50
51impl Samples {
52    fn get(&self, x: usize, y: usize, c: usize) -> u32 {
53        let row = &self.data[y * self.stride..];
54        match self.bpc {
55            8 => u32::from(*row.get(x * self.ncomp + c).unwrap_or(&0)),
56            16 => {
57                let i = (x * self.ncomp + c) * 2;
58                (u32::from(*row.get(i).unwrap_or(&0)) << 8)
59                    | u32::from(*row.get(i + 1).unwrap_or(&0))
60            }
61            bpc => {
62                let bit = (x * self.ncomp + c) * bpc as usize;
63                let byte = *row.get(bit / 8).unwrap_or(&0);
64                u32::from((byte >> (8 - bpc as usize - bit % 8)) & ((1u8 << bpc) - 1))
65            }
66        }
67    }
68
69    fn max(&self) -> f64 {
70        ((1u64 << self.bpc) - 1) as f64
71    }
72}
73
74enum Loaded {
75    Samples(Samples),
76    /// The codec could not be run: a neutral block is drawn instead, and the
77    /// reason is kept for the render's omission report (#916).
78    Placeholder(String),
79}
80
81/// An image decoded to samples, with everything the rasterizer needs.
82pub struct LoadedImage {
83    width: usize,
84    height: usize,
85    is_mask: bool,
86    decode_arr: Option<Vec<f64>>,
87    samples: Loaded,
88    /// The colour space the samples are in (after the CMYK JPEG rule).
89    cs: Option<ColorSpace>,
90    /// Alpha at source resolution: soft mask, stencil `/Mask`, colour key.
91    alpha: Option<Vec<u8>>,
92}
93
94impl LoadedImage {
95    /// Why the image is a placeholder block instead of its pixels (`None`
96    /// when it decoded) — the render's omission report (#916).
97    pub fn placeholder_reason(&self) -> Option<&str> {
98        match &self.samples {
99            Loaded::Placeholder(why) => Some(why),
100            Loaded::Samples(_) => None,
101        }
102    }
103
104    /// The memory the samples take (for a cache budget).
105    pub fn bytes(&self) -> usize {
106        let s = match &self.samples {
107            Loaded::Samples(s) => s.data.len(),
108            Loaded::Placeholder(_) => 0,
109        };
110        s + self.alpha.as_ref().map_or(0, Vec::len)
111    }
112}
113
114/// Decode `stream` to samples: the filter chain and codec, the colour
115/// space, the alpha plane.
116/// The `/Width` × `/Height` an image dictionary declares (the codec's own
117/// size wins once decoded; this is what the reduction rule is asked with).
118pub fn declared_size(doc: &Document, d: &Dictionary) -> Option<(i64, i64)> {
119    Some((
120        get_int2(doc, d, b"Width", b"W")?,
121        get_int2(doc, d, b"Height", b"H")?,
122    ))
123}
124
125/// docling-parse's `codec_reduction_shift`: how many halvings a JPEG may be
126/// decoded at (libjpeg's 1/2, 1/4, 1/8 reduced inverse DCT) and still hold
127/// at least the pixels it is drawn onto at `target_pixels_per_unit` — the
128/// renderer's `bitmap_target_pixels_per_unit`, docling's `render_scale` of
129/// 1.0 — so the rasterizer keeps minifying and never magnifies samples it
130/// once had. A 300 dpi scan drawn full-page decodes at a quarter for the
131/// 72 dpi hint and is blitted *up* onto the scale-2 canvas; matching that is
132/// what lines the Rust render of a scan up with the shim's. Capped at three
133/// halvings and never below 64 samples a side (a thumbnail is not worth the
134/// resampling risk); `drawn_*_units` is the axis-aligned extent of the drawn
135/// quad in PDF units.
136pub fn codec_reduction_shift(
137    drawn_width_units: f64,
138    drawn_height_units: f64,
139    source_width: i64,
140    source_height: i64,
141    target_pixels_per_unit: f64,
142) -> u32 {
143    const MAX_SHIFT: u32 = 3;
144    const MIN_SOURCE_EXTENT: i64 = 64;
145    if target_pixels_per_unit <= 0.0
146        || source_width <= 0
147        || source_height <= 0
148        || drawn_width_units <= 0.0
149        || drawn_height_units <= 0.0
150    {
151        return 0;
152    }
153    let target_width = drawn_width_units * target_pixels_per_unit;
154    let target_height = drawn_height_units * target_pixels_per_unit;
155    let mut shift = 0u32;
156    while shift < MAX_SHIFT {
157        let next_width = source_width >> (shift + 1);
158        let next_height = source_height >> (shift + 1);
159        if next_width < MIN_SOURCE_EXTENT || next_height < MIN_SOURCE_EXTENT {
160            break;
161        }
162        if (next_width as f64) < target_width || (next_height as f64) < target_height {
163            break;
164        }
165        shift += 1;
166    }
167    shift
168}
169
170/// Whether a reduced decode is allowed at all (docling-parse's
171/// `may_reduce_decode`): not for a stencil mask, an image with a soft mask or
172/// `/Mask` (its alpha plane is resolved on the full grid), or an Indexed image
173/// (its bytes are palette indices — interpolating them means nothing). Only
174/// the DCT decoder acts on the shift; every other codec ignores it.
175fn may_reduce_decode(doc: &Document, d: &Dictionary, res: Option<&Dictionary>) -> bool {
176    if get_bool2(doc, d, b"ImageMask", b"IM").unwrap_or(false) {
177        return false;
178    }
179    if d.has(b"SMask") || d.has(b"Mask") {
180        return false;
181    }
182    !matches!(
183        get2(doc, d, b"ColorSpace", b"CS").and_then(|o| ColorSpace::parse(doc, o, res)),
184        Some(ColorSpace::Indexed { .. })
185    )
186}
187
188/// Decode an image XObject (or inline image) into samples. `reduction_shift`
189/// asks the JPEG decoder for a `1 / 2^shift` reduced decode when the image
190/// allows one ([`codec_reduction_shift`], [`may_reduce_decode`]); the loaded
191/// image then reports the reduced size.
192pub fn load(
193    doc: &Document,
194    stream: &lopdf::Stream,
195    res: Option<&Dictionary>,
196    reduction_shift: u32,
197) -> Result<LoadedImage, String> {
198    let d = &stream.dict;
199    let (width, height) = declared_size(doc, d).ok_or("Width")?;
200    if width <= 0
201        || height <= 0
202        || width > 1 << 16
203        || height > 1 << 16
204        || width * height > 80_000_000
205    {
206        return Err("image size".into());
207    }
208    let is_mask = get_bool2(doc, d, b"ImageMask", b"IM").unwrap_or(false);
209    let decode_arr: Option<Vec<f64>> = get2(doc, d, b"Decode", b"D").and_then(|o| nums(doc, o));
210    let shift = if reduction_shift > 0 && may_reduce_decode(doc, d, res) {
211        reduction_shift
212    } else {
213        0
214    };
215    let mut samples = load_samples(doc, stream, res, is_mask, shift)?;
216    // The decoded samples' size is the image's (a JPEG's own header, or the
217    // reduced decode, wins over the dictionary's `/Width` × `/Height`).
218    let (w, h) = match &samples {
219        Loaded::Samples(s) => (s.width, s.height),
220        Loaded::Placeholder(_) => (width as usize, height as usize),
221    };
222    if is_mask {
223        return Ok(LoadedImage {
224            width: w,
225            height: h,
226            is_mask,
227            decode_arr,
228            samples,
229            cs: None,
230            alpha: None,
231        });
232    }
233    let (cs, alpha) = match &mut samples {
234        Loaded::Placeholder(_) => (None, None),
235        Loaded::Samples(s) => {
236            let cs_obj = get2(doc, d, b"ColorSpace", b"CS");
237            let guess = || match s.ncomp {
238                3 => ColorSpace::DeviceRGB,
239                4 => ColorSpace::DeviceCMYK,
240                _ => ColorSpace::DeviceGray,
241            };
242            let cs = match cs_obj {
243                Some(o) => ColorSpace::parse(doc, o, res).unwrap_or_else(guess),
244                None => guess(),
245            };
246            // A four-component JPEG under a colour space that is not CMYK:
247            // the dictionary contradicts its data, and only the Adobe marker
248            // is left to say what the samples hold — 255 minus the ink
249            // (docling-parse's rule; a /DeviceCMYK image's samples are ink
250            // amounts, and /Decode says otherwise).
251            let cs = if s.ncomp == 4 && cs.components() != 4 {
252                if s.adobe {
253                    for v in &mut s.data {
254                        *v = 255 - *v;
255                    }
256                }
257                ColorSpace::DeviceCMYK
258            } else {
259                cs
260            };
261            // `/SMask` / `/Mask` first; else the alpha the codec carried
262            // inside the data (a JPX codestream's, under `/SMaskInData`).
263            let alpha = match alpha_plane(doc, d, res, s, w, h)? {
264                Some(a) => Some(a),
265                None => s.inline_alpha.take(),
266            };
267            (Some(cs), alpha)
268        }
269    };
270    Ok(LoadedImage {
271        width: w,
272        height: h,
273        is_mask,
274        decode_arr,
275        samples,
276        cs,
277        alpha,
278    })
279}
280
281/// Rasterize a loaded image as it would be painted with `fill` (for stencil
282/// masks), reduced so that its whole extent covers about `target` device
283/// pixels (`None` = full size).
284pub fn rasterize(
285    img: &LoadedImage,
286    fill: [u8; 3],
287    target: Option<(u32, u32)>,
288    cmyk: &mut CmykCache,
289) -> Result<DecodedImage, String> {
290    let (w, h) = (img.width, img.height);
291    // Integer reduction factors (docling-parse's `fx = sw / dst_w`).
292    let (fx, fy) = match target {
293        Some((tw, th)) if tw > 0 && th > 0 => (
294            ((w as u32) / tw).max(1) as usize,
295            ((h as u32) / th).max(1) as usize,
296        ),
297        _ => (1, 1),
298    };
299    let out_w = (w / fx).max(1);
300    let out_h = (h / fy).max(1);
301    let mut pixmap = Pixmap::new(out_w as u32, out_h as u32).ok_or("pixmap")?;
302    let done = |pixmap| {
303        Ok(DecodedImage {
304            pixmap,
305            src_width: w as u32,
306            src_height: h as u32,
307        })
308    };
309
310    if img.is_mask {
311        // 1 bpc; sample 0 paints (Decode [0 1]) unless Decode [1 0].
312        let paint_on_one = img
313            .decode_arr
314            .as_ref()
315            .is_some_and(|v| v.first().is_some_and(|x| *x >= 0.5));
316        match &img.samples {
317            Loaded::Samples(s) => {
318                let px = pixmap.pixels_mut();
319                for oy in 0..out_h {
320                    for ox in 0..out_w {
321                        let mut cov = 0u32;
322                        let mut n = 0u32;
323                        for y in oy * fy..((oy + 1) * fy).min(h) {
324                            for x in ox * fx..((ox + 1) * fx).min(w) {
325                                let v = s.get(x, y, 0);
326                                let on = (v != 0) == paint_on_one;
327                                cov += u32::from(on);
328                                n += 1;
329                            }
330                        }
331                        let a = (cov * 255).checked_div(n).unwrap_or(0) as u8;
332                        px[oy * out_w + ox] = premul(fill, a);
333                    }
334                }
335            }
336            // An undecodable stencil (#811): the same neutral block an
337            // undecodable image gets, so the page shows *something* where
338            // the scan's text was instead of nothing at all.
339            Loaded::Placeholder(_) => {
340                for p in pixmap.pixels_mut() {
341                    *p = premul([128, 128, 128], 255);
342                }
343            }
344        }
345        return done(pixmap);
346    }
347
348    let (Loaded::Samples(s), Some(cs)) = (&img.samples, &img.cs) else {
349        // Undecodable (a codec failure): a neutral block the size of the image.
350        for p in pixmap.pixels_mut() {
351            *p = premul([128, 128, 128], 255);
352        }
353        return done(pixmap);
354    };
355
356    let ncomp = s.ncomp.min(cs.components()).max(1);
357    let max = s.max();
358    let default_decode = cs.default_decode(s.bpc);
359    let decode = match &img.decode_arr {
360        Some(v) if v.len() >= 2 * ncomp => v.clone(),
361        _ => default_decode.clone(),
362    };
363    let is_default_decode = decode
364        .iter()
365        .zip(default_decode.iter())
366        .all(|(a, b)| (a - b).abs() < 1e-9);
367    let alpha = &img.alpha;
368
369    // Fast paths: 8-bit gray / RGB samples with the default decode and no
370    // alpha — the scanned page and the photograph — averaged directly.
371    let direct = alpha.is_none()
372        && s.bpc == 8
373        && is_default_decode
374        && matches!(
375            (cs, s.ncomp),
376            (ColorSpace::DeviceGray, 1) | (ColorSpace::DeviceRGB, 3)
377        );
378    if direct {
379        let px = pixmap.pixels_mut();
380        let nc = s.ncomp;
381        for oy in 0..out_h {
382            for ox in 0..out_w {
383                let (mut r, mut g, mut b, mut n) = (0u32, 0u32, 0u32, 0u32);
384                for y in oy * fy..((oy + 1) * fy).min(h) {
385                    let row = &s.data[y * s.stride..];
386                    for x in ox * fx..((ox + 1) * fx).min(w) {
387                        let i = x * nc;
388                        if nc == 1 {
389                            let v = u32::from(row[i]);
390                            r += v;
391                            g += v;
392                            b += v;
393                        } else {
394                            r += u32::from(row[i]);
395                            g += u32::from(row[i + 1]);
396                            b += u32::from(row[i + 2]);
397                        }
398                        n += 1;
399                    }
400                }
401                let n = n.max(1);
402                px[oy * out_w + ox] = tiny_skia::PremultipliedColorU8::from_rgba(
403                    (r / n) as u8,
404                    (g / n) as u8,
405                    (b / n) as u8,
406                    255,
407                )
408                .unwrap_or(tiny_skia::PremultipliedColorU8::TRANSPARENT);
409            }
410        }
411        return done(pixmap);
412    }
413
414    // Sample tuple → RGB, memoised (indexed, gray, CMYK and low depths repeat).
415    let mut memo: HashMap<u64, [u8; 3]> = HashMap::new();
416    let mut convert = |vals: &[u32]| -> [u8; 3] {
417        let key = vals
418            .iter()
419            .take(4)
420            .fold(0u64, |a, &v| (a << 16) | u64::from(v & 0xFFFF));
421        if let Some(c) = memo.get(&key) {
422            return *c;
423        }
424        let rgb = match (cs, s.bpc, is_default_decode) {
425            (ColorSpace::DeviceRGB, 8, true) => [vals[0] as u8, vals[1] as u8, vals[2] as u8],
426            (ColorSpace::DeviceGray, 8, true) => [vals[0] as u8; 3],
427            (ColorSpace::DeviceCMYK, 8, true) => {
428                cmyk.rgb8(vals[0] as u8, vals[1] as u8, vals[2] as u8, vals[3] as u8)
429            }
430            _ => {
431                let comps: Vec<f64> = (0..ncomp)
432                    .map(|i| {
433                        let (dmin, dmax) = (decode[2 * i], decode[2 * i + 1]);
434                        dmin + f64::from(vals[i]) * (dmax - dmin) / max
435                    })
436                    .collect();
437                match cs.to_rgb(&comps) {
438                    Some(c) => [to_u8(c[0]), to_u8(c[1]), to_u8(c[2])],
439                    None => [255, 255, 255],
440                }
441            }
442        };
443        if memo.len() < 1 << 18 {
444            memo.insert(key, rgb);
445        }
446        rgb
447    };
448
449    let px = pixmap.pixels_mut();
450    let mut vals = vec![0u32; ncomp.max(4)];
451    for oy in 0..out_h {
452        for ox in 0..out_w {
453            let (mut r, mut g, mut b, mut a, mut n) = (0u32, 0u32, 0u32, 0u32, 0u32);
454            for y in oy * fy..((oy + 1) * fy).min(h) {
455                for x in ox * fx..((ox + 1) * fx).min(w) {
456                    for (c, v) in vals.iter_mut().enumerate().take(ncomp) {
457                        *v = s.get(x, y, c);
458                    }
459                    let rgb = convert(&vals[..ncomp.max(1)]);
460                    let al = match alpha {
461                        Some(pl) => u32::from(pl[y * w + x]),
462                        None => 255,
463                    };
464                    // Premultiply before averaging, like docling-parse.
465                    r += u32::from(rgb[0]) * al / 255;
466                    g += u32::from(rgb[1]) * al / 255;
467                    b += u32::from(rgb[2]) * al / 255;
468                    a += al;
469                    n += 1;
470                }
471            }
472            let n = n.max(1);
473            px[oy * out_w + ox] = tiny_skia::PremultipliedColorU8::from_rgba(
474                (r / n).min(255) as u8,
475                (g / n).min(255) as u8,
476                (b / n).min(255) as u8,
477                (a / n).min(255) as u8,
478            )
479            .unwrap_or(tiny_skia::PremultipliedColorU8::TRANSPARENT);
480        }
481    }
482    done(pixmap)
483}
484
485/// [`load`] then [`rasterize`].
486pub fn decode(
487    doc: &Document,
488    stream: &lopdf::Stream,
489    res: Option<&Dictionary>,
490    fill: [u8; 3],
491    target: Option<(u32, u32)>,
492    cmyk: &mut CmykCache,
493) -> Result<DecodedImage, String> {
494    let img = load(doc, stream, res, 0)?;
495    rasterize(&img, fill, target, cmyk)
496}
497
498fn premul(rgb: [u8; 3], a: u8) -> tiny_skia::PremultipliedColorU8 {
499    let m = |c: u8| ((u32::from(c) * u32::from(a) + 127) / 255) as u8;
500    tiny_skia::PremultipliedColorU8::from_rgba(m(rgb[0]), m(rgb[1]), m(rgb[2]), a)
501        .unwrap_or(tiny_skia::PremultipliedColorU8::TRANSPARENT)
502}
503
504/// Run the filter chain and the image codec; `Placeholder` for an image
505/// its codec cannot decode.
506fn load_samples(
507    doc: &Document,
508    stream: &lopdf::Stream,
509    res: Option<&Dictionary>,
510    is_mask: bool,
511    reduction_shift: u32,
512) -> Result<Loaded, String> {
513    let d = &stream.dict;
514    let w = get_int2(doc, d, b"Width", b"W").unwrap_or(0).max(0) as usize;
515    let h = get_int2(doc, d, b"Height", b"H").unwrap_or(0).max(0) as usize;
516    let chain = filters::filters(doc, d);
517    let (data, codec) =
518        filters::apply(doc, &stream.content, &chain).map_err(|e| format!("filter {e:?}"))?;
519    let bpc_dict = if is_mask {
520        1
521    } else {
522        get_int2(doc, d, b"BitsPerComponent", b"BPC")
523            .unwrap_or(8)
524            .clamp(1, 16) as u32
525    };
526    let cs_ncomp = if is_mask {
527        1
528    } else {
529        get2(doc, d, b"ColorSpace", b"CS")
530            .and_then(|o| ColorSpace::parse(doc, o, res))
531            .map(|c| c.components())
532            .unwrap_or(1)
533    };
534    match codec {
535        None => {
536            let bpc = match bpc_dict {
537                1 | 2 | 4 | 8 | 16 => bpc_dict,
538                _ => 8,
539            };
540            let stride = (w * cs_ncomp * bpc as usize).div_ceil(8);
541            let mut data = data;
542            if data.len() < stride * h {
543                // Short data: pad (a truncated image shows what it has).
544                data.resize(stride * h, 0);
545            }
546            Ok(Loaded::Samples(Samples {
547                width: w,
548                height: h,
549                bpc,
550                ncomp: cs_ncomp,
551                data,
552                stride,
553                adobe: false,
554                inline_alpha: None,
555            }))
556        }
557        Some(codec) if codec.name == "DCTDecode" => {
558            let transform = codec
559                .parms
560                .as_ref()
561                .and_then(|p| get_int(doc, p, b"ColorTransform"))
562                .unwrap_or(1)
563                != 0;
564            match jpeg::decode(&data, transform, 1u32 << reduction_shift.min(3)) {
565                Ok(img) => {
566                    let ncomp = img.channels;
567                    // The JPEG's own size wins over the dictionary's.
568                    Ok(Loaded::Samples(Samples {
569                        width: img.width,
570                        height: img.height,
571                        bpc: 8,
572                        ncomp,
573                        stride: img.width * ncomp,
574                        adobe: img.adobe_inverted,
575                        inline_alpha: None,
576                        data: img.data,
577                    }))
578                }
579                Err(e) => {
580                    docling_core::debug_log!("docling-pdf render: JPEG not decoded ({e:?})");
581                    Ok(Loaded::Placeholder(format!("JPEG not decoded ({e:?})")))
582                }
583            }
584        }
585        Some(codec) if codec.name == "CCITTFaxDecode" => {
586            let p = codec.parms.as_ref();
587            let pi = |k: &[u8], default: i64| p.and_then(|p| get_int(doc, p, k)).unwrap_or(default);
588            let pb = |k: &[u8]| p.and_then(|p| get_bool(doc, p, k)).unwrap_or(false);
589            let mut rows = pi(b"Rows", 0);
590            if rows > i64::from(u16::MAX) {
591                rows = 0;
592            }
593            let params = fax::Params {
594                k: pi(b"K", 0) as i32,
595                end_of_line: pb(b"EndOfLine"),
596                byte_align: pb(b"EncodedByteAlign"),
597                black_is_1: pb(b"BlackIs1"),
598                columns: pi(b"Columns", 1728).clamp(1, 65535) as usize,
599                rows: rows.max(0) as usize,
600            };
601            let lines = fax::decode(&data, &params, h);
602            let stride = w.div_ceil(8);
603            let mut out = vec![0u8; stride * h];
604            for (y, row) in out.chunks_exact_mut(stride).enumerate() {
605                match lines.get(y) {
606                    Some(Some(line)) => {
607                        let n = stride.min(line.len());
608                        row[..n].copy_from_slice(&line[..n]);
609                    }
610                    // Past the data: white (CCITT 1 = white unless BlackIs1).
611                    _ => row.fill(if params.black_is_1 { 0x00 } else { 0xff }),
612                }
613            }
614            Ok(Loaded::Samples(Samples {
615                width: w,
616                height: h,
617                bpc: 1,
618                ncomp: 1,
619                data: out,
620                stride,
621                adobe: false,
622                inline_alpha: None,
623            }))
624        }
625        Some(codec) if codec.name == "JPXDecode" => {
626            // 7.4.9: an `Indexed` colour space makes the samples palette
627            // indices, so the codestream's own palette must not be applied;
628            // `/SMaskInData` says whether the codestream's alpha is the soft
629            // mask (1, or 2 premultiplied) or to be ignored (0, default).
630            let indexed = !is_mask
631                && matches!(
632                    get2(doc, d, b"ColorSpace", b"CS").and_then(|o| ColorSpace::parse(doc, o, res)),
633                    Some(ColorSpace::Indexed { .. })
634                );
635            let smask_in_data = get_int(doc, d, b"SMaskInData").unwrap_or(0);
636            let target = (reduction_shift > 0 && w > 0 && h > 0).then(|| {
637                let shift = reduction_shift.min(3);
638                ((w >> shift).max(1) as u32, (h >> shift).max(1) as u32)
639            });
640            match jpx::decode(&data, indexed, target) {
641                Ok(img) => Ok(Loaded::Samples(Samples {
642                    width: img.width,
643                    height: img.height,
644                    bpc: 8,
645                    ncomp: img.ncomp,
646                    stride: img.width * img.ncomp,
647                    adobe: false,
648                    inline_alpha: if smask_in_data > 0 { img.alpha } else { None },
649                    data: img.data,
650                })),
651                Err(e) => {
652                    docling_core::debug_log!("docling-pdf render: JPX not decoded ({e})");
653                    Ok(Loaded::Placeholder(format!("JPX not decoded ({e})")))
654                }
655            }
656        }
657        Some(codec) if codec.name == "JBIG2Decode" => {
658            // 7.4.7: `/JBIG2Globals` is a stream of segments shared by the
659            // document's images, decoded ahead of this one's.
660            let globals = codec
661                .parms
662                .as_ref()
663                .and_then(|p| p.get(b"JBIG2Globals").ok())
664                .and_then(|o| as_stream(doc, o))
665                .and_then(|g| {
666                    let chain = filters::filters(doc, &g.dict);
667                    match filters::apply(doc, &g.content, &chain) {
668                        Ok((bytes, None)) => Some(bytes),
669                        _ => {
670                            docling_core::debug_log!(
671                                "docling-pdf render: JBIG2Globals not decoded, ignored"
672                            );
673                            None
674                        }
675                    }
676                });
677            match jbig2::decode(&data, globals.as_deref(), w, h) {
678                Ok(img) => Ok(Loaded::Samples(Samples {
679                    width: w,
680                    height: h,
681                    bpc: 1,
682                    ncomp: 1,
683                    stride: img.stride,
684                    adobe: false,
685                    inline_alpha: None,
686                    data: img.data,
687                })),
688                Err(e) => {
689                    docling_core::debug_log!("docling-pdf render: JBIG2 not decoded ({e})");
690                    Ok(Loaded::Placeholder(format!("JBIG2 not decoded ({e})")))
691                }
692            }
693        }
694        Some(codec) => {
695            docling_core::debug_log!(
696                "docling-pdf render: no {} decoder, drawing a placeholder",
697                codec.name
698            );
699            Ok(Loaded::Placeholder(format!("no {} decoder", codec.name)))
700        }
701    }
702}
703
704/// Take a mask's samples (any bit depth) as an alpha plane at the image size:
705/// the soft mask's gray, a stencil `/Mask`'s 1 = masked out, or the colour
706/// key ranges on the raw samples.
707fn alpha_plane(
708    doc: &Document,
709    d: &Dictionary,
710    res: Option<&Dictionary>,
711    s: &Samples,
712    w: usize,
713    h: usize,
714) -> Result<Option<Vec<u8>>, String> {
715    // Soft mask.
716    if let Some(sm) = d.get(b"SMask").ok().and_then(|o| as_stream(doc, o)) {
717        let smw = get_int(doc, &sm.dict, b"Width").unwrap_or(0).max(0) as usize;
718        let smh = get_int(doc, &sm.dict, b"Height").unwrap_or(0).max(0) as usize;
719        if smw > 0 && smh > 0 && smw * smh <= 80_000_000 {
720            if let Ok(Loaded::Samples(ms)) = load_samples(doc, sm, res, false, 0) {
721                let decode = get2(doc, &sm.dict, b"Decode", b"D").and_then(|o| nums(doc, o));
722                let invert = decode.is_some_and(|v| v.first().is_some_and(|x| *x >= 0.5));
723                let mmax = ms.max();
724                let mut plane = vec![255u8; w * h];
725                for y in 0..h {
726                    let my = (y * ms.height / h.max(1)).min(ms.height.saturating_sub(1));
727                    for x in 0..w {
728                        let mx = (x * ms.width / w.max(1)).min(ms.width.saturating_sub(1));
729                        let v = f64::from(ms.get(mx, my, 0)) / mmax;
730                        let v = if invert { 1.0 - v } else { v };
731                        plane[y * w + x] = (v * 255.0).round() as u8;
732                    }
733                }
734                return Ok(Some(plane));
735            }
736        }
737    }
738    match d.get(b"Mask").ok().map(|o| super::objects::deref(doc, o)) {
739        // Stencil mask: 1 bpc, sample 1 = masked (unless Decode [1 0]).
740        Some(Object::Stream(ms)) => {
741            let mw = get_int(doc, &ms.dict, b"Width").unwrap_or(0).max(0) as usize;
742            let mh = get_int(doc, &ms.dict, b"Height").unwrap_or(0).max(0) as usize;
743            if mw > 0 && mh > 0 && mw * mh <= 80_000_000 {
744                if let Ok(Loaded::Samples(bits)) = load_samples(doc, ms, res, true, 0) {
745                    let decode = get2(doc, &ms.dict, b"Decode", b"D").and_then(|o| nums(doc, o));
746                    let one_paints = decode.is_some_and(|v| v.first().is_some_and(|x| *x >= 0.5));
747                    let mut plane = vec![255u8; w * h];
748                    for y in 0..h {
749                        let my = (y * bits.height / h.max(1)).min(bits.height.saturating_sub(1));
750                        for x in 0..w {
751                            let mx = (x * bits.width / w.max(1)).min(bits.width.saturating_sub(1));
752                            let v = bits.get(mx, my, 0) != 0;
753                            let masked = if one_paints { !v } else { v };
754                            if masked {
755                                plane[y * w + x] = 0;
756                            }
757                        }
758                    }
759                    return Ok(Some(plane));
760                }
761            }
762            Ok(None)
763        }
764        // Colour key: ranges per component on the raw integer samples.
765        Some(Object::Array(ranges)) => {
766            let r: Vec<i64> = ranges
767                .iter()
768                .filter_map(|o| {
769                    super::objects::num(super::objects::deref(doc, o)).map(|v| v as i64)
770                })
771                .collect();
772            let n = s.ncomp;
773            if r.len() < 2 * n {
774                return Ok(None);
775            }
776            let mut plane = vec![255u8; w * h];
777            for y in 0..h.min(s.height) {
778                for x in 0..w.min(s.width) {
779                    let masked = (0..n).all(|c| {
780                        let v = i64::from(s.get(x, y, c));
781                        v >= r[2 * c] && v <= r[2 * c + 1]
782                    });
783                    if masked {
784                        plane[y * w + x] = 0;
785                    }
786                }
787            }
788            Ok(Some(plane))
789        }
790        _ => Ok(None),
791    }
792}