Initial ParallelPrint import

.codex/config.toml

@@ -0,0 +1 @@
+sandbox_mode = "workspace-write"

.codex/environments/environment.toml

@@ -0,0 +1,11 @@
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
+version = 1
+name = "STLtoGCode"
+
+[setup]
+script = ""
+
+[[actions]]
+name = "Run"
+icon = "run"
+command = "uv run gradio app.py"

.gitattributes

@@ -0,0 +1 @@
+*.stl filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+gradio.out.log
+gradio.err.log
+.claude/

AGENTS.md

@@ -0,0 +1,41 @@
+# Project Instructions
+
+## Python Environment
+
+- Always use `uv` to run Python scripts and manage dependencies — never use `pip` or `python` directly
+- Run scripts with `uv run python script.py` instead of `python script.py`
+- Install packages with `uv add package-name` instead of `pip install`
+- To run one-off commands: `uv run <command>`
+- The project uses `uv` for virtual environment management; do not create venvs manually with `python -m venv`
+
+## Common Commands
+
+- `uv run python script.py` — run a script
+- `uv add <package>` — add a dependency
+- `uv sync` — install all dependencies from lockfile
+- `uv run pytest` — run tests
+
+## Dependencies
+
+- After any `uv add` / `uv remove`, regenerate the Hugging Face requirements file or the deploy will not get the change — the Space installs from `requirements.txt`, not from `uv.lock`:
+  `uv export --format requirements.txt --no-hashes --no-dev --frozen --output-file requirements.txt`
+- Commit `pyproject.toml`, `uv.lock`, and `requirements.txt` together when dependencies change.
+
+## Rendering Constraints (Hugging Face)
+
+- Hugging Face Spaces run headless with no GPU/WebGL and no guaranteed `ffmpeg`.
+- For any server-side image or animation rendering, use CPU-only paths: Matplotlib's `Agg` backend, GIF via Pillow.
+- Avoid `kaleido` / Plotly static-image export (3D is extremely slow headless) and ffmpeg-dependent MP4 output. Both were tried and proved unreliable here; the parallel-print GIF export uses Matplotlib `Agg` instead.
+
+## Local Tooling
+
+- `.claude/` (e.g. `launch.json` for the local preview server) is gitignored and not deployed.
+
+## Hugging Face Deployment
+
+- `.stl` files must be tracked by Git LFS (`*.stl filter=lfs` in `.gitattributes`)
+- Verify Git LFS is available before push: `git lfs version`
+- Confirm tracked LFS files: `git lfs ls-files`
+- Standard push sequence: `git push origin main` then `git push hf-space main`
+- If Hugging Face rejects binaries, re-check `.gitattributes` and LFS status before retrying
+- `git lfs migrate` rewrites history; only use it intentionally and coordinate with collaborators first

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -0,0 +1,148 @@
+---
+title: STL to G-Code Slicer
+sdk: gradio
+sdk_version: 6.10.0
+python_version: "3.12"
+app_file: app.py
+fullWidth: true
+short_description: Upload STLs, export TIFF stacks, and generate G-code.
+---
+
+# STL to G-Code Gradio App
+
+This project provides a Gradio app that takes up to three uploaded STL files, shows interactive 3D viewers, slices each model along the Z axis, saves slices as TIFF images, generates G-code from those TIFF stacks, previews the resulting tool path (a fast line plot or an animated 3D tube plot), and can visualize all three shapes printing in parallel and export that animation as a GIF.
+
+## Prerequisites
+
+- Python 3.11 or newer for local development
+- `uv` for dependency management and script execution
+- Git LFS for the bundled `.stl` sample files
+
+## Run
+
+```powershell
+uv sync --all-groups
+uv run python app.py
+```
+
+For reload mode during development, run:
+
+```powershell
+uv run gradio app.py
+```
+
+When `app.py` changes, Gradio will automatically rerun the file and refresh the demo.
+
+Then open the local Gradio URL in your browser, upload STL files or load the bundled samples, and generate the TIFF stacks.
+
+## What the app does
+
+- Uploads up to three `.stl` files
+- Loads bundled sample STL files
+- Shows interactive 3D viewers for rotating each model
+- Shows model extents, face count, vertex count, and watertight status
+- Optionally scales loaded STLs per shape, either by fitting target X/Y/Z dimensions or by applying one uniform scale factor to all axes
+- Lets you choose layer height and XY pixel size
+- Produces one `.tif` image per slice
+- Encodes material as black (`0`) and empty space as white (`255`) in each TIFF slice
+- Lets you step through the slice stack in the browser
+- Exports a ZIP containing the generated TIFF images
+- Combines generated stacks into a reference TIFF stack
+- Converts generated TIFF ZIPs into G-code files with pressure, valve, and port settings per shape
+- Offers two G-code generation options: **Use G1 for all moves** (no rapid travel command) and **Use Reference Stack for motion** (all shapes share one nozzle path; each dispenses only its own geometry)
+- Previews each shape's generated G-code inline (text boxes under the downloads)
+- Visualizes generated or uploaded G-code tool paths, with the source selectable from Shape 1/2/3 or an uploaded file
+- Renders the tool path as a fast line plot or an animated 3D tube plot (play/pause, speed, scrub, frame-step, nozzle marker)
+- Plots all three shapes side by side (offset in X) and animates them printing in parallel, with a server-side GIF export of that animation
+
+## Behavior and Implementation Notes
+
+### Reference TIFF Stack Alignment
+
+When you click **Generate Reference TIFF Stack**, the app combines available TIFF stacks layer-by-layer.
+
+- If source TIFFs have different dimensions, each layer is placed on a canvas using the largest width and height.
+- Layers are centered in X and Y before merging.
+- Pixel merge uses a black-wins rule: a pixel is black in the reference if any source has black at that pixel.
+- Alignment is centered image placement, not bottom-left anchoring.
+- If image-size differences are odd, centering may produce a one-pixel shift due to integer rounding.
+
+### G-code XY Step Size
+
+- G-code generation uses the slicer's `Pixel Size/Fill Width` for XY step distance by passing `fil_width=pixel_size` into `generate_snake_path_gcode()`.
+
+### G-code Output
+
+- Generated G-code starts in relative coordinate mode (`G91`).
+- `G0` is travel and `G1` is print/feed.
+- The app generates print/feed moves from material pixels and travel moves between material regions.
+- Generated files include pressure preset commands and WAGO valve commands based on the selected pressure, valve, and port.
+- Pressure increases by `0.1` psi per layer by default.
+- **Use G1 for all moves**: when enabled, every movement line is emitted as `G1` (no `G0` rapid travel); the WAGO valve still marks where material is dispensed. Applies to all shapes.
+- **Use Reference Stack for motion**: when enabled, every shape's snake-path *motion* is taken from the combined Reference TIFF Stack while each shape's *valve/dispensing* comes from its own slices — so parallel print heads share one synchronized nozzle path and each deposits only its own geometry. Requires generating the Reference TIFF Stack on the first tab first; shapes are skipped with a message if it is missing.
+
+### Print vs Travel Classification
+
+When parsing G-code for visualization, the app decides print vs travel as follows:
+
+- If the file contains `WAGO_ValveCommands`, the valve state (open/closed) determines print vs travel. This overrides `G0`/`G1`, because some generators emit every move as `G1`, or invert `G0`/`G1` relative to the valve.
+- Otherwise it falls back to the convention `G1` = print, `G0` = travel.
+
+The parser also handles standard slicer G-code: single-axis and Z-only moves, axes in any order, and `F`/`E` tokens (feed rate, extrusion) are ignored for geometry.
+
+### G-code Visualization
+
+The G-code visualization tab renders the generated Shape 1/2/3 G-code or an uploaded `.txt`, `.gcode`, or `.nc` file. It parses `G0`/`G1` movement lines, supports relative (`G91`) and absolute (`G90`) positioning, and offers two render modes:
+
+- **Line Plot** — fast thin scatter lines (print and travel), with color/opacity controls.
+- **Tube Plot with Animation** — mm-width filament tubes (circular, capped, lit) with a client-side build animation (play/pause, speed, scrub, frame-step) and a moving nozzle marker. Filament/travel widths default to the layer height and its quarter.
+
+### Parallel Printing Visualization
+
+The fourth tab plots all three shapes' G-code at once, offset along X so they do not overlap, each in its own color. Like the visualization tab it has a fast **Line Plot** and an animated **Tube Plot**; the animation advances all parts on a shared cumulative-path-length timeline, so a shorter part finishes first.
+
+It can also **export the animation as a GIF**, rendered server-side with Matplotlib (the `Agg` CPU backend — no WebGL, no headless browser, and no `ffmpeg`, so it works locally and on Hugging Face). The GIF is line-style with faint grey travel and white, black-outlined nozzle markers drawn on top; controls cover duration, frames per second, elevation/azimuth viewing angle, and travel opacity (0 hides travel).
+
+## Dependency Updates
+
+The parallel-print GIF export requires `matplotlib` (rendered with the CPU `Agg` backend so it runs on Hugging Face).
+
+When dependencies change, update the lockfile and refresh the Hugging Face `requirements.txt` export — the Space installs from `requirements.txt`, not from the lockfile:
+
+```powershell
+uv sync --all-groups
+uv export --format requirements.txt --no-hashes --no-dev --frozen --output-file requirements.txt
+```
+
+## Test
+
+```powershell
+uv run pytest
+```
+
+## Hugging Face Deployment
+
+This repository tracks `.stl` files with Git LFS (see `.gitattributes`).
+
+Before your first push on a machine:
+
+```powershell
+git lfs install
+git lfs pull
+```
+
+Recommended push flow:
+
+```powershell
+git push origin main
+git push hf-space main
+```
+
+If Hugging Face rejects a push for binary files, verify LFS setup first:
+
+```powershell
+git lfs version
+git lfs ls-files
+```
+
+Warning: `git lfs migrate` rewrites commit history. Use it only when you intentionally want history rewritten and all collaborators are aligned.

