Skip to content

Canvases and scenes

Canvas specifications

CanvasSpec(
    x_range=(0, 10),
    y_range=(0, 10),
    width=6.0,
    height=6.0,
    dpi=300,
    x_label="X",
    y_label="Y",
    title=None
)

The physical dimensions and coordinate ranges of a diagram. x_range and y_range are the data ranges shown; width and height are the figure size in inches; dpi is an integer in \([1, 1200]\). The properties x_min, x_max, y_min, y_max read the ranges, and replace(**changes) returns a copy with some fields changed. Ranges must be finite with lo < hi, sizes positive and finite; anything else raises ConfigurationError.

Interval(lo, hi)

A finite increasing interval, lo < hi, shared by specifications and axes.

Canvas

Canvas(
    spec=None,
    theme=None,
    config=None,
    renderer=None,
    *,
    role_overrides=None
)
add(layer), extend(layers)

Append one layer or several; return the canvas.

remove(layer_id), clear()

Remove the layer with that id (searching inside groups) or every layer; return the canvas. An unknown id raises ConfigurationError.

snapshot()

The current Scene. Later calls to add() do not change it.

copy()

A new canvas with the same specification, theme, configuration, renderer, overrides, scene and bindings.

bind(parameter, value), bind(mapping)

A new canvas whose scene has those parameters replaced by values (Parameters, grids and animation); the original keeps its parameters.

render(*, renderer=None, cache=None)

Render the scene and return the renderer's result (Rendering).

save(target, *, renderer=None, cache=None, **options)

Render, write .png, .pdf or .svg, close the result and return the written paths. The options are those of SaveOptions.

A fluent builder around an immutable scene. Arguments left None come from the configuration active when the canvas is created (Configuration): its canvas_spec, theme and renderer. role_overrides maps role names to StyleBundles applied on top of the theme and the configuration (Resolution order).

The builder methods change the canvas, never an existing scene. Each call replaces the canvas's scene with a new one, so an earlier snapshot, copy or bound canvas remains unchanged.

from mosaickit import Canvas, PathLayer

canvas = Canvas()
before = canvas.snapshot()
canvas.add(PathLayer([(0, 0), (1, 1)], id="line"))
# the old snapshot is unchanged
assert before.layers == ()
assert canvas.snapshot().layers[0].id == "line"

Scenes

Scene(layers=(), metadata={})

A persistent, immutable, ordered collection of layers. add(), extend(), remove() and clear() return new scenes; Scene.empty() is the empty one. Layer ids must be unique across the whole scene, groups included; a duplicate raises ConfigurationError. ordered_layers sorts the top-level layers by z_index, keeping insertion order among equals, which is the order in which they are drawn.

Errors and warnings

MosaicKitError

Base class of the three errors below

ConfigurationError

A model, style, theme, specification or configuration value is invalid

BindingError

A parameter is missing, has the wrong type, or an expression cannot be evaluated

RenderError

A renderer cannot do what was asked: an unknown format or renderer, a missing legend entry

LayoutWarning

Automatic placement could not avoid every obstacle (Region and point labels)

CacheBypassWarning

A layer's model is not hashable, so it is rendered without caching

Comments