mpl-typst 0.3.0

Typst backend for matplotlib (Python visualization library).

Typst Matplotlib Backend

Typst backend for matplotlib (Python visualization library).

Overview

At the moment, Typst supports main vector and raster image formats. Namely, images in PNG, JPEG, GIF, or SVG format can be easily emplaced in a document with Typst. However, it is not possible to keep metadata and annotations. These are mandatory in order to allow a reader to select and interact with vector content (e.g. text) on images. Although SVG can contain text metadata in principle, Typst does not support this feature at the moment but still it is able to render SVG as a vector content.

This package solves this problem for matplotlib users. Basically, this project implements a custom render (or backend) for matplotlib which generates typ-file containing Typst markup. Generated markup file can be later included in the original markup so that the resulting PDF will have interactable content. Matplotlib exploits exactly the same strategy in order to generate PGF-files — a LaTeX markup itself — which can be included into LaTeX markup directly.

Usage

To export a figure using typst, just add

import matplotlib
import mpl_typst

# your drawing code

fig.savefig('figure.typ')

You may call plt.show() afterwards, which displays the figure using your default agg backend.

In order to set the mpl_typst module as default backend (which deactivates interactivity, but also renders SVG, PNG and PDF using typst) one can import mpl_typst.as_default module in order to use mpl_typst backend by default.

import mpl_typst.as_default

Or one can configure it manually.

import matplotlib as mpl
import mpl_typst
mpl.use('module://mpl_typst')

Also, it is possible to use rendering context as usual to override backend.

import matplotlib as mpl
import mpl_typst
with mpl.rc_context({'backend': 'module://mpl_typst'}):  # or mpl_typst.BACKEND
    ...

Next, you can save your figure to typ as usual.

fig, ax = plt.subplots()
...
fig.savefig('line-plot-simple.typ')

As soon as you get a typ-file you can included it directly to figure function and adjust figure time.

#figure(
  include "line-plot-simple.typ",
  kind: image,
  caption: [Simple line plot],
  placement: top,
) <line-plot-simple>

Development Notes

Generated Typst drawing elements use Matplotlib coordinates that have already been normalized to the page's top-left origin. For this reason, every generated Typst place() call must be explicitly anchored with top + left. Do not rely on Typst's default placement alignment; it depends on surrounding document context and can shift clipped drawing elements when a generated figure is included with figure(kind: image).