gantrix 0.1.0__tar.gz

gantrix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devk-op
+
+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.

gantrix-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: gantrix
+Version: 0.1.0
+Summary: A framework for controlling gantry-based (GRBL) devices with swappable tool heads — laser, solenoid, pen, and more.
+Author: devk-op
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Provides-Extra: gui
+Requires-Dist: fastapi>=0.110; extra == "gui"
+Requires-Dist: uvicorn>=0.29; extra == "gui"
+Provides-Extra: design
+Requires-Dist: Pillow>=10.0; extra == "design"
+Requires-Dist: qrcode>=7.4; extra == "design"
+Requires-Dist: svgpathtools>=1.6; extra == "design"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+# gantrix
+
+A small framework for driving GRBL-based gantry devices with swappable tool
+heads — laser engraver today, whatever else you bolt to the carriage later
+(solenoid stamp, pen plotter, spray head, ...). Grew out of a one-off laser
+text-engraving script; generalized so the same motion/fill planning works
+for any tool, without being locked to the laser.
+
+## Layout
+
+- `gantrix.transport` — serial connection to GRBL, command/ack handshake,
+  homes with the tool forced off first (a previous crashed run can leave a
+  tool physically engaged even after the host process dies). A command
+  that gets no reply at all (dead link, controller reset) raises `GrblError`
+  rather than being silently swallowed; a mid-command controller reboot is
+  detected from its boot banner instead of waiting out the full timeout.
+  `emergency_stop()` sends GRBL's real-time soft-reset byte directly,
+  bypassing the normal command queue, so it works even while another
+  thread is blocked waiting on a stuck command.
+- `gantrix.tools` — the `Tool` plugin interface (`engage`/`disengage` +
+  feed rates). `LaserTool` (M3/M5 with power) is the only concrete
+  implementation shipped so far; new device types are added by subclassing
+  `Tool` (see `src/gantrix/tools/laser.py` as the reference).
+- `gantrix.design` — turns a design into `Shape`s the planner can sweep.
+  `design.text` is a small stroke font (rects + tapered diagonals).
+  `design.shapes.RasterShape` is a generic bitmap-grid `Shape`, backing both
+  `design.qrcode` (any QR-encodable data) and `design.image` (any image —
+  logo, silhouette, photo — thresholded to black/white at a configurable
+  resolution). True vector/SVG import (arbitrary curves, not just bitmaps)
+  is the natural next addition here.
+- `gantrix.planner.fill` — generic boustrophedon (zigzag raster) fill:
+  given anything exposing `spans_at_y(y)`, sweeps scanlines and emits
+  direction-alternating segments that minimize travel.
+- `gantrix.job` — wires a design + tool + transport into a runnable job.
+  Accepts either a port string (opens/closes its own connection — CLI
+  usage) or an already-connected transport (keeps it open — GUI usage).
+- `gantrix.gui.app` — preview a design as SVG, connect/disconnect a serial
+  port, and run a job — all from the browser. `gantrix.gui.connection`
+  holds the one live serial connection the process manages;
+  `gantrix.gui.job_runner` runs a `Job` in a background thread (so the
+  HTTP request returns immediately) and exposes progress + cancellation
+  for the page to poll. Only one job at a time — it's a single physical
+  device, not a queue. Two ways to stop: **Cancel** is cooperative (checked
+  between fill segments — fine for "I want a different design," not fast
+  enough to rely on if something's actually wrong); **EMERGENCY STOP** hits
+  the hardware directly via `emergency_stop()` and works regardless of
+  whether a command is stuck. **Home** manually re-homes ($H) when
+  connected and no job is running.
+
+## Quickstart
+
+```bash
+pip install -e ".[dev,gui,design]"
+pytest                                  # no hardware needed
+
+# preview a design in the browser (no hardware needed)
+uvicorn gantrix.gui.app:app --reload
+# open http://127.0.0.1:8000
+
+# run it for real
+gantrix text HAND --port /dev/cu.usbserial-XXXXXX
+gantrix qr "https://example.com" --port /dev/cu.usbserial-XXXXXX --cell-size 1.5
+gantrix image logo.png --port /dev/cu.usbserial-XXXXXX --height 40 --cell-size 0.3
+```
+
+## Adding a new device
+
+Swapping tools without touching the design or planner is the point of the
+`Tool` split. To support a new actuator, subclass `Tool` and implement
+`engage`/`disengage` (see `src/gantrix/tools/laser.py`):
+
+```python
+class MyTool(Tool):
+    def engage(self, transport):
+        transport.send("M62 P1")   # e.g. a GRBL digital output pin
+
+    def disengage(self, transport):
+        transport.send("M63 P1")
+```
+
+Then use it exactly like `LaserTool` — same `layout_text`/`layout_qr`
+output, same `Job`, just a different tool instance passed in.
+
+## Status
+
+Early scaffold. Laser path is validated against a working engrave script.
+QR fill segments have been round-trip verified (reconstructing the module
+grid from planned segments reproduces the source matrix exactly) and
+rendered to confirm the code is well-formed. Only one concrete `Tool`
+(laser) ships so far — the interface is there for more, none built yet.
+Vector/SVG import and shape-drawing in the GUI (not just text/QR forms) are
+not built yet either. The GUI can connect/disconnect, run a job (text or
+QR), Cancel, Home, and hardware-level EMERGENCY STOP. A real incident
+during testing (the controller stopped responding mid-job) surfaced that
+failures weren't being surfaced at all — `send()` used to return `False`
+on a dead link and nothing checked it, so the job just kept retrying into
+the void with no visible error. Fixed: failures now raise and show up in
+the job's `error` field instead of hanging silently.

gantrix-0.1.0/README.md

@@ -0,0 +1,98 @@
+# gantrix
+
+A small framework for driving GRBL-based gantry devices with swappable tool
+heads — laser engraver today, whatever else you bolt to the carriage later
+(solenoid stamp, pen plotter, spray head, ...). Grew out of a one-off laser
+text-engraving script; generalized so the same motion/fill planning works
+for any tool, without being locked to the laser.
+
+## Layout
+
+- `gantrix.transport` — serial connection to GRBL, command/ack handshake,
+  homes with the tool forced off first (a previous crashed run can leave a
+  tool physically engaged even after the host process dies). A command
+  that gets no reply at all (dead link, controller reset) raises `GrblError`
+  rather than being silently swallowed; a mid-command controller reboot is
+  detected from its boot banner instead of waiting out the full timeout.
+  `emergency_stop()` sends GRBL's real-time soft-reset byte directly,
+  bypassing the normal command queue, so it works even while another
+  thread is blocked waiting on a stuck command.
+- `gantrix.tools` — the `Tool` plugin interface (`engage`/`disengage` +
+  feed rates). `LaserTool` (M3/M5 with power) is the only concrete
+  implementation shipped so far; new device types are added by subclassing
+  `Tool` (see `src/gantrix/tools/laser.py` as the reference).
+- `gantrix.design` — turns a design into `Shape`s the planner can sweep.
+  `design.text` is a small stroke font (rects + tapered diagonals).
+  `design.shapes.RasterShape` is a generic bitmap-grid `Shape`, backing both
+  `design.qrcode` (any QR-encodable data) and `design.image` (any image —
+  logo, silhouette, photo — thresholded to black/white at a configurable
+  resolution). True vector/SVG import (arbitrary curves, not just bitmaps)
+  is the natural next addition here.
+- `gantrix.planner.fill` — generic boustrophedon (zigzag raster) fill:
+  given anything exposing `spans_at_y(y)`, sweeps scanlines and emits
+  direction-alternating segments that minimize travel.
+- `gantrix.job` — wires a design + tool + transport into a runnable job.
+  Accepts either a port string (opens/closes its own connection — CLI
+  usage) or an already-connected transport (keeps it open — GUI usage).
+- `gantrix.gui.app` — preview a design as SVG, connect/disconnect a serial
+  port, and run a job — all from the browser. `gantrix.gui.connection`
+  holds the one live serial connection the process manages;
+  `gantrix.gui.job_runner` runs a `Job` in a background thread (so the
+  HTTP request returns immediately) and exposes progress + cancellation
+  for the page to poll. Only one job at a time — it's a single physical
+  device, not a queue. Two ways to stop: **Cancel** is cooperative (checked
+  between fill segments — fine for "I want a different design," not fast
+  enough to rely on if something's actually wrong); **EMERGENCY STOP** hits
+  the hardware directly via `emergency_stop()` and works regardless of
+  whether a command is stuck. **Home** manually re-homes ($H) when
+  connected and no job is running.
+
+## Quickstart
+
+```bash
+pip install -e ".[dev,gui,design]"
+pytest                                  # no hardware needed
+
+# preview a design in the browser (no hardware needed)
+uvicorn gantrix.gui.app:app --reload
+# open http://127.0.0.1:8000
+
+# run it for real
+gantrix text HAND --port /dev/cu.usbserial-XXXXXX
+gantrix qr "https://example.com" --port /dev/cu.usbserial-XXXXXX --cell-size 1.5
+gantrix image logo.png --port /dev/cu.usbserial-XXXXXX --height 40 --cell-size 0.3
+```
+
+## Adding a new device
+
+Swapping tools without touching the design or planner is the point of the
+`Tool` split. To support a new actuator, subclass `Tool` and implement
+`engage`/`disengage` (see `src/gantrix/tools/laser.py`):
+
+```python
+class MyTool(Tool):
+    def engage(self, transport):
+        transport.send("M62 P1")   # e.g. a GRBL digital output pin
+
+    def disengage(self, transport):
+        transport.send("M63 P1")
+```
+
+Then use it exactly like `LaserTool` — same `layout_text`/`layout_qr`
+output, same `Job`, just a different tool instance passed in.
+
+## Status
+
+Early scaffold. Laser path is validated against a working engrave script.
+QR fill segments have been round-trip verified (reconstructing the module
+grid from planned segments reproduces the source matrix exactly) and
+rendered to confirm the code is well-formed. Only one concrete `Tool`
+(laser) ships so far — the interface is there for more, none built yet.
+Vector/SVG import and shape-drawing in the GUI (not just text/QR forms) are
+not built yet either. The GUI can connect/disconnect, run a job (text or
+QR), Cancel, Home, and hardware-level EMERGENCY STOP. A real incident
+during testing (the controller stopped responding mid-job) surfaced that
+failures weren't being surfaced at all — `send()` used to return `False`
+on a dead link and nothing checked it, so the job just kept retrying into
+the void with no visible error. Fixed: failures now raise and show up in
+the job's `error` field instead of hanging silently.

gantrix-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gantrix"
+version = "0.1.0"
+description = "A framework for controlling gantry-based (GRBL) devices with swappable tool heads — laser, solenoid, pen, and more."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "devk-op" }]
+dependencies = [
+    "pyserial>=3.5",
+]
+
+[project.optional-dependencies]
+gui = ["fastapi>=0.110", "uvicorn>=0.29"]
+design = ["Pillow>=10.0", "qrcode>=7.4", "svgpathtools>=1.6"]
+dev = ["pytest>=8.0", "httpx>=0.27"]
+
+[project.scripts]
+gantrix = "gantrix.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

