Skip to main content

pltrs_render/
mixed.rs

1//! Rasterized parts of vector documents (matplotlib's `MixedModeRenderer`).
2//!
3//! A [`MixedModeRenderer`] forwards drawing to a vector backend until it is
4//! asked to [start rasterizing](Renderer::start_rasterizing): from then on
5//! drawing goes to a raster canvas covering the page at the save
6//! resolution, and when rasterizing [stops](Renderer::stop_rasterizing)
7//! the drawn part of that canvas is placed in the document as one image.
8//!
9//! As matplotlib changes the figure's resolution while rasterizing, the
10//! artists drawn meanwhile compute their geometry in raster pixels at
11//! [`Renderer::raster_dpi`]: the canvas receives exactly the coordinates
12//! (rounding included) that a raster save at that resolution draws.
13
14use pltrs_core::path::convert::SimplifySettings;
15use pltrs_core::{Affine2D, Path, Point, Rgba};
16use pltrs_text::TextRun;
17use pltrs_text::tex::{TexError, TexText};
18
19use crate::collection::PathCollection;
20use crate::filter::{FilterFn, SharedFilter};
21use crate::gc::GraphicsContext;
22use crate::image::RgbaImage;
23use crate::quad_mesh::QuadMesh;
24use crate::raster::{RasterBackendError, RasterRenderer};
25use crate::renderer::{Renderer, TextLines};
26
27/// A vector renderer that draws rasterized artists into a raster canvas
28/// placed in the document as an image (matplotlib's `MixedModeRenderer`).
29pub struct MixedModeRenderer<'a> {
30    vector: &'a mut dyn Renderer,
31    /// The page size in inches.
32    size: (f64, f64),
33    dpi: f64,
34    simplify: SimplifySettings,
35    raster: Option<RasterRenderer>,
36    problem: Option<RasterBackendError>,
37}
38
39impl std::fmt::Debug for MixedModeRenderer<'_> {
40    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
41        f.debug_struct("MixedModeRenderer")
42            .field("size", &self.size)
43            .field("dpi", &self.dpi)
44            .field("rasterizing", &self.raster.is_some())
45            .finish_non_exhaustive()
46    }
47}
48
49impl<'a> MixedModeRenderer<'a> {
50    /// Draws into `vector`, whose page is `width × height` inches,
51    /// rasterizing at `dpi` with the `path.simplify` settings `simplify`.
52    pub fn new(
53        vector: &'a mut dyn Renderer,
54        width: f64,
55        height: f64,
56        dpi: f64,
57        simplify: SimplifySettings,
58    ) -> Self {
59        Self {
60            vector,
61            size: (width, height),
62            dpi,
63            simplify,
64            raster: None,
65            problem: None,
66        }
67    }
68
69    /// Places what is still being rasterized; drawing is over.
70    ///
71    /// # Errors
72    ///
73    /// When a raster canvas could not be created (its part of the drawing
74    /// then went to the vector renderer).
75    pub fn finish(mut self) -> Result<(), RasterBackendError> {
76        self.stop_rasterizing();
77        self.problem.map_or(Ok(()), Err)
78    }
79
80    /// The renderer drawing calls currently go to.
81    fn active(&mut self) -> &mut dyn Renderer {
82        match &mut self.raster {
83            Some(canvas) => canvas,
84            None => &mut *self.vector,
85        }
86    }
87
88    /// The renderer drawing calls currently go to, for queries.
89    fn current(&self) -> &dyn Renderer {
90        match &self.raster {
91            Some(canvas) => canvas,
92            None => &*self.vector,
93        }
94    }
95}
96
97impl Renderer for MixedModeRenderer<'_> {
98    fn canvas_size(&self) -> (f64, f64) {
99        self.current().canvas_size()
100    }
101
102    fn dpi(&self) -> f64 {
103        self.current().dpi()
104    }
105
106    fn points_to_pixels(&self, points: f64) -> f64 {
107        self.current().points_to_pixels(points)
108    }
109
110    fn draw_path(
111        &mut self,
112        gc: &GraphicsContext,
113        path: &Path,
114        transform: &Affine2D,
115        fill: Option<Rgba>,
116    ) {
117        self.active().draw_path(gc, path, transform, fill);
118    }
119
120    fn draw_markers(
121        &mut self,
122        gc: &GraphicsContext,
123        marker: &Path,
124        marker_transform: &Affine2D,
125        path: &Path,
126        transform: &Affine2D,
127        fill: Option<Rgba>,
128    ) {
129        self.active()
130            .draw_markers(gc, marker, marker_transform, path, transform, fill);
131    }
132
133    fn draw_path_collection(&mut self, gc: &GraphicsContext, collection: &PathCollection<'_>) {
134        self.active().draw_path_collection(gc, collection);
135    }
136
137    fn draw_quad_mesh(&mut self, gc: &GraphicsContext, mesh: &QuadMesh<'_>) {
138        self.active().draw_quad_mesh(gc, mesh);
139    }
140
141    fn draw_tex(
142        &mut self,
143        gc: &GraphicsContext,
144        run: &TextRun,
145        tex: &TexText,
146        origin: Point,
147        angle: f64,
148    ) -> Result<(), TexError> {
149        self.active().draw_tex(gc, run, tex, origin, angle)
150    }
151
152    fn draw_gouraud_triangles(
153        &mut self,
154        gc: &GraphicsContext,
155        triangles: &[[Point; 3]],
156        colors: &[[Rgba; 3]],
157        transform: &Affine2D,
158    ) {
159        self.active()
160            .draw_gouraud_triangles(gc, triangles, colors, transform);
161    }
162
163    fn draw_image(
164        &mut self,
165        gc: &GraphicsContext,
166        origin: Point,
167        image: &RgbaImage,
168        transform: Option<&Affine2D>,
169    ) {
170        self.active().draw_image(gc, origin, image, transform);
171    }
172
173    fn draw_text(&mut self, gc: &GraphicsContext, run: &TextRun, origin: Point, angle: f64) {
174        self.active().draw_text(gc, run, origin, angle);
175    }
176
177    fn draw_text_lines(&mut self, gc: &GraphicsContext, text: &TextLines<'_>) -> bool {
178        self.active().draw_text_lines(gc, text)
179    }
180
181    fn takes_texts_whole(&self) -> bool {
182        self.current().takes_texts_whole()
183    }
184
185    fn rounds_glyph_positions(&self) -> bool {
186        self.current().rounds_glyph_positions()
187    }
188
189    fn open_group(&mut self, name: &str, gid: Option<&str>) {
190        self.active().open_group(name, gid);
191    }
192
193    /// Filters only while rasterizing, where the raster canvas draws
194    /// (matplotlib's mixed renderer hands `start_filter` to its current
195    /// renderer).
196    fn start_filter(&mut self) {
197        self.active().start_filter();
198    }
199
200    fn stop_filter(&mut self, filter: &FilterFn<'_>) {
201        self.active().stop_filter(filter);
202    }
203
204    fn stop_shared_filter(&mut self, filter: &SharedFilter) {
205        self.active().stop_shared_filter(filter);
206    }
207
208    fn close_group(&mut self, name: &str) {
209        self.active().close_group(name);
210    }
211
212    fn open_part_group(&mut self, name: &str, gid: Option<&str>) {
213        self.active().open_part_group(name, gid);
214    }
215
216    fn close_part_group(&mut self, name: &str) {
217        self.active().close_part_group(name);
218    }
219
220    /// A raster canvas of the page at the save resolution receives the
221    /// drawing from now on.
222    fn start_rasterizing(&mut self) {
223        let (width, height) = self.size;
224        match RasterRenderer::new(width * self.dpi, height * self.dpi, self.dpi) {
225            Ok(canvas) => self.raster = Some(canvas.with_simplify(self.simplify)),
226            Err(err) => {
227                self.problem.get_or_insert(err);
228            }
229        }
230    }
231
232    /// The drawn part of the raster canvas becomes an image of the
233    /// document, placed with a default graphics context.
234    fn stop_rasterizing(&mut self) {
235        let Some(canvas) = self.raster.take() else {
236            return;
237        };
238        let image = canvas.into_image();
239        let Some(bounds) = image.opaque_bounds() else {
240            return;
241        };
242        let (left, _, _, bottom) = bounds;
243        let height = self.size.1 * self.dpi;
244        // From raster pixels to the vector canvas's units (points, or the
245        // figure's pixels for PGF): matplotlib's `_figdpi / dpi`.
246        let to_canvas = self.vector.canvas_size().1 / self.size.1 / self.dpi;
247        let origin = Point::new(
248            left as f64 * to_canvas,
249            (height - bottom as f64) * to_canvas,
250        );
251        self.vector.draw_image(
252            &GraphicsContext::default(),
253            origin,
254            &image.crop(bounds),
255            None,
256        );
257    }
258
259    /// The save resolution while a raster canvas receives the drawing.
260    fn raster_dpi(&self) -> Option<f64> {
261        self.raster.as_ref().map(|_| self.dpi)
262    }
263
264    fn option_image_nocomposite(&self) -> bool {
265        self.current().option_image_nocomposite()
266    }
267
268    fn option_scale_image(&self) -> bool {
269        self.current().option_scale_image()
270    }
271
272    fn image_magnification(&self) -> f64 {
273        self.current().image_magnification()
274    }
275}
276
277#[cfg(test)]
278mod tests {
279    use super::*;
280    use crate::svg::{SvgOptions, SvgRenderer};
281
282    #[test]
283    fn rasterized_drawing_becomes_one_cropped_image() {
284        let mut svg = SvgRenderer::new(72.0, 36.0, 144.0, SvgOptions::default()).unwrap();
285        let mut mixed =
286            MixedModeRenderer::new(&mut svg, 1.0, 0.5, 144.0, SimplifySettings::default());
287        assert_eq!(mixed.raster_dpi(), None);
288        assert_eq!(
289            mixed.points_to_pixels(1.0),
290            1.0,
291            "the document is in points"
292        );
293        mixed.start_rasterizing();
294        assert_eq!(mixed.raster_dpi(), Some(144.0));
295        assert_eq!(mixed.points_to_pixels(1.0), 2.0, "the canvas is in pixels");
296        assert_eq!(mixed.canvas_size(), (144.0, 72.0));
297        assert_eq!(mixed.image_magnification(), 1.0);
298        assert!(!mixed.option_scale_image());
299        let gc = GraphicsContext {
300            linewidth: 0.0,
301            ..GraphicsContext::default()
302        };
303        // A 20 × 10 pixel red rectangle at (40, 20) pixels: 10 × 5 pt at
304        // (20, 10) pt.
305        let place = Affine2D::scaling(20.0, 10.0).translate(40.0, 20.0);
306        mixed.draw_path(
307            &gc,
308            &Path::unit_rectangle(),
309            &place,
310            Some(Rgba::new(1.0, 0.0, 0.0, 1.0)),
311        );
312        mixed.stop_rasterizing();
313        assert_eq!(mixed.raster_dpi(), None);
314        mixed.finish().unwrap();
315        let document = svg.finish().unwrap();
316        assert_eq!(document.matches("<image").count(), 1);
317        assert!(document.contains("x=\"20\""), "{document}");
318        assert!(document.contains("width=\"10\" height=\"5\""), "{document}");
319    }
320
321    #[test]
322    fn nothing_drawn_places_no_image() {
323        let mut svg = SvgRenderer::new(72.0, 36.0, 72.0, SvgOptions::default()).unwrap();
324        let mut mixed =
325            MixedModeRenderer::new(&mut svg, 1.0, 0.5, 72.0, SimplifySettings::default());
326        mixed.start_rasterizing();
327        mixed.stop_rasterizing();
328        mixed.finish().unwrap();
329        let document = svg.finish().unwrap();
330        assert!(!document.contains("<image"));
331    }
332}