gcode_viewer.py

@@ -0,0 +1,807 @@
+from __future__ import annotations
+
+import math
+import re
+from pathlib import Path
+
+import numpy as np
+import plotly.graph_objects as go
+
+
+# A move is any G0/G1 (or G00/G01) line. Coordinates may list any subset of
+# X/Y/Z in any order, mixed with other tokens (F feed rate, E extrusion); only
+# the axes named on a line change. This matches standard slicer/firmware G-code
+# as well as this app's own always-paired "X Y" output.
+_CMD_RE = re.compile(r"^G0*([01])(?![0-9])", re.IGNORECASE)
+_AXIS_RE = re.compile(r"([XYZ])\s*([-+]?(?:\d*\.\d+|\d+\.?))", re.IGNORECASE)
+# Pneumatic valve toggle: WAGO_ValveCommands(<valve>, <0=close|1=open>). Some
+# generators emit every move as G1 and convey extrusion only through the valve.
+_VALVE_RE = re.compile(r"WAGO_ValveCommands\(\s*(\d+)\s*,\s*(\d+)\s*\)", re.IGNORECASE)
+
+
+def parse_gcode_path(gcode_text: str) -> dict:
+    relative = True
+    x = y = z = 0.0
+
+    # Decide how to tell print from travel. The valve physically controls
+    # material flow, so when valve commands are present they are the ground
+    # truth: valve open = printing, valve closed = travel. This is correct for
+    # the app's own output (where valve state and G1/G0 agree) and for external
+    # generators whose G0/G1 labels are unreliable — some omit G0 entirely
+    # (every move G1), others invert G0/G1 relative to the valve. Only fall back
+    # to the G1 = print / G0 = travel convention when there is no valve to read.
+    use_valve = bool(_VALVE_RE.search(gcode_text))
+    open_valves: set[str] = set()
+
+    print_segments: list[list[tuple[float, float, float]]] = []
+    travel_segments: list[list[tuple[float, float, float]]] = []
+    moves: list[dict] = []
+    current_kind: str | None = None
+    current_segment: list[tuple[float, float, float]] = []
+
+    all_x: list[float] = []
+    all_y: list[float] = []
+    all_z: list[float] = []
+
+    def flush_segment() -> None:
+        nonlocal current_segment, current_kind
+        if current_segment and current_kind is not None:
+            target = print_segments if current_kind == "print" else travel_segments
+            target.append(current_segment)
+        current_segment = []
+        current_kind = None
+
+    for raw_line in gcode_text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            flush_segment()
+            continue
+
+        # Drop inline comments so axis letters in comment text are never read.
+        code = line.split(";", 1)[0].strip()
+        upper = code.upper()
+        if upper.startswith("G90"):
+            relative = False
+            continue
+        if upper.startswith("G91"):
+            relative = True
+            continue
+
+        cmd_match = _CMD_RE.match(code)
+        if not cmd_match:
+            # Track valve open/close so all-G1 files can be split into
+            # print (valve open) and travel (valve closed) runs.
+            valve_match = _VALVE_RE.search(code)
+            if valve_match:
+                valve, state = valve_match.group(1), valve_match.group(2)
+                if state == "0":
+                    open_valves.discard(valve)
+                else:
+                    open_valves.add(valve)
+            flush_segment()
+            continue
+
+        axes = {a.upper(): float(v) for a, v in _AXIS_RE.findall(code)}
+        if not axes:
+            # A G0/G1 with no coordinates (e.g. "G1 F1800") is not a move.
+            flush_segment()
+            continue
+
+        prev_pos = (x, y, z)
+
+        if relative:
+            x += axes.get("X", 0.0)
+            y += axes.get("Y", 0.0)
+            z += axes.get("Z", 0.0)
+        else:
+            if "X" in axes:
+                x = axes["X"]
+            if "Y" in axes:
+                y = axes["Y"]
+            if "Z" in axes:
+                z = axes["Z"]
+
+        if use_valve:
+            kind = "print" if open_valves else "travel"
+        else:
+            kind = "print" if cmd_match.group(1) == "1" else "travel"
+        moves.append({"kind": kind, "start": prev_pos, "end": (x, y, z)})
+
+        if kind != current_kind:
+            flush_segment()
+            current_kind = kind
+            current_segment = [prev_pos]
+
+        current_segment.append((x, y, z))
+        all_x.append(x)
+        all_y.append(y)
+        all_z.append(z)
+
+    flush_segment()
+
+    if all_x:
+        bounds = (
+            (min(all_x), min(all_y), min(all_z)),
+            (max(all_x), max(all_y), max(all_z)),
+        )
+    else:
+        bounds = ((0.0, 0.0, 0.0), (0.0, 0.0, 0.0))
+
+    # Assign a layer index to every move. Layers are the distinct Z heights at
+    # which printing (G1) happens; travel moves (including the Z lift between
+    # layers) are attributed to the layer of the next print move so a layer's
+    # timeline starts with the approach travel and ends with its last print.
+    print_z = sorted({round(m["end"][2], 6) for m in moves if m["kind"] == "print"})
+    z_to_layer = {z: i for i, z in enumerate(print_z)}
+    next_print_layer = len(print_z) - 1 if print_z else 0
+    for move in reversed(moves):
+        if move["kind"] == "print":
+            next_print_layer = z_to_layer[round(move["end"][2], 6)]
+        move["layer"] = next_print_layer
+
+    return {
+        "print_segments": print_segments,
+        "travel_segments": travel_segments,
+        "moves": moves,
+        "layer_count": len(print_z),
+        "bounds": bounds,
+        "point_count": len(all_x),
+    }
+
+
+def _move_length(move: dict) -> float:
+    (x0, y0, z0), (x1, y1, z1) = move["start"], move["end"]
+    return math.sqrt((x1 - x0) ** 2 + (y1 - y0) ** 2 + (z1 - z0) ** 2)
+
+
+def _chronological_trace_arrays(moves: list[dict]) -> dict:
+    """Build per-kind polyline arrays with a shared time axis for animation.
+
+    Each point gets a timestamp equal to the cumulative path length (print +
+    travel) at which the nozzle reaches it, so the browser can reveal both
+    traces in lockstep by slicing at a time cutoff. Gap markers (None) close a
+    trace's polyline whenever the move kind switches and carry the timestamp
+    of the segment they terminate.
+    """
+    arrays: dict[str, dict[str, list]] = {
+        "print": {"x": [], "y": [], "z": [], "t": []},
+        "travel": {"x": [], "y": [], "z": [], "t": []},
+    }
+    cum = 0.0
+    prev_kind: str | None = None
+    layer_end: dict[int, float] = {}
+
+    for move in moves:
+        trace = arrays[move["kind"]]
+        if move["kind"] != prev_kind:
+            if prev_kind is not None:
+                prev_trace = arrays[prev_kind]
+                prev_trace["x"].append(None)
+                prev_trace["y"].append(None)
+                prev_trace["z"].append(None)
+                prev_trace["t"].append(cum)
+            sx, sy, sz = move["start"]
+            trace["x"].append(sx)
+            trace["y"].append(sy)
+            trace["z"].append(sz)
+            trace["t"].append(cum)
+            prev_kind = move["kind"]
+        cum += _move_length(move)
+        ex, ey, ez = move["end"]
+        trace["x"].append(ex)
+        trace["y"].append(ey)
+        trace["z"].append(ez)
+        trace["t"].append(cum)
+        layer_end[move["layer"]] = cum
+
+    layer_count = (max(layer_end) + 1) if layer_end else 0
+    layer_t_end: list[float] = []
+    last = 0.0
+    for i in range(layer_count):
+        last = max(last, layer_end.get(i, last))
+        layer_t_end.append(last)
+
+    return {
+        "print": arrays["print"],
+        "travel": arrays["travel"],
+        "total_length": cum,
+        "layer_t_end": layer_t_end,
+    }
+
+
+def _path_arrays(moves: list[dict]) -> dict:
+    """Chronological nozzle positions with cumulative-length timestamps."""
+    xs = [moves[0]["start"][0]]
+    ys = [moves[0]["start"][1]]
+    zs = [moves[0]["start"][2]]
+    ts = [0.0]
+    cum = 0.0
+    for move in moves:
+        cum += _move_length(move)
+        ex, ey, ez = move["end"]
+        xs.append(ex)
+        ys.append(ey)
+        zs.append(ez)
+        ts.append(cum)
+    return {"x": xs, "y": ys, "z": zs, "t": ts}
+
+
+def _build_path_tube(
+    moves: list[dict],
+    radius: float,
+    kind: str = "print",
+    sides: int = 12,
+    max_rings: int = 5000,
+) -> dict:
+    """Extrude a tube of physical radius along the moves of the given kind.
+
+    Returns Mesh3d-ready vertex and face arrays. Rings are laid down in
+    chronological order and long moves are subdivided, so faces can be
+    revealed progressively by slicing the (sorted) per-face timestamps.
+    """
+    # Group consecutive moves of this kind into continuous runs (global times).
+    runs: list[tuple[list, list]] = []
+    cur_pts: list | None = None
+    cur_ts: list | None = None
+    cum = 0.0
+    for move in moves:
+        length = _move_length(move)
+        if move["kind"] == kind:
+            if cur_pts is None:
+                cur_pts = [move["start"]]
+                cur_ts = [cum]
+            cur_pts.append(move["end"])
+            cur_ts.append(cum + length)
+        elif cur_pts is not None:
+            runs.append((cur_pts, cur_ts))
+            cur_pts = cur_ts = None
+        cum += length
+    if cur_pts is not None:
+        runs.append((cur_pts, cur_ts))
+
+    total_print = sum(ts[-1] - ts[0] for _pts, ts in runs)
+    step = max(radius * 2.0, total_print / max_rings) if total_print > 0 else radius
+
+    xs: list[float] = []
+    ys: list[float] = []
+    zs: list[float] = []
+    fi: list[int] = []
+    fj: list[int] = []
+    fk: list[int] = []
+    face_t: list[float] = []
+    angles = np.linspace(0.0, 2.0 * np.pi, sides, endpoint=False)
+    cos_a, sin_a = np.cos(angles), np.sin(angles)
+
+    for pts, ts in runs:
+        # Subdivide long moves so the tube grows smoothly during playback.
+        sub_p = [np.asarray(pts[0], dtype=float)]
+        sub_t = [ts[0]]
+        for a in range(len(pts) - 1):
+            p0 = np.asarray(pts[a], dtype=float)
+            p1 = np.asarray(pts[a + 1], dtype=float)
+            seg = float(np.linalg.norm(p1 - p0))
+            pieces = max(1, math.ceil(seg / step))
+            for s in range(1, pieces + 1):
+                f = s / pieces
+                sub_p.append(p0 + (p1 - p0) * f)
+                sub_t.append(ts[a] + (ts[a + 1] - ts[a]) * f)
+
+        points = np.vstack(sub_p)
+        n_rings = len(points)
+        if n_rings < 2:
+            continue
+
+        # Per-ring tangents (averaged at interior points) and a perpendicular
+        # frame; vertical tangents fall back to the X axis for the side vector.
+        tangents = np.zeros_like(points)
+        tangents[1:-1] = points[2:] - points[:-2]
+        tangents[0] = points[1] - points[0]
+        tangents[-1] = points[-1] - points[-2]
+        norms = np.linalg.norm(tangents, axis=1, keepdims=True)
+        norms[norms == 0] = 1.0
+        tangents /= norms
+
+        side_vec = np.cross(tangents, np.array([0.0, 0.0, 1.0]))
+        side_norm = np.linalg.norm(side_vec, axis=1)
+        vertical = side_norm < 1e-6
+        if vertical.any():
+            side_vec[vertical] = np.cross(tangents[vertical], np.array([1.0, 0.0, 0.0]))
+        side_vec /= np.maximum(np.linalg.norm(side_vec, axis=1, keepdims=True), 1e-12)
+        up_vec = np.cross(side_vec, tangents)
+
+        base = len(xs)
+        rings = (
+            points[:, None, :]
+            + radius * (cos_a[None, :, None] * side_vec[:, None, :]
+                        + sin_a[None, :, None] * up_vec[:, None, :])
+        )
+        flat = np.round(rings.reshape(-1, 3), 4)
+        xs.extend(flat[:, 0].tolist())
+        ys.extend(flat[:, 1].tolist())
+        zs.extend(flat[:, 2].tolist())
+
+        # Center vertices for the end caps that close the tube.
+        cap_start = len(xs)
+        xs.append(round(float(points[0][0]), 4))
+        ys.append(round(float(points[0][1]), 4))
+        zs.append(round(float(points[0][2]), 4))
+        cap_end = len(xs)
+        xs.append(round(float(points[-1][0]), 4))
+        ys.append(round(float(points[-1][1]), 4))
+        zs.append(round(float(points[-1][2]), 4))
+
+        t_start = round(sub_t[0], 4)
+        t_end = round(sub_t[-1], 4)
+
+        # Start cap (fan around the first ring).
+        for k in range(sides):
+            k_next = (k + 1) % sides
+            fi.append(cap_start)
+            fj.append(base + k_next)
+            fk.append(base + k)
+            face_t.append(t_start)
+
+        for r in range(n_rings - 1):
+            r0 = base + r * sides
+            r1 = r0 + sides
+            t_face = round(sub_t[r + 1], 4)
+            for k in range(sides):
+                k_next = (k + 1) % sides
+                fi.extend((r0 + k, r0 + k))
+                fj.extend((r1 + k, r1 + k_next))
+                fk.extend((r1 + k_next, r0 + k_next))
+                face_t.extend((t_face, t_face))
+
+        # End cap (fan around the last ring).
+        last_ring = base + (n_rings - 1) * sides
+        for k in range(sides):
+            k_next = (k + 1) % sides
+            fi.append(cap_end)
+            fj.append(last_ring + k)
+            fk.append(last_ring + k_next)
+            face_t.append(t_end)
+
+    return {"x": xs, "y": ys, "z": zs, "i": fi, "j": fj, "k": fk, "face_t": face_t}
+
+
+def _segments_to_xyz(
+    segments: list[list[tuple[float, float, float]]],
+) -> tuple[list[float | None], list[float | None], list[float | None]]:
+    xs: list[float | None] = []
+    ys: list[float | None] = []
+    zs: list[float | None] = []
+    for segment in segments:
+        for px, py, pz in segment:
+            xs.append(px)
+            ys.append(py)
+            zs.append(pz)
+        xs.append(None)
+        ys.append(None)
+        zs.append(None)
+    return xs, ys, zs
+
+
+def build_toolpath_figure(
+    parsed: dict,
+    travel_opacity: float = 0.2,
+    print_opacity: float = 1.0,
+    travel_color: str = "#969696",
+    print_color: str = "#1f77b4",
+    print_width: float = 0.8,
+    travel_width: float = 0.2,
+    tube: bool = True,
+) -> go.Figure:
+    moves = parsed.get("moves") or []
+
+    fig = go.Figure()
+    meta = None
+
+    def add_tube_trace(tube: dict, name: str, color: str, opacity: float) -> None:
+        fig.add_trace(
+            go.Mesh3d(
+                x=tube["x"],
+                y=tube["y"],
+                z=tube["z"],
+                i=tube["i"],
+                j=tube["j"],
+                k=tube["k"],
+                color=color,
+                opacity=opacity,
+                name=name,
+                showlegend=True,
+                hoverinfo="skip",
+                lighting=dict(ambient=0.55, diffuse=0.8, specular=0.15, roughness=0.6),
+            )
+        )
+
+    if moves and tube:
+        chrono = _chronological_trace_arrays(moves)
+
+        # Physical-width tubes along both paths: filament-like rendering whose
+        # thickness scales with zoom (widths are diameters in mm).
+        travel_tube = _build_path_tube(
+            moves, radius=max(travel_width, 0.05) / 2.0, kind="travel"
+        )
+        if travel_tube["i"]:
+            add_tube_trace(travel_tube, "Travel (G0)", travel_color, travel_opacity)
+
+        print_tube = _build_path_tube(
+            moves, radius=max(print_width, 0.05) / 2.0, kind="print"
+        )
+        if print_tube["i"]:
+            add_tube_trace(print_tube, "Print (G1)", print_color, print_opacity)
+
+        # Nozzle position marker, driven client-side during playback.
+        end_x, end_y, end_z = moves[-1]["end"]
+        fig.add_trace(
+            go.Scatter3d(
+                x=[end_x],
+                y=[end_y],
+                z=[end_z],
+                mode="markers",
+                name="Nozzle",
+                marker=dict(size=5, color="#d62728"),
+                showlegend=False,
+                hoverinfo="skip",
+            )
+        )
+
+        path = _path_arrays(moves)
+        meta = {
+            "animation": {
+                "travel_face_t": travel_tube["face_t"],
+                "print_face_t": print_tube["face_t"],
+                "path_x": path["x"],
+                "path_y": path["y"],
+                "path_z": path["z"],
+                "path_t": path["t"],
+                "layer_t_end": chrono["layer_t_end"],
+                "total_length": chrono["total_length"],
+            }
+        }
+    else:
+        travel_xs, travel_ys, travel_zs = _segments_to_xyz(parsed["travel_segments"])
+        if travel_xs:
+            fig.add_trace(
+                go.Scatter3d(
+                    x=travel_xs,
+                    y=travel_ys,
+                    z=travel_zs,
+                    mode="lines",
+                    name="Travel (G0)",
+                    opacity=travel_opacity,
+                    line=dict(color=travel_color, width=2),
+                    hoverinfo="skip",
+                )
+            )
+        print_xs, print_ys, print_zs = _segments_to_xyz(parsed["print_segments"])
+        if print_xs:
+            fig.add_trace(
+                go.Scatter3d(
+                    x=print_xs,
+                    y=print_ys,
+                    z=print_zs,
+                    mode="lines",
+                    name="Print (G1)",
+                    opacity=print_opacity,
+                    line=dict(color=print_color, width=4),
+                    hovertemplate="X=%{x:.2f}<br>Y=%{y:.2f}<br>Z=%{z:.2f}<extra></extra>",
+                )
+            )
+
+    (x_min, y_min, z_min), (x_max, y_max, z_max) = parsed["bounds"]
+    fig.update_layout(
+        meta=meta,
+        height=700,
+        uirevision="toolpath",
+        scene=dict(
+            xaxis_title="X (mm)",
+            yaxis_title="Y (mm)",
+            zaxis_title="Z (mm)",
+            aspectmode="data",
+        ),
+        margin=dict(l=0, r=0, t=30, b=0),
+        legend=dict(orientation="h", yanchor="bottom", y=1.0, xanchor="left", x=0.0),
+        title=(
+            f"Tool path — {len(parsed['print_segments'])} print / "
+            f"{len(parsed['travel_segments'])} travel segments   "
+            f"X[{x_min:.1f},{x_max:.1f}]  Y[{y_min:.1f},{y_max:.1f}]  "
+            f"Z[{z_min:.1f},{z_max:.1f}]"
+        ),
+    )
+    return fig
+
+
+def build_parallel_figure(
+    parts: list[dict],
+    gap: float = 5.0,
+    filament_width: float = 0.8,
+    travel_width: float = 0.2,
+    travel_opacity: float = 0.2,
+    print_opacity: float = 1.0,
+    tube: bool = True,
+) -> go.Figure:
+    """Render several parsed shapes side by side, offset along X so they don't
+    overlap. `tube` True draws filament tubes with a shared-time animation
+    timeline; False draws fast thin scatter lines (no animation).
+
+    `parts` is a list of {"idx": int, "color": str, "parsed": dict}. Each part's
+    print and travel traces (and, in tube mode, a nozzle marker) are named by idx
+    so the client-side animation/recolor can address them.
+    """
+    fig = go.Figure()
+    anim_parts: list[dict] = []
+    total_length = 0.0
+    rendered = False
+    n_parts = 0
+    bx0 = by0 = bz0 = float("inf")
+    bx1 = by1 = bz1 = float("-inf")
+
+    running_x = 0.0
+    for part in parts:
+        idx = part["idx"]
+        color = part["color"]
+        parsed = part["parsed"]
+        moves = parsed.get("moves") or []
+        if not moves:
+            continue
+
+        (pxmin, pymin, pzmin), (pxmax, pymax, pzmax) = parsed["bounds"]
+        width = pxmax - pxmin
+        x_off = running_x - pxmin
+        running_x += width + gap
+
+        if tube:
+            print_tube = _build_path_tube(moves, radius=max(filament_width, 0.05) / 2.0, kind="print")
+            travel_tube = _build_path_tube(moves, radius=max(travel_width, 0.05) / 2.0, kind="travel")
+            path = _path_arrays(moves)
+
+            px = [v + x_off for v in print_tube["x"]]
+            tx = [v + x_off for v in travel_tube["x"]]
+            path_x = [v + x_off for v in path["x"]]
+
+            if travel_tube["i"]:
+                fig.add_trace(
+                    go.Mesh3d(
+                        x=tx, y=travel_tube["y"], z=travel_tube["z"],
+                        i=travel_tube["i"], j=travel_tube["j"], k=travel_tube["k"],
+                        color=color, opacity=travel_opacity, name=f"Travel {idx}",
+                        showlegend=False, hoverinfo="skip",
+                        lighting=dict(ambient=0.6, diffuse=0.8, specular=0.1, roughness=0.6),
+                    )
+                )
+            if print_tube["i"]:
+                fig.add_trace(
+                    go.Mesh3d(
+                        x=px, y=print_tube["y"], z=print_tube["z"],
+                        i=print_tube["i"], j=print_tube["j"], k=print_tube["k"],
+                        color=color, opacity=print_opacity, name=f"Shape {idx}",
+                        showlegend=True, hoverinfo="skip",
+                        lighting=dict(ambient=0.55, diffuse=0.8, specular=0.15, roughness=0.6),
+                    )
+                )
+            fig.add_trace(
+                go.Scatter3d(
+                    x=[path_x[-1]], y=[path["y"][-1]], z=[path["z"][-1]],
+                    mode="markers", name=f"Nozzle {idx}",
+                    marker=dict(size=4, color=color), showlegend=False, hoverinfo="skip",
+                )
+            )
+
+            part_total = path["t"][-1] if path["t"] else 0.0
+            total_length = max(total_length, part_total)
+            anim_parts.append({
+                "printName": f"Shape {idx}",
+                "travelName": f"Travel {idx}",
+                "nozzleName": f"Nozzle {idx}",
+                "print_face_t": print_tube["face_t"],
+                "travel_face_t": travel_tube["face_t"],
+                "path_x": path_x, "path_y": path["y"], "path_z": path["z"], "path_t": path["t"],
+            })
+        else:
+            t_xs, t_ys, t_zs = _segments_to_xyz(parsed["travel_segments"])
+            p_xs, p_ys, p_zs = _segments_to_xyz(parsed["print_segments"])
+            t_xs = [v + x_off if v is not None else None for v in t_xs]
+            p_xs = [v + x_off if v is not None else None for v in p_xs]
+            if t_xs:
+                fig.add_trace(
+                    go.Scatter3d(
+                        x=t_xs, y=t_ys, z=t_zs, mode="lines", name=f"Travel {idx}",
+                        opacity=travel_opacity, line=dict(color=color, width=2),
+                        showlegend=False, hoverinfo="skip",
+                    )
+                )
+            if p_xs:
+                fig.add_trace(
+                    go.Scatter3d(
+                        x=p_xs, y=p_ys, z=p_zs, mode="lines", name=f"Shape {idx}",
+                        opacity=print_opacity, line=dict(color=color, width=4),
+                        showlegend=True, hoverinfo="skip",
+                    )
+                )
+
+        rendered = True
+        n_parts += 1
+        bx0 = min(bx0, pxmin + x_off); bx1 = max(bx1, pxmax + x_off)
+        by0 = min(by0, pymin); by1 = max(by1, pymax)
+        bz0 = min(bz0, pzmin); bz1 = max(bz1, pzmax)
+
+    if not rendered:
+        fig.update_layout(height=700)
+        return fig
+
+    meta = {"animation": {"total_length": total_length, "parts": anim_parts}} if anim_parts else None
+    pad = max(bx1 - bx0, by1 - by0, bz1 - bz0, 1.0) * 0.05
+    fig.update_layout(
+        meta=meta,
+        height=700,
+        uirevision="parallel",
+        scene=dict(
+            xaxis_title="X (mm)", yaxis_title="Y (mm)", zaxis_title="Z (mm)",
+            xaxis_range=[bx0 - pad, bx1 + pad],
+            yaxis_range=[by0 - pad, by1 + pad],
+            zaxis_range=[bz0 - pad, bz1 + pad],
+            aspectmode="data",
+        ),
+        margin=dict(l=0, r=0, t=30, b=0),
+        legend=dict(orientation="h", yanchor="bottom", y=1.0, xanchor="left", x=0.0),
+        title=f"Parallel print — {n_parts} part(s)",
+    )
+    return fig
+
+
+def build_parallel_gif(
+    parts: list[dict],
+    out_path: str | Path,
+    gap: float = 5.0,
+    duration: float = 6.0,
+    fps: int = 10,
+    travel_opacity: float = 0.15,
+    travel_color: str = "#9a9a9a",
+    print_width: float = 4.0,
+    travel_width: float = 1.5,
+    elev: float = 22.0,
+    azim: float = -60.0,
+    progress_cb=None,
+) -> Path | None:
+    """Render the parallel print as an animated GIF using Matplotlib (CPU Agg
+    backend — no WebGL/headless browser, works on Hugging Face).
+
+    Each part's toolpath is drawn as growing colored lines (print solid, travel
+    faint), three parts in parallel on a shared cumulative-length time axis.
+    `parts` is a list of {"idx": int, "color": str, "parsed": dict}.
+    """
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    from matplotlib.animation import FuncAnimation, PillowWriter
+    from mpl_toolkits.mplot3d.art3d import Line3DCollection
+
+    pdata: list[dict] = []
+    running_x = 0.0
+    total_length = 0.0
+    bx0 = by0 = bz0 = float("inf")
+    bx1 = by1 = bz1 = float("-inf")
+
+    for part in parts:
+        parsed = part["parsed"]
+        moves = parsed.get("moves") or []
+        if not moves:
+            continue
+        (pxmin, pymin, pzmin), (pxmax, pymax, pzmax) = parsed["bounds"]
+        x_off = running_x - pxmin
+        running_x += (pxmax - pxmin) + gap
+
+        cum = 0.0
+        mlist: list[tuple] = []
+        for m in moves:
+            s = (m["start"][0] + x_off, m["start"][1], m["start"][2])
+            e = (m["end"][0] + x_off, m["end"][1], m["end"][2])
+            seg_len = math.dist(s, e)
+            mlist.append((m["kind"], s, e, cum, cum + seg_len))
+            cum += seg_len
+        total_length = max(total_length, cum)
+        pdata.append({
+            "color": part["color"], "moves": mlist,
+            "last": mlist[-1][2], "first": mlist[0][1],
+        })
+
+        bx0 = min(bx0, pxmin + x_off); bx1 = max(bx1, pxmax + x_off)
+        by0 = min(by0, pymin); by1 = max(by1, pymax)
+        bz0 = min(bz0, pzmin); bz1 = max(bz1, pzmax)
+
+    if not pdata or total_length <= 0:
+        return None
+
+    n_frames = max(2, int(round(duration * fps)))
+
+    def segs_at(mlist: list[tuple], kind: str, cutoff: float) -> list:
+        out = []
+        for k, s, e, t0, t1 in mlist:
+            if k != kind:
+                continue
+            if t1 <= cutoff:
+                out.append([s, e])
+            elif t0 < cutoff:
+                f = (cutoff - t0) / (t1 - t0) if t1 > t0 else 1.0
+                ei = (s[0] + (e[0] - s[0]) * f, s[1] + (e[1] - s[1]) * f, s[2] + (e[2] - s[2]) * f)
+                out.append([s, ei])
+        return out
+
+    def nozzle_at(mlist: list[tuple], cutoff: float) -> tuple:
+        last = mlist[0][1]
+        for _k, s, e, t0, t1 in mlist:
+            if cutoff >= t1:
+                last = e
+            elif t0 <= cutoff <= t1:
+                f = (cutoff - t0) / (t1 - t0) if t1 > t0 else 1.0
+                return (s[0] + (e[0] - s[0]) * f, s[1] + (e[1] - s[1]) * f, s[2] + (e[2] - s[2]) * f)
+            else:
+                return last
+        return last
+
+    fig = plt.figure(figsize=(8, 6), dpi=100)
+    ax = fig.add_subplot(111, projection="3d")
+    # Honour explicit zorder instead of depth-sorting, so the nozzle markers
+    # always draw on top of the toolpath lines.
+    try:
+        ax.computed_zorder = False
+    except Exception:
+        pass
+    pad = max(bx1 - bx0, by1 - by0, bz1 - bz0, 1.0) * 0.05
+    ax.set_xlim(bx0 - pad, bx1 + pad)
+    ax.set_ylim(by0 - pad, by1 + pad)
+    ax.set_zlim(bz0 - pad, bz1 + pad)
+    try:
+        ax.set_box_aspect((bx1 - bx0 + 1e-6, by1 - by0 + 1e-6, bz1 - bz0 + 1e-6))
+    except Exception:
+        pass
+    ax.set_xlabel("X (mm)"); ax.set_ylabel("Y (mm)"); ax.set_zlabel("Z (mm)")
+    ax.view_init(elev=elev, azim=azim)
+
+    artists = []
+    for pd in pdata:
+        # Seed with a degenerate segment: matplotlib 3.11's add_collection3d
+        # errors on an empty collection. Axis limits are fixed above, so this
+        # placeholder doesn't affect scaling; update() replaces it each frame.
+        seed = [[pd["first"], pd["first"]]]
+        # Travel drawn in neutral grey (distinct from the part's print color)
+        # and faint, so travel and print are easy to tell apart.
+        travel_col = Line3DCollection(seed, colors=travel_color, linewidths=travel_width, alpha=travel_opacity, zorder=1)
+        print_col = Line3DCollection(seed, colors=pd["color"], linewidths=print_width, zorder=2)
+        ax.add_collection3d(travel_col)
+        ax.add_collection3d(print_col)
+        # Nozzle marker: white fill with a black outline, drawn on top (high
+        # zorder + computed_zorder disabled) so it stays visible against any
+        # part color and the light background.
+        noz = ax.scatter(
+            [pd["last"][0]], [pd["last"][1]], [pd["last"][2]],
+            color="white", edgecolors="black", linewidths=1.4, s=90,
+            depthshade=False, zorder=10,
+        )
+        artists.append((print_col, travel_col, noz))
+
+    def update(frame: int):
+        cutoff = (frame / (n_frames - 1)) * total_length
+        if progress_cb is not None:
+            progress_cb(frame, n_frames)
+        drawn = []
+        for (print_col, travel_col, noz), pd in zip(artists, pdata):
+            print_col.set_segments(segs_at(pd["moves"], "print", cutoff))
+            travel_col.set_segments(segs_at(pd["moves"], "travel", cutoff))
+            nx, ny, nz = nozzle_at(pd["moves"], cutoff)
+            noz._offsets3d = ([nx], [ny], [nz])
+            drawn += [print_col, travel_col, noz]
+        return drawn
+
+    anim = FuncAnimation(fig, update, frames=n_frames, blit=False)
+    out_path = Path(out_path)
+    anim.save(str(out_path), writer=PillowWriter(fps=int(fps)))
+    plt.close(fig)
+    return out_path
+
+
+def render_gcode_file(path: str | Path) -> tuple[go.Figure, dict]:
+    text = Path(path).read_text()
+    parsed = parse_gcode_path(text)
+    return build_toolpath_figure(parsed), parsed

pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "stl-to-gcode"
+version = "0.1.0"
+description = "Gradio app for slicing STL files into TIFF image stacks."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "gradio>=5.23.0",
+    "matplotlib>=3.11.0",
+    "networkx>=3.4.2",
+    "numpy>=2.2.0",
+    "pillow>=11.1.0",
+    "plotly>=6.7.0",
+    "scipy>=1.15.2",
+    "shapely>=2.0.7",
+    "trimesh>=4.6.5",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+]
+
+[tool.uv]
+package = false

requirements.txt

@@ -0,0 +1,197 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --format requirements.txt --no-hashes --no-dev --frozen --output-file requirements.txt
+aiofiles==24.1.0
+    # via gradio
+annotated-doc==0.0.4
+    # via
+    #   fastapi
+    #   typer
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.13.0
+    # via
+    #   gradio
+    #   httpx
+    #   starlette
+audioop-lts==0.2.2 ; python_full_version >= '3.13'
+    # via gradio
+brotli==1.2.0
+    # via gradio
+certifi==2026.2.25
+    # via
+    #   httpcore
+    #   httpx
+click==8.3.1
+    # via
+    #   typer
+    #   uvicorn
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via
+    #   click
+    #   tqdm
+contourpy==1.3.3
+    # via matplotlib
+cycler==0.12.1
+    # via matplotlib
+fastapi==0.135.2
+    # via gradio
+ffmpy==1.0.0
+    # via gradio
+filelock==3.25.2
+    # via huggingface-hub
+fonttools==4.63.0
+    # via matplotlib
+fsspec==2026.3.0
+    # via
+    #   gradio-client
+    #   huggingface-hub
+gradio==6.10.0
+    # via stl-to-gcode
+gradio-client==2.4.0
+    # via
+    #   gradio
+    #   hf-gradio
+groovy==0.1.2
+    # via gradio
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+hf-gradio==0.3.0
+    # via gradio
+hf-xet==1.4.2 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   safehttpx
+huggingface-hub==1.8.0
+    # via
+    #   gradio
+    #   gradio-client
+idna==3.11
+    # via
+    #   anyio
+    #   httpx
+jinja2==3.1.6
+    # via gradio
+kiwisolver==1.5.0
+    # via matplotlib
+markdown-it-py==4.0.0
+    # via rich
+markupsafe==3.0.3
+    # via
+    #   gradio
+    #   jinja2
+matplotlib==3.11.0
+    # via stl-to-gcode
+mdurl==0.1.2
+    # via markdown-it-py
+narwhals==2.19.0
+    # via plotly
+networkx==3.6.1
+    # via stl-to-gcode
+numpy==2.4.4
+    # via
+    #   contourpy
+    #   gradio
+    #   matplotlib
+    #   pandas
+    #   scipy
+    #   shapely
+    #   stl-to-gcode
+    #   trimesh
+orjson==3.11.7
+    # via gradio
+packaging==26.0
+    # via
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   matplotlib
+    #   plotly
+pandas==3.0.1
+    # via gradio
+pillow==12.1.1
+    # via
+    #   gradio
+    #   matplotlib
+    #   stl-to-gcode
+plotly==6.7.0
+    # via stl-to-gcode
+pydantic==2.12.5
+    # via
+    #   fastapi
+    #   gradio
+pydantic-core==2.41.5
+    # via pydantic
+pydub==0.25.1
+    # via gradio
+pygments==2.20.0
+    # via rich
+pyparsing==3.3.2
+    # via matplotlib
+python-dateutil==2.9.0.post0
+    # via
+    #   matplotlib
+    #   pandas
+python-multipart==0.0.22
+    # via gradio
+pytz==2026.1.post1
+    # via gradio
+pyyaml==6.0.3
+    # via
+    #   gradio
+    #   huggingface-hub
+rich==14.3.3
+    # via typer
+safehttpx==0.1.7
+    # via gradio
+scipy==1.17.1
+    # via stl-to-gcode
+semantic-version==2.10.0
+    # via gradio
+shapely==2.1.2
+    # via stl-to-gcode
+shellingham==1.5.4
+    # via typer
+six==1.17.0
+    # via python-dateutil
+starlette==0.52.1
+    # via
+    #   fastapi
+    #   gradio
+tomlkit==0.13.3
+    # via gradio
+tqdm==4.67.3
+    # via huggingface-hub
+trimesh==4.11.5
+    # via stl-to-gcode
+typer==0.24.1
+    # via
+    #   gradio
+    #   hf-gradio
+    #   huggingface-hub
+typing-extensions==4.15.0
+    # via
+    #   anyio
+    #   fastapi
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   pydantic
+    #   pydantic-core
+    #   starlette
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   fastapi
+    #   pydantic
+tzdata==2025.3 ; sys_platform == 'emscripten' or sys_platform == 'win32'
+    # via pandas
+uvicorn==0.42.0
+    # via gradio

