Skip to main content

Crate pltrs_render

Crate pltrs_render 

Source
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:

  • RasterRenderer reproduces matplotlib’s Agg backend pixel for pixel and writes PNG.
  • SvgRenderer writes the SVG documents of matplotlib’s RendererSVG (text as glyph paths, or as text elements with svg.fonttype none).
  • PdfRenderer writes the PDF documents of matplotlib’s RendererPdf (text in Type 3 or Type 42 fonts or the 14 core fonts, usetex text in the Type 1 fonts of its DVI file).
  • PsRenderer writes the PostScript and EPS documents of matplotlib’s RendererPS (text in Type 3 or Type 42 fonts or the core fonts of ps.useafm).
  • PgfRenderer writes the LaTeX PGF pictures of matplotlib’s RendererPgf (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§

ClipPath
An arbitrary clip region: a path and the transform to display space.
CollectionItem
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).
FilterImage
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.
GlyphBitmap
A rendered glyph: FreeType’s FT_Bitmap and where it goes.
GraphicsContext
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.
ImageFile
An image written beside an SVG document instead of being embedded in it (see SvgOptions::image_files).
ImageSizeError
The pixel buffer does not match the declared dimensions.
Metadata
Metadata written into a saved document; None leaves an entry out.
MixedModeRenderer
A vector renderer that draws rasterized artists into a raster canvas placed in the document as an image (matplotlib’s MixedModeRenderer).
PathCollection
The arguments of matplotlib’s draw_path_collection.
PathCollectionData
The arguments of a PathCollection owned rather than borrowed, for a drawing kept until it is drawn (what a program drew through a renderer of its own, see pltrs::artist::Drawing).
PdfMarkerPaint
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 the metadata argument of savefig).
PdfRenderer
Renders into a PDF document exactly like matplotlib’s RendererPdf and PdfFile. Coordinates are points with the origin at the bottom left of the current page.
PdfTemplatePaint
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 being Title, Author, Description, Copyright, Creation Time, Software, Disclaimer, Warning, Source and Comment. They are written in order as tEXt chunks, or as iTXt chunks 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.
PsfragFigure
A figure whose usetex texts are psfrag tags, ready for LaTeX (_print_figure_tex up to _convert_psfrags).
QuadMesh
A grid of quadrilaterals, one colour per cell.
QuadMeshData
The fields of a QuadMesh owned rather than borrowed, for a drawing kept until it is drawn (what a program drew through a renderer of its own, see pltrs::artist::Drawing).
RasterRenderer
Renders into an RGBA pixel buffer exactly like matplotlib’s RendererAgg (straight alpha, initially transparent white).
RgbaImage
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 metadata keys), 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 the metadata argument of savefig).
SvgRenderer
Renders into an SVG document exactly like matplotlib’s RendererSVG.
TextLine
One line of a text as matplotlib’s Text.draw hands it to a renderer’s draw_text or draw_tex: the line laid out (its TextRun::source says what it is) and the left end of its baseline, in display coordinates.
TextLines
A text as matplotlib’s Text.draw draws 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 (see Renderer::draw_text_lines).
Timestamp
A moment in UTC, in whole seconds since the Unix epoch.
UnknownSvgFontType
A name that is not an SvgFontType.
XmlWriter
Writes an XML document into a string, which take hands out as it grows (matplotlib’s backend_svg.XMLWriter).

Enums§

CapStyle
How the ends of open strokes are drawn.
FontType
How PDF and PostScript documents embed TrueType fonts (matplotlib’s pdf.fonttype and ps.fonttype).
GlyphShape
A glyph’s tagged outline (26.6, origin at the pen) as FreeType hands it to a rasterizer.
ItemCycle
How the items of a PathCollection cycle through its shapes and their transforms, which matplotlib’s backends do two ways.
JoinStyle
How stroke segments are joined at corners.
PageOrientation
How the figure sits on the page (savefig.orientation).
PageSetupError
A paper or orientation name that does not exist.
Paper
The page a PostScript document is printed on (ps.papersize, or savefig’s papertype).
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 pdfRepr writes: numbers, names, strings, arrays, dictionaries, references, null, Ops and Verbatim content).
PdfShadingColors
Vertex colours of a Gouraud shading (addGouraudTriangles): RGB, or one grey level (alpha values for a soft mask).
PsOutput
What a PsRenderer made of a figure.
RasterBackendError
Why a raster canvas could not be created or encoded.
SnapMode
Snapping behaviour for rectilinear paths.
SvgFontType
How an SVG document writes text (matplotlib’s svg.fonttype).
Trapped
Whether a PDF document has been trapped for printing (its Trapped entry).
VectorError
Why a vector document could not be produced.

Constants§

PNG_SOFTWARE
The Software entry 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 run as one path in the colour of gc, laid out again from its source (matplotlib’s RendererBase._draw_text_as_path, how path effects and Agg without its own draw_text draw text): typeset by TextToPath at TEXT_PATH_FONT_SCALE points and TEXT_PATH_DPI, unhinted, then scaled to the text’s size in pixels, rotated by angle degrees about origin and placed there. A run without a source is filled as it is.
glyph_axis_aligned
Whether FreeType sees the glyph matrix matplotlib sets for angle degrees as a quarter turn: the only transforms it autohints glyphs under.
gzip
A gzip member (RFC 1952) holding data, as Python’s gzip.GzipFile writes it at its default level 9 (used for .svgz).
pdf_line
One line of objects as matplotlib’s PdfFile.output writes it: their syntax joined by _fill, then a newline.
pdf_text_string
A string as pdfRepr writes 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 text with in the font request asks for (its _escape_and_apply_props): the commands selecting the family (a font of options.font_names by name with options.rcfonts), size, style and weight, then the text with ^ and % made harmless outside math.
pgf_unknown_family
The first family of request when 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 a bbox, that bounding box instead of the page’s; after the header comments come a prolog saving the interpreter’s state and disabling showpage and setpagedevice and, when rotated (dvips turned a usetex figure into a landscape page), the rotation of bbox. The %%EOF comment becomes the state restored and the page shown, and %%PageBoundingBox comments go.
render_glyph
Renders a glyph outline rotated by angle degrees with its origin at pen (display pixels, y up, quantized to 1/64 pixel) — matplotlib’s _set_transform and _render_glyph: anti-aliased for a smooth outline, monochrome for a scan outline. None for a glyph without ink.
set_texts_as_paths
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).

Type Aliases§

Attribute
An element attribute: name and value.
FilterFn
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.
SharedFilter
An image filter the renderer may keep (see Renderer::stop_shared_filter).