tesserax 0.5.1__py3-none-any.whl

tesserax/__init__.py

@@ -0,0 +1,16 @@
+from .canvas import Canvas
+from .core import Shape, Bounds, Point
+from .base import (
+    Rect,
+    Square,
+    Circle,
+    Ellipse,
+    Line,
+    Arrow,
+    Group,
+    Path,
+    Polyline,
+    Text,
+)
+
+__version__ = "0.5.1"

tesserax/base.py

@@ -0,0 +1,459 @@
+from __future__ import annotations
+from typing import Callable, Literal, Self
+from .core import Anchor, Point, Shape, Bounds
+
+
+class Rect(Shape):
+    """A rectangular shape, the foundation for arrays and memory blocks."""
+
+    def __init__(
+        self,
+        w: float,
+        h: float,
+        stroke: str = "black",
+        fill: str = "none",
+    ) -> None:
+        super().__init__()
+        self.w, self.h = w, h
+        self.stroke, self.fill = stroke, fill
+
+    def local(self) -> Bounds:
+        return Bounds(0, 0, self.w, self.h)
+
+    def _render(self) -> str:
+        return f'<rect x="0" y="0" width="{self.w}" height="{self.h}" stroke="{self.stroke}" fill="{self.fill}" />'
+
+
+class Square(Rect):
+    """A specialized Rect where width equals height."""
+
+    def __init__(self, size: float, stroke: str = "black", fill: str = "none") -> None:
+        super().__init__(size, size, stroke, fill)
+
+
+class Circle(Shape):
+    """A circle, ideal for nodes in trees or states in automata."""
+
+    def __init__(self, r: float, stroke: str = "black", fill: str = "none") -> None:
+        super().__init__()
+        self.r = r
+        self.stroke, self.fill = stroke, fill
+
+    def local(self) -> Bounds:
+        return Bounds(-self.r, -self.r, self.r * 2, self.r * 2)
+
+    def _render(self) -> str:
+        return f'<circle cx="0" cy="0" r="{self.r}" stroke="{self.stroke}" fill="{self.fill}" />'
+
+
+class Ellipse(Shape):
+    """An ellipse for when text labels are wider than they are tall."""
+
+    def __init__(
+        self,
+        rx: float,
+        ry: float,
+        stroke: str = "black",
+        fill: str = "none",
+    ) -> None:
+        super().__init__()
+        self.rx, self.ry = rx, ry
+        self.stroke, self.fill = stroke, fill
+
+    def local(self) -> Bounds:
+        return Bounds(-self.rx, -self.ry, self.rx * 2, self.ry * 2)
+
+    def _render(self) -> str:
+        return f'<ellipse cx="0" cy="0" rx="{self.rx}" ry="{self.ry}" stroke="{self.stroke}" fill="{self.fill}" />'
+
+
+class Line(Shape):
+    """A basic connection between two points, supports dynamic point resolution."""
+
+    def __init__(
+        self,
+        p1: Point | Callable[[], Point],
+        p2: Point | Callable[[], Point],
+        stroke: str = "black",
+        width: float = 1.0,
+    ) -> None:
+        super().__init__()
+        self.p1, self.p2 = p1, p2
+        self.stroke, self.width = stroke, width
+
+    def _resolve(self) -> tuple[Point, Point]:
+        """Resolves coordinates if they are provided as callables."""
+        p1 = self.p1() if callable(self.p1) else self.p1
+        p2 = self.p2() if callable(self.p2) else self.p2
+        return p1, p2
+
+    def local(self) -> Bounds:
+        p1, p2 = self._resolve()
+        x = min(p1.x, p2.x)
+        y = min(p1.y, p2.y)
+        return Bounds(x, y, abs(p1.x - p2.x), abs(p1.y - p2.y))
+
+    def _render(self) -> str:
+        p1, p2 = self._resolve()
+        return (
+            f'<line x1="{p1.x}" y1="{p1.y}" x2="{p2.x}" y2="{p2.y}" '
+            f'stroke="{self.stroke}" stroke-width="{self.width}" />'
+        )
+
+
+class Arrow(Line):
+    """A line with an arrowhead, resolving points dynamically during render."""
+
+    def _render(self) -> str:
+        p1, p2 = self._resolve()
+        return (
+            f'<line x1="{p1.x}" y1="{p1.y}" x2="{p2.x}" y2="{p2.y}" '
+            f'stroke="{self.stroke}" stroke-width="{self.width}" marker-end="url(#arrowhead)" />'
+        )
+
+
+class Group(Shape):
+    stack: list[list[Shape]] = []
+
+    @classmethod
+    def current(cls) -> list[Shape] | None:
+        if cls.stack:
+            return cls.stack[-1]
+
+        return None
+
+    """A collection of shapes that behaves as a single unit."""
+
+    def __init__(self, shapes: list[Shape] | None = None) -> None:
+        super().__init__()
+        self.shapes: list[Shape] = []
+
+        if shapes:
+            self.add(*shapes)
+
+    def add(self, *shapes: Shape) -> Group:
+        """Adds a shape and returns self for chaining."""
+        for shape in shapes:
+            if shape.parent:
+                raise ValueError("Cannot add one object to more than one group.")
+
+            self.shapes.append(shape)
+            shape.parent = self
+
+        return self
+
+    def local(self) -> Bounds:
+        """Computes the union of all child bounds."""
+        if not self.shapes:
+            return Bounds(0, 0, 0, 0)
+
+        return Bounds.union(*[s.bounds() for s in self.shapes])
+
+    def _render(self) -> str:
+        return "\n".join(s.render() for s in self.shapes)
+
+    def __iadd__(self, other: Shape) -> Self:
+        """Enables 'group += shape'."""
+        self.shapes.append(other)
+        return self
+
+    def __enter__(self):
+        self.stack.append([])
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.add(*self.stack.pop())
+
+    def align(
+        self,
+        axis: Literal["horizontal", "vertical", "both"] = "both",
+        anchor: Anchor = "center",
+    ) -> Self:
+        """
+        Aligns all children in the group relative to the anchor of the first child.
+
+        The alignment is performed in the group's local coordinate system by
+        adjusting the translation (tx, ty) of each shape.
+        """
+        if not self.shapes:
+            return self
+
+        # The first shape acts as the reference datum for the alignment
+        first = self.shapes[0]
+        ref_p = first.transform.map(first.local().anchor(anchor))
+
+        for shape in self.shapes[1:]:
+            # Calculate the child's anchor point in the group's coordinate system
+            curr_p = shape.transform.map(shape.local().anchor(anchor))
+
+            if axis in ("horizontal", "both"):
+                shape.transform.tx += ref_p.x - curr_p.x
+
+            if axis in ("vertical", "both"):
+                shape.transform.ty += ref_p.y - curr_p.y
+
+        return self
+
+
+class Path(Shape):
+    """
+    A shape defined by an SVG path data string.
+    Maintains an internal cursor to support relative movements and
+    layout bounding box calculations.
+    """
+
+    def __init__(self, stroke: str = "black", width: float = 1) -> None:
+        super().__init__()
+        self.stroke = stroke
+        self.width = width
+        self._reset()
+
+    def _reset(self):
+        self._commands: list[str] = []
+        self._cursor: tuple[float, float] = (0.0, 0.0)
+
+        self._min_x: float = float("inf")
+        self._min_y: float = float("inf")
+        self._max_x: float = float("-inf")
+        self._max_y: float = float("-inf")
+
+    def local(self) -> Bounds:
+        """
+        Returns the bounding box of the path in its local coordinate system.
+        """
+        if not self._commands:
+            return Bounds(0, 0, 0, 0)
+
+        width = self._max_x - self._min_x
+        height = self._max_y - self._min_y
+
+        return Bounds(self._min_x, self._min_y, width, height)
+
+    def move_to(self, x: float, y: float) -> Self:
+        """Moves the pen to the absolute coordinates (x, y)."""
+        self._commands.append(f"M {x} {y}")
+        self._update_cursor(x, y)
+        return self
+
+    def move_by(self, dx: float, dy: float) -> Self:
+        """Moves the pen relative to the current position."""
+        x, y = self._cursor
+        return self.move_to(x + dx, y + dy)
+
+    def line_to(self, x: float, y: float) -> Self:
+        """Draws a straight line to the absolute coordinates (x, y)."""
+        self._commands.append(f"L {x} {y}")
+        self._update_cursor(x, y)
+        return self
+
+    def line_by(self, dx: float, dy: float) -> Self:
+        """Draws a line relative to the current position."""
+        x, y = self._cursor
+        return self.line_to(x + dx, y + dy)
+
+    def cubic_to(
+        self,
+        cp1_x: float,
+        cp1_y: float,
+        cp2_x: float,
+        cp2_y: float,
+        end_x: float,
+        end_y: float,
+    ) -> Self:
+        """
+        Draws a cubic Bezier curve to (end_x, end_y) using two control points.
+        """
+        self._commands.append(f"C {cp1_x} {cp1_y}, {cp2_x} {cp2_y}, {end_x} {end_y}")
+
+        # We include control points in bounds to ensure the curve is
+        # roughly contained, even though this is a loose approximation.
+        self._expand_bounds(cp1_x, cp1_y)
+        self._expand_bounds(cp2_x, cp2_y)
+        self._update_cursor(end_x, end_y)
+        return self
+
+    def quadratic_to(self, cx: float, cy: float, ex: float, ey: float) -> Self:
+        """
+        Draws a quadratic Bezier curve to (ex, ey) with control point (cx, cy).
+        """
+        self._commands.append(f"Q {cx} {cy}, {ex} {ey}")
+        self._expand_bounds(cx, cy)  # Approximate bounds including control point
+        self._update_cursor(ex, ey)
+        return self
+
+    def close(self) -> Self:
+        """Closes the path by drawing a line back to the start."""
+        self._commands.append("Z")
+        return self
+
+    def _update_cursor(self, x: float, y: float) -> None:
+        """Updates the internal cursor and expands the bounding box."""
+        self._cursor = (x, y)
+        self._expand_bounds(x, y)
+
+    def _expand_bounds(self, x: float, y: float) -> None:
+        """Updates the min/max bounds of the shape."""
+        # Initialize bounds on first move if logic dictates,
+        # or rely on 0,0 default if paths always start at origin.
+        self._min_x = min(self._min_x, x)
+        self._min_y = min(self._min_y, y)
+        self._max_x = max(self._max_x, x)
+        self._max_y = max(self._max_y, y)
+
+    def _render(self) -> str:
+        """Renders the standard SVG path element."""
+        # You might want to offset commands by self.x/self.y if
+        # this shape is moved by a Layout.
+        d_attr = " ".join(self._commands)
+        return f'<path d="{d_attr}" fill="none" stroke="{self.stroke}" stroke-width="{self.width}" />'
+
+
+class Polyline(Path):
+    """
+    A sequence of connected lines with optional corner rounding.
+
+    Args:
+        points: List of vertices.
+        smoothness: 0.0 (sharp) to 1.0 (fully rounded/spline-like).
+        closed: If True, connects the last point back to the first.
+    """
+
+    def __init__(
+        self,
+        points: list[Point],
+        smoothness: float = 0.0,
+        closed: bool = False,
+        stroke: str = "black",
+        width: float = 1.0,
+    ) -> None:
+        super().__init__(stroke=stroke, width=width)
+
+        self.points = points or []
+        self.smoothness = smoothness
+        self.closed = closed
+        self._build()
+
+    def add(self, p: Point) -> Self:
+        self.points.append(p)
+        return self
+
+    def _build(self):
+        self._reset()
+
+        if not self.points:
+            return
+
+        # Clamp smoothness to 0-1 range
+        s = max(0.0, min(1.0, self.smoothness))
+
+        # Determine effective loop of points
+        # If closed, we wrap around; if not, we handle start/end differently
+        verts = self.points + ([self.points[0], self.points[1]] if self.closed else [])
+
+        # 1. Move to the geometric start
+        # If smoothing is on and not self.closed, we start exactly at P0
+        # If closed, we start at the midpoint of the last segment (handled by loop)
+        self.move_to(verts[0].x, verts[0].y)
+
+        # We iterate through triplets: (Prev, Curr, Next)
+        # But for an open polyline, we only round the *internal* corners.
+
+        if len(verts) < 3:
+            # Fallback for simple line
+            for p in verts[1:]:
+                self.line_to(p.x, p.y)
+
+            return
+
+        # Logic for Open Polyline
+        # P0 -> ... -> Pn
+        # We start at P0.
+        # For every corner P_i, we draw a line to "Start of Curve", then curve to "End of Curve".
+
+        # Start
+        curr_p = verts[0]
+        self.move_to(curr_p.x, curr_p.y)
+
+        for i in range(1, len(verts) - 1):
+            prev_p = verts[i - 1]
+            curr_p = verts[i]
+            next_p = verts[i + 1]
+
+            # Vectors
+            vec_in = curr_p - prev_p
+            vec_out = next_p - curr_p
+
+            len_in = vec_in.magnitude()
+            len_out = vec_out.magnitude()
+
+            # Corner Radius determination
+            # We can't exceed 50% of the shortest leg, or curves will overlap
+            max_r = min(len_in, len_out) / 2.0
+            radius = max_r * s
+
+            # Calculate geometric points
+            # "Start of Curve" is back along the incoming vector
+            p_start = curr_p - vec_in.normalize() * radius
+
+            # "End of Curve" is forward along the outgoing vector
+            p_end = curr_p + vec_out.normalize() * radius
+
+            # Draw
+            self.line_to(p_start.x, p_start.y)
+            self.quadratic_to(curr_p.x, curr_p.y, p_end.x, p_end.y)
+
+        # Finish at the last point
+        last = verts[-1]
+        self.line_to(last.x, last.y)
+
+        if self.closed:
+            self.close()
+
+    def _render(self) -> str:
+        self._build()
+        return super()._render()
+
+
+class Text(Shape):
+    """
+    A text primitive with heuristic-based bounding box calculation.
+    """
+
+    def __init__(
+        self,
+        content: str,
+        size: float = 12,
+        font: str = "sans-serif",
+        fill: str = "black",
+        anchor: Literal["start", "middle", "end"] = "middle",
+    ) -> None:
+        super().__init__()
+        self.content = content
+        self.size = size
+        self.font = font
+        self.fill = fill
+        self._anchor = anchor
+
+    def local(self) -> Bounds:
+        # Heuristic: average character width is ~60% of font size
+        width = len(self.content) * self.size * 0.6
+        height = self.size
+
+        match self._anchor:
+            case "start":
+                return Bounds(0, -height + 2, width, height)
+            case "middle":
+                return Bounds(-width / 2, -height + 2, width, height)
+            case "end":
+                return Bounds(-width, -height + 2, width, height)
+            case _:
+                raise ValueError(f"Invalid anchor: {self._anchor}")
+
+    def _render(self) -> str:
+        # dominant-baseline="middle" or "alphabetic" helps vertical alignment
+        # but "central" is often more predictable for layout centers.
+        return (
+            f'<text x="0" y="0" font-family="{self.font}" font-size="{self.size}" '
+            f'fill="{self.fill}" text-anchor="{self._anchor}" dominant-baseline="middle">'
+            f"{self.content}</text>"
+        )