sample_stls/Hollow_Pyramid.stl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:045df2fcadec01360e37467bb29d791e9b63552d32ececa388f2e57ce95cb0db
+size 9860

sample_stls/Rounded_Cube_Through_Holes.stl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e0d8a159cc44350ea75c63699960216a7f097ccd2321698918c1bd5bace49510
+size 2299409

sample_stls/halfsphere.stl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3011534784a9849354d408401c37c6bfb59116e9a19163adac953047b362178c
+size 362001

stl_slicer.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+import math
+import tempfile
+import uuid
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Sequence
+
+import numpy as np
+from PIL import Image, ImageDraw
+from shapely.geometry import GeometryCollection, MultiPolygon, Polygon
+import trimesh
+
+
+ProgressCallback = Callable[[int, int], None] | None
+ScaleFactors = tuple[float, float, float]
+
+
+@dataclass(slots=True)
+class SliceStack:
+    output_dir: Path
+    zip_path: Path
+    tiff_paths: list[Path]
+    z_values: list[float]
+    image_size: tuple[int, int]
+    bounds: tuple[tuple[float, float, float], tuple[float, float, float]]
+    layer_height: float
+    pixel_size: float
+
+
+def load_mesh(stl_path: str | Path) -> trimesh.Trimesh:
+    loaded = trimesh.load(stl_path, force="scene")
+    if isinstance(loaded, trimesh.Scene):
+        if not loaded.geometry:
+            raise ValueError("The STL file does not contain any mesh geometry.")
+        mesh = trimesh.util.concatenate(tuple(loaded.geometry.values()))
+    else:
+        mesh = loaded
+
+    if not isinstance(mesh, trimesh.Trimesh) or mesh.is_empty:
+        raise ValueError("Unable to load a valid mesh from the STL file.")
+
+    return mesh
+
+
+def _normalize_scale_factors(scale_factors: Sequence[float] | None) -> ScaleFactors:
+    if scale_factors is None:
+        return (1.0, 1.0, 1.0)
+
+    values = tuple(float(value) for value in scale_factors)
+    if len(values) != 3:
+        raise ValueError("Scale factors must contain X, Y, and Z values.")
+
+    if any(value <= 0 for value in values):
+        raise ValueError("Scale factors must be greater than zero.")
+
+    return (values[0], values[1], values[2])
+
+
+def scale_mesh(mesh: trimesh.Trimesh, scale_factors: Sequence[float] | None = None) -> trimesh.Trimesh:
+    """Return a copy of `mesh` scaled around its minimum XYZ corner."""
+    sx, sy, sz = _normalize_scale_factors(scale_factors)
+    scaled = mesh.copy()
+
+    if math.isclose(sx, 1.0) and math.isclose(sy, 1.0) and math.isclose(sz, 1.0):
+        return scaled
+
+    anchor = np.asarray(mesh.bounds[0], dtype=float)
+    transform = np.eye(4)
+    transform[0, 0] = sx
+    transform[1, 1] = sy
+    transform[2, 2] = sz
+    transform[:3, 3] = anchor * (1.0 - np.array([sx, sy, sz], dtype=float))
+    scaled.apply_transform(transform)
+    return scaled
+
+
+def scale_factors_for_target_extents(
+    mesh: trimesh.Trimesh,
+    target_extents: Sequence[float],
+) -> ScaleFactors:
+    target = _normalize_scale_factors(target_extents)
+    extents = np.asarray(mesh.extents, dtype=float)
+    if np.any(extents <= 0):
+        raise ValueError("Cannot scale a mesh with a zero-sized X, Y, or Z extent.")
+
+    return (
+        target[0] / float(extents[0]),
+        target[1] / float(extents[1]),
+        target[2] / float(extents[2]),
+    )
+
+
+def calculate_z_levels(z_min: float, z_max: float, layer_height: float) -> list[float]:
+    if layer_height <= 0:
+        raise ValueError("Layer height must be greater than zero.")
+
+    thickness = z_max - z_min
+    if thickness <= 0:
+        return [z_min]
+
+    layer_count = max(1, math.ceil(thickness / layer_height))
+    top_guard = math.nextafter(z_max, z_min)
+
+    return [
+        min(z_min + ((index + 0.5) * layer_height), top_guard)
+        for index in range(layer_count)
+    ]
+
+
+def _to_pixel_ring(
+    coords: np.ndarray,
+    x_min: float,
+    y_min: float,
+    pixel_size: float,
+    image_height: int,
+) -> list[tuple[int, int]]:
+    pixels: list[tuple[int, int]] = []
+    for x_value, y_value in coords:
+        x_pixel = int(round((float(x_value) - x_min) / pixel_size))
+        y_pixel = int(round((float(y_value) - y_min) / pixel_size))
+        pixels.append((x_pixel, image_height - 1 - y_pixel))
+    return pixels
+
+
+def _ring_to_world_xy(ring_coords: object, to_3d: np.ndarray) -> np.ndarray:
+    planar = np.asarray(ring_coords, dtype=float)
+    if planar.ndim != 2 or planar.shape[1] < 2:
+        raise ValueError("Encountered an invalid polygon ring while slicing.")
+
+    planar_3d = np.column_stack([planar[:, 0], planar[:, 1], np.zeros(len(planar))])
+    world = trimesh.transform_points(planar_3d, to_3d)
+    return world[:, :2]
+
+
+def _compose_even_odd_polygons(polygons: list[Polygon]) -> list[Polygon]:
+    geometry: Polygon | MultiPolygon | GeometryCollection | None = None
+    for polygon in polygons:
+        geometry = polygon if geometry is None else geometry.symmetric_difference(polygon)
+
+    if geometry is None or geometry.is_empty:
+        return []
+
+    if isinstance(geometry, Polygon):
+        return [geometry]
+
+    if isinstance(geometry, MultiPolygon):
+        return list(geometry.geoms)
+
+    if isinstance(geometry, GeometryCollection):
+        return [geom for geom in geometry.geoms if isinstance(geom, Polygon) and not geom.is_empty]
+
+    return []
+
+
+def _extract_world_polygons(section: trimesh.path.Path3D) -> list[tuple[np.ndarray, list[np.ndarray]]]:
+    if hasattr(section, "to_2D"):
+        planar, to_3d = section.to_2D()
+    else:
+        planar, to_3d = section.to_planar()
+
+    composed_polygons = _compose_even_odd_polygons(list(planar.polygons_closed))
+    polygons: list[tuple[np.ndarray, list[np.ndarray]]] = []
+    for polygon in composed_polygons:
+        exterior = _ring_to_world_xy(polygon.exterior.coords, to_3d)
+        holes = [_ring_to_world_xy(interior.coords, to_3d) for interior in polygon.interiors]
+        polygons.append((exterior, holes))
+
+    return polygons
+
+
+def _render_slice(
+    section: trimesh.path.Path3D | None,
+    x_min: float,
+    y_min: float,
+    image_size: tuple[int, int],
+    pixel_size: float,
+) -> Image.Image:
+    image = Image.new("L", image_size, 255)
+
+    if section is None:
+        return image
+
+    polygons = _extract_world_polygons(section)
+    if not polygons:
+        return image
+
+    draw = ImageDraw.Draw(image)
+    for exterior, holes in polygons:
+        draw.polygon(
+            _to_pixel_ring(exterior, x_min, y_min, pixel_size, image.height),
+            fill=0,
+        )
+        for hole in holes:
+            draw.polygon(
+                _to_pixel_ring(hole, x_min, y_min, pixel_size, image.height),
+                fill=255,
+            )
+
+    return image
+
+
+def _make_output_paths(stl_path: Path, output_root: str | Path | None) -> tuple[Path, Path]:
+    root = Path(output_root) if output_root else Path(tempfile.mkdtemp(prefix="stl_slices_"))
+    stem = stl_path.stem or "mesh"
+    job_dir = root / f"{stem}_{uuid.uuid4().hex[:8]}"
+    slices_dir = job_dir / "tiff_slices"
+    slices_dir.mkdir(parents=True, exist_ok=True)
+    zip_path = job_dir / f"{stem}_tiff_slices.zip"
+    return slices_dir, zip_path
+
+
+def _zip_tiffs(tiff_paths: list[Path], zip_path: Path) -> None:
+    with zipfile.ZipFile(zip_path, mode="w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for tiff_path in tiff_paths:
+            archive.write(tiff_path, arcname=tiff_path.name)
+
+
+def slice_stl_to_tiffs(
+    stl_path: str | Path,
+    layer_height: float,
+    pixel_size: float,
+    output_root: str | Path | None = None,
+    progress_callback: ProgressCallback = None,
+    scale_factors: Sequence[float] | None = None,
+) -> SliceStack:
+    if pixel_size <= 0:
+        raise ValueError("Pixel size must be greater than zero.")
+
+    stl_path = Path(stl_path)
+    mesh = scale_mesh(load_mesh(stl_path), scale_factors)
+    bounds = mesh.bounds
+    (x_min, y_min, z_min), (x_max, y_max, z_max) = bounds
+
+    z_values = calculate_z_levels(float(z_min), float(z_max), layer_height)
+    width = max(1, math.ceil((float(x_max) - float(x_min)) / pixel_size) + 1)
+    height = max(1, math.ceil((float(y_max) - float(y_min)) / pixel_size) + 1)
+    image_size = (width, height)
+
+    output_dir, zip_path = _make_output_paths(stl_path, output_root)
+    tiff_paths: list[Path] = []
+
+    for index, z_value in enumerate(z_values):
+        section = mesh.section(
+            plane_origin=np.array([0.0, 0.0, z_value], dtype=float),
+            plane_normal=np.array([0.0, 0.0, 1.0], dtype=float),
+        )
+        image = _render_slice(section, float(x_min), float(y_min), image_size, pixel_size)
+        tiff_path = output_dir / f"slice_{index:04d}.tif"
+        image.save(tiff_path, compression="tiff_deflate")
+        tiff_paths.append(tiff_path)
+
+        if progress_callback is not None:
+            progress_callback(index + 1, len(z_values))
+
+    _zip_tiffs(tiff_paths, zip_path)
+
+    return SliceStack(
+        output_dir=output_dir,
+        zip_path=zip_path,
+        tiff_paths=tiff_paths,
+        z_values=z_values,
+        image_size=image_size,
+        bounds=(
+            (float(x_min), float(y_min), float(z_min)),
+            (float(x_max), float(y_max), float(z_max)),
+        ),
+        layer_height=layer_height,
+        pixel_size=pixel_size,
+    )

tests/conftest.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))

