pltrs-render 0.1.0

Renderer abstraction with raster (PNG), SVG, PDF, PostScript and PGF backends
Documentation
//! The raster backend: matplotlib's `RendererAgg` on top of `pltrs-raster`.
//!
//! Every drawing call conditions its geometry with pltrs-core's port of
//! matplotlib's path converters, chained exactly as `_backend_agg.h` chains
//! them, and rasterizes it with pltrs-raster's port of Agg, so the pixels
//! match matplotlib's Agg output.

mod bitmap;
mod condition;
mod draw;
mod filter;
mod glyph;
mod mono;
mod tex;
mod text;

use std::cell::RefCell;
use std::fmt;
use std::rc::Rc;

use pltrs_codec::png::{self, EncodeError, ImageRef};
use pltrs_core::Path;
use pltrs_core::path::convert::SimplifySettings;
use pltrs_raster::{Mask, Painter, Pixmap, RasterError, Rgba8};

use crate::gc::ClipPath;
use crate::image::RgbaImage;
use crate::vector::PngMetadata;

pub use self::bitmap::{GlyphBitmap, GlyphShape, glyph_axis_aligned, render_glyph};

pltrs_core::thread_state! {
    /// What says whether the thread's raster canvases draw text as paths.
    static TEXTS_AS_PATHS: RefCell<Option<Rc<dyn Fn() -> bool>>> = const { RefCell::new(None) };
}

/// Makes the raster canvases of this thread draw text as paths whenever
/// `rule` says so (or as glyphs again, with `None`), as matplotlib's Agg
/// renderer does without its own `draw_text`: `RendererBase.draw_text`
/// fills the outlines `TextToPath` makes of the text
/// (`_draw_text_as_path`). The rule is asked each time a canvas draws
/// text, so that it can follow the program (pltrs (Python): whether
/// `RendererAgg.draw_text` is taken away).
pub fn set_texts_as_paths(rule: Option<Rc<dyn Fn() -> bool>>) {
    TEXTS_AS_PATHS.set(rule);
}

/// Whether the thread's raster canvases draw text as paths now.
fn texts_as_paths() -> bool {
    TEXTS_AS_PATHS
        .with_borrow(Clone::clone)
        .is_some_and(|rule| rule())
}

/// Why a raster canvas could not be created or encoded.
#[derive(Debug)]
pub enum RasterBackendError {
    /// The canvas size is invalid (matplotlib caps each side below 2²³).
    Canvas(RasterError),
    /// The resolution is not a positive finite number.
    Dpi(f64),
    /// PNG encoding failed.
    Encode(EncodeError),
}

impl fmt::Display for RasterBackendError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Canvas(err) => write!(f, "invalid canvas: {err}"),
            Self::Dpi(dpi) => write!(f, "dpi must be positive, got {dpi}"),
            Self::Encode(err) => write!(f, "PNG encoding failed: {err}"),
        }
    }
}

impl std::error::Error for RasterBackendError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Canvas(err) => Some(err),
            Self::Encode(err) => Some(err),
            Self::Dpi(_) => None,
        }
    }
}

/// A rasterized clip path, reused while the same clip path and transform
/// come back (matplotlib's `lastclippath` cache).
#[derive(Debug)]
struct CachedClip {
    key: ClipPath,
    mask: Mask,
}

/// Renders into an RGBA pixel buffer exactly like matplotlib's
/// `RendererAgg` (straight alpha, initially transparent white).
#[derive(Debug)]
pub struct RasterRenderer {
    pixmap: Pixmap,
    painter: Painter,
    /// Canvas size as requested; the buffer holds its truncated size, as
    /// matplotlib's `RendererAgg(int(width), int(height), dpi)` does.
    size: (f64, f64),
    dpi: f64,
    simplify: SimplifySettings,
    /// Long unfilled paths are drawn in pieces of at most this many
    /// vertices (matplotlib's `agg.path.chunksize`; 0 never splits).
    chunksize: usize,
    clip_cache: Option<CachedClip>,
    /// The last conditioned path, kept for its allocations.
    conditioned: Path,
    /// The last conditioned path with its curves flattened, likewise.
    flattened: Path,
    /// Canvases set aside while filtered artists draw (`None` where the
    /// canvas to draw them on could not be made).
    set_aside: Vec<Option<Pixmap>>,
    errors: Vec<RasterError>,
}

