Document parallel print, GIF export, and dependency workflow

Update README for the line/tube visualization modes, Shape 1/2/3
source selection, the G1/Reference-motion generation toggles, valve-
based print/travel classification, and the Parallel Printing tab with
its Matplotlib GIF export. Add AGENTS notes on regenerating
requirements.txt after dependency changes and the CPU-only (Agg/Pillow)
rendering constraint for Hugging Face.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

AGENTS.md

@@ -15,6 +15,22 @@
 - `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`)

README.md

@@ -10,7 +10,7 @@ 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, and lets you preview the resulting tool path.
+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
 
@@ -48,7 +48,11 @@ Then open the local Gradio URL in your browser, upload STL files or load the bun
 - 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
-- Visualizes generated or uploaded G-code tool paths
+- 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
 
@@ -73,14 +77,36 @@ When you click **Generate Reference TIFF Stack**, the app combines available TIF
 - 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 can render either the generated Shape 1 G-code or an uploaded `.txt`, `.gcode`, or `.nc` file. It parses `G0` and `G1` movement lines, supports relative (`G91`) and absolute (`G90`) positioning, and displays travel and print segments with separate colors and opacity controls.
+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
 
-When dependencies change, update the lockfile and refresh the Hugging Face `requirements.txt` export:
+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