tests/test_app_scaling.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import numpy as np
+import trimesh
+
+from app import (
+    SCALE_MODE_TARGET_DIMENSIONS,
+    SCALE_MODE_UNIFORM_FACTOR,
+    _resolve_mesh_scale_factors,
+)
+
+
+def test_resolve_mesh_scale_factors_uses_uniform_factor_for_all_axes() -> None:
+    mesh = trimesh.creation.box(extents=(2.0, 4.0, 8.0))
+
+    scale_factors = _resolve_mesh_scale_factors(
+        mesh,
+        scale_to_target=True,
+        scale_mode=SCALE_MODE_UNIFORM_FACTOR,
+        target_x=10.0,
+        target_y=20.0,
+        target_z=30.0,
+        uniform_scale=1.5,
+    )
+
+    assert scale_factors == (1.5, 1.5, 1.5)
+
+
+def test_resolve_mesh_scale_factors_fits_each_axis_in_target_mode() -> None:
+    mesh = trimesh.creation.box(extents=(2.0, 4.0, 8.0))
+
+    scale_factors = _resolve_mesh_scale_factors(
+        mesh,
+        scale_to_target=True,
+        scale_mode=SCALE_MODE_TARGET_DIMENSIONS,
+        target_x=10.0,
+        target_y=20.0,
+        target_z=4.0,
+        uniform_scale=1.5,
+    )
+
+    np.testing.assert_allclose(scale_factors, (5.0, 5.0, 0.5))