tesserax/canvas.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+from pathlib import Path
+from .core import Shape, Bounds
+from .base import Group
+
+
+class Canvas(Group):
+    def __init__(self, width: float = 1000, height: float = 1000) -> None:
+        super().__init__()
+
+        self.width = width
+        self.height = height
+        self._defs: list[str] = [
+            """<marker id="arrowhead" markerWidth="10" markerHeight="7"
+            refX="9" refY="3.5" orient="auto">
+                <polygon points="0 0, 10 3.5, 0 7" fill="black" />
+            </marker>"""
+        ]
+        # Default viewbox is the full canvas size
+        self._viewbox: tuple[float, float, float, float] = (0, 0, width, height)
+
+    def _repr_svg_(self) -> str:
+        """Enables automatic rendering in Jupyter/Quarto environments."""
+        return self._build_svg()
+
+    def display(self) -> None:
+        """
+        Explicitly renders the SVG in supported interactive environments.
+
+        Uses IPython.display to render the SVG. If the environment does
+        not support rich display, it falls back to printing the SVG string.
+        """
+        from IPython.display import SVG, display as ipy_display
+
+        ipy_display(SVG(self._build_svg()))
+
+    def fit(self, padding: float = 0, crop: bool = True) -> Canvas:
+        """
+        Reduces the viewBox to perfectly fit all added shapes.
+        If crop is True (default), the width and height will also be adjusted.
+        """
+        all_bounds = [s.bounds() for s in self.shapes]
+        tight_bounds = Bounds.union(*all_bounds).padded(padding)
+
+        self._viewbox = (
+            tight_bounds.x,
+            tight_bounds.y,
+            tight_bounds.width,
+            tight_bounds.height,
+        )
+
+        if crop:
+            self.width = tight_bounds.width
+            self.height = tight_bounds.height
+
+        return self
+
+    def _build_svg(self) -> str:
+        content = "\n  ".join(s.render() for s in self.shapes)
+        defs_content = "\n    ".join(self._defs)
+
+        vx, vy, vw, vh = self._viewbox
+        return (
+            f'<svg width="{self.width}" height="{self.height}" '
+            f'viewBox="{vx} {vy} {vw} {vh}" '
+            'xmlns="http://www.w3.org/2000/svg">\n'
+            f"  <defs>\n    {defs_content}\n  </defs>\n"
+            f"  {content}\n"
+            "</svg>"
+        )
+
+    def save(self, path: str | Path, dpi: int = 300) -> None:
+        """
+        Exports the canvas to a raster or vector format with a transparent background.
+
+        Supported formats: .png, .pdf, .svg, .ps.
+        Requires the 'export' extra (cairosvg).
+        """
+
+        svg_data = self._build_svg().encode("utf-8")
+        target = str(path)
+        extension = Path(path).suffix.lower()
+
+        if extension == ".svg":
+            with open(path, "wb") as fp:
+                fp.write(svg_data)
+
+            return
+
+        try:
+            import cairosvg
+        except ImportError:
+            raise ImportError(
+                "Export requires 'cairosvg'. Install with: pip install tesserax[export]"
+            )
+
+        match extension:
+            case ".png":
+                # CairoSVG handles transparency by default if the SVG has no background rect
+                cairosvg.svg2png(bytestring=svg_data, write_to=target, dpi=dpi)
+            case ".pdf":
+                cairosvg.svg2pdf(bytestring=svg_data, write_to=target, dpi=dpi)
+            case ".ps":
+                cairosvg.svg2ps(bytestring=svg_data, write_to=target, dpi=dpi)
+            case _:
+                raise ValueError(f"Unsupported export format: {extension}")
+
+    def __str__(self) -> str:
+        return self._build_svg()