gantrix-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gantrix-0.1.0/src/gantrix/__init__.py

@@ -0,0 +1,5 @@
+from gantrix.job import Job
+from gantrix.transport import GrblTransport
+
+__all__ = ["Job", "GrblTransport"]
+__version__ = "0.1.0"

gantrix-0.1.0/src/gantrix/cli.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import argparse
+
+from gantrix.design.text import layout_text
+from gantrix.job import Job
+from gantrix.tools.laser import LaserTool
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="gantrix", description="Drive a GRBL gantry.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    text_cmd = sub.add_parser("text", help="Engrave text using the built-in stroke font.")
+    text_cmd.add_argument("text")
+    text_cmd.add_argument("--port", required=True)
+    text_cmd.add_argument("--power", type=int, default=600)
+    text_cmd.add_argument("--speed", type=int, default=500)
+    text_cmd.add_argument("--line-gap", type=float, default=0.25)
+    text_cmd.add_argument("--height", type=float, default=20.0)
+
+    qr_cmd = sub.add_parser("qr", help="Engrave a QR code.")
+    qr_cmd.add_argument("data")
+    qr_cmd.add_argument("--port", required=True)
+    qr_cmd.add_argument("--power", type=int, default=600)
+    qr_cmd.add_argument("--speed", type=int, default=500)
+    qr_cmd.add_argument("--cell-size", type=float, default=1.5, help="mm per QR module")
+
+    image_cmd = sub.add_parser("image", help="Engrave a raster image (logo, silhouette, photo).")
+    image_cmd.add_argument("path")
+    image_cmd.add_argument("--port", required=True)
+    image_cmd.add_argument("--power", type=int, default=600)
+    image_cmd.add_argument("--speed", type=int, default=500)
+    image_cmd.add_argument("--height", type=float, default=40.0)
+    image_cmd.add_argument("--cell-size", type=float, default=0.3, help="mm per pixel (resolution)")
+    image_cmd.add_argument("--threshold", type=int, default=128)
+    image_cmd.add_argument("--invert", action="store_true")
+
+    args = parser.parse_args()
+
+    if args.command == "text":
+        placed, total_w = layout_text(args.text.upper())
+        print(f"{args.text!r} — {total_w:.0f}mm wide x {args.height:.0f}mm tall")
+        tool = LaserTool(power=args.power, speed=args.speed)
+        Job(args.port, tool, placed, height=args.height, line_gap=args.line_gap).run()
+
+    elif args.command == "qr":
+        from gantrix.design.qrcode import layout_qr
+
+        placed, w, h, line_gap = layout_qr(args.data, cell_size=args.cell_size)
+        print(f"QR {args.data!r} — {w:.0f}mm x {h:.0f}mm, {args.cell_size}mm/module")
+        tool = LaserTool(power=args.power, speed=args.speed)
+        Job(args.port, tool, placed, height=h, line_gap=line_gap).run()
+
+    elif args.command == "image":
+        from gantrix.design.image import layout_image
+
+        placed, w, h = layout_image(
+            args.path, args.height, cell_size=args.cell_size,
+            threshold=args.threshold, invert=args.invert,
+        )
+        print(f"{args.path} — {w:.0f}mm x {h:.0f}mm, {args.cell_size}mm/pixel")
+        tool = LaserTool(power=args.power, speed=args.speed)
+        Job(args.port, tool, placed, height=h, line_gap=args.cell_size).run()
+
+
+if __name__ == "__main__":
+    main()

