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 of 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

alias of FigureCanvasTemplate

class matplotlib.backends.backend_template.FigureCanvasTemplate(figure=None)

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:

figurematplotlib.figure.Figure

A high-level Figure instance

draw()

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 = {'eps': 'Encapsulated Postscript', 'foo': 'My magic Foo 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()

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

alias of FigureManagerTemplate

print_foo(filename, *args, **kwargs)

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

alias of FigureManagerTemplate

class matplotlib.backends.backend_template.FigureManagerTemplate(canvas, num)

Bases: FigureManagerBase

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

For non-interactive backends, the base class is sufficient.

class matplotlib.backends.backend_template.GraphicsContextTemplate

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 a 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)

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)

Draw an RGBA image.

Parameters:

gcGraphicsContextBase

A graphics context with clipping information.

xscalar

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

yscalar

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

im(N, M, 4) array-like of np.uint8

An array of RGBA pixels.

transformmatplotlib.transforms.Affine2DBase

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 translating the 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)

Draw a Path instance using the given affine transform.

draw_text(gc, x, y, s, prop, angle, ismath=False, mtext=None)

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.

propmatplotlib.font_manager.FontProperties

The font properties.

anglefloat

The rotation angle in degrees anti-clockwise.

mtextmatplotlib.text.Text

The original text object to be rendered.

Notes

Note for backend implementers:

When you are trying to determine if you have gotten your bounding box right (which is what enables the text layout/alignment to work properly), it helps to change the line in text.py:

if 0: bbox_artist(self, renderer)

to if 1, and then the actual bounding box will be plotted along with your text.

flipy()

Return whether y values increase from top to bottom.

Note that this only affects drawing of texts.

get_canvas_width_height()

Return the canvas width and height in display coords.

get_text_width_height_descent(s, prop, ismath)

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

new_gc()

Return an instance of a GraphicsContextBase.

points_to_pixels(points)

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

a float or a numpy array of float

Returns:

Points converted to pixels

matplotlib.backends.backend_template.show(*, block=None)

For image backends - is not required. For GUI backends - show() is usually the last line of a pyplot script and tells the backend that it is time to draw. In interactive mode, this should do nothing.