画布与场景

画布规格

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
)

图形的物理尺寸与坐标范围。x_range 与 y_range 是显示的数据范围；width 与 height 是以英寸计算的图形尺寸；dpi 是 \([1, 1200]\) 内的整数。属性 x_min、x_max、y_min、y_max 可读取范围，replace(**changes) 则返回只修改指定字段的副本。范围必须有限且 lo < hi，尺寸必须是有限正数，否则会引发 ConfigurationError。

Interval(lo, hi)

有限的递增区间，lo < hi，供规格与坐标轴共用。

画布

Canvas(
    spec=None,
    theme=None,
    config=None,
    renderer=None,
    *,
    role_overrides=None
)

add(layer), extend(layers)

加入一个或多个图层；返回画布。

remove(layer_id), clear()

移除该 id 的图层（含群组内）或所有图层；返回画布。未知的 id 引发 ConfigurationError。

snapshot()

目前的 Scene。之后调用 add() 不会改变它。

copy()

规格、主题、配置、渲染器、覆盖、场景与绑定都相同的新画布。

bind(parameter, value), bind(mapping)

新画布，其场景中的这些参数换成数值（详见参数、网格与动画）；原画布保留参数。

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

绘制场景并返回渲染器的结果（详见绘制）。

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

绘制、写出 .png、.pdf 或 .svg、关闭结果并返回写出的路径。选项即 SaveOptions 的字段。

封装不可变场景的流式构建器。如果参数为 None，便采用创建画布当下生效的配置（详见配置），分别是其中的 canvas_spec、theme 与 renderer。role_overrides 将角色名称映射到 StyleBundle，并应用在主题与配置之上（参见解析顺序）。

构造方法会修改画布，但不会就地改动场景：每次调用都以新场景取代画布中的场景，因此先前获取的快照、副本或绑定后的画布都会维持原有内容。

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"

场景

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

具有持久性且有序的图层集合，也就是每次操作都会保留旧版本。add()、extend()、remove() 与 clear() 都会返回新场景；Scene.empty() 是空场景。图层 id 在整个场景（包括群组）中必须唯一，如有重复便引发 ConfigurationError。ordered_layers 按 z_index 排序顶层图层；值相同时维持加入顺序，而这个顺序就是绘制顺序。