gantrix-0.1.0/src/gantrix/design/image.py

@@ -0,0 +1,51 @@
+"""Arbitrary raster images (logos, photos, silhouettes) as engravable designs.
+
+Downsamples to one pixel per `cell_size` mm, thresholds to black/white, and
+exposes the result as a RasterShape — same fill-planner path as text and QR.
+"""
+from __future__ import annotations
+
+from PIL import Image
+
+from gantrix.design.shapes import RasterShape
+from gantrix.planner.fill import Placed
+
+
+def image_shape(
+    path: str,
+    height_mm: float,
+    cell_size: float = 0.3,
+    threshold: int = 128,
+    invert: bool = False,
+) -> RasterShape:
+    """Load an image and reduce it to a boolean fill grid.
+
+    `height_mm` is the desired physical output height; `cell_size` (mm) sets
+    the resolution (pixels per engraved dot) — smaller means finer detail
+    and more scanlines. Width is derived from the image's aspect ratio.
+    Pixels darker than `threshold` (0-255) are treated as fill; pass
+    `invert=True` if your source has a light subject on a dark background.
+    """
+    rows = max(1, round(height_mm / cell_size))
+    img = Image.open(path).convert("L")
+    cols = max(1, round(rows * img.width / img.height))
+    img = img.resize((cols, rows), Image.LANCZOS)
+
+    pixels = img.load()
+    grid = [
+        [(pixels[c, r] < threshold) != invert for c in range(cols)]
+        for r in range(rows)
+    ]
+    return RasterShape(grid, cell_size)
+
+
+def layout_image(
+    path: str,
+    height_mm: float,
+    cell_size: float = 0.3,
+    threshold: int = 128,
+    invert: bool = False,
+) -> tuple[list[Placed], float, float]:
+    """Convenience wrapper: returns (placed, total_width, total_height)."""
+    shape = image_shape(path, height_mm, cell_size, threshold, invert)
+    return [Placed(shape, x=0.0)], shape.width, shape.height