tests/test_gcode_viewer.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from gcode_viewer import parse_gcode_path
+
+
+def test_parse_gcode_classifies_g0_as_travel_and_g1_as_print() -> None:
+    parsed = parse_gcode_path(
+        "\n".join(
+            [
+                "G91",
+                "G0 X1 Y0 ; travel",
+                "G1 X0 Y1 ; print",
+            ]
+        )
+    )
+
+    assert len(parsed["travel_segments"]) == 1
+    assert len(parsed["print_segments"]) == 1

tests/test_stl_slicer.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image
+from shapely.geometry import Polygon
+import trimesh
+
+from stl_slicer import (
+    _compose_even_odd_polygons,
+    calculate_z_levels,
+    scale_factors_for_target_extents,
+    scale_mesh,
+    slice_stl_to_tiffs,
+)
+
+
+def test_calculate_z_levels_creates_single_layer_for_thin_mesh() -> None:
+    z_values = calculate_z_levels(0.0, 0.01, 0.1)
+
+    assert len(z_values) == 1
+    assert 0.0 <= z_values[0] < 0.01
+
+
+def test_slice_stl_to_tiffs_creates_non_empty_tiffs(tmp_path) -> None:
+    mesh = trimesh.creation.box(extents=(2.0, 2.0, 2.0))
+    stl_path = tmp_path / "cube.stl"
+    mesh.export(stl_path)
+
+    stack = slice_stl_to_tiffs(
+        stl_path,
+        layer_height=0.5,
+        pixel_size=0.25,
+        output_root=tmp_path / "generated",
+    )
+
+    assert len(stack.tiff_paths) == 4
+    assert stack.zip_path.exists()
+    assert all(path.exists() for path in stack.tiff_paths)
+
+    with Image.open(stack.tiff_paths[0]) as first_image:
+        pixels = np.array(first_image)
+
+    assert np.any(pixels == 0)
+
+
+def test_scale_mesh_matches_target_extents_and_preserves_min_corner() -> None:
+    mesh = trimesh.creation.box(extents=(2.0, 4.0, 5.0))
+    mesh.apply_translation((5.0, 6.0, 7.0))
+
+    target_extents = (10.0, 8.0, 2.5)
+    scale_factors = scale_factors_for_target_extents(mesh, target_extents)
+    scaled = scale_mesh(mesh, scale_factors)
+
+    np.testing.assert_allclose(scaled.extents, target_extents)
+    np.testing.assert_allclose(scaled.bounds[0], mesh.bounds[0])
+
+
+def test_slice_stl_to_tiffs_applies_scale_factors(tmp_path) -> None:
+    mesh = trimesh.creation.box(extents=(2.0, 2.0, 2.0))
+    stl_path = tmp_path / "cube.stl"
+    mesh.export(stl_path)
+
+    stack = slice_stl_to_tiffs(
+        stl_path,
+        layer_height=0.5,
+        pixel_size=0.25,
+        output_root=tmp_path / "scaled",
+        scale_factors=(2.0, 1.0, 0.5),
+    )
+
+    bounds = np.array(stack.bounds)
+    np.testing.assert_allclose(bounds[1] - bounds[0], (4.0, 2.0, 1.0))
+    assert stack.image_size == (17, 9)
+    assert len(stack.tiff_paths) == 2
+
+
+def test_compose_even_odd_polygons_preserves_holes() -> None:
+    outer = Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])
+    inner = Polygon([(3, 3), (7, 3), (7, 7), (3, 7)])
+
+    composed = _compose_even_odd_polygons([outer, inner])
+
+    assert len(composed) == 1
+    assert composed[0].area == outer.area - inner.area
+    assert len(composed[0].interiors) == 1