tesserax/core.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+import copy
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+import math
+from typing import Literal, Self, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import Group
+
+type Anchor = Literal[
+    "top",
+    "bottom",
+    "left",
+    "right",
+    "center",
+    "topleft",
+    "topright",
+    "bottomleft",
+    "bottomright",
+]
+
+
+@dataclass(frozen=True)
+class Point:
+    x: float
+    y: float
+
+    def apply(self, tx=0.0, ty=0.0, r=0.0, s=1.0) -> Point:
+        rad = math.radians(r)
+        nx, ny = self.x * s, self.y * s
+        rx = nx * math.cos(rad) - ny * math.sin(rad)
+        ry = nx * math.sin(rad) + ny * math.cos(rad)
+        return Point(rx + tx, ry + ty)
+
+    def __add__(self, other: Point) -> Point:
+        return Point(self.x + other.x, self.y + other.y)
+
+    def __sub__(self, other: Point) -> Point:
+        return Point(self.x - other.x, self.y - other.y)
+
+    def magnitude(self) -> float:
+        return math.sqrt(self.x**2 + self.y**2)
+
+    def normalize(self) -> Point:
+        m = self.magnitude()
+
+        if m == 0:
+            return Point(0, 0)
+
+        return Point(self.x / m, self.y / m)
+
+    def __mul__(self, scalar: float) -> Point:
+        return Point(self.x * scalar, self.y * scalar)
+
+    def __truediv__(self, scalar: float) -> Point:
+        return Point(self.x / scalar, self.y / scalar)
+
+    def dx(self, dx: float) -> Point:
+        return self + Point(dx, 0)
+
+    def dy(self, dy: float) -> Point:
+        return self + Point(0, dy)
+
+    def d(self, dx: float, dy: float) -> Point:
+        return self + Point(dx, dy)
+
+
+@dataclass
+class Transform:
+    tx: float = 0.0
+    ty: float = 0.0
+    rotation: float = 0.0
+    scale: float = 1.0
+
+    def map(self, p: Point) -> Point:
+        return p.apply(self.tx, self.ty, self.rotation, self.scale)
+
+    def reset(self) -> None:
+        self.tx = 0.0
+        self.ty = 0.0
+        self.rotation = 0.0
+        self.scale = 1.0
+
+
+@dataclass(frozen=True)
+class Bounds:
+    x: float
+    y: float
+    width: float
+    height: float
+
+    @property
+    def left(self) -> Point:
+        return Point(self.x, self.y + self.height / 2)
+
+    @property
+    def right(self) -> Point:
+        return Point(self.x + self.width, self.y + self.height / 2)
+
+    @property
+    def top(self) -> Point:
+        return Point(self.x + self.width / 2, self.y)
+
+    @property
+    def bottom(self) -> Point:
+        return Point(self.x + self.width / 2, self.y + self.height)
+
+    @property
+    def topleft(self) -> Point:
+        return Point(self.x, self.y)
+
+    @property
+    def topright(self) -> Point:
+        return Point(self.x + self.width, self.y)
+
+    @property
+    def bottomleft(self) -> Point:
+        return Point(self.x, self.y + self.height)
+
+    @property
+    def bottomright(self) -> Point:
+        return Point(self.x + self.width, self.y + self.height)
+
+    @property
+    def center(self) -> Point:
+        return Point(self.x + self.width / 2, self.y + self.height / 2)
+
+    def padded(self, amount: float) -> Bounds:
+        return Bounds(
+            self.x - amount,
+            self.y - amount,
+            self.width + 2 * amount,
+            self.height + 2 * amount,
+        )
+
+    def anchor(self, name: Anchor) -> Point:
+        match name:
+            case "top":
+                return self.top
+            case "bottom":
+                return self.bottom
+            case "left":
+                return self.left
+            case "right":
+                return self.right
+            case "center":
+                return self.center
+            case "topleft":
+                return self.topleft
+            case "topright":
+                return self.topright
+            case "bottomleft":
+                return self.bottomleft
+            case "bottomright":
+                return self.bottomright
+            case _:
+                raise ValueError(f"Unknown anchor: {name}")
+
+    @classmethod
+    def union(cls, *bounds: Bounds) -> Bounds:
+        if not bounds:
+            return Bounds(0, 0, 0, 0)
+
+        x_min = min(b.x for b in bounds)
+        y_min = min(b.y for b in bounds)
+        x_max = max(b.x + b.width for b in bounds)
+        y_max = max(b.y + b.height for b in bounds)
+
+        return Bounds(x_min, y_min, x_max - x_min, y_max - y_min)
+
+
+class Shape(ABC):
+    def __init__(self) -> None:
+        from .base import Group
+
+        self.transform = Transform()
+        self.parent: Group | None = None
+
+        if (gp := Group.current()) is not None:
+            gp.append(self)
+
+    @abstractmethod
+    def local(self) -> Bounds:
+        pass
+
+    def bounds(self) -> Bounds:
+        base = self.local()
+
+        corners = [base.topleft, base.topright, base.bottomleft, base.bottomright]
+        transformed = [self.transform.map(p) for p in corners]
+        xs = [p.x for p in transformed]
+        ys = [p.y for p in transformed]
+
+        return Bounds(min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys))
+
+    @abstractmethod
+    def _render(self) -> str:
+        pass
+
+    def render(self) -> str:
+        """Wraps the inner content in a transform group."""
+        t = self.transform
+        ts = f' transform="translate({t.tx} {t.ty}) rotate({t.rotation}) scale({t.scale})"'
+        return f"<g{ts}>\n{self._render()}\n</g>"
+
+    def resolve(self, p: Point) -> Point:
+        world_p = self.transform.map(p)
+        if self.parent:
+            return self.parent.resolve(world_p)
+        return world_p
+
+    def anchor(self, name: Anchor) -> Point:
+        return self.resolve(self.local().anchor(name))
+
+    def translated(self, dx: float, dy: float) -> Self:
+        self.transform.tx += dx
+        self.transform.ty += dy
+        return self
+
+    def rotated(self, r: float) -> Self:
+        self.transform.rotation += r
+        return self
+
+    def scaled(self, s: float) -> Self:
+        self.transform.scale += s
+        return self
+
+    def clone(self) -> Self:
+        return copy.deepcopy(self)
+
+    def __add__(self, other: Shape) -> Group:
+        # Import internally to avoid circular import with base.py
+        from .base import Group
+
+        return Group().add(self, other)

