Expand description
Renderer abstraction with raster (PNG), SVG, PDF, PostScript and PGF backends.
Artists in the pltrs crate describe what to draw through the
Renderer trait, using a GraphicsContext for stroke and clipping
state. Backends translate those calls into pixels or vector documents:
RasterRendererreproduces matplotlib’s Agg backend pixel for pixel and writes PNG.SvgRendererwrites the SVG documents of matplotlib’sRendererSVG(text as glyph paths, or as text elements withsvg.fonttypenone).PdfRendererwrites the PDF documents of matplotlib’sRendererPdf(text in Type 3 or Type 42 fonts or the 14 core fonts, usetex text in the Type 1 fonts of its DVI file).PsRendererwrites the PostScript and EPS documents of matplotlib’sRendererPS(text in Type 3 or Type 42 fonts or the core fonts ofps.useafm).PgfRendererwrites the LaTeX PGF pictures of matplotlib’sRendererPgf(text left to LaTeX).
TeX text (text.usetex) reaches a backend through
Renderer::draw_tex, which each backend implements as matplotlib’s
draw_tex: from the DVI file’s glyphs (or dvipng’s image), as
embedded Type 1 fonts, as glyph paths, or as LaTeX source. With
text.usetex, the PostScript backend tags it for LaTeX’s psfrag
package and leaves LaTeX, dvips and Ghostscript to the caller
(PsOutput::Psfrag).
The vector backends draw in points, rasterize images at their own
resolution (Renderer::image_magnification) and share Metadata
and VectorError. A MixedModeRenderer around one of them draws
rasterized artists into an image placed in the document.
Structs§
- Clip
Path - An arbitrary clip region: a path and the transform to display space.
- Collection
Item - One resolved item of a
PathCollection. - Dashes
- A dash pattern in points: alternating on/off lengths starting at
offset(matplotlib’s(offset, dash_list)of a graphics context). - Filter
Image - The pixels an image filter works on: straight-alpha RGBA, nominally in
[0, 1], row-major with the top row first (matplotlib’s(height, width, 4)float array). - Filtered
- What an image filter returns: the new image, and where its bottom-left corner goes in pixels from the bottom-left corner of the image it was given.
- Glyph
Bitmap - A rendered glyph:
FreeType’sFT_Bitmapand where it goes. - Graphics
Context - Everything about how a primitive is drawn, mirroring matplotlib’s
GraphicsContextBase. Lengths are in points unless stated otherwise; coordinates are display pixels with the origin at the bottom left. - Hatch
- A hatch fill drawn over a path’s face.
- Image
File - An image written beside an SVG document instead of being embedded in
it (see
SvgOptions::image_files). - Image
Size Error - The pixel buffer does not match the declared dimensions.
- Metadata
- Metadata written into a saved document;
Noneleaves an entry out. - Mixed
Mode Renderer - A vector renderer that draws rasterized artists into a raster canvas
placed in the document as an image (matplotlib’s
MixedModeRenderer). - Path
Collection - The arguments of matplotlib’s
draw_path_collection. - Path
Collection Data - The arguments of a
PathCollectionowned rather than borrowed, for a drawing kept until it is drawn (what a program drew through a renderer of its own, seepltrs::artist::Drawing). - PdfMarker
Paint - How a marker form paints its path, and the line width it is drawn
with (the arguments of
markerObject). - PdfOptions
- Settings of a PDF document (matplotlib’s
pdf.*rcParams and themetadataargument ofsavefig). - PdfRenderer
- Renders into a PDF document exactly like matplotlib’s
RendererPdfandPdfFile. Coordinates are points with the origin at the bottom left of the current page. - PdfTemplate
Paint - How the paths of a collection are painted (the arguments of
pathCollectionObject). - PgfDocument
- A finished PGF document and the images to write beside it.
- PgfOptions
- Settings of a PGF document (matplotlib’s
pgf.*rcParams and the file it is written to). - PgfRenderer
- Renders into a PGF picture exactly like matplotlib’s
RendererPgf. - PngMetadata
- The text entries of a PNG file (matplotlib’s PNG
metadata): any keywords, PNG’s own beingTitle,Author,Description,Copyright,Creation Time,Software,Disclaimer,Warning,SourceandComment. They are written in order astEXtchunks, or asiTXtchunks when the text is not Latin-1, as Pillow writes them. - PsDocument
- A finished PostScript document and where the figure sits on its page.
- PsOptions
- Settings of a PostScript document.
- PsRenderer
- Renders into a PostScript document exactly like matplotlib’s
RendererPS. Coordinates are points with the origin at the bottom left. - Psfrag
Figure - A figure whose usetex texts are psfrag tags, ready for LaTeX
(
_print_figure_texup to_convert_psfrags). - Quad
Mesh - A grid of quadrilaterals, one colour per cell.
- Quad
Mesh Data - The fields of a
QuadMeshowned rather than borrowed, for a drawing kept until it is drawn (what a program drew through a renderer of its own, seepltrs::artist::Drawing). - Raster
Renderer - Renders into an RGBA pixel buffer exactly like matplotlib’s
RendererAgg(straight alpha, initially transparent white). - Rgba
Image - An RGBA8 image with straight alpha, rows stored top to bottom.
- Sketch
- Parameters of the hand-drawn “sketch” path filter.
- SvgMetadata
- The Dublin Core entries of SVG documents besides the title, creator and
date every format writes (matplotlib’s SVG
metadatakeys), and the several agents, subjects and dates SVG can record where the shared entries hold one. - SvgOptions
- Settings of an SVG document (matplotlib’s
svg.*rcParams and themetadataargument ofsavefig). - SvgRenderer
- Renders into an SVG document exactly like matplotlib’s
RendererSVG. - Text
Line - One line of a text as matplotlib’s
Text.drawhands it to a renderer’sdraw_textordraw_tex: the line laid out (itsTextRun::sourcesays what it is) and the left end of its baseline, in display coordinates. - Text
Lines - A text as matplotlib’s
Text.drawdraws it through a renderer: its lines, its rotation, and what drew it (its artist and its font, as the crate drawing it describes them), for renderers that take texts whole (seeRenderer::draw_text_lines). - Timestamp
- A moment in UTC, in whole seconds since the Unix epoch.
- Unknown
SvgFont Type - A name that is not an
SvgFontType. - XmlWriter
- Writes an XML document into a string, which
takehands out as it grows (matplotlib’sbackend_svg.XMLWriter).
Enums§
- CapStyle
- How the ends of open strokes are drawn.
- Font
Type - How PDF and PostScript documents embed TrueType fonts (matplotlib’s
pdf.fonttypeandps.fonttype). - Glyph
Shape - A glyph’s tagged outline (26.6, origin at the pen) as
FreeTypehands it to a rasterizer. - Item
Cycle - How the items of a
PathCollectioncycle through its shapes and their transforms, which matplotlib’s backends do two ways. - Join
Style - How stroke segments are joined at corners.
- Page
Orientation - How the figure sits on the page (
savefig.orientation). - Page
Setup Error - A paper or orientation name that does not exist.
- Paper
- The page a PostScript document is printed on (
ps.papersize, orsavefig’spapertype). - PdfFont
- A font a document names (a key of matplotlib’s
PdfFile.fontNames). - PdfObject
- A PDF object, or an operator or verbatim content in a content stream
(what matplotlib’s
pdfReprwrites: numbers, names, strings, arrays, dictionaries, references,null,Ops andVerbatimcontent). - PdfShading
Colors - Vertex colours of a Gouraud shading (
addGouraudTriangles): RGB, or one grey level (alpha values for a soft mask). - PsOutput
- What a
PsRenderermade of a figure. - Raster
Backend Error - Why a raster canvas could not be created or encoded.
- Snap
Mode - Snapping behaviour for rectilinear paths.
- SvgFont
Type - How an SVG document writes text (matplotlib’s
svg.fonttype). - Trapped
- Whether a PDF document has been trapped for printing (its
Trappedentry). - Vector
Error - Why a vector document could not be produced.
Constants§
- PNG_
SOFTWARE - The
Softwareentry of pltrs’ PNG files, where matplotlib writes its own name and version (Matplotlib version3.11.2, https://matplotlib.org/). - SVG_
PROLOG - The XML declaration and doctype every document starts with
(matplotlib’s
svgProlog).
Traits§
- Renderer
- A drawing target: a raster canvas, an SVG/PDF/PS document, a window.
Functions§
- draw_
text_ as_ path - Fills
runas one path in the colour ofgc, laid out again from its source (matplotlib’sRendererBase._draw_text_as_path, how path effects and Agg without its owndraw_textdraw text): typeset byTextToPathatTEXT_PATH_FONT_SCALEpoints andTEXT_PATH_DPI, unhinted, then scaled to the text’s size in pixels, rotated byangledegrees aboutoriginand placed there. A run without a source is filled as it is. - glyph_
axis_ aligned - Whether
FreeTypesees the glyph matrix matplotlib sets forangledegrees as a quarter turn: the only transforms it autohints glyphs under. - gzip
- A gzip member (RFC 1952) holding
data, as Python’sgzip.GzipFilewrites it at its default level 9 (used for.svgz). - pdf_
line - One line of
objectsas matplotlib’sPdfFile.outputwrites it: their syntax joined by_fill, then a newline. - pdf_
text_ string - A string as
pdfReprwrites Python text: ASCII as is, anything else as UTF-16BE with a byte-order mark. - pgf_
text - The TeX source matplotlib’s PGF backend typesets
textwith in the fontrequestasks for (its_escape_and_apply_props): the commands selecting the family (a font ofoptions.font_namesby name withoptions.rcfonts), size, style and weight, then the text with^and%made harmless outside math. - pgf_
unknown_ family - The first family of
requestwhen no font has it, which matplotlib’s PGF backend leaves out of the text’s font commands, logging “Ignoring unknown font” (its_escape_and_apply_props). - pstoeps
- matplotlib’s
pstoeps:document, a PostScript file a distiller wrote, as Encapsulated PostScript. The header declares EPS and, given abbox, that bounding box instead of the page’s; after the header comments come a prolog saving the interpreter’s state and disablingshowpageandsetpagedeviceand, whenrotated(dvipsturned a usetex figure into a landscape page), the rotation ofbbox. The%%EOFcomment becomes the state restored and the page shown, and%%PageBoundingBoxcomments go. - render_
glyph - Renders a glyph outline rotated by
angledegrees with its origin atpen(display pixels, y up, quantized to 1/64 pixel) — matplotlib’s_set_transformand_render_glyph: anti-aliased for a smooth outline, monochrome for a scan outline.Nonefor a glyph without ink. - set_
texts_ as_ paths - Makes the raster canvases of this thread draw text as paths whenever
rulesays so (or as glyphs again, withNone), as matplotlib’s Agg renderer does without its owndraw_text:RendererBase.draw_textfills the outlinesTextToPathmakes 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): whetherRendererAgg.draw_textis taken away).
Type Aliases§
- Attribute
- An element attribute: name and value.
- Filter
Fn - An image filter (matplotlib’s agg filter function): it receives what an artist drew, cropped to its visible pixels, and the resolution in dots per inch.
- PdfHatch
- A hatch pattern a document holds (matplotlib’s
hatchPatterns): the edge and face colours and the hatch string. - Shared
Filter - An image filter the renderer may keep (see
Renderer::stop_shared_filter).