tests/test_tiff_to_gcode.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import zipfile
+
+from PIL import Image
+
+from tiff_to_gcode import generate_snake_path_gcode
+
+
+def test_gcode_header_writes_presets_before_initial_aux_commands(tmp_path) -> None:
+    tiff_path = tmp_path / "slice_0000.tif"
+    Image.new("L", (1, 1), 0).save(tiff_path)
+
+    zip_path = tmp_path / "slices.zip"
+    with zipfile.ZipFile(zip_path, mode="w") as archive:
+        archive.write(tiff_path, arcname=tiff_path.name)
+
+    gcode_path = generate_snake_path_gcode(
+        zip_path,
+        shape_name="header_order",
+        pressure=25,
+        valve=7,
+        port=3,
+    )
+
+    lines = [
+        line.strip()
+        for line in gcode_path.read_text().splitlines()
+        if line.strip()
+    ]
+
+    assert lines[0] == "G91"
+    assert lines[1].startswith("{preset}serialPort3.write(")
+    assert lines[2].startswith("{preset}serialPort3.write(")
+    assert lines[3].startswith("{aux_command}WAGO_ValveCommands(")
+    assert lines[4].startswith("{aux_command}WAGO_ValveCommands(")
+
+
+def test_gcode_uses_g1_for_print_and_g0_for_travel(tmp_path) -> None:
+    tiff_path = tmp_path / "slice_0000.tif"
+    Image.new("L", (1, 1), 0).save(tiff_path)
+
+    zip_path = tmp_path / "slices.zip"
+    with zipfile.ZipFile(zip_path, mode="w") as archive:
+        archive.write(tiff_path, arcname=tiff_path.name)
+
+    gcode_path = generate_snake_path_gcode(
+        zip_path,
+        shape_name="move_types",
+        pressure=25,
+        valve=7,
+        port=3,
+    )
+
+    move_lines = [
+        line.strip()
+        for line in gcode_path.read_text().splitlines()
+        if line.startswith(("G0", "G1"))
+    ]
+
+    assert any(line.startswith("G1") and "; Color 255" in line for line in move_lines)
+    assert all(not line.startswith("G0") for line in move_lines if "; Color 255" in line)
+    assert all(not line.startswith("G1") for line in move_lines if "; Color 0" in line)

tiff_to_gcode.py

