mosaickit

A domain-neutral toolkit for assembling two-dimensional diagrams from reusable scenes, layers, styles, parameters, and renderers.

Domain libraries define their own models and semantic roles; MosaicKit composes their visual layers and renders the result. It knows nothing about any domain and does not depend on a model package or a curve-fitting library.

Installation

Add MosaicKit to a project with uv:

uv add mosaickit

A plain pip install mosaickit also works. MosaicKit supports Python 3.10–3.13. GlyphKit (>=1.0.0b2,<2) is installed as a required dependency for font processing.

Python API

from mosaickit import (
    Canvas,
    Fill,
    FillLayer,
    MarkerLayer,
    PathLayer,
    Stroke,
    TextLayer,
    quadrant_axes,
)

canvas = Canvas().extend(quadrant_axes(10, 10))
canvas.add(
    FillLayer(
        [(1, 1), (1, 7), (8, 1)],
        fill=Fill(color="#377EB8", opacity=0.12),
        z_index=-1,
    )
)
canvas.add(
    PathLayer(
        [(1, 8), (2, 5), (4, 3), (7, 1.5), (9, 1)],
        stroke=Stroke(color="#984EA3", width=2),
        id="curve",
    )
)
canvas.add(MarkerLayer([(4, 3)], id="point"))
canvas.add(TextLayer((4, 3), "A", offset=(8, 8)))
canvas.save("diagram.svg")

Canvas.add(), extend(), remove(), and clear() are fluent builder operations. snapshot() returns an immutable Scene; copy() and bind() produce a new canvas without changing the original. Public layers never contain Matplotlib artists, and importing mosaickit does not import Matplotlib.

Scenes and layers

The scene graph is deliberately small:

• PathLayer joins ordered finite (x, y) coordinates with straight segments.
• FillLayer describes filled regions.
• MarkerLayer, TextLayer, and ArrowLayer add annotations.
• RegionLabelLayer names a filled region (inside it, or as a callout), and PointLabelLayer names a point with text placed right beside it. Both are placed after everything else is drawn so they cover no line, marker, filled region, or other text; a LayoutWarning names any label that cannot avoid everything.
• LegendLayer builds legends from stable layer IDs.
• AxisMarkLayer, AxisNoteLayer, and BraceLayer annotate values and spans on an axis.
• SpanBraceLayer braces a horizontal or vertical span between two points inside the plot, with its label placed so it covers nothing (on a leader when there is no room).
• GroupLayer groups layers without adding renderer-specific state.

AxisSpec and build_axes() construct axes from the same ordinary path and text layers. quadrant_axes(), crosshair_axes(), and box_frame() cover common layouts. CanvasSpec owns ranges, physical size, DPI, labels, and title.

Saving to a .tex path writes the scene as TikZ, for a Canvas or a CanvasGrid; pass standalone=False to get just the tikzpicture. Paths are written as polylines unless a geometry package registers a serializer for its curve type with register_path_serializer, which lets it emit native Bézier segments without MosaicKit depending on it. Curve construction itself stays outside MosaicKit.

Axis marks, notes, and braces

from mosaickit import AxisMarkLayer, AxisNoteLayer, BraceLayer, Canvas, quadrant_axes

canvas = Canvas().extend(quadrant_axes(10, 10))
for value, symbol, note in [(7, "a_1", "Upper\nvalue"), (5, "a_0", "Lower\nvalue")]:
    canvas.add(AxisMarkLayer("y", value, symbol, math=True))
    canvas.add(AxisNoteLayer("y", value, note))
canvas.add(BraceLayer("y", 5, 7, "Span", side="outside"))

The y axis is the plot's left edge and the x axis its bottom edge; the space outside them is the gutter. Columns run outward from the axis: marks, then outside braces, then notes, each as wide as its widest text. Marks and notes are spread along the axis so none overlap, keeping their order and moving as little as possible. An "inside" brace sits just inside the plot and its label is placed so it covers no line, point, region, or text. Notes use the axes.note role, which the default theme sets smaller and lighter than marks.

Saving grows the canvas just enough to include text drawn past its edges and never crops; pass expand=False to save() to keep the exact CanvasSpec size. Axis titles from build_axes() sit past the arrow tips: the x title to the right, the y title above.

Styles and themes

Set values shared by every role with defaults. Individual roles and layer styles can still override them:

from mosaickit import StyleBundle, TextStyle, Theme

paper = Theme(
    "paper",
    {"title": StyleBundle(text=TextStyle(size=16, color="grey-900"))},
    defaults=StyleBundle(text=TextStyle(size=12)),
)

TextLayer and TextStyle remain public. Color, size, opacity, and rotation continue to be supported. Use GlyphKit for new font selection and processing; MosaicKit's TextStyle.family and TextStyle.weight fields are deprecated. The following legacy example still renders through Matplotlib in this release, but each style supplying a font field emits one DeprecationWarning:

paper = Theme(
    "paper",
    {
        "title": StyleBundle(text=TextStyle(family="Noto Serif TC")),
    },
    defaults=StyleBundle(text=TextStyle(family="Noto Sans TC")),
)

from mosaickit import Config, Stroke, StyleBundle, Theme, use_config

paper = Theme(
    "paper",
    {"mypkg.boundary": StyleBundle(stroke=Stroke(color="#984EA3", width=2))},
)

with use_config(Config(theme=paper)):
    canvas = Canvas()

