tesserax 0.2.1__tar.gz → 0.5.1__tar.gz

{tesserax-0.2.1 → tesserax-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesserax
-Version: 0.2.1
+Version: 0.5.1
 Summary: A pure-Python library for rendering professional CS graphics.
 Author-email: Alejandro Piad <apiad@apiad.net>
 License-File: LICENSE
@@ -80,7 +80,8 @@ Layouts are a unique feature of Tesserax to automate the positioning of child el
 
 * **Row**: Aligns shapes horizontally. Baselines can be set to `start`, `middle`, or `end`.
 * **Column**: Aligns shapes vertically with `start`, `middle`, or `end` alignment.
-* **ForceLayout**: Typically used to draw graphs.
+* **HierarchicalLayout**: Useful for drawing trees, DAGs, automata, etc.
+* **ForceLayout**: Typically used to draw arbitrary graphs with a force-directed algorithm.
 
 ### Transforms
 

{tesserax-0.2.1 → tesserax-0.5.1}/README.md

@@ -71,7 +71,8 @@ Layouts are a unique feature of Tesserax to automate the positioning of child el
 
 * **Row**: Aligns shapes horizontally. Baselines can be set to `start`, `middle`, or `end`.
 * **Column**: Aligns shapes vertically with `start`, `middle`, or `end` alignment.
-* **ForceLayout**: Typically used to draw graphs.
+* **HierarchicalLayout**: Useful for drawing trees, DAGs, automata, etc.
+* **ForceLayout**: Typically used to draw arbitrary graphs with a force-directed algorithm.
 
 ### Transforms
 

{tesserax-0.2.1 → tesserax-0.5.1}/docs/_quarto.yml

@@ -9,7 +9,7 @@ website:
       - href: index.qmd
         text: Home
       - href: core.qmd
-        text: Core Concepts
+        text: User Guide
       - href: gallery.qmd
         text: Gallery
 

{tesserax-0.2.1 → tesserax-0.5.1}/docs/core.qmd

@@ -1,4 +1,4 @@
-This "Core Concepts" guide will walk you through building a scene from scratch, demonstrating how **Tesserax** handles shapes, positioning, and composition.
+This guide will walk you through building a scene from scratch, demonstrating how **Tesserax** handles shapes, positioning, and composition.
 
 ## The Canvas and the First Shape
 
@@ -21,6 +21,20 @@ canvas.fit(padding=10).display()
 
 ```
 
+## Drawing Text
+
+Text behaves exactly like any other shape in Tesserax.
+
+```{python}
+from tesserax import Canvas, Text
+
+with Canvas() as canvas:
+    Rect(150, 40, fill="lightblue")
+    Text("Hello World", size=24, font="serif").translated(0, 22)
+
+canvas.align("horizontal").fit(10).display()
+```
+
 ## Adding and Transforming Shapes
 
 While you can add shapes and manually set their coordinates, Tesserax provides a fluent API for transformations. Here, we add a `Circle` and use `translated()` to move it into position.
@@ -141,3 +155,77 @@ When you call `shape.anchor(name)`, Tesserax performs the following behind the s
 This means you never have to manually calculate `sin()` or `cos()` to find where a rotated object's edge is located—you just ask for the anchor.
 
 For explicit anchoring, you can use `Shape.resolve(p: Point)` to map a point in local space to the global space, this way you can, e.g., get the point at 2/3rds of the way inside a rectangle and map it to global space.
+
+## Drawing Paths and Lines
+
+While shapes like `Rect` and `Circle` cover many use cases, sometimes you need to draw arbitrary lines, custom shapes, or connectors. Tesserax offers two ways to do this: the low-level `Path` for precise control and the high-level `Polyline` for rapid sequences.
+
+### The Low-Level `Path` Object
+
+The `Path` class roughly corresponds to the SVG `<path>` element. It operates like a pen: you move it to a location, then draw lines or curves to subsequent points.
+
+This is ideal for creating custom glyphs or specific geometric curves.
+
+```{python}
+from tesserax import Canvas, Path
+
+with Canvas() as canvas:
+    # 1. A simple custom shape (a triangle)
+    p = Path()
+    p.move_to(0, 0).line_to(50, 50).line_to(0, 50).close()
+    p.translated(20, 20)
+
+    # 2. A curved path using Bezier curves
+    curve = Path()
+    curve.move_to(100, 20)
+    # Cubic Bezier: 2 control points, 1 end point
+    curve.cubic_to(
+        150, 20,   # Control Point 1
+        150, 80,   # Control Point 2
+        200, 80    # End Point
+    )
+
+    # Quadratic Bezier: 1 control point, 1 end point
+    curve.quadratic_to(
+        250, 80,   # Control Point
+        300, 20    # End Point
+    )
+
+canvas.fit(padding=10).display()
+```
+
+### The High-Level `Polyline`
+
+For many diagrams, you simply want to connect a sequence of points. The `Polyline` shape automates this.
+
+Its most powerful feature is the `smoothness` parameter. Instead of manually calculating Bezier control points to round a corner, you can simply tell `Polyline` to blend the corners for you.
+
+* `smoothness=0`: Sharp corners (standard polygon).
+* `smoothness=0.2`: Subtle rounded corners (like a modern UI box).
+* `smoothness=1`: Maximum rounding (spline-like).
+
+```{python}
+from tesserax import Canvas, Polyline, Point
+
+# Helper to generate a zigzag pattern
+points = [
+    Point(0, 50), Point(50, 0), Point(100, 50),
+    Point(150, 0), Point(200, 50)
+]
+
+with Canvas() as canvas:
+    # 1. Sharp Polyline (Default)
+    Polyline(points, smoothness=0).translated(0, 0)
+
+    # 2. Slightly Rounded (20% smoothing)
+    # Note how it preserves most of the straight line but rounds the tip.
+    Polyline(points, smoothness=0.2, stroke="blue").translated(0, 60)
+
+    # 3. Fully Smooth (100% smoothing)
+    # This creates a flowing wave-like appearance.
+    Polyline(points, smoothness=1.0, stroke="red").translated(0, 120)
+
+canvas.fit(10).display()
+```
+
+This makes `Polyline` an excellent tool for drawing graph edges, wiring diagrams, or "hand-drawn" style annotations where sharp vertices look unnatural.

{tesserax-0.2.1 → tesserax-0.5.1}/docs/gallery.qmd

@@ -58,7 +58,7 @@ This example uses a force layout to draw a simple graph that represents an autom
 ```{python}
 import math
 from tesserax import Canvas, Circle, Arrow
-from tesserax.force import ForceLayout
+from tesserax.layout import HierarchicalLayout
 from tesserax.core import Point
 
 def get_boundary_point(center: Point, target: Point, radius: float) -> Point:
@@ -76,10 +76,10 @@ def get_boundary_point(center: Point, target: Point, radius: float) -> Point:
 
 with Canvas() as canvas:
     states: list[Shape] = []
-    radius = 25
+    radius = 20
 
     # 1. Define the Graph Structure
-    with ForceLayout(k=75, iterations=300) as graph:
+    with HierarchicalLayout(orientation="horizontal") as graph:
         # Create 5 states
         for i in range(4):
             states.append(Circle(r=radius))
@@ -87,11 +87,13 @@ with Canvas() as canvas:
         # Connect them (Topology)
         # q0 -> q1 -> q2
         graph.connect(states[0], states[1])
-        graph.connect(states[1], states[2])
+        graph.connect(states[0], states[2])
         # q2 -> q0 (cycle)
         graph.connect(states[2], states[0])
         # q2 -> q3 -> q4
         graph.connect(states[2], states[3])
+        # Set the root
+        graph.root(states[0])
 
     # 2. Draw Transitions (Visuals)
     # We define edges manually to ensure directionality (ForceLayout is undirected)

{tesserax-0.2.1 → tesserax-0.5.1}/docs/index.qmd

@@ -69,7 +69,8 @@ Layouts are a unique feature of Tesserax to automate the positioning of child el
 
 * **Row**: Aligns shapes horizontally. Baselines can be set to `start`, `middle`, or `end`.
 * **Column**: Aligns shapes vertically with `start`, `middle`, or `end` alignment.
-* **ForceLayout**: Typically used to draw graphs.
+* **HierarchicalLayout**: Useful for drawing trees, DAGs, automata, etc.
+* **ForceLayout**: Typically used to draw arbitrary graphs with a force-directed algorithm.
 
 ### Transforms
 

{tesserax-0.2.1 → tesserax-0.5.1}/makefile

@@ -54,7 +54,7 @@ release:
 	@echo Remove backup files
 	@rm pyproject.toml.bak src/tesserax/__init__.py.bak
 
-	@uv sync
+	@uv sync --all-groups
 
 	@echo "Committing version bump..."
 	@git add pyproject.toml src/tesserax/__init__.py uv.lock

{tesserax-0.2.1 → tesserax-0.5.1}/pyproject.toml

@@ -1,13 +1,12 @@
 [project]
 name = "tesserax"
-version = "0.2.1"
+version = "0.5.1"
 description = "A pure-Python library for rendering professional CS graphics."
 readme = "README.md"
 authors = [
     { name = "Alejandro Piad", email = "apiad@apiad.net" }
 ]
 requires-python = ">=3.12"
-dependencies = []
 
 [build-system]
 requires = ["hatchling"]
@@ -22,3 +21,6 @@ dev = [
     "pytest-coverage>=0.0",
     "ruff>=0.14.14",
 ]
+export = [
+    "cairosvg>=2.8.2",
+]

tesserax-0.5.1/src/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-0.2.1 → tesserax-0.5.1}/src/tesserax/base.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
-from typing import Callable, Self
-from .core import Point, Shape, Bounds
+from typing import Callable, Literal, Self
+from .core import Anchor, Point, Shape, Bounds
 
 
 class Rect(Shape):
@@ -164,6 +164,36 @@ class Group(Shape):
     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):
     """
@@ -172,8 +202,13 @@ class Path(Shape):
     layout bounding box calculations.
     """
 
-    def __init__(self) -> None:
+    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)
 
@@ -237,6 +272,15 @@ class Path(Shape):
         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")
@@ -261,4 +305,155 @@ class Path(Shape):
         # 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="black" stroke-width="2" />'
+        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-0.2.1 → tesserax-0.5.1}/src/tesserax/canvas.py

@@ -69,10 +69,41 @@ class Canvas(Group):
             "</svg>"
         )
 
-    def save(self, path: str | Path) -> None:
-        """Writes the canvas content to an SVG file."""
-        with open(path, "w", encoding="utf-8") as f:
-            f.write(self._build_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-0.2.1 → tesserax-0.5.1}/src/tesserax/core.py

@@ -39,6 +39,23 @@ class Point:
     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)