impl RasterRenderer {
    /// A canvas of `width × height` display pixels at `dpi`.
    pub fn new(width: f64, height: f64, dpi: f64) -> Result<Self, RasterBackendError> {
        if !(dpi.is_finite() && dpi > 0.0) {
            return Err(RasterBackendError::Dpi(dpi));
        }
        let pixmap = Pixmap::filled(width as u32, height as u32, Rgba8::TRANSPARENT_WHITE)
            .map_err(RasterBackendError::Canvas)?;
        Ok(Self {
            pixmap,
            painter: Painter::new(),
            size: (width, height),
            dpi,
            simplify: SimplifySettings::default(),
            chunksize: 0,
            clip_cache: None,
            conditioned: Path::default(),
            flattened: Path::default(),
            set_aside: Vec::new(),
            errors: Vec::new(),
        })
    }

    /// Uses matplotlib's `path.simplify` / `path.simplify_threshold`
    /// settings (the defaults otherwise).
    #[must_use]
    pub fn with_simplify(mut self, settings: SimplifySettings) -> Self {
        self.simplify = settings;
        self
    }

    /// Draws unfilled, unhatched paths that would be simplified in pieces
    /// of at most `chunksize` vertices when they have more, as matplotlib
    /// does with `agg.path.chunksize` (0, the default, never splits; nor do
    /// sizes up to 100).
    #[must_use]
    pub fn with_path_chunksize(mut self, chunksize: usize) -> Self {
        self.chunksize = chunksize;
        self
    }

    /// The pixels drawn so far.
    pub fn pixmap(&self) -> &Pixmap {
        &self.pixmap
    }

    /// The pixels, for changes made outside drawing calls (matplotlib's
    /// `restore_region` writes saved pixels back into the canvas).
    pub fn pixmap_mut(&mut self) -> &mut Pixmap {
        &mut self.pixmap
    }

    /// Consumes the renderer, returning its pixels.
    pub fn into_pixmap(self) -> Pixmap {
        self.pixmap
    }

    /// The pixels as an [`RgbaImage`] (a copy; see
    /// [`into_image`](Self::into_image)).
    pub fn to_image(&self) -> RgbaImage {
        filter::image_of(self.pixmap.clone())
    }

    /// Consumes the renderer, returning its pixels as an [`RgbaImage`]
    /// without copying them.
    pub fn into_image(self) -> RgbaImage {
        filter::image_of(self.pixmap)
    }

    /// Encodes the pixels as an RGBA PNG carrying the resolution, without
    /// text entries.
    ///
    /// # Errors
    ///
    /// When the image cannot be encoded.
    pub fn to_png(&self) -> Result<Vec<u8>, RasterBackendError> {
        self.to_png_with(&PngMetadata::none())
    }

    /// Encodes the canvas as PNG with the text entries of `metadata`, as
    /// matplotlib's `savefig` writes them.
    ///
    /// # Errors
    ///
    /// When the image cannot be encoded, or a keyword is not a valid PNG
    /// keyword (1 to 79 printable Latin-1 characters).
    pub fn to_png_with(&self, metadata: &PngMetadata) -> Result<Vec<u8>, RasterBackendError> {
        let image = ImageRef::rgba8(
            self.pixmap.width(),
            self.pixmap.height(),
            self.pixmap.data(),
        )
        .map_err(RasterBackendError::Encode)?;
        metadata
            .apply_to(png::Encoder::new().dpi(self.dpi))
            .encode(image)
            .map_err(RasterBackendError::Encode)
    }

    /// Resets every pixel to transparent white (matplotlib's `clear()`).
    pub fn clear(&mut self) {
        self.pixmap.fill(Rgba8::TRANSPARENT_WHITE);
    }

    /// Problems met while drawing (matplotlib would have raised, e.g.
    /// `OverflowError` for paths exceeding the cell limit), oldest first.
    pub fn take_errors(&mut self) -> Vec<RasterError> {
        std::mem::take(&mut self.errors)
    }

    /// Records the outcome of one raster operation.
    fn record(&mut self, result: Result<(), RasterError>) {
        if let Err(err) = result {
            self.errors.push(err);
        }
    }

    fn width(&self) -> u32 {
        self.pixmap.width()
    }

    fn height(&self) -> u32 {
        self.pixmap.height()
    }
}

#[cfg(test)]
mod tests;