tesserax/layout.py

@@ -0,0 +1,355 @@
+from abc import abstractmethod
+from collections import defaultdict
+import math
+from typing import Literal, Self
+from .core import Shape, Bounds
+from .base import Group
+
+
+class Layout(Group):
+    def __init__(self, shapes: list[Shape] | None = None) -> None:
+        super().__init__(shapes)
+
+    @abstractmethod
+    def do_layout(self) -> None:
+        """
+        Implementation must iterate over self.shapes, RESET their transforms,
+        and then apply new translations.
+        """
+        ...
+
+    def add(self, *shapes: Shape) -> "Layout":
+        super().add(*shapes)
+        self.do_layout()
+        return self
+
+
+type Align = Literal["start", "middle", "end"]
+
+
+class Row(Layout):
+    def __init__(
+        self,
+        shapes: list[Shape] | None = None,
+        align: Align = "middle",
+        gap: float = 0,
+    ) -> None:
+        self.align = align
+        self.gap = gap
+        super().__init__(shapes)
+
+    def do_layout(self) -> None:
+        if not self.shapes:
+            return
+
+        # 1. First pass: Reset transforms so we get pure local bounds
+        for s in self.shapes:
+            s.transform.reset()
+
+        # 2. Calculate offsets based on the 'clean' shapes
+        max_h = max(s.local().height for s in self.shapes)
+        current_x = 0.0
+
+        for shape in self.shapes:
+            b = shape.local()
+
+            # Calculate Y based on baseline
+            match self.align:
+                case "start":
+                    dy = -b.y
+                case "middle":
+                    dy = (max_h / 2) - (b.y + b.height / 2)
+                case "end":
+                    dy = max_h - (b.y + b.height)
+                case _:
+                    dy = 0
+
+            # 3. Apply the strict layout position
+            shape.transform.tx = current_x - b.x
+            shape.transform.ty = dy
+
+            current_x += b.width + self.gap
+
+
+class Column(Row):
+    def __init__(
+        self,
+        shapes: list[Shape] | None = None,
+        align: Align = "middle",
+        gap: float = 0,
+    ) -> None:
+        super().__init__(shapes, align, gap)
+
+    def do_layout(self) -> None:
+        if not self.shapes:
+            return
+
+        for s in self.shapes:
+            s.transform.reset()
+
+        max_w = max(s.local().width for s in self.shapes)
+        current_y = 0.0
+
+        for shape in self.shapes:
+            b = shape.local()
+
+            match self.align:
+                case "start":
+                    dx = -b.x
+                case "end":
+                    dx = max_w - (b.x + b.width)
+                case "middle":
+                    dx = (max_w / 2) - (b.x + b.width / 2)
+                case _:
+                    dx = 0
+
+            shape.transform.tx = dx
+            shape.transform.ty = current_y - b.y
+
+            current_y += b.height + self.gap
+
+
+class ForceLayout(Layout):
+    """
+    A force-directed layout for graph visualization.
+
+    Nodes are positioned using a physical simulation where connections act
+    as springs (attraction) and all nodes repel each other (repulsion).
+    """
+
+    def __init__(
+        self,
+        shapes: list[Shape] | None = None,
+        iterations: int = 100,
+        k: float | None = None,
+    ) -> None:
+        super().__init__(shapes)
+        self.connections: list[tuple[Shape, Shape]] = []
+        self.iterations = iterations
+        self.k_const = k
+
+    def connect(self, u: Shape, v: Shape) -> Self:
+        """
+        Defines an undirected connection between two shapes.
+        The layout will use this connection to apply attractive forces.
+        """
+        self.connections.append((u, v))
+        return self
+
+    def do_layout(self) -> None:
+        """
+        Executes the Fruchterman-Reingold force-directed simulation.
+        """
+        if not self.shapes:
+            return
+
+        # 1. Initialize positions in a circle to avoid overlapping origins
+        for i, shape in enumerate(self.shapes):
+            if shape.transform.tx == 0 and shape.transform.ty == 0:
+                angle = (2 * math.pi * i) / len(self.shapes)
+                shape.transform.tx = 100 * math.cos(angle)
+                shape.transform.ty = 100 * math.sin(angle)
+
+        # 2. Simulation parameters
+        # k is the optimal distance between nodes
+        area = 600 * 600
+        k = self.k_const or math.sqrt(area / len(self.shapes))
+        t = 100.0  # Temperature (max displacement per step)
+        dt = t / self.iterations
+
+        for _ in range(self.iterations):
+            # Store displacement for each shape ID
+            disp = {id(s): [0.0, 0.0] for s in self.shapes}
+
+            # Repulsion Force (between all pairs)
+            for i, v in enumerate(self.shapes):
+                for j, u in enumerate(self.shapes):
+                    if i == j:
+                        continue
+
+                    dx = v.transform.tx - u.transform.tx
+                    dy = v.transform.ty - u.transform.ty
+                    dist = math.sqrt(dx * dx + dy * dy) + 0.01
+
+                    # fr(d) = k^2 / d
+                    mag = (k * k) / dist
+                    disp[id(v)][0] += (dx / dist) * mag
+                    disp[id(v)][1] += (dy / dist) * mag
+
+            # Attraction Force (only between connected nodes)
+            for u, v in self.connections:
+                dx = v.transform.tx - u.transform.tx
+                dy = v.transform.ty - u.transform.ty
+                dist = math.sqrt(dx * dx + dy * dy) + 0.01
+
+                # fa(d) = d^2 / k
+                mag = (dist * dist) / k
+                fx, fy = (dx / dist) * mag, (dy / dist) * mag
+
+                disp[id(v)][0] -= fx
+                disp[id(v)][1] -= fy
+                disp[id(u)][0] += fx
+                disp[id(u)][1] += fy
+
+            # Apply displacement limited by temperature
+            for shape in self.shapes:
+                dx, dy = disp[id(shape)]
+                dist = math.sqrt(dx * dx + dy * dy) + 0.01
+
+                shape.transform.tx += (dx / dist) * min(dist, t)
+                shape.transform.ty += (dy / dist) * min(dist, t)
+
+            # Cool the simulation
+            t -= dt
+
+
+class HierarchicalLayout(Layout):
+    """
+    Arranges nodes in distinct layers based on directed connections.
+    Supports both Vertical (Top-Bottom) and Horizontal (Left-Right) flows.
+    """
+
+    def __init__(
+        self,
+        shapes: list[Shape] | None = None,
+        roots: list[Shape] | None = None,
+        rank_sep: float = 50.0,
+        node_sep: float = 20.0,
+        orientation: Literal["vertical", "horizontal"] = "vertical",
+    ) -> None:
+        super().__init__(shapes)
+        self.rank_sep = rank_sep
+        self.node_sep = node_sep
+        self.orientation = orientation
+        self.roots = set(roots or [])
+        self.adj: dict[Shape, list[Shape]] = defaultdict(list)
+        self.rev_adj: dict[Shape, list[Shape]] = defaultdict(list)
+
+    def root(self, n: Shape) -> Self:
+        self.roots.add(n)
+        return self
+
+    def connect(self, u: Shape, v: Shape) -> Self:
+        """Defines a directed dependency u -> v."""
+        self.adj[u].append(v)
+        self.rev_adj[v].append(u)
+        return self
+
+    def do_layout(self) -> None:
+        if not self.shapes:
+            return
+
+        # 1. Ranking Phase: Assign layers (ignoring back-edges)
+        ranks = self._assign_ranks()
+
+        layers: dict[int, list[Shape]] = defaultdict(list)
+        for s, r in ranks.items():
+            layers[r].append(s)
+
+        max_rank = max(layers.keys()) if layers else 0
+
+        # 2. Ordering Phase: Minimize crossings (Barycenter Method)
+        for r in range(1, max_rank + 1):
+            layers[r].sort(key=lambda node: self._barycenter(node, layers[r - 1]))
+
+        # 3. Positioning Phase: Assign physical coordinates
+        # 'current_flow' tracks the position along the main axis (Y for vert, X for horz)
+        current_flow = 0.0
+
+        for r in sorted(layers.keys()):
+            layer = layers[r]
+
+            # Reset transforms to get clean local bounds
+            for s in layer:
+                s.transform.reset()
+
+            # Calculate metrics for centering this layer
+            if self.orientation == "horizontal":
+                # In horizontal, 'breadth' is the height of the nodes
+                breadths = [s.local().height for s in layer]
+                # 'depth' is the width of the nodes (rank thickness)
+                depths = [s.local().width for s in layer]
+            else:
+                # In vertical, 'breadth' is the width of the nodes
+                breadths = [s.local().width for s in layer]
+                # 'depth' is the height of the nodes (rank thickness)
+                depths = [s.local().height for s in layer]
+
+            # Center the layer along the cross-axis
+            total_breadth = sum(breadths) + self.node_sep * (len(layer) - 1)
+            current_cross = -total_breadth / 2
+
+            # The thickness of this rank is determined by the tallest/widest node
+            max_depth_in_rank = 0.0
+
+            for i, s in enumerate(layer):
+                b = s.local()
+
+                if self.orientation == "horizontal":
+                    # Flow is X, Cross is Y
+                    # Align Left edge to current_flow
+                    s.transform.tx = current_flow - b.x
+                    # Align Top edge to current_cross
+                    s.transform.ty = current_cross - b.y
+
+                    max_depth_in_rank = max(max_depth_in_rank, b.width)
+                    current_cross += b.height + self.node_sep
+                else:
+                    # Flow is Y, Cross is X
+                    # Align Left edge to current_cross
+                    s.transform.tx = current_cross - b.x
+                    # Align Top edge to current_flow
+                    s.transform.ty = current_flow - b.y
+
+                    max_depth_in_rank = max(max_depth_in_rank, b.height)
+                    current_cross += b.width + self.node_sep
+
+            # Advance the main flow axis
+            current_flow += max_depth_in_rank + self.rank_sep
+
+    def _assign_ranks(self) -> dict[Shape, int]:
+        """
+        Computes the layer index for each node using DFS.
+        Detects back-edges (cycles) and ignores them for rank calculation.
+        """
+        ranks: dict[Shape, int] = {}
+        visiting = set()
+
+        def get_rank(node: Shape) -> int:
+            if node in ranks:
+                return ranks[node]
+
+            # Cycle detection: We are currently visiting this node's descendant
+            if node in visiting:
+                return -1  # Signal to ignore this parent
+
+            visiting.add(node)
+
+            parents = self.rev_adj[node]
+            if not parents:
+                r = 0
+            else:
+                parent_ranks = [get_rank(p) for p in parents]
+                # Filter out back-edges (-1s)
+                valid_ranks = [pr for pr in parent_ranks if pr != -1]
+                # If all parents were back-edges, treat as root (0)
+                r = 1 + max(valid_ranks, default=-1)
+
+            visiting.remove(node)
+            ranks[node] = r
+            return r
+
+        for r in self.roots:
+            ranks[r] = 0
+
+        for s in self.shapes:
+            get_rank(s)
+
+        return ranks
+
+    def _barycenter(self, node: Shape, prev_layer: list[Shape]) -> float:
+        parents = [p for p in self.rev_adj[node] if p in prev_layer]
+        if not parents:
+            return 0.0
+        indices = [prev_layer.index(p) for p in parents]
+        return sum(indices) / len(indices)