gantrix-0.1.0/src/gantrix/design/qrcode.py

@@ -0,0 +1,29 @@
+"""QR codes as an engravable design: encode data, render as a RasterShape."""
+from __future__ import annotations
+
+import qrcode as _qrcode
+
+from gantrix.design.shapes import RasterShape
+from gantrix.planner.fill import Placed
+
+
+def qr_shape(data: str, cell_size: float = 1.5, border: int = 4) -> tuple[RasterShape, float]:
+    """Build a QR code shape for `data`.
+
+    `cell_size` is the physical size (mm) of one QR module — this should
+    also be used as the fill planner's `line_gap` so each module row gets
+    exactly one scanline pass (returned as the second element).
+    `border` is the quiet-zone width in modules (4 is the QR spec minimum).
+    """
+    qr = _qrcode.QRCode(border=border, box_size=1)
+    qr.add_data(data)
+    qr.make(fit=True)
+    grid = qr.get_matrix()  # list[list[bool]], already includes the border
+    shape = RasterShape(grid, cell_size)
+    return shape, cell_size
+
+
+def layout_qr(data: str, cell_size: float = 1.5, border: int = 4) -> tuple[list[Placed], float, float, float]:
+    """Convenience wrapper: returns (placed, total_width, total_height, recommended_line_gap)."""
+    shape, line_gap = qr_shape(data, cell_size, border)
+    return [Placed(shape, x=0.0)], shape.width, shape.height, line_gap