Style resolution proceeds from layer style to canvas role override, configuration role override, theme, and finally primitive defaults. A field set to None inherits; falsey values such as opacity=0, width=0, and LegendStyle(visible=False) remain explicit overrides.

Colors by name

Style color and edge_color fields take a Color, a "#hex" string, or a palette name such as "blue". Names stay names in themes and styles; they are looked up in the active palette (Config.palette, default DEFAULT_PALETTE) when a canvas renders, so renderers only ever receive concrete colors. The built-in default theme names its colors (primary is "blue", secondary is "red", accent is "teal", neutrals are the grey-* names), so changing a color once in the palette recolors every role that names it:

from mosaickit import (
    DEFAULT_PALETTE,
    Canvas,
    Config,
    Palette,
    Stroke,
    StyleBundle,
    Theme,
    use_config,
)
from mosaickit.themes import default

palette = Palette("brand", {**DEFAULT_PALETTE.colors, "blue": "#0072B2", "accent": "#984EA3"})

# A domain package can name colors in its theme without knowing the palette.
mypkg = Theme(
    "mypkg",
    {
        **default.roles,
        "mypkg.line": StyleBundle(stroke=Stroke(color="blue", width=2)),
        "mypkg.boundary": StyleBundle(stroke=Stroke(color="accent")),
    },
)

with use_config(Config(theme=mypkg, palette=palette)):
    canvas = Canvas()  # primary and mypkg.line draw in #0072B2

A name the palette does not define raises ConfigurationError at render time, naming the role, the style field, and the palette. A Python Palette replaces the default palette, so start from DEFAULT_PALETTE.colors (as above) to keep the names the built-in theme uses.

Domain packages register dotted role names through ThemeRegistry. Typed RolePack dataclasses and expand_roles() let those packages author themes without making MosaicKit import their domain types.

Configuration can also be loaded from TOML:

[canvas]
x_range = [0, 20]
dpi = 150

[palette]
blue = "#0072B2"     # override a default color
accent = "#984EA3"   # add a new name

[styles."mypkg.boundary".stroke]
color = "accent"     # a palette name or a "#hex" value
width = 2
dash = "dashed"

[styles."mypkg.line".stroke]
color = "blue"

The [palette] table layers named hex colors over DEFAULT_PALETTE, and the loaded palette is available as config.palette. Overriding blue there recolors the built-in primary role and any theme or style that names blue, with no styles needed. Style color and edge_color values accept palette names as well as hex; an unknown name raises ConfigurationError naming the file and key when the file is loaded.

Use Config.load(path) to validate it. Runtime defaults are isolated with contextvars, while explicit constructor arguments always take precedence.

Grids, parameters, and animation

Grid sweeps and parameter binding remain supported. The Animation.sweep() line below is a deprecated compatibility example:

from mosaickit import Animation, Canvas, CanvasGrid, Parameter, TextLayer

position = Parameter("position", value_type=float)
template = Canvas().add(TextLayer((position, 5), "moving"))
values = position.values([1.0, 3.0, 5.0])

CanvasGrid.sweep(template, values, cols=3).save("sweep.svg")
Animation.sweep(template, values, fps=2).save("sweep.gif")  # Deprecated: use KineticKit.

CanvasGrid accepts flat canvases, nested rows, None cells, and Span(canvas, rows=..., cols=...). A flat list infers a roughly square grid; explicit rows and cols may leave trailing cells empty.

Parameters and expressions support arithmetic, ordered comparisons, partial binding, and stable structural equality. Animation.frames() yields backend-neutral scenes. GIF output uses Pillow; MP4 output requires ffmpeg.

Font and animation migration

Use GlyphKit for font processing and KineticKit for new animation work. Install KineticKit separately when needed; MosaicKit does not depend on it. This transition release retains the Matplotlib font path and exports Animation from both mosaickit and mosaickit.canvas. Direct construction and Animation.sweep() each emit one DeprecationWarning at the caller. Frame iteration, GIF/MP4 saving, and the existing Matplotlib playback helper continue to work. Internal style copying and rendering do not repeat warnings.

The next release may remove the legacy family/weight font-selection path and MosaicKit's animation APIs and renderer helpers. Migrate those uses before upgrading; retain TextLayer, non-font TextStyle fields, CanvasGrid, and parameter binding for static scene composition. No new cross-library scene adapter is introduced in this release.

Rendering

PNG, SVG, and PDF use the built-in Matplotlib renderer:

result = canvas.render()
try:
    result.show()
finally:
    result.close()

canvas.save() closes its temporary render result automatically. The public Renderer protocol and RendererRegistry allow other backends without placing backend state in the scene graph. Render plans and contexts remain private while the built-in backends evolve.

Each render, grid, or animation job owns its cache. Pass an explicit RenderCache to reuse work across jobs. Non-hashable models bypass caching and emit one warning per model type and cache.

Scope

MosaicKit owns domain-neutral scene composition, styles, themes, parameter binding, grid layout, renderer contracts, and static output. GlyphKit owns font processing; KineticKit owns animation. MosaicKit retains deprecated font and animation compatibility paths for this release. Domain semantics belong to the packages that build on it. Mathematical curve construction and native TikZ Bézier segments belong to geometry packages such as BezierKit, which plug into the scene-level TikZ export through a path serializer.

Development

uv sync --locked
uv run pre-commit install
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run lint-imports
uv build

The lockfile pins all development dependencies.