Tesserax is a modern Python 3.12 library designed for programmatic SVG generation with a focus on ease of use, layout management, and flexible geometric primitives. It is particularly well-suited for visualizing data structures, algorithms, and technical diagrams.
Beyond static diagrams, Tesserax now includes a deterministic physics engine and a cinematic animation system, making it a complete toolkit for scientific communication.
- Rich Primitives: Includes standard shapes (
Rect,Circle) plus advanced procedural geometry likePolylinewith smoothing and subdivision support. - Declarative Layouts: Effortlessly arrange shapes in
Row,Column, orGridcontainers, or use algorithmic layouts likeTreeandForce. - Smart Canvas: Automatically fit the canvas viewport to the content with adjustable padding.
- Anchor System: Connect shapes using semantic anchors like
top,bottom,left,right, andcenter. - Cinematic Animations: Create complex motion graphics using a declarative, code-first API that supports keyframes, morphing, and warping.
- Physics Simulation: Bake high-precision rigid body simulations directly into your animations using the built-in
WorldandBodyprimitives. - Reactive Statistical Visualization: Build data-driven graphics with an Altair-inspired API that supports automatic axis generation and seamless Enter-Update-Exit animations.
- Rock-Solid Reliability: 90% test coverage ensuring predictable behavior across all geometric, layout, and animation systems.
Tesserax has zero dependencies (literally). It's 100% pure Python, and can be easily installed with pip:
pip install tesseraxOr if you're one of the cool kids, using uv:
uv add tesseraxIf you want support for saving PNG files, install with the export extra:
pip install tesserax[export]The following example demonstrates how to create a simple logo and highlights the most basic functionality of Tesserax.
import math
from tesserax import Canvas, Square, Circle, Text, Polyline, Point, Group
from tesserax.layout import RowLayout
with Canvas() as canvas:
# We use a top-level row layout
with RowLayout(align="end") as logo:
# Left Block
r = Square(30, fill="green", stroke="none")
# Center Text
t = Text(
"tesserax",
size=48,
font="sans-serif",
fill="navyblue",
anchor="middle",
baseline="bottom",
)
# Right Circle
c = Circle(20, fill="red", stroke="none")
# Create the "Squiggly" Underline
Polyline(
[
r.anchor("bottom").dy(10),
c.anchor("bottom").dy(10),
],
smoothness=1.0,
stroke="black",
marker_end="arrow",
).subdivide(5).apply(
lambda p: p.dy(math.sin((p.x / logo.bounds().width * 20 + 5)) * 5)
)
# Use fit() to frame the logo perfectly
canvas.fit(padding=10).display()
The display() method in the Canvas class is an IPython/Jupyter/Quarto compatible shortcut to automatically include the rendered SVG (in all its beautiful vectorial glory) directly in a notebook. But you can also use Canvas.save() to generate a plain old, boring SVG file on this, and str(canvas) to get the actual SVG code as a plain string.
Tesserax scales from simple scripts to complex simulations. Here is an overview of the advanced capabilities available.
Tesserax provides a robust suite of atoms like Rect, Circle, Ellipse, and Arrow.
- Polyline API: The
Polylineclass supportssmoothing(Bezier interpolation),subdivision(increasing resolution), andsimplification(reducing vertices). - Path API: For low-level control, use the
Pathclass with standard SVG commands (move_to,cubic_to,arc).
Forget manual pixel pushing. Tesserax offers a hierarchy of layout engines:
- Standard Layouts:
Row,Column, andGridautomatically position elements based on gaps and alignment. - Hierarchical Layout: Automatically draws Trees and Directed Acyclic Graphs (DAGs).
- Force-Directed Layout: Simulates physical forces to arrange arbitrary network graphs.
The animation system is designed for storytelling, not just movement.
- Declarative API: Compose animations using
parallel (|)andsequential (+)operators. - Keyframes: Define complex multi-stage timelines for any property (position, rotation, color).
- Morphing & Warping: Smoothly transform one shape into another or apply wave functions to geometry.
Tesserax includes a baked physics engine for high-precision rigid body simulations.
- Deterministic: Define a
World, addBodyobjects, and applyFields like Gravity or Drag. - Baked Playback: The simulation is calculated upfront and converted into standard keyframes, allowing high-resolution physics (e.g., 1000 steps/sec) to play back smoothly at any framerate.
- Interoperable: Physics animations can be mixed and matched with standard tweens.
Bridging the gap between diagrams and plots, Tesserax offers a grammar-of-graphics charting API.
- Altair-lite API: Define a
Chart, select aMark(bar, point), andencodevisual channels likex,y, andcolor. - Automated Scales: Includes built-in
Linear,Band, andColorscales that automatically map data values to pixels and palettes. - Integrated Axes: Effortlessly add titles, ticks, and gridlines with smart coordinate management.
In the Python ecosystem, there is a clear divide between data visualization (plotting numbers) and diagrammatic representation (drawing concepts).
Tesserax is for Scientific Drawing---providing the low-level primitives needed for total layout authority.
Libraries like Matplotlib map data to charts. Tesserax maps concepts to geometry. Use Tesserax for the schematics, geometric proofs, and algorithmic walkthroughs in your papers.
TikZ is the industry standard for academic figures but uses a cryptic macro language. Tesserax brings that same "total-control" philosophy to Python 3.12, giving you coordinate-invariant precision with the power of Python's loops and types.
Tesserax is free as in both free beer and free speech. License is MIT.
Contributions are always welcomed! Fork, clone, and submit a pull request.