gantrix-0.1.0/src/gantrix/design/shapes.py

@@ -0,0 +1,39 @@
+"""Generic bitmap-grid Shape: a design as a grid of filled/empty cells.
+
+QR codes and thresholded raster images are both "a grid of dark cells at
+some physical cell size" — this one class backs both, each row of the
+grid becoming one scanline's worth of fill spans.
+"""
+from __future__ import annotations
+
+
+class RasterShape:
+    def __init__(self, grid: list[list[bool]], cell_size: float):
+        assert grid, "grid must have at least one row"
+        self.grid = grid
+        self.cell_size = cell_size
+        self.n_rows = len(grid)
+        self.n_cols = len(grid[0])
+        self.height = self.n_rows * cell_size
+        self.width = self.n_cols * cell_size
+
+    def spans_at_y(self, y: float) -> list[tuple[float, float]]:
+        if not (-0.001 <= y <= self.height + 0.001):
+            return []
+        # local y is bottom-up (0 = bottom, matches the fill planner's
+        # convention); grid row 0 is the top row, so flip.
+        row_idx = self.n_rows - 1 - int(min(y, self.height - 1e-9) // self.cell_size)
+        row_idx = max(0, min(self.n_rows - 1, row_idx))
+        row = self.grid[row_idx]
+
+        spans: list[tuple[float, float]] = []
+        start = None
+        for col, filled in enumerate(row):
+            if filled and start is None:
+                start = col
+            elif not filled and start is not None:
+                spans.append((start * self.cell_size, col * self.cell_size))
+                start = None
+        if start is not None:
+            spans.append((start * self.cell_size, self.n_cols * self.cell_size))
+        return spans

gantrix-0.1.0/src/gantrix/design/text.py

@@ -0,0 +1,93 @@
+"""Simple stroke-font text as a fill design source.
+
+Each letter is defined as rectangles plus tapered diagonals; this is the
+same scanline math the original one-off engraving script used, now
+implementing the `Shape` protocol so it plugs into the generic fill planner.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from gantrix.planner.fill import Placed
+
+H = 20.0  # default letter height (mm)
+S = 3.0   # default stroke thickness (mm)
+W = 12.0  # default standard letter width (mm)
+
+
+@dataclass(frozen=True)
+class Letter:
+    width: float
+    rects: list[tuple[float, float, float, float]] = field(default_factory=list)
+    diags: list[dict] = field(default_factory=list)
+
+    def spans_at_y(self, y: float) -> list[tuple[float, float]]:
+        raw = []
+        for x1, y1, x2, y2 in self.rects:
+            if y1 - 0.001 <= y <= y2 + 0.001:
+                raw.append((min(x1, x2), max(x1, x2)))
+        for d in self.diags:
+            yt, yb = d.get("yt", H), d.get("yb", 0)
+            if not (yb - 0.001 <= y <= yt + 0.001):
+                continue
+            span = yt - yb
+            t = (y - yb) / span if span > 0 else 1.0
+            xc = d["xb"] + (d["xt"] - d["xb"]) * t
+            raw.append((max(0, xc - d["hw"]), min(self.width, xc + d["hw"])))
+        if not raw:
+            return []
+        raw.sort()
+        merged = [list(raw[0])]
+        for x1, x2 in raw[1:]:
+            if x1 <= merged[-1][1] + 0.001:
+                merged[-1][1] = max(merged[-1][1], x2)
+            else:
+                merged.append([x1, x2])
+        return [(a, b) for a, b in merged]
+
+
+FONT: dict[str, Letter] = {
+    "M": Letter(15.0, rects=[(0, 0, S, H), (15 - S, 0, 15, H)], diags=[
+        {"xt": S / 2, "xb": 7.5, "hw": S / 2, "yt": H, "yb": H / 2},
+        {"xt": 15 - S / 2, "xb": 7.5, "hw": S / 2, "yt": H, "yb": H / 2},
+    ]),
+    "A": Letter(W, rects=[(0, H * 0.32 - S / 2, W, H * 0.32 + S / 2)], diags=[
+        {"xt": W / 2, "xb": 0, "hw": S / 2, "yt": H, "yb": 0},
+        {"xt": W / 2, "xb": W, "hw": S / 2, "yt": H, "yb": 0},
+    ]),
+    "D": Letter(W, rects=[
+        (0, 0, S, H), (0, H - S, 11, H), (0, 0, 11, S), (11 - S, S, 11, H - S),
+    ]),
+    "H": Letter(W, rects=[
+        (0, 0, S, H), (W - S, 0, W, H), (0, H / 2 - S / 2, W, H / 2 + S / 2),
+    ]),
+    "V": Letter(W, diags=[
+        {"xt": S / 2, "xb": W / 2, "hw": S / 2, "yt": H, "yb": 0},
+        {"xt": W - S / 2, "xb": W / 2, "hw": S / 2, "yt": H, "yb": 0},
+    ]),
+    "F": Letter(W, rects=[
+        (0, 0, S, H), (0, H - S, W, H), (0, H / 2 - S / 2, W * 0.75, H / 2 + S / 2),
+    ]),
+    "U": Letter(W, rects=[(0, S, S, H), (W - S, S, W, H), (0, 0, W, S)]),
+    "S": Letter(W, rects=[
+        (0, H - S, W, H), (0, H / 2 + S / 2, S, H - S),
+        (0, H / 2 - S / 2, W, H / 2 + S / 2),
+        (W - S, S, W, H / 2 - S / 2), (0, 0, W, S),
+    ]),
+    "I": Letter(8.0, rects=[(0, H - S, 8, H), (4 - S / 2, 0, 4 + S / 2, H), (0, 0, 8, S)]),
+    "O": Letter(W, rects=[(0, 0, S, H), (W - S, 0, W, H), (0, H - S, W, H), (0, 0, W, S)]),
+    "N": Letter(W, rects=[(0, 0, S, H), (W - S, 0, W, H)], diags=[
+        {"xt": S / 2, "xb": W - S / 2, "hw": S / 2, "yt": H, "yb": 0},
+    ]),
+}
+
+
+def layout_text(text: str, start_x: float = 0.0, gap: float = 3.0) -> tuple[list[Placed], float]:
+    """Lay out `text` left to right. Returns (placed shapes, total width)."""
+    placed = []
+    cx = start_x
+    for ch in text:
+        letter = FONT[ch]
+        placed.append(Placed(letter, cx))
+        cx += letter.width + gap
+    return placed, cx - gap - start_x