pltrs_render/lib.rs
1//! Renderer abstraction with raster (PNG), SVG, PDF, PostScript and PGF
2//! backends.
3//!
4//! Artists in the `pltrs` crate describe what to draw through the
5//! [`Renderer`] trait, using a [`GraphicsContext`] for stroke and clipping
6//! state. Backends translate those calls into pixels or vector documents:
7//!
8//! * [`RasterRenderer`] reproduces matplotlib's Agg backend pixel for
9//! pixel and writes PNG.
10//! * [`SvgRenderer`] writes the SVG documents of matplotlib's `RendererSVG`
11//! (text as glyph paths, or as text elements with `svg.fonttype` none).
12//! * [`PdfRenderer`] writes the PDF documents of matplotlib's
13//! `RendererPdf` (text in Type 3 or Type 42 fonts or the 14 core fonts,
14//! usetex text in the Type 1 fonts of its DVI file).
15//! * [`PsRenderer`] writes the PostScript and EPS documents of
16//! matplotlib's `RendererPS` (text in Type 3 or Type 42 fonts or the
17//! core fonts of `ps.useafm`).
18//! * [`PgfRenderer`] writes the LaTeX PGF pictures of matplotlib's
19//! `RendererPgf` (text left to LaTeX).
20//!
21//! TeX text (`text.usetex`) reaches a backend through
22//! [`Renderer::draw_tex`], which each backend implements as matplotlib's
23//! `draw_tex`: from the DVI file's glyphs (or `dvipng`'s image), as
24//! embedded Type 1 fonts, as glyph paths, or as LaTeX source. With
25//! `text.usetex`, the PostScript backend tags it for LaTeX's `psfrag`
26//! package and leaves LaTeX, `dvips` and Ghostscript to the caller
27//! ([`PsOutput::Psfrag`]).
28//!
29//! The vector backends draw in points, rasterize images at their own
30//! resolution ([`Renderer::image_magnification`]) and share [`Metadata`]
31//! and [`VectorError`]. A [`MixedModeRenderer`] around one of them draws
32//! rasterized artists into an image placed in the document.
33#![forbid(unsafe_code)]
34
35mod collection;
36mod filter;
37mod gc;
38mod image;
39mod mixed;
40mod pdf;
41mod pgf;
42mod ps;
43mod quad_mesh;
44mod raster;
45mod renderer;
46mod svg;
47#[cfg(test)]
48mod testing;
49mod vector;
50
51pub use collection::{CollectionItem, ItemCycle, PathCollection, PathCollectionData};
52pub use filter::{FilterFn, FilterImage, Filtered, SharedFilter};
53pub use gc::{CapStyle, ClipPath, Dashes, GraphicsContext, Hatch, JoinStyle, Sketch, SnapMode};
54pub use image::{ImageSizeError, RgbaImage};
55pub use mixed::MixedModeRenderer;
56pub use pdf::{
57 PdfFont, PdfHatch, PdfMarkerPaint, PdfObject, PdfOptions, PdfRenderer, PdfShadingColors,
58 PdfTemplatePaint, pdf_line, pdf_text_string,
59};
60pub use pgf::{PgfDocument, PgfOptions, PgfRenderer, pgf_text, pgf_unknown_family};
61pub use ps::{
62 PageOrientation, PageSetupError, Paper, PsDocument, PsOptions, PsOutput, PsRenderer,
63 PsfragFigure, pstoeps,
64};
65pub use quad_mesh::{QuadMesh, QuadMeshData};
66pub use raster::{
67 GlyphBitmap, GlyphShape, RasterBackendError, RasterRenderer, glyph_axis_aligned, render_glyph,
68 set_texts_as_paths,
69};
70pub use renderer::{Renderer, TextLine, TextLines, draw_text_as_path};
71pub use svg::{
72 Attribute, ImageFile, PROLOG as SVG_PROLOG, SvgFontType, SvgOptions, SvgRenderer,
73 UnknownSvgFontType, XmlWriter,
74};
75pub use vector::{
76 FontType, Metadata, PNG_SOFTWARE, PngMetadata, SvgMetadata, Timestamp, Trapped, VectorError,
77 gzip,
78};
79
80use pltrs_core::{Affine2D, Bbox};
81
82/// The affine map taking the unit square onto `bbox`.
83fn unit_box(bbox: &Bbox) -> Affine2D {
84 Affine2D::scaling(bbox.width(), bbox.height()).translate(bbox.x0(), bbox.y0())
85}