@@ -0,0 +1,378 @@
+from __future__ import annotations
+
+import os
+import tempfile
+import zipfile
+from codecs import encode
+from pathlib import Path
+from textwrap import wrap
+
+import numpy as np
+from PIL import Image
+
+
+def _setpress(pressure: float) -> str:
+    pressure_str = str(int(pressure * 10)).zfill(4)
+    command_bytes = bytes("08PS  " + pressure_str, "utf-8")
+    hex_command = encode(command_bytes, "hex").decode("utf-8")
+    format_command = "\\x" + "\\x".join(
+        hex_command[i : i + 2] for i in range(0, len(hex_command), 2)
+    )
+
+    hex_pairs = wrap(hex_command, 2)
+    decimal_sum = sum(int(pair, 16) for pair in hex_pairs)
+    checksum_bin = bin(decimal_sum % 256)[2:].zfill(8)
+    inverted = int("".join("1" if c == "0" else "0" for c in checksum_bin), 2) + 1
+    checksum_hex = hex(inverted)[2:].upper()
+    format_checksum = "\\x" + "\\x".join(
+        checksum_hex[i : i + 2] for i in range(0, len(checksum_hex), 2)
+    )
+
+    return "b'" + "\\x05\\x02" + format_command + format_checksum + "\\x03" + "'"
+
+
+def _togglepress() -> str:
+    return "b'\\x05\\x02\\x30\\x34\\x44\\x49\\x20\\x20\\x43\\x46\\x03'"
+
+
+def _setpress_cmd(port: str, pressure: float, start: bool) -> str:
+    insert = "{preset}" if start else ""
+    return f"\n\r{insert}{port}.write({_setpress(pressure)})"
+
+
+def _toggle_cmd(port: str, start: bool) -> str:
+    insert = "{preset}" if start else ""
+    return f"\n\r{insert}{port}.write({_togglepress()})"
+
+
+def _valve_cmd(valve: int, command: int) -> str:
+    return f"\n{{aux_command}}WAGO_ValveCommands({valve}, {command})\n"
+
+
+def _gcode_layer(
+    path_img: np.ndarray,
+    color_img: np.ndarray,
+    output_list: list[dict],
+    pixel_size: float,
+    direction: int,
+    layer_number: int,
+) -> int:
+    mask = path_img > 0
+    first_nonblack = np.where(mask.any(axis=1), mask.argmax(axis=1), -1)
+    last_nonblack = np.where(
+        mask.any(axis=1),
+        mask.shape[1] - 1 - np.fliplr(mask).argmax(axis=1),
+        -1,
+    )
+
+    stored_gcode: list[dict] = []
+    nonblank_rows = np.where(first_nonblack != -1)[0]
+
+    for idx, i in enumerate(nonblank_rows):
+        f_idx, l_idx = int(first_nonblack[i]), int(last_nonblack[i])
+        if f_idx == -1:
+            continue
+
+        if direction < 0:
+            rng = range(f_idx, l_idx + 1)
+        else:
+            rng = range(l_idx, f_idx - 1, -1)
+        direction *= -1
+
+        prev_color = None
+        color_len = 0
+        buffer = direction
+        stored_gcode.append({"X": buffer * pixel_size, "Y": 0, "Color": 0})
+
+        for j in rng:
+            this_color = int(color_img[i, j])
+            if prev_color is None:
+                prev_color = this_color
+                color_len = 1
+            elif this_color == prev_color:
+                color_len += 1
+            else:
+                stored_gcode.append(
+                    {
+                        "X": direction * color_len * pixel_size,
+                        "Y": 0,
+                        "Color": prev_color,
+                    }
+                )
+                color_len = 1
+                prev_color = this_color
+
+        if color_len > 0:
+            stored_gcode.append(
+                {
+                    "X": direction * color_len * pixel_size,
+                    "Y": 0,
+                    "Color": prev_color,
+                }
+            )
+
+        stored_gcode.append({"X": buffer * pixel_size, "Y": 0, "Color": 0})
+
+        curr_x = l_idx if direction > 0 else f_idx
+        curr_x += buffer
+
+        if idx + 1 < len(nonblank_rows):
+            next_i = int(nonblank_rows[idx + 1])
+            y_travel_dist = next_i - int(i)
+            nf, nl = int(first_nonblack[next_i]), int(last_nonblack[next_i])
+            if nf == -1:
+                continue
+            next_start = nf if direction < 0 else nl
+            travel_x = (next_start + buffer) - curr_x
+            y_dir = -1 if layer_number % 2 == 1 else 1
+            stored_gcode.append(
+                {
+                    "X": travel_x * pixel_size,
+                    "Y": y_travel_dist * pixel_size * y_dir,
+                    "Color": 0,
+                }
+            )
+
+    output_list.extend(stored_gcode)
+    return direction
+
+
+def _sort_key(filename: str) -> int:
+    digits = "".join(filter(str.isdigit, filename))
+    return int(digits) if digits else 2**31
+
+
+def _extract_zip_tiffs(zip_path: Path, dest: Path) -> list[Path]:
+    with zipfile.ZipFile(zip_path) as archive:
+        archive.extractall(dest)
+
+    tiffs: list[Path] = []
+    for root, _, files in os.walk(dest):
+        for name in files:
+            if name.lower().endswith((".tif", ".tiff")):
+                tiffs.append(Path(root) / name)
+    tiffs.sort(key=lambda p: _sort_key(p.name))
+    return tiffs
+
+
+def _load_grayscale(path: Path, invert: bool) -> np.ndarray:
+    with Image.open(path) as image:
+        array = np.array(image.convert("L"), dtype=np.uint8)
+    if invert:
+        array = 255 - array
+    return array
+
+
+def _center_on_canvas(
+    img: np.ndarray, canvas_h: int, canvas_w: int, fill: int = 0
+) -> np.ndarray:
+    """Place `img` centred on a (canvas_h, canvas_w) canvas filled with `fill`.
+
+    Mirrors the centring used to build the reference stack, so a shape's slice
+    lines up pixel-for-pixel with the reference (motion) slice of the same layer.
+    """
+    h, w = img.shape[:2]
+    out = np.full((canvas_h, canvas_w), fill, dtype=img.dtype)
+    y_off = max(0, (canvas_h - h) // 2)
+    x_off = max(0, (canvas_w - w) // 2)
+    out[y_off : y_off + h, x_off : x_off + w] = img[: canvas_h, : canvas_w]
+    return out
+
+
+def generate_snake_path_gcode(
+    zip_path: str | Path,
+    shape_name: str,
+    pressure: float,
+    valve: int,
+    port: int,
+    layer_height: float = 0.8,
+    fil_width: float = 0.8,
+    invert: bool = True,
+    increase_pressure_per_layer: float = 0.1,
+    all_g1: bool = False,
+    motion_tiffs: list[str] | None = None,
+) -> Path:
+    zip_path = Path(zip_path)
+    if not zip_path.exists():
+        raise FileNotFoundError(f"ZIP file not found: {zip_path}")
+
+    work_dir = Path(tempfile.mkdtemp(prefix="tiff_gcode_"))
+    extract_dir = work_dir / "tiffs"
+    extract_dir.mkdir(parents=True, exist_ok=True)
+    tiff_files = _extract_zip_tiffs(zip_path, extract_dir)
+    if not tiff_files:
+        raise ValueError("No TIFF files found in the ZIP archive.")
+
+    off_color = 0
+    com_port = f"serialPort{port}"
+    color_dict: dict[int, int] = {0: 100, 255: valve}
+
+    # Two non-flipped source image lists. The "path" images drive the nozzle
+    # motion (which rows are swept, the sweep extent, the inter-layer shifts);
+    # the "color" images decide the valve state (material) at each swept pixel.
+    # Normally both are this shape's own slices. When reference motion tiffs are
+    # supplied, motion comes from the combined reference stack while the valve is
+    # still driven by this shape's slices, centred onto the reference canvas — so
+    # parallel heads share one motion path but each dispenses only its geometry.
+    shape_imgs = [_load_grayscale(p, invert=invert) for p in tiff_files]
+
+    if motion_tiffs:
+        motion_paths = sorted(
+            (Path(p) for p in motion_tiffs), key=lambda p: _sort_key(p.name)
+        )
+        path_ref_list = [_load_grayscale(p, invert=invert) for p in motion_paths]
+        if not path_ref_list:
+            raise ValueError("No reference TIFF files provided for motion.")
+        color_ref_list: list[np.ndarray] = []
+        for li, motion_img in enumerate(path_ref_list):
+            h_c, w_c = motion_img.shape[:2]
+            if li < len(shape_imgs):
+                color_ref_list.append(
+                    _center_on_canvas(shape_imgs[li], h_c, w_c, fill=off_color)
+                )
+            else:
+                # Reference is taller than this shape: move but dispense nothing.
+                color_ref_list.append(np.full((h_c, w_c), off_color, dtype=np.uint8))
+    else:
+        path_ref_list = [im.copy() for im in shape_imgs]
+        color_ref_list = [im.copy() for im in shape_imgs]
+
+    setpress_lines = [_setpress_cmd(com_port, pressure, start=True)]
+    pressure_on_lines = [_toggle_cmd(com_port, start=True)]
+    pressure_off_lines = [_toggle_cmd(com_port, start=False)]
+
+    gcode_list: list[dict] = []
+    dist_sign_long = 1
+    current_offsets_x: list[int] = []
+    use_flip_y = False
+    direction = -1
+
+    for layers in range(len(path_ref_list)):
+        current_image_ref = path_ref_list[layers]
+        last_image_ref = path_ref_list[layers - 1] if layers > 0 else None
+        y_ref = current_image_ref.shape[0]
+
+        def find_first_valid_y(row: np.ndarray | None, flip: bool = False) -> int | None:
+            if row is None:
+                return None
+            row_data = np.flip(row) if flip else row
+            for j, pixel in enumerate(row_data):
+                if np.any(pixel) != off_color:
+                    return y_ref - 1 - j if flip else j
+            return None
+
+        last_x = last_y = None
+        if current_offsets_x:
+            use_flip_x = layers % 2 == 1
+            last_x = current_offsets_x[-1] if use_flip_x else current_offsets_x[0]
+            last_row = (
+                last_image_ref[last_x] if last_image_ref is not None else None
+            )
+            last_y = find_first_valid_y(last_row, flip=use_flip_y)
+            current_offsets_x.clear()
+
+        current_offsets_x = [
+            i for i, row in enumerate(current_image_ref) if np.any(row) != off_color
+        ]
+
+        first_x = first_y = None
+        if current_offsets_x:
+            use_flip_x = layers % 2 == 1
+            first_x = current_offsets_x[-1] if use_flip_x else current_offsets_x[0]
+            first_row = current_image_ref[first_x]
+            first_y = find_first_valid_y(first_row, flip=use_flip_y)
+
+        if None in (last_x, last_y, first_x, first_y):
+            shift_x = shift_y = 0
+        else:
+            shift_x = (first_x - last_x) * fil_width
+            shift_y = (first_y - last_y) * fil_width * dist_sign_long
+            if use_flip_y:
+                shift_y = -shift_y
+
+        if len(current_offsets_x) % 2 == 1:
+            use_flip_y = not use_flip_y
+
+        if layers > 0:
+            gcode_list.append(
+                {"X": shift_y, "Y": shift_x, "Z": layer_height, "Color": 0}
+            )
+
+        for row in current_image_ref:
+            if all(p == off_color for p in row):
+                dist_sign_long = -dist_sign_long
+            dist_sign_long = -dist_sign_long
+
+        # Flip path and color together on even layers so they stay aligned.
+        even_layer = (layers + 1) % 2 == 0
+        ref_for_path = (
+            np.flipud(current_image_ref) if even_layer else current_image_ref.copy()
+        )
+        current_image = (
+            np.flipud(color_ref_list[layers]) if even_layer else color_ref_list[layers]
+        )
+
+        if layers == 0:
+            direction = -1
+        direction = _gcode_layer(
+            ref_for_path,
+            current_image,
+            gcode_list,
+            fil_width,
+            direction,
+            layers,
+        )
+
+    gcode_path = work_dir / f"{shape_name}_SnakePath_gcode.txt"
+    pressure_cur = float(pressure)
+
+    with open(gcode_path, "w") as f:
+        f.write("G91\n")
+        for line in setpress_lines:
+            f.write(f"{line}\n")
+        for line in pressure_on_lines:
+            f.write(f"{line}\n")
+        for color in color_dict:
+            f.write(_valve_cmd(color_dict[color], 0))
+
+        pressure_next: str | None = None
+        for i, move in enumerate(gcode_list):
+            prev_color = gcode_list[i - 1]["Color"] if i > 0 else 0
+            cur_color = move["Color"]
+            if prev_color != cur_color:
+                if cur_color == off_color:
+                    f.write(_valve_cmd(color_dict[prev_color], 0))
+                else:
+                    if prev_color == off_color:
+                        f.write(_valve_cmd(color_dict[cur_color], 1))
+                    else:
+                        f.write(_valve_cmd(color_dict[cur_color], 1))
+                        f.write(_valve_cmd(color_dict[prev_color], 0))
+
+            # When all_g1 is set, every move is emitted as G1 regardless of
+            # valve state; the valve commands still mark print vs travel.
+            move_type = "G1" if (all_g1 or cur_color != off_color) else "G0"
+            if "Z" in move:
+                line = (
+                    f"{move_type} X{move['X']} Y{move['Y']} Z{move['Z']} "
+                    f"; Color {move['Color']}"
+                )
+                pressure_cur += increase_pressure_per_layer
+                pressure_next = _setpress_cmd(com_port, pressure_cur, start=False)
+            else:
+                line = (
+                    f"{move_type} X{move['X']} Y{move['Y']} ; Color {move['Color']}"
+                )
+                pressure_next = None
+
+            f.write(f"{line}\n")
+            if pressure_next is not None:
+                f.write(f"{pressure_next}\n")
+                pressure_next = None
+
+        for color in color_dict:
+            f.write(_valve_cmd(color_dict[color], 0))
+        for line in pressure_off_lines:
+            f.write(f"{line}\n")
+
+    return gcode_path