matplotlib.backends.backend_template#

A fully functional, do-nothing backend intended as a template for backend writers. It is fully functional in that you can select it as a backend e.g. with

import matplotlib
matplotlib.use("template")

and your program will (should!) run without error, though no output is produced. This provides a starting point for backend writers; you can selectively implement drawing methods (draw_path, draw_image, etc.) and slowly see your figure come to life instead having to have a full-blown implementation before getting any results.

Copy this file to a directory outside the Matplotlib source tree, somewhere where Python can import it (by adding the directory to your sys.path or by packaging it as a normal Python package); if the backend is importable as import my.backend you can then select it using

import matplotlib
matplotlib.use("module://my.backend")

If your backend implements support for saving figures (i.e. has a print_xyz method), you can register it as the default handler for a given file type:

from matplotlib.backend_bases import register_backend
register_backend('xyz', 'my_backend', 'XYZ File Format')
...
plt.savefig("figure.xyz")

matplotlib.backends.backend_template.FigureCanvas[source]#

alias of FigureCanvasTemplate

class matplotlib.backends.backend_template.FigureCanvasTemplate(figure=None)[source]#

Bases: FigureCanvasBase

The canvas the figure renders into. Calls the draw and print fig methods, creates the renderers, etc.

Note: GUI templates will want to connect events for button presses, mouse movements and key presses to functions that call the base class methods button_press_event, button_release_event, motion_notify_event, key_press_event, and key_release_event. See the implementations of the interactive backends for examples.

Attributes:

figureFigure

A high-level Figure instance

draw()[source]#

Draw the figure using the renderer.

It is important that this method actually walk the artist tree even if not output is produced because this will trigger deferred work (like computing limits auto-limits and tick values) that users may want access to before saving to disk.

filetypes = {'avif': 'AV1 Image File Format', 'eps': 'Encapsulated Postscript', 'foo': 'My magic Foo format', 'gif': 'Graphics Interchange Format', 'jpeg': 'Joint Photographic Experts Group', 'jpg': 'Joint Photographic Experts Group', 'pdf': 'Portable Document Format', 'pgf': 'PGF code for LaTeX', 'png': 'Portable Network Graphics', 'ps': 'Postscript', 'raw': 'Raw RGBA bitmap', 'rgba': 'Raw RGBA bitmap', 'svg': 'Scalable Vector Graphics', 'svgz': 'Scalable Vector Graphics', 'tif': 'Tagged Image File Format', 'tiff': 'Tagged Image File Format', 'webp': 'WebP Image Format'}#

get_default_filetype()[source]#

Return the default savefig file format as specified in rcParams["savefig.format"] (default: 'png').

The returned string does not include a period. This method is overridden in backends that only support a single file type.

manager_class[source]#

alias of FigureManagerTemplate

print_foo(filename, **kwargs)[source]#

Write out format foo.

This method is normally called via Figure.savefig and FigureCanvasBase.print_figure, which take care of setting the figure facecolor, edgecolor, and dpi to the desired output values, and will restore them to the original values. Therefore, print_foo does not need to handle these settings.

matplotlib.backends.backend_template.FigureManager[source]#

alias of FigureManagerTemplate

class matplotlib.backends.backend_template.FigureManagerTemplate(canvas, num)[source]#

Bases: FigureManagerBase

Helper class for pyplot mode, wraps everything up into a neat bundle.

For non-interactive backends, the base class is sufficient. For interactive backends, see the documentation of the FigureManagerBase class for the list of methods that can/should be overridden.

class matplotlib.backends.backend_template.GraphicsContextTemplate[source]#

Bases: GraphicsContextBase

The graphics context provides the color, line styles, etc. See the cairo and postscript backends for examples of mapping the graphics context attributes (cap styles, join styles, line widths, colors) to a particular backend. In cairo this is done by wrapping a cairo.Context object and forwarding the appropriate calls to it using a dictionary mapping styles to gdk constants. In Postscript, all the work is done by the renderer, mapping line styles to postscript calls.

If it's more appropriate to do the mapping at the renderer level (as in the postscript backend), you don't need to override any of the GC methods. If it's more appropriate to wrap an instance (as in the cairo backend) and do the mapping here, you'll need to override several of the setter methods.

The base GraphicsContext stores colors as an RGB tuple on the unit interval, e.g., (0.5, 0.0, 1.0). You may need to map this to colors appropriate for your backend.

class matplotlib.backends.backend_template.RendererTemplate(dpi)[source]#

Bases: RendererBase

The renderer handles drawing/rendering operations.

This is a minimal do-nothing class that can be used to get started when writing a new backend. Refer to backend_bases.RendererBase for documentation of the methods.

draw_image(gc, x, y, im)[source]#

Draw an RGBA image.

Parameters:

gcGraphicsContextBase

A graphics context with clipping information.

xfloat

The distance in physical units (i.e., dots or pixels) from the left hand side of the canvas.

yfloat

The distance in physical units (i.e., dots or pixels) from the bottom side of the canvas.

im(N, M, 4) array of numpy.uint8

An array of RGBA pixels.

transformAffine2DBase

If and only if the concrete backend is written such that option_scale_image returns True, an affine transformation (i.e., an Affine2DBase) may be passed to draw_image. The translation vector of the transformation is given in physical units (i.e., dots or pixels). Note that the transformation does not override x and y, and has to be applied before translatingthe result by x and y (this can be accomplished by adding x and y to the translation vector defined by transform).

draw_path(gc, path, transform, rgbFace=None)[source]#

Draw a Path instance using the given affine transform.

draw_text(gc, x, y, s, prop, angle, ismath=False, mtext=None)[source]#

Draw a text instance.

Parameters:

gcGraphicsContextBase

The graphics context.

xfloat

The x location of the text in display coords.

yfloat

The y location of the text baseline in display coords.

sstr

The text string.

propFontProperties

The font properties.

anglefloat

The rotation angle in degrees anti-clockwise.

ismathbool or "TeX"

If True, use mathtext parser.

mtextText

The original text object to be rendered.

Notes

Notes for backend implementers:

RendererBase.draw_text also supports passing "TeX" to the ismath parameter to use TeX rendering, but this is not required for actual rendering backends, and indeed many builtin backends do not support this. Rather, TeX rendering is provided by draw_tex.

flipy()[source]#

Return whether y values increase from top to bottom.

Note that this only affects drawing of texts.

get_canvas_width_height()[source]#

Return the canvas width and height in display coords.

get_text_width_height_descent(s, prop, ismath)[source]#

Get the width, height, and descent (offset from the bottom to the baseline), in display coords, of the string s with FontProperties prop.

Whitespace at the start and the end of s is included in the reported width.

new_gc()[source]#

Return an instance of a GraphicsContextBase.

points_to_pixels(points)[source]#

Convert points to display units.

You need to override this function (unless your backend doesn't have a dpi, e.g., postscript or svg). Some imaging systems assume some value for pixels per inch:

points to pixels = points * pixels_per_inch/72 * dpi/72

Parameters:

pointsfloat or array-like

Returns:

Points converted to pixels