Skip to main content

pdf2_render/
walk.rs

1//! The content-stream walker: graphics state, path construction, painting
2//! operators, clipping and dash handling.
3//!
4//! The walker reuses [`pdf2::Parser`] (the same tokenizer the object parser
5//! uses) and maps operators to draw calls. Operators it does not implement —
6//! text and images, until the next round — are counted and reported, never
7//! fatal: a page with text still paints its paths.
8
9use std::collections::BTreeMap;
10use std::fmt;
11
12use pdf2::lexer::{is_delimiter, is_whitespace};
13use pdf2::{Dictionary, Document, Encoding, Object, Page, Parser, Token};
14
15use crate::canvas::{Canvas, ClipMask, Color};
16use crate::font::Font;
17use crate::geom::{Matrix, Point};
18use crate::image::{resolve, Image};
19use crate::path::{dash_polyline, stroke_outline, Cap, Dash, Join, Path};
20use crate::raster::{clip_mask, fill_polygons};
21
22/// What a page render should look like.
23#[derive(Debug, Clone, PartialEq)]
24pub struct RenderOptions {
25    /// Device pixels per PDF point: `1.0` is 72 dpi.
26    pub scale: f64,
27    /// Canvas background.
28    pub background: Color,
29}
30
31impl Default for RenderOptions {
32    fn default() -> Self {
33        Self {
34            scale: 1.0,
35            background: Color::WHITE,
36        }
37    }
38}
39
40/// What happened while rendering, beyond the pixels.
41#[derive(Debug, Clone, Default, PartialEq)]
42pub struct Report {
43    /// Operators that were recognised but not drawn, with how often each
44    /// appeared. Text and image operators land here until they are implemented.
45    pub unsupported: BTreeMap<String, usize>,
46}
47
48impl Report {
49    /// Total unsupported operators.
50    pub fn unsupported_total(&self) -> usize {
51        self.unsupported.values().sum()
52    }
53
54    fn note(&mut self, operator: &[u8]) {
55        let name = String::from_utf8_lossy(operator).into_owned();
56        *self.unsupported.entry(name).or_insert(0) += 1;
57    }
58}
59
60impl fmt::Display for Report {
61    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
62        if self.unsupported.is_empty() {
63            return write!(formatter, "all operators supported");
64        }
65        let mut first = true;
66        for (name, count) in &self.unsupported {
67            if !first {
68                write!(formatter, ", ")?;
69            }
70            first = false;
71            write!(formatter, "{name}×{count}")?;
72        }
73        Ok(())
74    }
75}
76
77/// A rendered page.
78#[derive(Debug, Clone)]
79pub struct RenderedPage {
80    /// The raster.
81    pub canvas: Canvas,
82    /// What was skipped.
83    pub report: Report,
84}
85
86/// A document, page number (zero based) and rasterisation scale in one call.
87pub fn render_page_number(
88    document: &Document,
89    page_index: usize,
90    options: &RenderOptions,
91) -> crate::Result<RenderedPage> {
92    let page = document.page(page_index)?;
93    render_page(document, &page, options)
94}
95
96/// Rasterise one page.
97pub fn render_page(
98    document: &Document,
99    page: &Page,
100    options: &RenderOptions,
101) -> crate::Result<RenderedPage> {
102    let scale = if options.scale.is_finite() && options.scale > 0.0 {
103        options.scale
104    } else {
105        1.0
106    };
107    let media = page
108        .media_box
109        .unwrap_or(pdf2::Rect::new(0.0, 0.0, 612.0, 792.0));
110    let width = ((media.width() * scale).round().max(1.0)) as u32;
111    let height = ((media.height() * scale).round().max(1.0)) as u32;
112    let mut canvas = Canvas::new(width, height, options.background);
113    let mut report = Report::default();
114
115    // PDF user space to device space: shift the media box origin to (0, 0) and
116    // flip the y axis, which grows downwards in the raster.
117    let base = Matrix::new(scale, 0.0, 0.0, -scale, -media.x0 * scale, media.y1 * scale);
118
119    let content = document.page_content(page)?;
120    let mut walker = Walker {
121        canvas: &mut canvas,
122        report: &mut report,
123        document,
124        resources: page.resources.clone(),
125        state: State::new(base),
126        stack: Vec::new(),
127        path: Path::new(),
128        pending_clip: None,
129        mask: ClipMask::all(width, height),
130    };
131    walker.run(&content)?;
132    Ok(RenderedPage { canvas, report })
133}
134
135/// The part of the graphics state that painting depends on.
136#[derive(Debug, Clone)]
137struct State {
138    ctm: Matrix,
139    line_width: f64,
140    cap: Cap,
141    join: Join,
142    dash: Dash,
143    fill: Color,
144    stroke: Color,
145    font: Option<Font>,
146    font_size: f64,
147    char_spacing: f64,
148    word_spacing: f64,
149    horizontal_scale: f64,
150    leading: f64,
151    rise: f64,
152    text_matrix: Matrix,
153    line_matrix: Matrix,
154}
155
156impl State {
157    fn new(ctm: Matrix) -> Self {
158        Self {
159            ctm,
160            line_width: 1.0,
161            cap: Cap::Butt,
162            join: Join::Miter,
163            dash: Dash::solid(),
164            fill: Color::BLACK,
165            stroke: Color::BLACK,
166            font: None,
167            font_size: 0.0,
168            char_spacing: 0.0,
169            word_spacing: 0.0,
170            horizontal_scale: 1.0,
171            leading: 0.0,
172            rise: 0.0,
173            text_matrix: Matrix::IDENTITY,
174            line_matrix: Matrix::IDENTITY,
175        }
176    }
177}
178
179struct Walker<'a> {
180    canvas: &'a mut Canvas,
181    report: &'a mut Report,
182    document: &'a Document,
183    resources: Option<Dictionary>,
184    state: State,
185    stack: Vec<(State, ClipMask)>,
186    path: Path,
187    pending_clip: Option<bool>,
188    mask: ClipMask,
189}
190
191impl Walker<'_> {
192    fn run(&mut self, content: &[u8]) -> crate::Result<()> {
193        let mut parser = Parser::new(content);
194        let mut operands: Vec<Object> = Vec::new();
195        loop {
196            match parser.peek_token()? {
197                Token::Eof => break,
198                Token::Keyword(_) => {
199                    let operator = match parser.next_token()? {
200                        Token::Keyword(operator) => operator,
201                        _ => return Err(crate::Error::malformed("content-stream operator")),
202                    };
203                    self.execute(&operator, &mut operands, &mut parser)?;
204                    operands.clear();
205                }
206                _ => {
207                    operands.push(parser.parse_object()?);
208                }
209            }
210        }
211        Ok(())
212    }
213
214    fn execute(
215        &mut self,
216        operator: &[u8],
217        operands: &mut [Object],
218        parser: &mut Parser<'_>,
219    ) -> crate::Result<()> {
220        match operator {
221            b"q" => {
222                self.stack.push((self.state.clone(), self.mask.clone()));
223            }
224            b"Q" => {
225                if let Some((state, mask)) = self.stack.pop() {
226                    self.state = state;
227                    self.mask = mask;
228                }
229            }
230            b"cm" => {
231                if let Some(matrix) = matrix_operand(operands) {
232                    self.state.ctm = matrix.multiply(self.state.ctm);
233                }
234            }
235            b"w" => self.state.line_width = number(operands, 0),
236            b"J" => {
237                self.state.cap = match integer(operands, 0) {
238                    1 => Cap::Round,
239                    2 => Cap::Square,
240                    _ => Cap::Butt,
241                }
242            }
243            b"j" => {
244                self.state.join = match integer(operands, 0) {
245                    1 => Join::Round,
246                    2 => Join::Bevel,
247                    _ => Join::Miter,
248                }
249            }
250            b"M" => {}
251            b"d" => self.state.dash = dash_operand(operands),
252            b"m" => {
253                if let Some(point) = point_operand(operands, 0) {
254                    self.path.move_to(point);
255                }
256            }
257            b"l" => {
258                if let Some(point) = point_operand(operands, 0) {
259                    self.path.line_to(point);
260                }
261            }
262            b"c" => {
263                if let (Some(c1), Some(c2), Some(to)) = (
264                    point_operand(operands, 0),
265                    point_operand(operands, 1),
266                    point_operand(operands, 2),
267                ) {
268                    self.path.curve_to(c1, c2, to);
269                }
270            }
271            b"v" | b"y" => {
272                // `v` and `y` are shorthand curves; draw them as a straight
273                // line to the end point, which keeps the path closed.
274                if let Some(to) = point_operand(operands, 1) {
275                    self.path.line_to(to);
276                }
277            }
278            b"h" => self.path.close(),
279            b"re" => {
280                let x = number(operands, 0);
281                let y = number(operands, 1);
282                let width = number(operands, 2);
283                let height = number(operands, 3);
284                self.path.add_rect(x, y, width, height);
285            }
286            b"S" => self.paint(Paint::Stroke, false)?,
287            b"s" => {
288                self.path.close();
289                self.paint(Paint::Stroke, false)?;
290            }
291            b"f" | b"F" => self.paint(Paint::Fill, false)?,
292            b"f*" => self.paint(Paint::Fill, true)?,
293            b"B" => self.paint(Paint::Both, false)?,
294            b"B*" => self.paint(Paint::Both, true)?,
295            b"b" => {
296                self.path.close();
297                self.paint(Paint::Both, false)?;
298            }
299            b"b*" => {
300                self.path.close();
301                self.paint(Paint::Both, true)?;
302            }
303            b"W" => self.pending_clip = Some(false),
304            b"W*" => self.pending_clip = Some(true),
305            b"n" => {
306                self.apply_pending_clip();
307                self.path = Path::new();
308            }
309            b"g" => {
310                self.state.fill = Color::rgb(
311                    number(operands, 0),
312                    number(operands, 0),
313                    number(operands, 0),
314                )
315            }
316            b"G" => {
317                self.state.stroke = Color::rgb(
318                    number(operands, 0),
319                    number(operands, 0),
320                    number(operands, 0),
321                )
322            }
323            b"rg" => {
324                self.state.fill = Color::rgb(
325                    number(operands, 0),
326                    number(operands, 1),
327                    number(operands, 2),
328                );
329            }
330            b"RG" => {
331                self.state.stroke = Color::rgb(
332                    number(operands, 0),
333                    number(operands, 1),
334                    number(operands, 2),
335                );
336            }
337            b"k" => {
338                self.state.fill = Color::from_cmyk(
339                    number(operands, 0),
340                    number(operands, 1),
341                    number(operands, 2),
342                    number(operands, 3),
343                );
344            }
345            b"K" => {
346                self.state.stroke = Color::from_cmyk(
347                    number(operands, 0),
348                    number(operands, 1),
349                    number(operands, 2),
350                    number(operands, 3),
351                );
352            }
353            b"BT" => {
354                self.state.text_matrix = Matrix::IDENTITY;
355                self.state.line_matrix = Matrix::IDENTITY;
356            }
357            b"ET" => {}
358            b"Tf" => {
359                let name = match operands.first() {
360                    Some(Object::Name(name)) => name.clone(),
361                    _ => return Err(crate::Error::malformed("/Tf needs a font name")),
362                };
363                self.state.font_size = number(operands, 1);
364                self.state.font = self.load_font(&name);
365            }
366            b"Td" | b"TD" => {
367                let tx = number(operands, 0);
368                let ty = number(operands, 1);
369                self.state.line_matrix =
370                    Matrix::new(1.0, 0.0, 0.0, 1.0, tx, ty).multiply(self.state.line_matrix);
371                self.state.text_matrix = self.state.line_matrix;
372                if operator == b"TD" {
373                    self.state.leading = -ty;
374                }
375            }
376            b"T*" => {
377                self.state.line_matrix = Matrix::new(1.0, 0.0, 0.0, 1.0, 0.0, -self.state.leading)
378                    .multiply(self.state.line_matrix);
379                self.state.text_matrix = self.state.line_matrix;
380            }
381            b"Tm" => {
382                if let Some(matrix) = matrix_operand(operands) {
383                    self.state.line_matrix = matrix;
384                    self.state.text_matrix = matrix;
385                }
386            }
387            b"TL" => self.state.leading = number(operands, 0),
388            b"Tc" => self.state.char_spacing = number(operands, 0),
389            b"Tw" => self.state.word_spacing = number(operands, 0),
390            b"Tz" => self.state.horizontal_scale = number(operands, 0) / 100.0,
391            b"Ts" => self.state.rise = number(operands, 0),
392            b"Tj" => {
393                if let Some(Object::String(string)) = operands.first() {
394                    let bytes = string.as_bytes().to_vec();
395                    self.show_text(&bytes)?;
396                }
397            }
398            b"'" => {
399                self.state.line_matrix = Matrix::new(1.0, 0.0, 0.0, 1.0, 0.0, -self.state.leading)
400                    .multiply(self.state.line_matrix);
401                self.state.text_matrix = self.state.line_matrix;
402                if let Some(Object::String(string)) = operands.first() {
403                    let bytes = string.as_bytes().to_vec();
404                    self.show_text(&bytes)?;
405                }
406            }
407            b"\"" => {
408                self.state.word_spacing = number(operands, 0);
409                self.state.char_spacing = number(operands, 1);
410                self.state.line_matrix = Matrix::new(1.0, 0.0, 0.0, 1.0, 0.0, -self.state.leading)
411                    .multiply(self.state.line_matrix);
412                self.state.text_matrix = self.state.line_matrix;
413                if let Some(Object::String(string)) = operands.get(2) {
414                    let bytes = string.as_bytes().to_vec();
415                    self.show_text(&bytes)?;
416                }
417            }
418            b"TJ" => {
419                if let Some(Object::Array(items)) = operands.first() {
420                    for item in items {
421                        match item {
422                            Object::String(string) => {
423                                let bytes = string.as_bytes().to_vec();
424                                self.show_text(&bytes)?;
425                            }
426                            Object::Integer(adjustment) => {
427                                self.adjust_text(*adjustment as f64);
428                            }
429                            Object::Real(adjustment) => self.adjust_text(*adjustment),
430                            _ => {}
431                        }
432                    }
433                }
434            }
435            b"Do" => {
436                if let Some(Object::Name(name)) = operands.first() {
437                    let name = name.clone();
438                    self.draw_image(&name)?;
439                }
440            }
441            b"BI" => {
442                skip_inline_image(parser)?;
443                self.report.note(operator);
444            }
445            _ => self.report.note(operator),
446        }
447        Ok(())
448    }
449
450    fn paint(&mut self, what: Paint, even_odd: bool) -> crate::Result<()> {
451        self.apply_pending_clip();
452        let ctm = self.state.ctm;
453        let scale = determinant_scale(ctm);
454        let polylines = self.path.flatten(ctm);
455        let painted = match what {
456            Paint::Fill | Paint::Both => true,
457            Paint::Stroke => false,
458        };
459        if painted && !polylines.is_empty() {
460            fill_polygons(
461                self.canvas,
462                &self.mask,
463                &polylines,
464                self.state.fill,
465                even_odd,
466                1.0,
467            );
468        }
469        if matches!(what, Paint::Stroke | Paint::Both) {
470            let mut stroked: Vec<Vec<Point>> = Vec::new();
471            for polyline in &polylines {
472                stroked.extend(dash_polyline(polyline, &self.state.dash, scale));
473            }
474            let outline = stroke_outline(&stroked, self.state.line_width * scale, self.state.cap);
475            if !outline.is_empty() {
476                fill_polygons(
477                    self.canvas,
478                    &self.mask,
479                    &outline,
480                    self.state.stroke,
481                    false,
482                    1.0,
483                );
484            }
485        }
486        self.path = Path::new();
487        Ok(())
488    }
489
490    fn adjust_text(&mut self, adjustment: f64) {
491        let tx = -adjustment / 1000.0 * self.state.font_size * self.state.horizontal_scale;
492        self.state.text_matrix =
493            Matrix::new(1.0, 0.0, 0.0, 1.0, tx, 0.0).multiply(self.state.text_matrix);
494    }
495
496    fn show_text(&mut self, bytes: &[u8]) -> crate::Result<()> {
497        let Some(font) = self.state.font.clone() else {
498            return Ok(());
499        };
500        for &code in bytes {
501            if let Some(glyph) = font.glyph(code) {
502                if !glyph.contours.is_empty() {
503                    let scale = Matrix::new(
504                        self.state.font_size * self.state.horizontal_scale,
505                        0.0,
506                        0.0,
507                        self.state.font_size,
508                        0.0,
509                        self.state.rise,
510                    );
511                    let transform = scale
512                        .multiply(self.state.text_matrix)
513                        .multiply(self.state.ctm);
514                    let polygons: Vec<Vec<Point>> = glyph
515                        .contours
516                        .iter()
517                        .map(|contour| {
518                            contour
519                                .iter()
520                                .map(|point| transform.apply(*point))
521                                .collect()
522                        })
523                        .collect();
524                    fill_polygons(
525                        self.canvas,
526                        &self.mask,
527                        &polygons,
528                        self.state.fill,
529                        false,
530                        1.0,
531                    );
532                }
533            }
534            let mut advance = font.advance(code) * self.state.font_size + self.state.char_spacing;
535            if code == b' ' {
536                advance += self.state.word_spacing;
537            }
538            advance *= self.state.horizontal_scale;
539            self.state.text_matrix =
540                Matrix::new(1.0, 0.0, 0.0, 1.0, advance, 0.0).multiply(self.state.text_matrix);
541        }
542        Ok(())
543    }
544
545    fn draw_image(&mut self, name: &[u8]) -> crate::Result<()> {
546        let Some(resources) = self.resources.clone() else {
547            self.report.note(b"Do");
548            return Ok(());
549        };
550        let xobjects = match resolve(self.document, resources.get(b"XObject")) {
551            Ok(Object::Dictionary(xobjects)) => xobjects,
552            _ => {
553                self.report.note(b"Do");
554                return Ok(());
555            }
556        };
557        let entry = match xobjects.get(name) {
558            Some(entry) => entry.clone(),
559            None => {
560                self.report.note(b"Do");
561                return Ok(());
562            }
563        };
564        let object = resolve(self.document, Some(&entry))?;
565        let Object::Stream(stream) = object else {
566            self.report.note(b"Do");
567            return Ok(());
568        };
569        if !matches!(stream.dict().get(b"Subtype"), Some(Object::Name(name)) if name == b"Image") {
570            self.report.note(b"Do");
571            return Ok(());
572        }
573        match Image::from_stream(self.document, &stream) {
574            Ok(image) => {
575                image.paint(self.canvas, &self.mask, self.state.ctm);
576            }
577            // An image we cannot decode is reported, not fatal: the rest of the
578            // page still renders.
579            Err(_) => self.report.note(b"Do"),
580        }
581        Ok(())
582    }
583
584    fn load_font(&mut self, name: &[u8]) -> Option<Font> {
585        let resources = self.resources.clone()?;
586        let fonts = match resolve(self.document, resources.get(b"Font")) {
587            Ok(Object::Dictionary(fonts)) => fonts,
588            _ => return None,
589        };
590        let entry = fonts.get(name)?.clone();
591        let font_object = resolve(self.document, Some(&entry)).ok()?;
592        let Object::Dictionary(font) = font_object else {
593            return None;
594        };
595        let encoding = self.encoding_for(&font);
596        if let Some(descriptor) = font.get(b"FontDescriptor") {
597            let descriptor = resolve(self.document, Some(descriptor)).ok()?;
598            if let Object::Dictionary(descriptor) = descriptor {
599                if let Some(font_file) = descriptor.get(b"FontFile2") {
600                    let data = match font_file {
601                        Object::Reference(id) => self.document.stream_data(*id).ok(),
602                        _ => None,
603                    };
604                    if let Some(data) = data {
605                        if let Some(font) = Font::true_type(encoding.clone(), data) {
606                            return Some(font);
607                        }
608                    }
609                }
610            }
611        }
612        Some(Font::builtin(encoding))
613    }
614
615    fn encoding_for(&self, font: &Dictionary) -> Encoding {
616        let Some(encoding_object) = font.get(b"Encoding") else {
617            return Encoding::standard();
618        };
619        let Ok(encoding_object) = resolve(self.document, Some(encoding_object)) else {
620            return Encoding::standard();
621        };
622        let mut encoding = Encoding::from_object(Some(&encoding_object)).unwrap_or_default();
623        if let Object::Dictionary(dict) = &encoding_object {
624            if let Some(differences) = dict.get(b"Differences") {
625                if let Ok(Object::Array(items)) = resolve(self.document, Some(differences)) {
626                    let _ = encoding.apply_differences(&items);
627                }
628            }
629        }
630        encoding
631    }
632
633    fn apply_pending_clip(&mut self) {
634        let Some(even_odd) = self.pending_clip.take() else {
635            return;
636        };
637        let polylines = self.path.flatten(self.state.ctm);
638        let mask = clip_mask(
639            self.canvas.width(),
640            self.canvas.height(),
641            &polylines,
642            even_odd,
643        );
644        self.mask.intersect(&mask);
645    }
646}
647
648#[derive(Debug, Clone, Copy, PartialEq, Eq)]
649enum Paint {
650    Fill,
651    Stroke,
652    Both,
653}
654
655fn determinant_scale(ctm: Matrix) -> f64 {
656    let determinant = ctm.a * ctm.d - ctm.b * ctm.c;
657    determinant.abs().sqrt()
658}
659
660fn number(operands: &[Object], index: usize) -> f64 {
661    operands.get(index).and_then(Object::as_real).unwrap_or(0.0)
662}
663
664fn integer(operands: &[Object], index: usize) -> i64 {
665    operands
666        .get(index)
667        .and_then(Object::as_integer)
668        .unwrap_or(0)
669}
670
671fn matrix_operand(operands: &[Object]) -> Option<Matrix> {
672    if operands.len() < 6 {
673        return None;
674    }
675    Some(Matrix::new(
676        number(operands, 0),
677        number(operands, 1),
678        number(operands, 2),
679        number(operands, 3),
680        number(operands, 4),
681        number(operands, 5),
682    ))
683}
684
685fn point_operand(operands: &[Object], start: usize) -> Option<Point> {
686    if operands.len() < start + 2 {
687        return None;
688    }
689    Some(Point::new(
690        number(operands, start),
691        number(operands, start + 1),
692    ))
693}
694
695fn dash_operand(operands: &[Object]) -> Dash {
696    let pattern = match operands.first() {
697        Some(Object::Array(items)) => items
698            .iter()
699            .filter_map(Object::as_real)
700            .collect::<Vec<f64>>(),
701        _ => Vec::new(),
702    };
703    let phase = number(operands, 1);
704    Dash { pattern, phase }
705}
706
707/// Skip inline image data (`BI` … `EI`), which cannot be tokenised.
708fn skip_inline_image(parser: &mut Parser<'_>) -> crate::Result<()> {
709    let start = parser.raw_position();
710    let content = parser.content();
711    let found = content
712        .get(start..)
713        .and_then(|rest| find_operator(rest, b"EI"))
714        .ok_or_else(|| crate::Error::malformed("inline image without a closing EI"))?;
715    parser.seek(start + found + 2);
716    Ok(())
717}
718
719fn find_operator(haystack: &[u8], needle: &[u8]) -> Option<usize> {
720    let mut index = 0;
721    while index + needle.len() <= haystack.len() {
722        if &haystack[index..index + needle.len()] == needle {
723            let delimiter = |byte: u8| is_whitespace(byte) || is_delimiter(byte);
724            let before_ok = index == 0 || delimiter(haystack[index - 1]);
725            let after = index + needle.len();
726            let after_ok = after >= haystack.len() || delimiter(haystack[after]);
727            if before_ok && after_ok {
728                return Some(index);
729            }
730        }
731        index += 1;
732    }
733    None
734}
735
736#[cfg(test)]
737mod tests {
738    use super::{dash_operand, Report};
739    use pdf2::Object;
740
741    #[test]
742    fn reports_collect_operator_counts_in_order() {
743        let mut report = Report::default();
744        report.note(b"Tj");
745        report.note(b"Tj");
746        report.note(b"Do");
747        assert_eq!(report.unsupported_total(), 3);
748        assert_eq!(report.unsupported.get("Tj"), Some(&2));
749        assert_eq!(report.to_string(), "Do×1, Tj×2");
750    }
751
752    #[test]
753    fn dash_operands_default_to_solid() {
754        assert!(dash_operand(&[]).is_solid());
755        let dash = dash_operand(&[
756            Object::array([Object::Integer(4), Object::Integer(2)]),
757            Object::Integer(1),
758        ]);
759        assert_eq!(dash.pattern, vec![4.0, 2.0]);
760        assert_eq!(dash.phase, 1.0);
761    }
762}