Skip to main content

pdf2_render/
image.rs

1//! Image XObjects: decode an 8-bit image, then sample it into the canvas.
2
3use pdf2::{Dictionary, Document, Object, Stream};
4
5use crate::canvas::{BlendMode, Canvas, ClipMask, Color};
6use crate::geom::{Matrix, Point};
7use crate::{Error, Result};
8
9/// A decoded image: width, height and one colour per pixel, top row first.
10#[derive(Debug, Clone)]
11pub struct Image {
12    width: u32,
13    height: u32,
14    pixels: Vec<Color>,
15    interpolate: bool,
16}
17
18impl Image {
19    /// Decode an `/Image` XObject.
20    ///
21    /// Supports 8 bits per component, `DeviceGray`/`DeviceRGB`/`DeviceCMYK`,
22    /// `Indexed` images with those bases, and `ICCBased` streams by component
23    /// count. Anything else is reported rather than guessed.
24    pub fn from_stream(
25        document: &Document,
26        stream: &Stream,
27        id: Option<pdf2::ObjectId>,
28    ) -> Result<Self> {
29        let dict = stream.dict();
30        let width = integer(dict, b"Width")?;
31        let height = integer(dict, b"Height")?;
32        if width == 0 || height == 0 {
33            return Err(Error::malformed("image with zero width or height"));
34        }
35        let bits = dict
36            .get(b"BitsPerComponent")
37            .and_then(Object::as_integer)
38            .unwrap_or(8);
39        // One bit per component is how every fax image arrives; the packed rows
40        // are widened to bytes here so the sampler below has one path.
41        if bits != 8 && bits != 1 {
42            return Err(Error::malformed(
43                "only 1 and 8 bits per component images are rendered",
44            ));
45        }
46        let interpolate = matches!(dict.get(b"Interpolate"), Some(Object::Boolean(true)));
47        let space = resolve(document, dict.get(b"ColorSpace"))?;
48        // The colour space is dictionary metadata, so the size the image claims
49        // is known before its stream is touched — and that is the order that
50        // keeps a lying /Width from being paid for. Every component is one byte
51        // here (8 bits per component is the only depth drawn), so the decoded
52        // size is width × height × components.
53        let colours = ColourSpace::from_object(document, space)?;
54        let per_pixel = colours.components();
55        let count = (width as usize)
56            .checked_mul(height as usize)
57            .and_then(|pixels| pixels.checked_mul(per_pixel))
58            .ok_or_else(|| Error::malformed("image dimensions overflow"))?;
59        let limit = document.decoded_limit();
60        if count > limit {
61            return Err(Error::Limit {
62                what: "an image of the /Width and /Height it declares",
63                limit,
64            });
65        }
66        if is_dct(dict) {
67            return Self::from_dct(document, stream, id, interpolate);
68        }
69        let decoded = document.decode_stream(stream)?;
70        let data = if bits == 1 {
71            widen_one_bit(&decoded, width, height, per_pixel)?
72        } else {
73            decoded
74        };
75        if data.len() < count {
76            return Err(Error::Malformed {
77                what: "image data is shorter than width × height × components",
78                offset: None,
79            });
80        }
81        // `/Decode` remaps every sample before the colour space sees it; the
82        // default is the identity, and `[1 0]` per component is an inversion
83        // (8.9.5.2).
84        let decode = decode_ranges(dict.get(b"Decode"), per_pixel);
85        let mut pixels = Vec::with_capacity((width as usize) * (height as usize));
86        for index in (0..count).step_by(per_pixel) {
87            let sample = &data[index..index + per_pixel];
88            let mut components = [0.0_f64; 4];
89            for (slot, byte) in sample.iter().enumerate().take(per_pixel) {
90                let (from, to) = decode[slot];
91                components[slot] = (from + f64::from(*byte) / 255.0 * (to - from)).clamp(0.0, 1.0);
92            }
93            pixels.push(colour_at(&colours, &components));
94        }
95        Ok(Self {
96            width,
97            height,
98            pixels,
99            interpolate,
100        })
101    }
102
103    /// Decode a `/DCTDecode` image through `zune-jpeg`.
104    ///
105    /// A JPEG in a PDF has no leading filters to unwind, so the bytes come
106    /// straight from [`Document::stream_bytes`] — decrypted, not decoded — and
107    /// `zune-jpeg` converts YCbCr to RGB itself. The size is checked against the
108    /// budget twice: once from the dictionary, and once from the JPEG's own
109    /// header, because the header is the authority on what the decoder produces.
110    #[cfg(feature = "dct")]
111    fn from_dct(
112        document: &Document,
113        _stream: &Stream,
114        id: Option<pdf2::ObjectId>,
115        interpolate: bool,
116    ) -> Result<Self> {
117        let Some(id) = id else {
118            return Err(Error::malformed(
119                "a /DCTDecode image without an object number",
120            ));
121        };
122        let data = document.stream_bytes(id)?;
123        // PDF 7.4.8: a four-component JPEG from an Adobe writer stores its CMYK
124        // samples **inverted** (255 - sample), and its `/Decode` array — when the
125        // writer states one — is the same statement in words. Asking the decoder
126        // for CMYK rather than RGB is what makes the inversion possible: its RGB
127        // conversion assumes the already-uninverted order and comes out black.
128        let cmyk = dict_component_count(_stream) == Some(4);
129        let mut decoder =
130            zune_jpeg::JpegDecoder::new(zune_jpeg::zune_core::bytestream::ZCursor::new(&data));
131        if cmyk {
132            decoder.set_options(
133                zune_jpeg::zune_core::options::DecoderOptions::default()
134                    .jpeg_set_out_colorspace(zune_jpeg::zune_core::colorspace::ColorSpace::CMYK),
135            );
136        }
137        let pixels = decoder
138            .decode()
139            .map_err(|_| Error::malformed("/DCTDecode payload"))?;
140        let Some(info) = decoder.info() else {
141            return Err(Error::malformed(
142                "/DCTDecode payload without a frame header",
143            ));
144        };
145        let components = match decoder.output_colorspace() {
146            Some(zune_jpeg::zune_core::colorspace::ColorSpace::Luma) => 1,
147            Some(zune_jpeg::zune_core::colorspace::ColorSpace::CMYK) => 4,
148            _ => 3,
149        };
150        let count = usize::from(info.width)
151            .checked_mul(usize::from(info.height))
152            .and_then(|samples| samples.checked_mul(components))
153            .ok_or_else(|| Error::malformed("image dimensions overflow"))?;
154        let limit = document.decoded_limit();
155        if count > limit {
156            return Err(Error::Limit {
157                what: "a /DCTDecode image of the size its header declares",
158                limit,
159            });
160        }
161        if pixels.len() < count {
162            return Err(Error::malformed(
163                "/DCTDecode payload is shorter than its header",
164            ));
165        }
166        // The Adobe inversion is applied here only when the writer did not state
167        // it as `/Decode`: the two are the same statement, and applying both
168        // would invert twice (which is what pdf.js does, and what
169        // `cmykjpeg.pdf` — an Adobe APP14 all-zero transform with no `/Decode` —
170        // needs).
171        let stated_decode = _stream.dict().get(b"Decode").is_some();
172        let invert = cmyk && !stated_decode && has_adobe_marker(&data);
173        // A `/Decode` array, when the writer states one, is applied to the samples
174        // after the Adobe inversion; when it inverts, the two cancel out.
175        let decode = decode_ranges(_stream.dict().get(b"Decode"), components);
176        let sample = |bytes: &[u8]| -> Vec<f64> {
177            bytes
178                .iter()
179                .enumerate()
180                .map(|(index, byte)| {
181                    let value = f64::from(*byte) / 255.0;
182                    let (from, to) = decode[index.min(decode.len() - 1)];
183                    (from + value * (to - from)).clamp(0.0, 1.0)
184                })
185                .collect()
186        };
187        let pixels = pixels[..count]
188            .chunks_exact(components)
189            .map(|bytes| {
190                let bytes: Vec<u8> = if invert {
191                    bytes.iter().map(|byte| 255 - byte).collect()
192                } else {
193                    bytes.to_vec()
194                };
195                let values = sample(&bytes);
196                match components {
197                    1 => Color::rgb(values[0], values[0], values[0]),
198                    4 => Color::from_cmyk(values[0], values[1], values[2], values[3]),
199                    _ => Color::rgb(values[0], values[1], values[2]),
200                }
201            })
202            .collect();
203        Ok(Self {
204            width: u32::from(info.width),
205            height: u32::from(info.height),
206            pixels,
207            interpolate,
208        })
209    }
210
211    /// Without the feature a JPEG is reported, not guessed at.
212    #[cfg(not(feature = "dct"))]
213    fn from_dct(
214        _document: &Document,
215        _stream: &Stream,
216        _id: Option<pdf2::ObjectId>,
217        _interpolate: bool,
218    ) -> Result<Self> {
219        Err(Error::Unsupported {
220            what: "/DCTDecode images (build with the `dct` feature)",
221        })
222    }
223
224    /// Width in samples.
225    pub fn width(&self) -> u32 {
226        self.width
227    }
228
229    /// Height in samples.
230    pub fn height(&self) -> u32 {
231        self.height
232    }
233
234    /// The colour at a sample position, nearest or bilinear.
235    pub fn sample(&self, u: f64, v: f64) -> Color {
236        if self.width == 0 || self.height == 0 {
237            return Color::WHITE;
238        }
239        let x = (u.clamp(0.0, 1.0) * f64::from(self.width) - 0.5).max(0.0);
240        let y = (v.clamp(0.0, 1.0) * f64::from(self.height) - 0.5).max(0.0);
241        if !self.interpolate {
242            return self.pixel(x.round() as u32, y.round() as u32);
243        }
244        let x0 = x.floor() as u32;
245        let y0 = y.floor() as u32;
246        let x1 = (x0 + 1).min(self.width - 1);
247        let y1 = (y0 + 1).min(self.height - 1);
248        let fx = x - f64::from(x0);
249        let fy = y - f64::from(y0);
250        let top = mix(self.pixel(x0, y0), self.pixel(x1, y0), fx);
251        let bottom = mix(self.pixel(x0, y1), self.pixel(x1, y1), fx);
252        mix(top, bottom, fy)
253    }
254
255    fn pixel(&self, x: u32, y: u32) -> Color {
256        let x = x.min(self.width - 1);
257        let y = y.min(self.height - 1);
258        self.pixels[(y as usize) * (self.width as usize) + (x as usize)]
259    }
260
261    /// Paint into the canvas through `ctm`, restricted to `mask`.
262    pub fn paint(
263        &self,
264        canvas: &mut Canvas,
265        mask: &ClipMask,
266        ctm: Matrix,
267        alpha: f64,
268        mode: BlendMode,
269    ) {
270        let Some(inverse) = ctm.invert() else {
271            return;
272        };
273        let corners = [
274            ctm.apply(Point::new(0.0, 0.0)),
275            ctm.apply(Point::new(1.0, 0.0)),
276            ctm.apply(Point::new(0.0, 1.0)),
277            ctm.apply(Point::new(1.0, 1.0)),
278        ];
279        let min_x = corners
280            .iter()
281            .fold(f64::INFINITY, |min, point| min.min(point.x))
282            .floor()
283            .max(0.0);
284        let max_x = corners
285            .iter()
286            .fold(f64::NEG_INFINITY, |max, point| max.max(point.x))
287            .ceil()
288            .min(f64::from(canvas.width()));
289        let min_y = corners
290            .iter()
291            .fold(f64::INFINITY, |min, point| min.min(point.y))
292            .floor()
293            .max(0.0);
294        let max_y = corners
295            .iter()
296            .fold(f64::NEG_INFINITY, |max, point| max.max(point.y))
297            .ceil()
298            .min(f64::from(canvas.height()));
299        for y in min_y as u32..max_y as u32 {
300            for x in min_x as u32..max_x as u32 {
301                let coverage = mask.alpha(x, y);
302                if coverage <= 0.0 {
303                    continue;
304                }
305                let device = Point::new(f64::from(x) + 0.5, f64::from(y) + 0.5);
306                let user = inverse.apply(device);
307                if !(0.0..=1.0).contains(&user.x) || !(0.0..=1.0).contains(&user.y) {
308                    continue;
309                }
310                // Image space has its origin at the bottom-left, but the first
311                // sample row is the top one.
312                let colour = self.sample(user.x, 1.0 - user.y);
313                canvas.blend_with(x, y, colour, alpha * coverage, mode);
314            }
315        }
316    }
317}
318
319/// The `/Decode` range for each component, defaulting to the identity.
320fn decode_ranges(decode: Option<&Object>, components: usize) -> Vec<(f64, f64)> {
321    let mut ranges = vec![(0.0, 1.0); components];
322    let Some(Object::Array(items)) = decode else {
323        return ranges;
324    };
325    if items.len() < components * 2 {
326        return ranges;
327    }
328    for (slot, pair) in items.chunks_exact(2).enumerate().take(components) {
329        let (Some(from), Some(to)) = (pair[0].as_real(), pair[1].as_real()) else {
330            continue;
331        };
332        ranges[slot] = (from, to);
333    }
334    ranges
335}
336
337/// Turn decoded components (0–1 each) into a colour through `colours`.
338fn colour_at(colours: &ColourSpace, components: &[f64; 4]) -> Color {
339    match colours {
340        ColourSpace::Gray => Color::rgb(components[0], components[0], components[0]),
341        ColourSpace::Rgb => Color::rgb(components[0], components[1], components[2]),
342        ColourSpace::Cmyk => {
343            Color::from_cmyk(components[0], components[1], components[2], components[3])
344        }
345        ColourSpace::Indexed { base, lookup } => {
346            // For an indexed image the decoded value is the index, not a colour
347            // component, so it is scaled back into the table's range.
348            let index = (components[0] * 255.0).round().max(0.0) as usize;
349            let count = base.components();
350            let entry = index * count;
351            let slice = lookup.get(entry..entry + count).unwrap_or(&[]);
352            if slice.len() < count {
353                return Color::BLACK;
354            }
355            let mut table = [0.0_f64; 4];
356            for (slot, byte) in slice.iter().enumerate().take(4) {
357                table[slot] = f64::from(*byte) / 255.0;
358            }
359            colour_at(base, &table)
360        }
361    }
362}
363
364fn mix(left: Color, right: Color, t: f64) -> Color {
365    let t = t.clamp(0.0, 1.0);
366    Color::rgb(
367        left.r * (1.0 - t) + right.r * t,
368        left.g * (1.0 - t) + right.g * t,
369        left.b * (1.0 - t) + right.b * t,
370    )
371}
372
373/// The colour space of an image, resolved to what the sampler needs.
374#[derive(Debug, Clone, PartialEq)]
375enum ColourSpace {
376    Gray,
377    Rgb,
378    Cmyk,
379    Indexed {
380        base: Box<ColourSpace>,
381        lookup: Vec<u8>,
382    },
383}
384
385impl ColourSpace {
386    fn from_object(document: &Document, object: Object) -> Result<Self> {
387        match object {
388            Object::Name(name) => match name.as_slice() {
389                b"DeviceGray" | b"G" | b"CalGray" => Ok(Self::Gray),
390                b"DeviceRGB" | b"RGB" | b"CalRGB" => Ok(Self::Rgb),
391                b"DeviceCMYK" | b"CMYK" => Ok(Self::Cmyk),
392                _ => Err(Error::malformed("unsupported image /ColorSpace")),
393            },
394            Object::Array(items) => {
395                let family = match items.first() {
396                    Some(Object::Name(name)) => name.clone(),
397                    _ => return Err(Error::malformed("image /ColorSpace array family")),
398                };
399                match family.as_slice() {
400                    b"Indexed" | b"I" => {
401                        let base = match items.get(1) {
402                            Some(base) => {
403                                Self::from_object(document, resolve(document, Some(base))?)?
404                            }
405                            None => return Err(Error::malformed("Indexed image without a base")),
406                        };
407                        let lookup = match items.get(3) {
408                            Some(Object::String(string)) => string.as_bytes().to_vec(),
409                            Some(Object::Reference(id)) => document.stream_data(*id)?,
410                            _ => {
411                                return Err(Error::malformed(
412                                    "Indexed image without a lookup table",
413                                ))
414                            }
415                        };
416                        Ok(Self::Indexed {
417                            base: Box::new(base),
418                            lookup,
419                        })
420                    }
421                    b"ICCBased" => {
422                        let stream = match items.get(1) {
423                            Some(Object::Reference(id)) => document.stream(*id)?,
424                            _ => return Err(Error::malformed("ICCBased without a stream")),
425                        };
426                        let components = stream
427                            .dict()
428                            .get(b"N")
429                            .and_then(Object::as_integer)
430                            .unwrap_or(3);
431                        match components {
432                            1 => Ok(Self::Gray),
433                            3 => Ok(Self::Rgb),
434                            4 => Ok(Self::Cmyk),
435                            _ => Err(Error::malformed("unsupported ICCBased components")),
436                        }
437                    }
438                    _ => Err(Error::malformed("unsupported image /ColorSpace array")),
439                }
440            }
441            _ => Err(Error::malformed("unsupported image /ColorSpace value")),
442        }
443    }
444
445    fn components(&self) -> usize {
446        match self {
447            Self::Gray => 1,
448            Self::Rgb => 3,
449            Self::Cmyk => 4,
450            Self::Indexed { .. } => 1,
451        }
452    }
453}
454
455fn integer(dict: &Dictionary, key: &[u8]) -> Result<u32> {
456    dict.get(key)
457        .and_then(Object::as_integer)
458        .and_then(|value| u32::try_from(value).ok())
459        .ok_or_else(|| Error::malformed("image without integer /Width and /Height"))
460}
461
462/// How many components the stream's `/ColorSpace` declares, when it is a name or
463/// a known family — enough to know whether a JPEG is CMYK.
464fn dict_component_count(stream: &Stream) -> Option<usize> {
465    match stream.dict().get(b"ColorSpace") {
466        Some(Object::Name(name)) if name == b"DeviceCMYK" => Some(4),
467        Some(Object::Name(name)) if name == b"DeviceGray" => Some(1),
468        Some(Object::Name(name)) if name == b"DeviceRGB" => Some(3),
469        _ => None,
470    }
471}
472
473/// Widen packed one-bit samples to one byte each, 0 or 255.
474///
475/// PDF pads each row to a byte boundary, so a 1728-pixel fax line occupies 216
476/// bytes; a row shorter than its padding is malformed rather than merely short.
477fn widen_one_bit(data: &[u8], width: u32, height: u32, components: usize) -> Result<Vec<u8>> {
478    if components != 1 {
479        return Err(Error::malformed(
480            "one-bit samples need a single-component colour space",
481        ));
482    }
483    let bits_per_row = usize::try_from(width).unwrap_or(0);
484    let stride = bits_per_row.div_ceil(8);
485    let rows = usize::try_from(height).unwrap_or(0);
486    if data.len() < stride.saturating_mul(rows) {
487        return Err(Error::malformed(
488            "one-bit image data is shorter than its rows",
489        ));
490    }
491    let mut out = Vec::with_capacity(bits_per_row.saturating_mul(rows));
492    for row in 0..rows {
493        for column in 0..bits_per_row {
494            let byte = data[row * stride + column / 8];
495            let shift = 7 - column % 8;
496            let bit = (byte >> shift) & 1;
497            out.push(if bit == 1 { 255 } else { 0 });
498        }
499    }
500    Ok(out)
501}
502
503/// Whether a JPEG carries an Adobe APP14 marker, which is what makes its CMYK
504/// samples stored inverted (PDF 7.4.8).
505///
506/// The marker is `FFEE` then a two-byte length and the identifier `Adobe`; only
507/// the identifier matters here, because the transform byte says whether the
508/// samples are plain CMYK or YCCK, and both are stored inverted.
509fn has_adobe_marker(data: &[u8]) -> bool {
510    let mut index = 2; // past the `FF D8` start-of-image marker
511    while index + 4 <= data.len() {
512        if data[index] != 0xFF {
513            return false;
514        }
515        let marker = data[index + 1];
516        // Segments with no payload.
517        if matches!(marker, 0xD8 | 0x01 | 0xD0..=0xD7) {
518            index += 2;
519            continue;
520        }
521        let length = usize::from(u16::from_be_bytes([data[index + 2], data[index + 3]]));
522        if length < 2 {
523            return false;
524        }
525        if marker == 0xEE {
526            let payload = &data[index + 4..(index + 2 + length).min(data.len())];
527            return payload.starts_with(b"Adobe");
528        }
529        // Start of scan: no more header segments follow.
530        if marker == 0xDA {
531            return false;
532        }
533        index += 2 + length;
534    }
535    false
536}
537
538/// Whether the stream's filter chain ends in `/DCTDecode`.
539fn is_dct(dict: &Dictionary) -> bool {
540    match dict.get(b"Filter") {
541        Some(Object::Name(name)) => name == b"DCTDecode",
542        Some(Object::Array(items)) => items
543            .iter()
544            .rev()
545            .find_map(Object::as_name)
546            .is_some_and(|name| name == b"DCTDecode"),
547        _ => false,
548    }
549}
550
551/// Follow one indirect reference; deeper chains are not needed for images.
552pub(crate) fn resolve(document: &Document, object: Option<&Object>) -> Result<Object> {
553    match object {
554        Some(Object::Reference(id)) => document.get_object(*id),
555        Some(other) => Ok(other.clone()),
556        None => Ok(Object::Null),
557    }
558}
559
560#[cfg(test)]
561mod tests {
562    use super::Image;
563    use crate::canvas::{BlendMode, Canvas, ClipMask, Color};
564    use crate::geom::Matrix;
565
566    fn image(width: u32, height: u32, interpolate: bool) -> Image {
567        let mut pixels = Vec::new();
568        for y in 0..height {
569            for x in 0..width {
570                pixels.push(if (x + y) % 2 == 0 {
571                    Color::BLACK
572                } else {
573                    Color::WHITE
574                });
575            }
576        }
577        Image {
578            width,
579            height,
580            pixels,
581            interpolate,
582        }
583    }
584
585    #[test]
586    fn nearest_sampling_returns_whole_pixels() {
587        let image = image(2, 2, false);
588        assert_eq!(image.sample(0.25, 0.25), Color::BLACK);
589        assert_eq!(image.sample(0.75, 0.25), Color::WHITE);
590        assert_eq!(image.sample(0.25, 0.75), Color::WHITE);
591    }
592
593    #[test]
594    fn bilinear_sampling_blends_neighbours() {
595        let image = image(2, 2, true);
596        let middle = image.sample(0.5, 0.5);
597        assert!((middle.r - 0.5).abs() < 1e-9, "{middle:?}");
598    }
599
600    #[test]
601    fn painting_covers_the_unit_square_transform() {
602        let image = image(2, 2, false);
603        let mut canvas = Canvas::new(4, 4, Color::WHITE);
604        let mask = ClipMask::all(4, 4);
605        // Unit square scaled to 4×4 with y flipped like the page transform.
606        let ctm = Matrix::new(4.0, 0.0, 0.0, -4.0, 0.0, 4.0);
607        image.paint(&mut canvas, &mask, ctm, 1.0, BlendMode::Normal);
608        assert_eq!(canvas.pixel(0, 0), Some([0, 0, 0, 255]));
609        assert_eq!(canvas.pixel(3, 0), Some([255, 255, 255, 255]));
610        assert_eq!(canvas.pixel(0, 3), Some([255, 255, 255, 255]));
611        assert_eq!(canvas.pixel(3, 3), Some([0, 0, 0, 255]));
612    }
613}