tesserax-0.5.1.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: tesserax
+Version: 0.5.1
+Summary: A pure-Python library for rendering professional CS graphics.
+Author-email: Alejandro Piad <apiad@apiad.net>
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Tesserax: A Lightweight SVG Rendering Library
+
+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.
+
+> [**Read the full documentation**](https://apiad.github.io/tesserax).
+
+## Key Features
+
+* **Declarative Layouts**: Effortlessly arrange shapes in `Row` or `Column` containers with automatic alignment and spacing.
+* **Anchor System**: Connect shapes using semantic anchors like `top`, `bottom`, `left`, `right`, and `center`.
+* **Context Manager Support**: Use `with` statements to group shapes naturally within the code.
+* **Smart Canvas**: Automatically fit the canvas viewport to the content with adjustable padding.
+* **Rich Primitives**: Includes `Rect`, `Square`, `Circle`, `Ellipse`, `Line`, `Arrow`, and `Path`.
+
+## Installation
+
+Tesserax has zero dependencies (literally). It's 100% pure Python, and can be easily installed with `pip`:
+
+```bash
+pip install tesserax
+```
+
+Or if you're one of the cool kids, using `uv`:
+
+```bash
+uv add tesserax
+```
+
+## Quick Start
+
+The following example demonstrates how to create two shapes in a row and connect them with an arrow using the anchor system.
+
+```python
+from tesserax import Canvas, Rect, Arrow, Circle
+from tesserax.layout import Row
+
+# Initialize a canvas
+with Canvas() as canvas:
+    # Arrange a circle and a rectangle in a row with a 50px gap
+    with Row(gap=50):
+        circle = Circle(30, fill="#fee")
+        rect = Rect(100, 60, fill="#eef")
+
+    # Draw an arrow between the two shapes using anchors
+    # .dx() provides a small offset for better visual spacing
+    Arrow(
+        circle.anchor("right").dx(5),
+        rect.anchor("left").dx(-5)
+    )
+
+# Fit the viewport to the shapes and render
+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.
+
+## Core Components
+
+Tesserax comes with all basic components you need to draw the spectrum of SVG shapes.
+All shapes support standard SVG attributes like `stroke` and `fill`.
+
+* **Rect & Square**: Defined by width/height or a single size.
+* **Circle & Ellipse**: Defined by radii.
+* **Groups**: For grouping shapes and applying transforms to them as a single shape.
+* **Arrow**: A specialized line that automatically includes an arrowhead marker.
+* **Path**: Supports a fluent API for complex paths using `move_to`, `line_to`, `cubic_to`, and `close`.
+
+### Layouts
+
+Layouts are a unique feature of Tesserax to automate the positioning of child elements. We currently have three layouts, but these are very easy to extend:
+
+* **Row**: Aligns shapes horizontally. Baselines can be set to `start`, `middle`, or `end`.
+* **Column**: Aligns shapes vertically with `start`, `middle`, or `end` alignment.
+* **HierarchicalLayout**: Useful for drawing trees, DAGs, automata, etc.
+* **ForceLayout**: Typically used to draw arbitrary graphs with a force-directed algorithm.
+
+### Transforms
+
+Every shape has a `Transform` object allowing for:
+
+* **Translation**: `shape.translated(dx, dy)`.
+* **Rotation**: `shape.rotated(degrees)`.
+* **Scaling**: `shape.scaled(factor)`.
+
+Groups of shapes also have their own transform, and this can be composed _ad-infinitum_ to create complex drawing.
+
+## Why Tesserax?
+
+In the Python ecosystem, there is a clear divide between **data visualization** (plotting numbers) and **diagrammatic representation** (drawing concepts). Tesserax is built for the latter.
+
+It is designed for researchers, educators, and authors who need the geometric precision of a professional drafting tool combined with the power of a modern programming language.
+
+### Tesserax vs. The Alternatives
+
+#### Precision over Statistics
+
+Libraries like **Matplotlib**, **Seaborn**, or **Altair** are designed to map data points to visual encodings (bars, lines, scatter points).
+
+**The Difference**: Tesserax does not compete with these libraries because it does not render data graphs. You wouldn't use Tesserax to plot a CSV. Instead, Tesserax is for "the rest" of the figures in a paper: the schematics, the geometric proofs, the architectural diagrams, and the algorithmic walkthroughs where exact spatial relationships convey the meaning.
+
+#### Control over Constraints
+
+**Mermaid** and **Graphviz** are excellent for quickly rendering flowcharts using "black-box" layout engines.
+
+**The Difference**: These tools sacrifice control for convenience. If you need an arrow to point exactly at the tangent of a rotated ellipse, or a shape to be sized exactly according to a geometric ratio, Mermaid cannot help you. Tesserax is for **Scientific Drawing**—providing the low-level primitives needed for total layout authority.
+
+#### The "TikZ for Python" Philosophy
+
+**TikZ** is the industry standard for academic figures, but it requires learning a specialized, often cryptic macro language.
+
+**The Difference**: Tesserax brings the "low-level, total-control" philosophy of TikZ into **Python 3.12**. You get coordinate-invariant precision and semantic anchoring while using Python’s loops, logic, and types. We are building from the bottom up: starting with geometric atoms and moving toward high-level scientific abstractions (like automated neural network architectures or commutative diagrams) that maintain the ability to "drop down" and tweak a single pixel.
+
+### The SVG Advantage
+
+While TikZ is the gold standard for LaTeX-based PDF generation, it belongs to a "print-first" era. Tesserax leverages **SVG (Scalable Vector Graphics)** as its native format, offering a portability that TikZ cannot match without significant friction.
+
+* **Native Web Rendering**: Tesserax figures are native SVGs. They render instantly in any browser, remain crisp at any zoom level, and can be embedded directly into HTML or Markdown (via Quarto) without conversion.
+* **WYSIWYG Portability**: Converting TikZ to SVG for blog posts or online journals often results in broken fonts or misaligned elements. Because Tesserax *starts* with SVG, what you see in your development notebook is exactly what appears in your final PDF and your website.
+* **Accessibility & Interaction**: Unlike static PDFs, Tesserax SVGs can include metadata and ARIA labels for screen readers. Since they are part of the DOM, they can also be styled with CSS or even animated for interactive educational content.
+* **Perfect Print**: SVG is fully convertible to high-quality, vector-perfect PDF, meeting the highest standards for academic journals and book publishing.
+
+## Contribution
+
+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.

tesserax-0.5.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+tesserax/__init__.py,sha256=XitPTo-_7JHiHKO9XipLgu_HnijDja0q_lmeTLfaUeQ,224
+tesserax/align.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tesserax/base.py,sha256=o7ZQ0ED7EPPCvas78OBq4fE5w38iWdMwl7WYxzFlWyw,14404
+tesserax/canvas.py,sha256=uY-L3DvIDwciDWQ1l9QLEH-unVUk8Am0k1ykeMIxqG0,3663
+tesserax/core.py,sha256=7t_UxMl0cRJYspCIYPPUc0aXIdqcaHa_o01MrM_9IaY,6180
+tesserax/layout.py,sha256=C_enRYUUizCQpnQy_MK8hPbZUT7gJ7sa8l7mJwp_Kak,11591
+tesserax/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tesserax-0.5.1.dist-info/METADATA,sha256=8mfM0_-XroM93xd13EO6x_FAsmZnBNKD8RMIXBVR4CE,7320
+tesserax-0.5.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tesserax-0.5.1.dist-info/licenses/LICENSE,sha256=MqaKRdqJfordIyistXMUlS7MVRj7fnJABGUD0Q3Fy14,1071
+tesserax-0.5.1.dist-info/RECORD,,

tesserax-0.5.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tesserax-0.5.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Piad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.