dew.figures
SVG figures for notebooks and docs, in colors that follow the page’s light or dark theme.
A Figure is plain SVG. Its colors are CSS variables that the figure defines twice, for a
light and a dark page, and it picks one from where it is shown: the docs site’s data-theme,
Colab’s output frames, JupyterLab and VS Code, and otherwise the reader’s system setting. A
notebook shows a figure through _repr_html_; the docs and the tutorials’ concept figures are
the same markup in files (save), embedded as images. Animations are CSS keyframes inside the
SVG, so they play with no script, in an <img> too. Each one loops: it builds the picture,
holds it, and eases back to the start. With reduced motion asked for, only the held picture
shows.
curve, bars, heatmap, images, points and tokens draw the charts the tutorials make from their own
runs.
| Name | Summary |
|---|---|
THEMES | Each theme’s color for each role a figure draws with. |
Figure | An SVG drawing, width by height, whose animations loop every seconds. |
Shape | One SVG element: its tag, attributes, style, text, children and, once animated, its keyframes. |
bars | Bars that move from frame to frame: frames[t][k] is bar k’s height in frame t. |
curve | Lines over steps that draw themselves, one per entry of series, the first in the accent color. |
heatmap | A grid whose cells fade from frame to frame: frames[t][r][c], from 0 to 1, is cell (r, c)‘s strength in frame t. |
images | A grid of photographs that changes from frame to frame: frames[t] is frame t’s images, uint8 [N, H, W, C], drawn size wide in rows of columns. |
points | Dots, one series per entry of series, the first in the accent color and the others neutral, as curve colors them. |
tokens | Rows of token boxes, each as wide as its text and at least cell, fills[i][j] filling token j of row i (“none” leaves it an outline), with notes[i] beside row i. |
THEMES
Section titled “THEMES”THEMES: dict[str, dict[str, str]]Each theme’s color for each role a figure draws with.
Figure
Section titled “Figure”class Figure( width: float, height: float, *, seconds: float = 0.0, label: str = '', palette: Mapping[str, str] = VARIABLES,)An SVG drawing, width by height, whose animations loop every seconds.
Each drawing method adds a shape and returns it, for animate. Colors are roles (Role),
which palette turns into CSS: by default the theme variables, or one theme’s colors from
THEMES for a figure drawn once per theme. label is what a screen reader says.
Figure.add
Section titled “Figure.add”def add( tag: str, attributes: Mapping[str, float | str], style: Mapping[str, str] | None = None, text: str = '',) -> ShapeAdd an element with these attributes (numbers rounded to hundredths) and this text, which the markup escapes, to the open group.
Figure.rect
Section titled “Figure.rect”def rect( x: float, y: float, w: float, h: float, *, fill: Role = 'surface', stroke: Role = 'rule', rx: float = 6, width: float = 1,) -> ShapeA rectangle with corners rounded by rx, outlined width wide.
Figure.circle
Section titled “Figure.circle”def circle( cx: float, cy: float, r: float, *, fill: Role = 'accent', stroke: Role = 'none',) -> ShapeA circle of radius r centred on (cx, cy).
Figure.line
Section titled “Figure.line”def line( x1: float, y1: float, x2: float, y2: float, *, color: Role = 'muted', width: float = 1.25, dash: str | None = None,) -> ShapeA straight line, dashed by the SVG dash pattern dash when given.
Figure.polyline
Section titled “Figure.polyline”def polyline( points: Sequence[tuple[float, float]], *, color: Role = 'accent', width: float = 1.75, dash: str | None = None,) -> ShapeA line through points, as a path, which draw can trace.
Figure.arrow
Section titled “Figure.arrow”def arrow( x1: float, y1: float, x2: float, y2: float, *, color: Role = 'muted', width: float = 1.25,) -> ShapeA line from (x1, y1) with a filled head at (x2, y2).
Figure.text
Section titled “Figure.text”def text( x: float, y: float, words: str, *, size: float = 13, color: Role = 'text', mono: bool = False, anchor: str = 'start', weight: int = 400,) -> Shapewords on one line, anchored at (x, y) by anchor: “start”, “middle” or “end”.
Figure.image
Section titled “Figure.image”def image( x: float, y: float, size: float, pixels: np.ndarray, *, photo: bool = False,) -> ShapeA uint8 image, [H, W] or [H, W, C], drawn size wide: a PNG with its pixels kept sharp, or
with photo a WebP at quality 90 and smoothed, a fraction of a photograph’s PNG.
Figure.group
Section titled “Figure.group”def group(x: float = 0, y: float = 0) -> Iterator[Shape]Draw the block’s shapes into one group, moved by (x, y). Animate the shapes inside, or the group when it is not moved: a CSS transform replaces the group’s own.
Figure.animate
Section titled “Figure.animate”def animate( shape: Shape, keys: Mapping[float, Mapping[str, str | float]], *, origin: str = '',) -> ShapeGive shape these CSS properties at these seconds of the loop, eased in between.
Before the first key the shape holds the first key’s state; after the last it holds the
last’s, which is also its state when animation is off. origin is the transform origin
within the shape’s own box, as “50% 100%” to scale a bar from its foot.
Figure.appear
Section titled “Figure.appear”def appear(shape: Shape, at: float, fade: float = 0.4) -> ShapeHide shape until at seconds into the loop, then fade it in.
Figure.draw
Section titled “Figure.draw”def draw(shape: Shape, start: float, end: float) -> ShapeTrace a polyline from its first point to its last between start and end seconds.
Figure.show_in_turn
Section titled “Figure.show_in_turn”def show_in_turn( shapes: Sequence[Shape], times: Sequence[float], fade: float = 0.15,) -> NoneShow each of shapes from its time in times until the next one’s, the last until the
loop ends. One fades out before the next fades in, so shapes drawn in one place, such as
a frame’s caption, never show together.
Figure.svg
Section titled “Figure.svg”def svg() -> strThe figure as one SVG element, its stylesheet and keyframes inside.
Figure.save
Section titled “Figure.save”def save(path: str | Path) -> NoneWrite the figure to path, as one line of SVG.
class Shape( tag: str, attributes: dict[str, str], style: dict[str, str] = dict(), text: str = '', children: list[Shape] = list(), keyframes: str = '',)One SVG element: its tag, attributes, style, text, children and, once animated, its keyframes.
def bars( frames: Sequence[Sequence[float]], *, labels: Sequence[str], captions: Sequence[str] = (), colors: Sequence[Role] = (), y_max: float = 1.0, y_label: str = '', width: float = WIDE, height: float = 260, seconds: float = 8.0,) -> FigureBars that move from frame to frame: frames[t][k] is bar k’s height in frame t.
captions[t] names frame t, and colors[k] colors bar k (accent by default). Each bar
shows its value above it.
def curve( series: Mapping[str, Sequence[float]], *, x_label: str, y_label: str, x: Sequence[float] | Mapping[str, Sequence[float]] | None = None, y_range: tuple[float, float] | None = None, smooth: int = 1, width: float = WIDE, height: float = 290, seconds: float = 8.0,) -> FigureLines over steps that draw themselves, one per entry of series, the first in the accent color.
x holds each point’s step, as a tracker logged it: one sequence for every series, or a mapping
from each series’ name to its own steps, as a run’s training and validation are logged at
different steps. Without it the points are steps 0, 1, 2 and on. With smooth above 1 each line
is drawn faint, and its running mean over smooth points over it. A nonfinite value (a journal
keeps NaN and infinities) is left out of its line and of the axes, and the figure says how many
were.
heatmap
Section titled “heatmap”def heatmap( frames: Sequence[Sequence[Sequence[float]]], *, rows: Sequence[str], columns: Sequence[str], captions: Sequence[str] = (), x_label: str = '', y_label: str = '', marks: Sequence[tuple[int, int]] = (), cell: float = 28, seconds: float = 8.0,) -> FigureA grid whose cells fade from frame to frame: frames[t][r][c], from 0 to 1, is cell (r, c)‘s
strength in frame t. marks outlines cells, such as the ones the values should move to.
images
Section titled “images”def images( frames: Sequence[np.ndarray], *, captions: Sequence[str] = (), columns: int = 8, size: float = 64, rows: Sequence[str] = (), seconds: float = 8.0,) -> FigureA grid of photographs that changes from frame to frame: frames[t] is frame t’s images,
uint8 [N, H, W, C], drawn size wide in rows of columns. captions[t] names frame t, and
rows[r] names row r at its left. One frame is a still grid.
points
Section titled “points”def points( series: Mapping[str, Sequence[tuple[float, float]]], *, x_label: str, y_label: str, joined: bool = True, moved: Mapping[str, Sequence[tuple[float, float]]] | None = None, captions: Sequence[str] = (), log_x: bool = False, log_y: bool = False, width: float = WIDE, height: float = 300, seconds: float = 8.0,) -> FigureDots, one series per entry of series, the first in the accent color and the others neutral, as
curve colors them. Joined, each series is a line through its dots in order, named beside its last
dot, dashed past the third, and the series appear one after another. Not joined, the dots are a
scatter with the names in a legend; with moved, each dot then slides to its place there, and
captions name the two pictures. With log_x or log_y that axis is logarithmic.
tokens
Section titled “tokens”def tokens( rows: Sequence[Sequence[str]], *, fills: Sequence[Sequence[Role]], notes: Sequence[str] = (), cell: float = 27, seconds: float = 0.0,) -> FigureRows of token boxes, each as wide as its text and at least cell, fills[i][j] filling token j
of row i (“none” leaves it an outline), with notes[i] beside row i. With seconds, the rows
appear one after another.