Add multi-material assemblies, fix slicing of multi-body STLs, improve circle spiral

Multi-material printing (STLs sharing a nozzle number):
- Shapes on one nozzle are detected as one assembly: sliced on a shared
Z grid (empty lower layers for parts that start higher) and aligned as
one rigid unit at their modeled positions via a shared group frame
- Contour tracing skips material-to-material interfaces (within half a
bead, covering fit-tolerance gaps) - only the assembly's true outer
surface is traced, like split-piece seam exclusion
- Multi-Nozzle Split treats a group as one shape: all materials clipped
by the same cell grid, cell-mates share a nozzle, each piece keeps its
own valve; split source dropdown warns before a group split

Slicer fixes for multi-body STLs (Maryland flag, checkerboard cubes):
- Watertight bodies slice per-body and union (interpenetrating stripe
prisms no longer XOR into holes); inverted bodies subtract as cavities
- Non-watertight fragments section together as one remainder mesh, so
shredded topology (T-vertices) still reconstructs whole rings
- Ring composition uses containment depth (polygons_full, new rtree dep)

Circle spiral raster:
- Rings live on one global radii grid anchored at the frame centre, so
walls stack across layers instead of aliasing wider on higher layers
- Outermost revolution is a perimeter wall hugging the material edge
(smooth silhouette); rings that cannot touch material are skipped
(halfsphere travel dropped to ~3% of path length)

UI:
- In-table color dropdown works: Color cells swallow pointer events
before the dataframe opens its raw-HTML cell editor (which was killing
the native popup); picks relay through a hidden sink/apply pair
- Yellow and White added to the palette
- G-code visualization filament widths follow the slicer's Filament/Line
Width instead of the layer height

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

README.md

@@ -45,6 +45,7 @@ Then open the local Gradio URL in your browser, upload STL files or load the bun
 - Scales loaded STLs from editable target X/Y/Z dimensions in the Shape Settings table; new rows default to the STL's original dimensions, **Reset Dimensions** restores them, and **Keep Proportions** updates the other target sides from the edited side
 - Lets you choose layer height and filament/line width
 - Slices each shape into per-layer vector outlines held in memory (no intermediate image files)
+- Shapes that share a **nozzle number** are treated automatically as one multi-material assembly: sliced on one shared Z grid and kept exactly where they were modeled, while shapes alone on their nozzle behave as ordinary independent parts
 - Automatically unions the sliced shapes into a combined reference layer set whenever shapes are sliced
 - Splits one sliced shape's geometry into an editable row/column grid for multi-nozzle printing of one large shape
 - Converts sliced layers into G-code files with pressure, valve, nozzle, port, and infill % settings per shape from the Shape Settings table
@@ -57,6 +58,7 @@ Then open the local Gradio URL in your browser, upload STL files or load the bun
 - Visualizes generated or uploaded G-code tool paths, with the source selectable from any active generated shape 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 the generated shapes using the configured nozzle spacing and animates them printing in parallel, with a server-side GIF export of that animation
+- Each shape's plot color is set with one click on a palette chip embedded in the Shape Settings **Color** column (Orange, Blue, Green, Red, Purple, Pink, Teal, Yellow, White, Black) — the cell shows the current color's name and highlights its chip
 
 ## Behavior and Implementation Notes
 
@@ -71,6 +73,18 @@ When you click **Slice Shapes**, the app automatically unions the sliced shapes
 - Shapes are aligned by centering each shape's XY bounding box on a common center before the union.
 - Alignment is centered placement (in exact millimetres), not bottom-left anchoring.
 
+### Multi-Material Assemblies (shared nozzle numbers)
+
+For a multi-material object exported as separate STLs (one per material), give every part the **same nozzle number** in Shape Settings — parts sharing a nozzle print from the same physical position, so the app treats them automatically as one assembly:
+
+- Group members are sliced on **one shared Z grid** spanning the whole assembly, so a part that starts higher in the model simply has empty lower layers — it travels the shared path but dispenses nothing until the print reaches its height.
+- The group is aligned into the reference union as **one rigid unit**: each part keeps exactly the position it was modeled at relative to the others, so asymmetric assemblies line up the way they do in the 3D preview.
+- Shapes alone on their nozzle keep the normal behavior (centered onto the common reference), so regular shapes and multi-material assemblies can print together in one job.
+- **Contour Tracing** on assembly parts outlines only the assembly's true outer surface: edges where one material meets (or nearly meets, within half a bead — fit tolerances included) another material are internal interfaces and are skipped, exactly like the cut seams of grid-split pieces.
+- Combine with **Use combined reference outline for motion** so all heads share one synchronized path while each dispenses only its own part.
+- Nozzle renumbering in the table takes effect on the next slice or G-code generation — groups are re-detected automatically.
+- Leave assembly parts' target dimensions at their defaults (or scale every part identically); parts are scaled about their own corners, so unequal scaling would misalign an assembly.
+
 ### Multi-Nozzle Split
 
 The **Multi-Nozzle Split** accordion on the **Shapes & Slicing** tab can split one sliced shape into a grid of print-ready piece stacks. Choose a source shape that has been sliced, set the number of columns and rows, choose the starting nozzle and valve numbers, then click **Split Selected Shape into Grid Pieces**.
@@ -79,6 +93,7 @@ The **Multi-Nozzle Split** accordion on the **Shapes & Slicing** tab can split o
 - The selected shape is replaced in Shape Settings by one generated record per grid cell, named by row and column.
 - Nozzle and valve numbers are assigned sequentially from the starting values, and the **Generate G-Code** tab can generate separate G-code for each piece.
 - **Overlapping Layers** alternates the interior cut lines by one filament width per layer so neighbouring pieces interlock.
+- **Multi-material assemblies split as one shape**: if the selected shape shares its nozzle with other shapes, the whole group is split together — every material is clipped by the same cell grid over the group's combined bounds. Pieces are emitted cell by cell: each cell's pieces share a nozzle (so every cell is itself a multi-material group, keeping the alignment and seam-free contour behavior), each piece gets its own valve, and cells where a material has no geometry are skipped. Auto Align works on the result like any other split.
 
 ### G-code XY Step Size
 
@@ -95,9 +110,9 @@ The **Multi-Nozzle Split** accordion on the **Shapes & Slicing** tab can split o
 - **Lead In**: enabled per shape via the **Lead In** column in Shape Settings; the Lead In Options accordion on the Generate G-Code tab sets the patch geometry. Prints a purge patch before layer 1, in a selectable direction (Left/Right/Up/Down) at the configured clearance from the start point. The return route exits the patch laterally and comes home through the clearance lane, so the primed nozzle never drags back across the wet purge lines. For grid-split pieces the clearance is automatically extended by the assembly's remaining extent along the purge axis (reported in the G-code status), so under shared reference motion every nozzle's purge patch lands clear of the whole assembled part instead of on a neighbor's print area. The **Lead In** column in Shape Settings controls dispensing per shape: an opted-out head still travels the shared patch (keeping parallel heads in sync) but keeps its valve shut, and skips the lead-in moves entirely when printing without shared motion.
 - **Use combined reference outline for motion**: when enabled, every shape's *motion* is taken from the combined reference layer union while each shape's *valve/dispensing* comes from its own layer polygons — so parallel print heads share one synchronized nozzle path and each deposits only its own geometry. The reference union is rebuilt automatically when shapes are sliced. Contour tracing stays synchronized too: every shape traces every traced shape's contour, opening its valve only on its own outline.
 - Every generated file starts with a `; PathOrigin X.. Y..` comment: the world position (in the shape's own frame) that the relative toolpath starts from. Tools use it to place parallel parts so split pieces reassemble.
-- **Raster Pattern**: `X-direction raster` sweeps every layer back-and-forth in X. `Y-direction raster` rasters every layer in Y. `90° Woodpile raster` alternates the raster axis by layer, switching between X-direction and Y-direction sweeps. `45° Woodpile raster` rotates the sweep 45 degrees per layer, cycling 0, 45, 90, 135 degrees. `Rectangular Spiral raster` walks each layer from the outer layer bounds toward the center, then reverses from center to edge on the next layer. `Circle Spiral raster` prints concentric circles from the layer bounds toward the center — each revolution stays at a constant radius and steps inward by one line width between revolutions, so the walls are smooth true circles — then reverses outward on the next layer. Spiral motion covers the layer bounds; the valve opens only where the path is inside material.
+- **Raster Pattern**: `X-direction raster` sweeps every layer back-and-forth in X. `Y-direction raster` rasters every layer in Y. `90° Woodpile raster` alternates the raster axis by layer, switching between X-direction and Y-direction sweeps. `45° Woodpile raster` rotates the sweep 45 degrees per layer, cycling 0, 45, 90, 135 degrees. `Rectangular Spiral raster` walks each layer from the outer layer bounds toward the center, then reverses from center to edge on the next layer. `Circle Spiral raster` prints concentric circles stepping inward by one line width per revolution — each revolution stays at a constant radius, so the walls are smooth true circles — then reverses outward on the next layer. The outermost revolution is a perimeter wall hugging the layer's material edge (half a bead inside its farthest boundary point), so the printed silhouette follows the shape smoothly; a matching inner wall hugs a central hole when there is one. The fill rings between the walls come from one global radii grid anchored at the shape frame's center, so interior rings stack exactly across layers, and rings that cannot touch a layer's material (or would overlap a wall bead) are skipped instead of traveled. Walls always dispense even under partial infill, like contour tracing; elsewhere the valve opens only where the path is inside material.
 - **Auto Align Split Parts**: in Nozzle Spacing, computes exact per-connection grid gaps from the split pieces' generated G-code (`PathOrigin` anchors + toolpath bounds), sets the grid columns/rows from the split, and fills the Advanced Grid Spacing table. Works for every raster pattern, filament width, reference-motion setting, and overlapping-layer split. Requires the pieces' G-code to be generated first.
-- **Contour Tracing**: enabled per row in Shape Settings. The app traces the layer polygon's boundary rings (holes traced separately), travels from the layer raster end to the nearest contour point, prints the contour, then returns to the raster endpoint before the next layer. For grid-split pieces only the parent shape's true outer surface is traced — the cut seams between sibling pieces are excluded (open arcs are printed end-to-end without closing the loop; fully interior pieces get no contour).
+- **Contour Tracing**: enabled per row in Shape Settings. The app traces the layer polygon's boundary rings (holes traced separately), travels from the layer raster end to the nearest contour point, prints the contour, then returns to the raster endpoint before the next layer. For grid-split pieces only the parent shape's true outer surface is traced — the cut seams between sibling pieces are excluded (open arcs are printed end-to-end without closing the loop; fully interior pieces get no contour). Multi-material assembly parts (shapes sharing a nozzle) work the same way: boundary within half a bead of a sibling material counts as an internal interface and is not contoured — only the assembled shape's true outer surface is traced, and a part fully embedded in the assembly gets no contour at all.
 
 ### Print vs Travel Classification
 
@@ -113,7 +128,7 @@ The parser also handles standard slicer G-code: single-axis and Z-only moves, ax
 The G-code visualization tab renders generated shape 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.
+- **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 automatically follow the slicer's Filament/Line Width and its quarter.
 
 ### Parallel Printing Visualization
 

app.py

@@ -30,6 +30,7 @@ from gcode_viewer import (
 )
 from stl_slicer import (
     LayerStack,
+    calculate_z_levels,
     load_mesh,
     scale_factors_for_target_extents,
     scale_mesh,
@@ -44,6 +45,7 @@ from vector_toolpath import (
     RASTER_PATTERN_Y_DIRECTION,
     ContourSource,
     build_reference_stack,
+    group_contour_paths,
     split_layer_stack_grid,
 )
 
@@ -69,6 +71,56 @@ NOZZLE_LAYOUT_PRESETS = [
     "5 x 2",
 ]
 APP_CSS = """
+.pp-visually-hidden {
+    position: absolute !important;
+    width: 1px !important;
+    height: 1px !important;
+    min-width: 0 !important;
+    min-height: 0 !important;
+    padding: 0 !important;
+    margin: -1px !important;
+    border: 0 !important;
+    overflow: hidden !important;
+    clip-path: inset(50%);
+}
+.pp-color-cell {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    min-width: 170px;
+}
+.pp-color-current {
+    display: inline-block;
+    min-width: 46px;
+    padding: 1px 5px;
+    border: 1px solid rgba(0, 0, 0, 0.25);
+    border-radius: 4px;
+    font-size: 0.75em;
+    text-align: center;
+    white-space: nowrap;
+}
+.pp-swatches {
+    display: inline-flex;
+    gap: 3px;
+    align-items: center;
+}
+.pp-swatch {
+    display: inline-block;
+    width: 13px;
+    height: 13px;
+    border: 1px solid rgba(0, 0, 0, 0.35);
+    border-radius: 3px;
+    cursor: pointer;
+    box-sizing: border-box;
+}
+.pp-swatch:hover {
+    transform: scale(1.3);
+}
+.pp-swatch.pp-current {
+    outline: 2px solid var(--color-accent, #f97316);
+    outline-offset: 1px;
+}
+
 .gradio-container {
     font-size: 90%;
     padding-top: 0.5rem !important;
@@ -319,6 +371,39 @@ APP_CSS = """
 APP_HEAD = """
 <script>
 (function () {
+    function relayColorChoice(rowIdx, hex) {
+        var sink = document.querySelector('#pp-color-sink textarea, #pp-color-sink input');
+        var apply = document.querySelector('#pp-color-apply button, button#pp-color-apply, #pp-color-apply');
+        if (!sink || !apply) return;
+        sink.value = rowIdx + '|' + hex;
+        sink.dispatchEvent(new Event('input', { bubbles: true }));
+        if (apply.tagName !== 'BUTTON') { apply = apply.querySelector('button') || apply; }
+        apply.click();
+    }
+    // In-table color dropdowns: relay each select's pick to the hidden sink
+    // textbox + apply button so the backend updates the shape record. The
+    // native popup survives because Color cells' pointer events are
+    // swallowed before the dataframe can open its cell editor (see
+    // isolateColorCell below).
+    document.addEventListener('change', function (event) {
+        var el = event.target;
+        if (!el || !el.classList || !el.classList.contains('pp-color-select')) return;
+        var match = (el.className || '').match(/pp-idx-([0-9]+)/);
+        if (!match) return;
+        relayColorChoice(match[1], el.value);
+    }, true);
+    // In-table color swatches (if a cell renders palette chips instead):
+    // clicking a chip relays "rowIdx|#hex" the same way.
+    document.addEventListener('click', function (event) {
+        var el = event.target;
+        if (!el || !el.classList || !el.classList.contains('pp-swatch')) return;
+        var idxMatch = (el.className || '').match(/pp-idx-([0-9]+)/);
+        var hexMatch = (el.className || '').match(/pp-hex-([0-9a-fA-F]{6})/);
+        if (!idxMatch || !hexMatch) return;
+        event.preventDefault();
+        event.stopPropagation();
+        relayColorChoice(idxMatch[1], '#' + hexMatch[1].toLowerCase());
+    }, true);
     function enableUndoButtons(root) {
         (root || document).querySelectorAll('.model3D button[aria-label="Undo"]').forEach(function (btn) {
             if (btn.disabled) {
@@ -335,9 +420,29 @@ APP_HEAD = """
             }
         }, 0);
     }
+    // Color cells host clickable palette chips: swallow pointer events before
+    // the dataframe's own handlers run, or a click would select the cell and
+    // open the raw-HTML cell editor on top of the chips.
+    function isolateColorCell(event) {
+        var el = event.target;
+        if (!el || !el.closest) return;
+        var cell = el.closest('td, [role="gridcell"]');
+        if (!cell || !cell.querySelector('.pp-color-cell')) return;
+        event.stopPropagation();
+        if (event.type === 'dblclick') {
+            event.preventDefault();
+        }
+    }
     function start() {
         enableUndoButtons();
         document.addEventListener('focusin', suppressDeleteCellEditor);
+        document.addEventListener('pointerdown', isolateColorCell, true);
+        document.addEventListener('mousedown', isolateColorCell, true);
+        document.addEventListener('touchstart', isolateColorCell, true);
+        document.addEventListener('dblclick', isolateColorCell, true);
+        // 'click' too: registered AFTER the swatch relay above, so the chip
+        // click is applied first, then the dataframe never sees the event.
+        document.addEventListener('click', isolateColorCell, true);
         var observer = new MutationObserver(function (mutations) {
             for (var i = 0; i < mutations.length; i++) {
                 var m = mutations[i];
@@ -1154,7 +1259,8 @@ GCODE_SOURCE_UPLOAD = "Upload G-Code file"
 PARALLEL_COLOR_CHOICES = [
     ("Orange", "#ff7f0e"), ("Blue", "#1f77b4"), ("Green", "#2ca02c"),
     ("Red", "#d62728"), ("Purple", "#9467bd"), ("Pink", "#e377c2"),
-    ("Teal", "#17becf"), ("Black", "#000000"),
+    ("Teal", "#17becf"), ("Yellow", "#ffe119"), ("White", "#ffffff"),
+    ("Black", "#000000"),
 ]
 DEFAULT_PARALLEL_COLORS = ("#ff7f0e", "#1f77b4", "#2ca02c")
 SHAPE_COLOR_NAMES = [name for name, _hex in PARALLEL_COLOR_CHOICES]
@@ -1168,6 +1274,62 @@ def _color_display(value: str | None) -> str:
     return _COLOR_NAME_BY_HEX.get(text.lower(), text)
 
 
+def apply_color_selection(
+    records: list[dict] | None,
+    settings_table: Any,
+    payload: str | None,
+) -> tuple[list[dict], list[list[Any]]]:
+    """Apply an in-table color dropdown change ("idx|#hex" from the sink)."""
+    records = _apply_shape_settings(records or [], settings_table)
+    parts = str(payload or "").split("|")
+    if len(parts) >= 2:
+        try:
+            idx = int(parts[0])
+        except (TypeError, ValueError):
+            idx = None
+        hex_value = parts[1].strip().lower()
+        palette = {value.lower() for _name, value in PARALLEL_COLOR_CHOICES}
+        if idx is not None and hex_value in palette:
+            records = [
+                dict(record, color=hex_value)
+                if int(record.get("idx", 0) or 0) == idx
+                else record
+                for record in records
+            ]
+    return records, _shape_settings_rows(records)
+
+
+def _color_select_cell(record: dict) -> str:
+    """HTML dropdown for a shape's Color cell (markdown-rendered).
+
+    The select carries the record idx as a sanitizer-safe class token; a
+    delegated head-script change listener relays picks to the hidden
+    sink/apply pair, which updates the record and re-renders the table. The
+    closed select shows the current color as its background. Works because
+    the head script also swallows pointer events on Color cells before the
+    dataframe's handlers run — otherwise the cell editor would open on
+    mousedown and kill the native dropdown popup.
+    """
+    idx = int(record.get("idx", 0) or 0)
+    current = str(record.get("color", _default_color(idx))).strip().lower()
+    options = "".join(
+        '<option value="{hex}"{sel}>{name}</option>'.format(
+            hex=hex_value,
+            sel=" selected" if hex_value.lower() == current else "",
+            name=name,
+        )
+        for name, hex_value in PARALLEL_COLOR_CHOICES
+    )
+    text_color = "#ffffff" if current in ("#000000",) else "#000000"
+    return (
+        '<span class="pp-color-cell">'
+        '<select class="pp-color-select pp-idx-{idx}" '
+        'style="background-color:{bg};color:{fg}">{options}</select>'
+        "</span>"
+    ).format(idx=idx, bg=current if current.startswith("#") else "#ffffff",
+             fg=text_color, options=options)
+
+
 def _color_from_cell(cell, fallback: str) -> str:
     """Parse a Color cell: palette name (case-insensitive) or a hex value.
 
@@ -1403,7 +1565,7 @@ SHAPE_SETTINGS_DATATYPES = [
     "number",
     "number",
     "number",
-    "str",
+    "markdown",
     "number",
     "bool",
     "bool",
@@ -1584,7 +1746,7 @@ def _shape_settings_rows(records: list[dict]) -> list[list[Any]]:
             record.get("valve", 4),
             _record_nozzle_number(record, int(record["idx"])),
             record.get("port", 1),
-            _color_display(record.get("color", _default_color(record["idx"]))),
+            _color_select_cell(record),
             _coerce_float(record.get("infill", 100.0), 100.0),
             bool(record.get("contour_tracing", False)),
             bool(record.get("lead_in", False)),
@@ -2249,21 +2411,129 @@ def show_selected_model(
     )
 
 
-def _slice_params_snapshot(record: dict, layer_height: float, scale_mode: str | None) -> dict:
+def _slice_params_snapshot(
+    record: dict,
+    layer_height: float,
+    scale_mode: str | None,
+    z_levels: list[float] | None = None,
+) -> dict:
     return {
         "layer_height": float(layer_height),
         "scale_mode": _normalize_scale_mode(scale_mode),
         "target_x": record.get("target_x"),
         "target_y": record.get("target_y"),
         "target_z": record.get("target_z"),
+        # Multi-material mode: the shared Z grid fingerprint. Adding/removing
+        # an assembly part changes the grid, which correctly marks every
+        # part's slices stale.
+        "z_grid": (round(z_levels[0], 6), len(z_levels)) if z_levels else None,
     }
 
 
+def _multi_material_groups(records: list[dict]) -> dict[int, list[dict]]:
+    """Multi-material groups: uploaded shapes that share a nozzle number.
+
+    Shapes on the same nozzle print from the same physical position, so
+    their STLs are parts of one assembly (one STL per material). They must
+    slice on one shared Z grid and keep their modelled positions relative to
+    each other. Shapes alone on their nozzle stay ordinary. Split pieces
+    (no stl_path) are excluded — they carry their own frame alignment.
+    """
+    by_nozzle: dict[int, list[dict]] = {}
+    for record in records:
+        if not record.get("stl_path"):
+            continue
+        nozzle = _record_nozzle_number(record, int(record.get("idx", 1) or 1))
+        by_nozzle.setdefault(nozzle, []).append(record)
+    return {nozzle: members for nozzle, members in by_nozzle.items() if len(members) > 1}
+
+
+def _stamp_multi_material_frames(records: list[dict], fil_width: float = 0.8) -> None:
+    """Stamp each sliced stack's multi-material group frame and seam-free
+    contour paths (or clear them).
+
+    Group members get the group's combined XY bbox as `align_frame`, so the
+    reference alignment moves them as one rigid unit, and `contour_paths`
+    that exclude material-to-material interfaces — the assembled parts form
+    ONE shape, so only its true outer surface is contoured (boundary within
+    half a bead of a sibling material counts as an interface, covering both
+    exact contact and fit-tolerance gaps). Idempotent — safe to call before
+    every reference build so nozzle renumbering in the table takes effect
+    without re-slicing.
+    """
+    grouped_ids: set[int] = set()
+    for members in _multi_material_groups(records).values():
+        stacks = [
+            member.get("layer_stack")
+            for member in members
+            if member.get("layer_stack") is not None
+        ]
+        if len(stacks) < 2:
+            continue
+        frame = (
+            min(stack.bounds[0][0] for stack in stacks),
+            min(stack.bounds[0][1] for stack in stacks),
+            max(stack.bounds[1][0] for stack in stacks),
+            max(stack.bounds[1][1] for stack in stacks),
+        )
+        for stack in stacks:
+            stack.align_frame = frame
+            stack.contour_paths = group_contour_paths(
+                stack,
+                [other for other in stacks if other is not stack],
+                tolerance=float(fil_width or 0.8) / 2.0,
+            )
+            grouped_ids.add(id(stack))
+    for record in records:
+        stack = record.get("layer_stack")
+        if stack is not None and id(stack) not in grouped_ids and record.get("stl_path"):
+            stack.align_frame = None
+            stack.contour_paths = None
+
+
+def _multi_material_z_levels(
+    records: list[dict],
+    layer_height: float,
+    scale_mode: str | None,
+) -> list[float] | None:
+    """One shared Z grid spanning the given parts' scaled extents.
+
+    Multi-material group members must slice on the SAME planes so a part
+    that starts higher gets empty lower layers instead of having its first
+    material layer treated as layer 0.
+    """
+    z_lo = math.inf
+    z_hi = -math.inf
+    for record in records:
+        stl_path = record.get("stl_path")
+        if not stl_path:
+            continue
+        try:
+            mesh = load_mesh(stl_path)
+            scale_factors = _resolve_mesh_scale_factors(
+                mesh,
+                True,
+                scale_mode,
+                record.get("target_x"),
+                record.get("target_y"),
+                record.get("target_z"),
+            )
+            scaled = scale_mesh(mesh, scale_factors)
+        except Exception:
+            continue
+        z_lo = min(z_lo, float(scaled.bounds[0][2]))
+        z_hi = max(z_hi, float(scaled.bounds[1][2]))
+    if not math.isfinite(z_lo) or not math.isfinite(z_hi):
+        return None
+    return calculate_z_levels(z_lo, z_hi, float(layer_height))
+
+
 def _slice_record(
     record: dict,
     layer_height: float,
     scale_mode: str | None,
     progress_callback=None,
+    z_levels: list[float] | None = None,
 ) -> LayerStack:
     stl_path = record["stl_path"]
     mesh = load_mesh(stl_path)
@@ -2281,12 +2551,36 @@ def _slice_record(
         progress_callback=progress_callback,
         scale_factors=scale_factors,
         name=str(record.get("name") or Path(stl_path).stem),
+        z_levels=z_levels,
     )
     record["layer_stack"] = stack
-    record["slice_params"] = _slice_params_snapshot(record, layer_height, scale_mode)
+    record["slice_params"] = _slice_params_snapshot(record, layer_height, scale_mode, z_levels)
     return stack
 
 
+def _group_z_levels_by_record(
+    records: list[dict],
+    layer_height: float,
+    scale_mode: str | None,
+    messages: list[str] | None = None,
+) -> dict[int, list[float]]:
+    """Shared Z grid per multi-material group, keyed by member record id."""
+    z_by_record: dict[int, list[float]] = {}
+    for nozzle, members in sorted(_multi_material_groups(records).items()):
+        z_levels = _multi_material_z_levels(members, layer_height, scale_mode)
+        if z_levels is None:
+            continue
+        for member in members:
+            z_by_record[id(member)] = z_levels
+        if messages is not None:
+            names = ", ".join(str(m.get("name") or f"Shape {m['idx']}") for m in members)
+            messages.append(
+                f"Multi-material group (nozzle {nozzle}): {names} — sliced on one "
+                f"shared Z grid ({len(z_levels)} layers), positions locked together."
+            )
+    return z_by_record
+
+
 def generate_dynamic_layer_stacks(
     records: list[dict] | None,
     settings_table: Any,
@@ -2300,6 +2594,7 @@ def generate_dynamic_layer_stacks(
         return records, "Upload at least one STL first.", None
     total = len(records)
     messages: list[str] = []
+    z_by_record = _group_z_levels_by_record(records, layer_height, scale_mode, messages)
     for pos, record in enumerate(records):
         stl_path = record.get("stl_path")
         if not stl_path:
@@ -2313,7 +2608,9 @@ def generate_dynamic_layer_stacks(
             progress((offset + cur / tot) / total, desc=f"Slicing shape {offset + 1} of {total}...")
 
         try:
-            stack = _slice_record(record, layer_height, scale_mode, report_progress)
+            stack = _slice_record(
+                record, layer_height, scale_mode, report_progress, z_by_record.get(id(record))
+            )
             (x_min, y_min, _z_min), (x_max, y_max, _z_max) = stack.bounds
             messages.append(
                 f"Shape {record['idx']}: sliced {len(stack.layers)} layers "
@@ -2335,12 +2632,184 @@ def generate_dynamic_reference_stack(
 ) -> LayerStack | None:
     # Snapping the alignment to the fil grid keeps split pieces' scan-grid
     # phase intact under shared reference motion (exact one-fil seam pitch).
+    # Shapes sharing a nozzle are multi-material assembly parts: their group
+    # frame makes them align as one rigid unit at their modeled positions.
+    records = records or []
+    _stamp_multi_material_frames(records, fil_width)
     return build_reference_stack(
-        [record.get("layer_stack") for record in (records or [])],
+        [record.get("layer_stack") for record in records],
         grid=float(fil_width) if fil_width else None,
     )
 
 
+SPLIT_STATUS_DEFAULT = (
+    "Slice a shape, then split it for multi-nozzle printing. Shapes that share "
+    "a nozzle number are one multi-material assembly: selecting any of them "
+    "splits the **whole group** together as one shape."
+)
+
+
+def describe_split_source(records: list[dict] | None, selected: str | None) -> str:
+    """Split-source note: warn up front when the selection splits a whole group."""
+    records = records or []
+    pos = _selected_record_index(records, selected)
+    if pos < 0 or pos >= len(records):
+        return SPLIT_STATUS_DEFAULT
+    source = records[pos]
+    if not source.get("stl_path"):
+        return SPLIT_STATUS_DEFAULT
+    nozzle = _record_nozzle_number(source, int(source.get("idx", pos + 1) or (pos + 1)))
+    members = _multi_material_groups(records).get(nozzle, [])
+    if len(members) <= 1:
+        return SPLIT_STATUS_DEFAULT
+    names = ", ".join(
+        "**{}**".format(member.get("name") or f"Shape {member.get('idx')}")
+        for member in members
+    )
+    return (
+        f"⚠️ This shape is part of the multi-material group on nozzle {nozzle} "
+        f"({names}). Splitting it splits the **whole group as one shape**: every "
+        "material is clipped by the same cells, each cell's pieces share a nozzle, "
+        "and every piece gets its own valve."
+    )
+
+
+def _split_group_records(
+    records: list[dict],
+    group_members: list[dict],
+    group_nozzle: int,
+    split_column_count: int,
+    split_row_count: int,
+    overlapping_layers: bool,
+    starting_nozzle: Any,
+    starting_valve: Any,
+    fil_width: float,
+    selected: str | None,
+    _outputs,
+) -> tuple:
+    """Split a whole multi-material group as one shape.
+
+    Every material is clipped by the same cell grid over the group's
+    combined bounds and one shared scan frame, so cell-mates assemble
+    exactly. Pieces are emitted cell-major: each cell's pieces share a
+    nozzle (making the cell a multi-material group again, with the same
+    alignment and seam-free-contour behavior), and every piece gets its own
+    valve. Cells where a material has no geometry are skipped.
+    """
+    unsliced = [
+        member
+        for member in group_members
+        if member.get("layer_stack") is None or not member["layer_stack"].layers
+    ]
+    if unsliced:
+        return _outputs(
+            records,
+            selected,
+            f"Split failed: shape(s) on nozzle {group_nozzle} have no sliced layers yet - "
+            "press Slice Shapes first so the group shares one Z grid.",
+        )
+    stacks = [member["layer_stack"] for member in group_members]
+    layer_counts = {len(stack.layers) for stack in stacks}
+    z_starts = {round(stack.z_values[0], 6) for stack in stacks if stack.z_values}
+    if len(layer_counts) != 1 or len(z_starts) > 1:
+        return _outputs(
+            records,
+            selected,
+            f"Split failed: the shapes on nozzle {group_nozzle} were sliced on different "
+            "Z grids - press Slice Shapes to re-slice the group together.",
+        )
+
+    # Stamp group frames + seam-free contours so pieces inherit contour
+    # linework that already excludes material-to-material interfaces.
+    _stamp_multi_material_frames(records, float(fil_width))
+    frame = stacks[0].align_frame
+
+    try:
+        pieces_by_member = [
+            (
+                member,
+                split_layer_stack_grid(
+                    member["layer_stack"],
+                    columns=split_column_count,
+                    rows=split_row_count,
+                    overlapping_layers=bool(overlapping_layers),
+                    overlap=float(fil_width) if overlapping_layers else 0.0,
+                    grid=float(fil_width),
+                    frame=frame,
+                ),
+            )
+            for member in group_members
+        ]
+    except Exception as exc:
+        return _outputs(records, selected, f"Split failed: {exc}")
+
+    first_member = group_members[0]
+    first_nozzle = max(1, _coerce_int(starting_nozzle, 1))
+    first_valve = max(
+        1, _coerce_int(starting_valve, _coerce_int(first_member.get("valve", 4), 4))
+    )
+    split_group_id = f"split-{int(time.time() * 1_000_000)}-{first_member.get('idx', 1)}"
+    cell_count = split_column_count * split_row_count
+    split_records: list[dict] = []
+    valve_cursor = first_valve
+    for cell in range(cell_count):
+        row_index = cell // split_column_count + 1
+        col_index = cell % split_column_count + 1
+        for member, pieces in pieces_by_member:
+            piece = pieces[cell]
+            if all(layer.is_empty for layer in piece.layers):
+                continue  # this material has nothing in this cell
+            (piece_x_min, piece_y_min, _z_min), (piece_x_max, piece_y_max, _z_max) = piece.bounds
+            member_name = str(member.get("name") or f"Shape {member.get('idx')}")
+            piece_record = dict(member)
+            piece_record.update({
+                "name": f"{member_name} - R{row_index}C{col_index}",
+                "stl_path": None,
+                "target_x": (piece_x_max - piece_x_min) or member.get("target_x", DEFAULT_TARGET_EXTENTS[0]),
+                "target_y": (piece_y_max - piece_y_min) or member.get("target_y", DEFAULT_TARGET_EXTENTS[1]),
+                "nozzle": first_nozzle + cell,
+                "valve": valve_cursor,
+                "split_group_id": split_group_id,
+                "split_index": cell,
+                "split_row": row_index,
+                "split_col": col_index,
+                "split_rows": split_row_count,
+                "split_columns": split_column_count,
+                "layer_stack": piece,
+                "slice_params": member.get("slice_params"),
+                "gcode_path": None,
+            })
+            valve_cursor += 1
+            split_records.append(piece_record)
+
+    member_ids = {id(member) for member in group_members}
+    first_pos = min(
+        index for index, record in enumerate(records) if id(record) in member_ids
+    )
+    kept = [record for record in records if id(record) not in member_ids]
+    insert_at = sum(1 for record in records[:first_pos] if id(record) not in member_ids)
+    next_records = _reindex_shape_records(
+        [*kept[:insert_at], *split_records, *kept[insert_at:]]
+    )
+    split_selected = (
+        _shape_choice(next_records[insert_at]) if insert_at < len(next_records) else None
+    )
+    status = (
+        f"Split the multi-material group on nozzle {group_nozzle} "
+        f"({len(group_members)} materials) as one shape into {cell_count} cells "
+        f"({split_column_count} columns x {split_row_count} rows) - "
+        f"{len(split_records)} piece(s); material-empty cells skipped.  \n"
+        f"Each cell's pieces share a nozzle (nozzles {first_nozzle}-"
+        f"{first_nozzle + cell_count - 1}); valves {first_valve}-{valve_cursor - 1}."
+    )
+    if overlapping_layers:
+        status += (
+            "  \nOverlapping Layers is enabled: split boundaries alternate by one "
+            "filament width per layer so neighbouring pieces interlock."
+        )
+    return _outputs(next_records, split_selected, status)
+
+
 def split_selected_shape_for_grid(
     records: list[dict] | None,
     selected: str | None,
@@ -2383,6 +2852,33 @@ def split_selected_shape_for_grid(
 
     split_column_count = max(1, _coerce_int(columns, 2))
     split_row_count = max(1, _coerce_int(rows, 1))
+
+    # A shape sharing its nozzle with others is one material of a
+    # multi-material assembly: the whole group splits together as ONE shape,
+    # every material clipped by the same cell grid over the group's combined
+    # bounds. Cell-mates share a nozzle (so each cell is itself a
+    # multi-material group); every piece keeps its own valve.
+    group_nozzle = _record_nozzle_number(source, int(source.get("idx", pos + 1) or (pos + 1)))
+    group_members = (
+        _multi_material_groups(records).get(group_nozzle, [])
+        if source.get("stl_path")
+        else []
+    )
+    if len(group_members) > 1:
+        return _split_group_records(
+            records,
+            group_members,
+            group_nozzle,
+            split_column_count,
+            split_row_count,
+            overlapping_layers,
+            starting_nozzle,
+            starting_valve,
+            fil_width,
+            selected,
+            _outputs,
+        )
+
     try:
         pieces = split_layer_stack_grid(
             stack,
@@ -2464,16 +2960,18 @@ def _ensure_records_sliced(
     messages: list[str],
 ) -> bool:
     """Re-slice records whose layers are missing or stale for the current settings."""
+    z_by_record = _group_z_levels_by_record(records, layer_height, scale_mode)
     resliced = False
     for record in records:
         stl_path = record.get("stl_path")
         if not stl_path:
             continue  # Split pieces carry their clipped layers; nothing to re-slice.
-        current = _slice_params_snapshot(record, layer_height, scale_mode)
+        z_levels = z_by_record.get(id(record))
+        current = _slice_params_snapshot(record, layer_height, scale_mode, z_levels)
         if record.get("layer_stack") is not None and record.get("slice_params") == current:
             continue
         try:
-            stack = _slice_record(record, layer_height, scale_mode)
+            stack = _slice_record(record, layer_height, scale_mode, None, z_levels)
             messages.append(
                 f"Shape {record['idx']}: sliced automatically ({len(stack.layers)} layers)."
             )
@@ -2532,12 +3030,14 @@ def generate_dynamic_gcode(
     records = _apply_shape_settings(records or [], settings_table)
     messages: list[str] = []
     resliced = _ensure_records_sliced(records, layer_height, scale_mode, messages)
-    if use_reference_motion:
+    if use_reference_motion or resliced:
         # Always rebuild with the CURRENT fil width: the reference stack's
         # alignment snap grid must match the fil the G-code is generated with.
         ref_layers = generate_dynamic_reference_stack(records, fil_width)
-    elif resliced:
-        ref_layers = generate_dynamic_reference_stack(records, fil_width)
+    else:
+        # Still refresh group frames + seam-free contours: nozzle numbers may
+        # have been edited in the table since the last slice.
+        _stamp_multi_material_frames(records, fil_width)
     contour_sources = _contour_tracing_sources(records)
     if contour_sources:
         enabled = ", ".join(f"Shape {source.owner_idx}" for source in contour_sources)
@@ -2834,7 +3334,7 @@ def build_dynamic_demo() -> gr.Blocks:
                 """
                 # Shapes & Slicing
                 Upload any number of STL files, edit per-shape dimensions and print settings in the table, then slice each shape into per-layer outlines.
-                Color accepts: Orange, Blue, Green, Red, Purple, Pink, Teal, Black.
+                Pick each shape's plot color straight from the dropdown in the **Color** column.
                 """
             )
             with gr.Row():
@@ -2856,6 +3356,19 @@ def build_dynamic_demo() -> gr.Blocks:
                         label="Scaling Mode",
                     )
 
+            # Visually hidden (not visible=False: Gradio would omit them
+            # from the DOM entirely and the color-select relay needs them).
+            color_sink = gr.Textbox(
+                label="color sink",
+                container=False,
+                elem_id="pp-color-sink",
+                elem_classes=["pp-visually-hidden"],
+            )
+            color_apply = gr.Button(
+                "apply color",
+                elem_id="pp-color-apply",
+                elem_classes=["pp-visually-hidden"],
+            )
             shape_settings = gr.Dataframe(
                 headers=SHAPE_SETTINGS_HEADERS,
                 value=[],
@@ -2863,6 +3376,7 @@ def build_dynamic_demo() -> gr.Blocks:
                 column_count=(len(SHAPE_SETTINGS_HEADERS), "fixed"),
                 datatype=SHAPE_SETTINGS_DATATYPES,
                 interactive=True,
+                static_columns=[SHAPE_SETTINGS_HEADERS.index("Color")],
                 label="Shape Settings",
                 elem_id="shape-settings-table",
             )
@@ -2882,7 +3396,7 @@ def build_dynamic_demo() -> gr.Blocks:
                     split_start_valve = gr.Number(label="Starting Valve", value=4, minimum=1, step=1)
                 split_overlapping_layers = gr.Checkbox(label="Overlapping Layers", value=False)
                 split_button = gr.Button("Split Selected Shape into Grid Pieces", variant="primary")
-                split_status = gr.Markdown("Slice a shape, then split it for multi-nozzle printing.")
+                split_status = gr.Markdown(SPLIT_STATUS_DEFAULT)
 
             with gr.Accordion("Selected Shape Preview", open=False, elem_classes=["settings-accordion"]):
                 with gr.Row():
@@ -3099,6 +3613,12 @@ def build_dynamic_demo() -> gr.Blocks:
             outputs=[nozzle_grid_spacing_table],
             queue=False,
         )
+        color_apply.click(
+            fn=apply_color_selection,
+            inputs=[shape_records, shape_settings, color_sink],
+            outputs=[shape_records, shape_settings],
+            queue=False,
+        )
         shape_settings.select(
             fn=delete_shape_from_settings,
             inputs=[shape_records, shape_settings, last_shape_delete_at],
@@ -3162,6 +3682,14 @@ def build_dynamic_demo() -> gr.Blocks:
         )
 
         split_refresh_sources.click(fn=lambda records: _dropdown_update(records), inputs=[shape_records], outputs=[split_source], queue=False)
+        # .input (user selections only): programmatic dropdown refills after a
+        # split must not overwrite the split result message.
+        split_source.input(
+            fn=describe_split_source,
+            inputs=[shape_records, split_source],
+            outputs=[split_status],
+            queue=False,
+        )
         split_button.click(
             fn=split_selected_shape_for_grid,
             inputs=[
@@ -3311,15 +3839,25 @@ def build_dynamic_demo() -> gr.Blocks:
         travel_width_slider.release(fn=rerender_dynamic_toolpath_current_mode, inputs=[render_mode] + render_inputs, outputs=[toolpath_plot, toolpath_status, parsed_state])
         print_width_slider.release(fn=rerender_dynamic_toolpath_current_mode, inputs=[render_mode] + render_inputs, outputs=[toolpath_plot, toolpath_status, parsed_state])
 
-        def sync_width_sliders(v: float):
-            height = float(v or 0.8)
-            travel = height / 4
+        def sync_width_sliders(value: float):
+            # Visualization filament widths track the slicer's Filament/Line
+            # Width (what the G-code is actually generated with); travel
+            # lines render at a quarter of it.
+            width = float(value or 0.8)
+            travel = width / 4
             return (
-                gr.update(value=height, minimum=min(0.1, height), maximum=height * 1.5),
-                gr.update(value=travel, minimum=min(0.05, travel), maximum=height * 1.5),
+                gr.update(value=width, minimum=min(0.1, width), maximum=width * 1.5),
+                gr.update(value=travel, minimum=min(0.05, travel), maximum=width * 1.5),
+                gr.update(value=width, minimum=min(0.1, width), maximum=max(3.0, width * 1.5)),
+                gr.update(value=travel, minimum=min(0.05, travel), maximum=max(3.0, width * 1.5)),
             )
 
-        layer_height.change(fn=sync_width_sliders, inputs=[layer_height], outputs=[print_width_slider, travel_width_slider], queue=False)
+        fil_width.change(
+            fn=sync_width_sliders,
+            inputs=[fil_width],
+            outputs=[print_width_slider, travel_width_slider, pp_filament_width, pp_travel_width],
+            queue=False,
+        )
 
         parallel_render_inputs = [
             shape_records,

pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
     "numpy>=2.2.0",
     "pillow>=11.1.0",
     "plotly>=6.7.0",
+    "rtree>=1.4.1",
     "scipy>=1.15.2",
     "shapely>=2.0.7",
     "trimesh>=4.6.5",

requirements.txt

@@ -149,6 +149,8 @@ pyyaml==6.0.3
     #   huggingface-hub
 rich==14.3.3
     # via typer
+rtree==1.4.1
+    # via stl-to-gcode
 safehttpx==0.1.7
     # via gradio
 scipy==1.17.1

stl_slicer.py

@@ -7,6 +7,7 @@ from typing import Callable, Sequence
 
 import numpy as np
 from shapely.geometry import GeometryCollection, MultiPolygon, Polygon
+from shapely.ops import unary_union
 from shapely.validation import make_valid
 import trimesh
 
@@ -44,6 +45,12 @@ class LayerStack:
     scan_frame: tuple[float, float, float, float] | None = None
     align_center: tuple[float, float] | None = None
     align_grid: float | None = None
+    # Multi-material group frame: the combined XY bbox of every part sharing
+    # this shape's nozzle. Group members all carry the SAME frame and are
+    # aligned by its centre instead of their own bbox centre, so they move as
+    # one rigid unit and keep their modelled positions relative to each
+    # other. None = align by the shape's own bbox centre (normal shapes).
+    align_frame: tuple[float, float, float, float] | None = None
     # Grid-split pieces: per-layer contour polylines from the PARENT shape's
     # boundary clipped to this piece's cell — cut seams between sibling
     # pieces are excluded, so contour tracing only outlines the true outer
@@ -168,7 +175,20 @@ def _extract_world_polygons(section: trimesh.path.Path3D) -> list[tuple[np.ndarr
     else:
         planar, to_3d = section.to_planar()
 
-    composed_polygons = _compose_even_odd_polygons(list(planar.polygons_closed))
+    # polygons_full composes rings by containment depth (ring in a ring is a
+    # hole, ring in a hole is an island), so rings from separate solids that
+    # merely OVERLAP each other stay separate solids — the caller unions
+    # them. A flat even-odd XOR across all rings would punch false holes
+    # wherever interpenetrating solids overlap (e.g. flag stripe prisms
+    # packed into one STL).
+    try:
+        composed_polygons = [
+            polygon
+            for polygon in planar.polygons_full
+            if polygon is not None and not polygon.is_empty
+        ]
+    except BaseException:
+        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)
@@ -206,13 +226,56 @@ def _section_to_multipolygon(section: trimesh.path.Path3D | None) -> MultiPolygo
         return MultiPolygon()
 
     polygons = [
-        Polygon(exterior, holes)
+        make_valid(Polygon(exterior, holes))
         for exterior, holes in _extract_world_polygons(section)
     ]
     if not polygons:
         return MultiPolygon()
 
-    return _as_multipolygon(make_valid(MultiPolygon(polygons)))
+    # Union, not just collect: polygons from interpenetrating solids overlap.
+    return _as_multipolygon(make_valid(unary_union(polygons)))
+
+
+def _split_solids_and_cavities(
+    mesh: trimesh.Trimesh,
+) -> tuple[list[trimesh.Trimesh], list[trimesh.Trimesh]]:
+    """Connected bodies of a mesh, split into solids and explicit cavities.
+
+    A single STL often packs several separate solids that touch or
+    interpenetrate (checkerboard cells, overlapping stripe prisms).
+    Sectioning such a mesh whole corrupts the ring reconstruction where
+    rings cross or meet, so each WATERTIGHT body is sliced separately and
+    the results unioned; a watertight body wound inside-out (negative
+    volume) is a modeller's cavity, subtracted instead of unioned.
+
+    Everything that is not watertight — stray internal quads, meshes whose
+    face connectivity shreds into open fragments (T-vertices, unstitched
+    fans) — is kept together as ONE remainder mesh and sectioned whole,
+    where ring reconstruction can stitch across fragment boundaries; open
+    slivers there simply produce no closed rings and drop out.
+    """
+    try:
+        bodies = [body for body in mesh.split(only_watertight=False) if len(body.faces)]
+    except Exception:
+        return [mesh], []
+    if len(bodies) <= 1:
+        return [mesh], []
+
+    solids: list[trimesh.Trimesh] = []
+    cavities: list[trimesh.Trimesh] = []
+    remainder: list[trimesh.Trimesh] = []
+    for body in bodies:
+        if not body.is_watertight:
+            remainder.append(body)
+        elif body.is_winding_consistent and float(body.volume) < 0.0:
+            cavities.append(body)
+        else:
+            solids.append(body)
+    if remainder:
+        solids.append(
+            trimesh.util.concatenate(remainder) if len(remainder) > 1 else remainder[0]
+        )
+    return solids, cavities
 
 
 def slice_stl_to_layers(
@@ -221,21 +284,41 @@ def slice_stl_to_layers(
     progress_callback: ProgressCallback = None,
     scale_factors: Sequence[float] | None = None,
     name: str | None = None,
+    z_levels: Sequence[float] | None = None,
 ) -> LayerStack:
-    """Slice an STL into per-layer vector outlines (world-XY millimetres)."""
+    """Slice an STL into per-layer vector outlines (world-XY millimetres).
+
+    `z_levels` overrides the per-mesh Z planes with an explicit (world) grid —
+    used by multi-material assemblies so every part slices on ONE shared grid
+    and parts that start higher simply get empty lower layers.
+    """
     stl_path = Path(stl_path)
     mesh = scale_mesh(load_mesh(stl_path), scale_factors)
     (x_min, y_min, z_min), (x_max, y_max, z_max) = mesh.bounds
 
-    z_values = calculate_z_levels(float(z_min), float(z_max), layer_height)
+    if z_levels is not None:
+        z_values = [float(z) for z in z_levels]
+    else:
+        z_values = calculate_z_levels(float(z_min), float(z_max), layer_height)
+
+    solids, cavities = _split_solids_and_cavities(mesh)
+
+    def section_at(body: trimesh.Trimesh, z_value: float) -> MultiPolygon:
+        return _section_to_multipolygon(
+            body.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),
+            )
+        )
 
     layers: list[MultiPolygon] = []
     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),
-        )
-        layers.append(_section_to_multipolygon(section))
+        layer = unary_union([section_at(body, z_value) for body in solids])
+        if cavities:
+            layer = layer.difference(
+                unary_union([section_at(body, z_value) for body in cavities])
+            )
+        layers.append(_as_multipolygon(make_valid(layer)))
 
         if progress_callback is not None:
             progress_callback(index + 1, len(z_values))

tests/test_nozzle_spacing.py

@@ -164,7 +164,9 @@ def test_shape_settings_round_trip_infill_column() -> None:
     assert _apply_shape_settings(records, rows)[0]["infill"] == 0.0
 
 
-def test_shape_settings_color_column_uses_palette_names() -> None:
+def test_color_cell_renders_an_in_table_dropdown() -> None:
+    from app import PARALLEL_COLOR_CHOICES
+
     records = [
         {
             "idx": 1,
@@ -184,18 +186,47 @@ def test_shape_settings_color_column_uses_palette_names() -> None:
 
     rows = _shape_settings_rows(records)
     color_pos = SHAPE_SETTINGS_HEADERS.index("Color")
-    # Stored hex displays as its friendly name.
-    assert rows[0][color_pos] == "Orange"
+    cell = rows[0][color_pos]
+
+    # The cell is a select carrying the record idx (as a class token — data
+    # attributes get sanitized out of markdown cells), wrapped in the
+    # pp-color-cell span the head script's pointer-event isolation keys on,
+    # with every palette color as an option and the current one selected.
+    assert cell.startswith('<span class="pp-color-cell">')
+    assert '<select class="pp-color-select pp-idx-1"' in cell
+    for name, hex_value in PARALLEL_COLOR_CHOICES:
+        assert f'value="{hex_value}"' in cell
+        assert f">{name}<" in cell
+    assert '<option value="#ff7f0e" selected>Orange</option>' in cell
+    assert cell.count(" selected") == 1
+
+    # Round-tripping the table through _apply_shape_settings keeps the color
+    # (the html cell never parses as a color value).
+    assert _apply_shape_settings(records, rows)[0]["color"] == "#ff7f0e"
 
-    # Typing a palette name (any case) stores the matching hex.
-    rows[0][color_pos] = "red"
-    assert _apply_shape_settings(records, rows)[0]["color"] == "#d62728"
 
-    # Raw hex still works; unknown text keeps the previous color.
-    rows[0][color_pos] = "#123456"
-    assert _apply_shape_settings(records, rows)[0]["color"] == "#123456"
-    rows[0][color_pos] = "not-a-color"
-    assert _apply_shape_settings(records, rows)[0]["color"] == "#ff7f0e"
+def test_apply_color_selection_updates_the_right_record() -> None:
+    from app import apply_color_selection
+
+    records = [
+        {"idx": 1, "name": "a", "stl_path": "a.stl", "color": "#ff7f0e",
+         "target_x": 1.0, "target_y": 1.0, "target_z": 1.0,
+         "pressure": 25.0, "valve": 4, "nozzle": 1, "port": 1},
+        {"idx": 2, "name": "b", "stl_path": "b.stl", "color": "#1f77b4",
+         "target_x": 1.0, "target_y": 1.0, "target_z": 1.0,
+         "pressure": 25.0, "valve": 5, "nozzle": 2, "port": 1},
+    ]
+
+    updated, rows = apply_color_selection(records, None, "2|#ffe119")
+    assert updated[0]["color"] == "#ff7f0e"
+    assert updated[1]["color"] == "#ffe119"  # Yellow applied to shape 2
+    assert 'value="#ffe119" selected' in rows[1][SHAPE_SETTINGS_HEADERS.index("Color")]
+
+    # White is available; junk payloads change nothing.
+    assert apply_color_selection(records, None, "1|#ffffff")[0][0]["color"] == "#ffffff"
+    assert apply_color_selection(records, None, "1|#123456")[0][0]["color"] == "#ff7f0e"
+    assert apply_color_selection(records, None, "garbage")[0][0]["color"] == "#ff7f0e"
+    assert apply_color_selection(records, None, None)[0][0]["color"] == "#ff7f0e"
 
 
 def test_lead_in_assembly_extension_covers_the_split_extent() -> None:
@@ -668,3 +699,120 @@ def test_delete_shape_cooldown_blocks_immediate_second_delete() -> None:
     )
 
     assert [record["name"] for record in second_outputs[1]] == ["first", "last"]
+
+
+def test_group_split_splits_all_materials_on_one_shared_grid() -> None:
+    from shapely.geometry import MultiPolygon, box
+
+    from app import split_selected_shape_for_grid
+    from stl_slicer import LayerStack
+
+    def _material(polygon, name: str) -> LayerStack:
+        layers = [MultiPolygon([polygon]), MultiPolygon([polygon])]
+        x_min, y_min, x_max, y_max = polygon.bounds
+        return LayerStack(
+            layers=layers,
+            z_values=[0.5, 1.5],
+            bounds=((x_min, y_min, 0.0), (x_max, y_max, 2.0)),
+            layer_height=1.0,
+            name=name,
+        )
+
+    def _record(idx: int, name: str, stack: LayerStack) -> dict:
+        return {
+            "idx": idx,
+            "name": name,
+            "stl_path": f"{name}.stl",
+            "target_x": 20.0,
+            "target_y": 5.0,
+            "target_z": 2.0,
+            "pressure": 25.0,
+            "valve": 4,
+            "nozzle": 1,  # both materials on nozzle 1 -> one assembly
+            "port": 1,
+            "color": "#111111",
+            "layer_stack": stack,
+        }
+
+    # Two materials tiling one 20x10 shape as horizontal strips.
+    records = [
+        _record(1, "bottom", _material(box(0.0, 0.0, 20.0, 5.0), "bottom")),
+        _record(2, "top", _material(box(0.0, 5.0, 20.0, 10.0), "top")),
+    ]
+
+    outputs = split_selected_shape_for_grid(
+        records,
+        None,  # selected -> defaults to the first record
+        None,  # settings table
+        2,  # columns
+        1,  # rows
+        False,  # overlapping layers
+        5,  # starting nozzle
+        9,  # starting valve
+        1.0,  # fil width
+    )
+    next_records = outputs[0]
+
+    pieces = [record for record in next_records if record.get("split_group_id")]
+    assert len(pieces) == 4  # 2 cells x 2 materials
+
+    # Cell-major: cell 1 pieces share nozzle 5, cell 2 pieces share nozzle 6;
+    # every piece gets its own valve.
+    assert [piece["nozzle"] for piece in pieces] == [5, 5, 6, 6]
+    assert [piece["valve"] for piece in pieces] == [9, 10, 11, 12]
+    assert [piece["name"] for piece in pieces] == [
+        "bottom - R1C1",
+        "top - R1C1",
+        "bottom - R1C2",
+        "top - R1C2",
+    ]
+
+    # Cell-mates carry IDENTICAL nominal cell bounds (the shared grid) and
+    # one shared scan frame covering the whole assembly.
+    for cell_first, cell_second in ((0, 1), (2, 3)):
+        assert pieces[cell_first]["layer_stack"].bounds == pieces[cell_second]["layer_stack"].bounds
+    frames = {piece["layer_stack"].scan_frame for piece in pieces}
+    assert frames == {(0.0, 0.0, 20.0, 10.0)}
+
+    # Geometry: each piece is its material clipped to its cell.
+    assert pieces[0]["layer_stack"].layers[0].bounds == (0.0, 0.0, 10.0, 5.0)
+    assert pieces[1]["layer_stack"].layers[0].bounds == (0.0, 5.0, 10.0, 10.0)
+    assert pieces[2]["layer_stack"].layers[0].bounds == (10.0, 0.0, 20.0, 5.0)
+
+    # Contours exclude BOTH the material interface (y=5) and the cut seam
+    # (x=10): piece R1C1 of `bottom` keeps only its west + south edges.
+    for path in pieces[0]["layer_stack"].contour_paths[0]:
+        for x, y in path:
+            assert x <= 10.0 - 0.5 + 1e-9 or y <= 5.0 - 0.5 + 1e-9
+
+
+def test_describe_split_source_warns_about_group_splits() -> None:
+    from shapely.geometry import MultiPolygon, box
+
+    from app import SPLIT_STATUS_DEFAULT, describe_split_source
+    from stl_slicer import LayerStack
+
+    def _stack(name: str) -> LayerStack:
+        return LayerStack(
+            layers=[MultiPolygon([box(0.0, 0.0, 1.0, 1.0)])],
+            z_values=[0.5],
+            bounds=((0.0, 0.0, 0.0), (1.0, 1.0, 1.0)),
+            layer_height=1.0,
+            name=name,
+        )
+
+    records = [
+        {"idx": 1, "name": "black", "stl_path": "black.stl", "nozzle": 1, "layer_stack": _stack("black")},
+        {"idx": 2, "name": "gold", "stl_path": "gold.stl", "nozzle": 1, "layer_stack": _stack("gold")},
+        {"idx": 3, "name": "solo", "stl_path": "solo.stl", "nozzle": 2, "layer_stack": _stack("solo")},
+    ]
+
+    grouped_note = describe_split_source(records, "1: black")
+    assert "whole group as one shape" in grouped_note
+    assert "black" in grouped_note and "gold" in grouped_note
+    assert "nozzle 1" in grouped_note
+
+    assert describe_split_source(records, "3: solo") == SPLIT_STATUS_DEFAULT
+    # No selection defaults to the first shape - which is grouped here.
+    assert "whole group as one shape" in describe_split_source(records, None)
+    assert describe_split_source([], None) == SPLIT_STATUS_DEFAULT

tests/test_stl_slicer.py

@@ -82,3 +82,61 @@ def test_compose_even_odd_polygons_preserves_holes() -> None:
     assert len(composed) == 1
     assert composed[0].area == outer.area - inner.area
     assert len(composed[0].interiors) == 1
+
+
+def test_slice_stl_unions_interpenetrating_bodies(tmp_path) -> None:
+    # One STL packing several separate solids that overlap (e.g. the stripe
+    # prisms of a flag part) must slice to their union — the whole-mesh
+    # even-odd rule would XOR the overlap into a false hole.
+    a = trimesh.creation.box(extents=(4.0, 2.0, 2.0))
+    b = trimesh.creation.box(extents=(2.0, 4.0, 2.0))
+    b.apply_translation((1.0, 0.0, 0.0))  # overlaps half of `a`
+    stl_path = tmp_path / "cross.stl"
+    trimesh.util.concatenate([a, b]).export(stl_path)
+
+    stack = slice_stl_to_layers(stl_path, layer_height=1.0)
+
+    # Union area: 8 + 8 - 2x2 overlap = 12 (XOR would give 8).
+    for layer in stack.layers:
+        assert layer.area == pytest.approx(12.0)
+        assert all(not polygon.interiors for polygon in layer.geoms)
+
+
+def test_slice_stl_subtracts_inverted_cavity_bodies(tmp_path) -> None:
+    # A watertight body wound inside-out (negative volume) is a modeller's
+    # cavity: it must stay a hole, not be unioned as a solid.
+    outer = trimesh.creation.box(extents=(6.0, 6.0, 2.0))
+    cavity = trimesh.creation.box(extents=(2.0, 2.0, 2.0))
+    cavity.invert()
+    stl_path = tmp_path / "hollow.stl"
+    trimesh.util.concatenate([outer, cavity]).export(stl_path)
+
+    stack = slice_stl_to_layers(stl_path, layer_height=1.0)
+
+    for layer in stack.layers:
+        assert layer.area == pytest.approx(36.0 - 4.0)
+        assert sum(len(polygon.interiors) for polygon in layer.geoms) == 1
+
+
+def test_slice_stl_handles_abutting_cells_and_stray_open_quads(tmp_path) -> None:
+    # Checkerboard-style STL: watertight cells that touch at edges/corners,
+    # plus stray open quad fragments (internal walls). The cells must slice
+    # per body and union into the exact checker pattern; the open quads
+    # produce no closed rings and drop out.
+    cells = []
+    for cx, cy in ((0, 0), (1, 1), (2, 0), (0, 2), (2, 2)):
+        cell = trimesh.creation.box(extents=(10.0, 10.0, 10.0))
+        cell.apply_translation((cx * 10.0 + 5.0, cy * 10.0 + 5.0, 5.0))
+        cells.append(cell)
+    quad = trimesh.Trimesh(
+        vertices=[(10.0, 0.0, 0.0), (10.0, 10.0, 0.0), (10.0, 10.0, 10.0), (10.0, 0.0, 10.0)],
+        faces=[(0, 1, 2), (0, 2, 3)],
+    )
+    stl_path = tmp_path / "checker.stl"
+    trimesh.util.concatenate(cells + [quad]).export(stl_path)
+
+    stack = slice_stl_to_layers(stl_path, layer_height=1.0)
+
+    for layer in stack.layers:
+        assert layer.area == pytest.approx(500.0)
+        assert layer.bounds == pytest.approx((0.0, 0.0, 30.0, 30.0))

tests/test_vector_gcode.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import math
 
-from shapely.geometry import MultiPolygon, Polygon, box
+from shapely.geometry import MultiPolygon, Point, Polygon, box
 
 from stl_slicer import LayerStack
 from vector_gcode import generate_vector_gcode
@@ -13,7 +13,8 @@ from vector_toolpath import (
     RASTER_PATTERN_Y_DIRECTION,
     ContourSource,
     _append_layer_contours,
-    _circle_spiral_points,
+    _circle_ring_radii,
+    _circle_rings_polyline,
     _layer_contour_loops,
     _rectangular_spiral_polyline,
     build_reference_stack,
@@ -660,33 +661,106 @@ def test_rectangular_spiral_raster_reverses_between_layers(tmp_path) -> None:
     assert end_z == 1.0
 
 
-def test_circle_spiral_points_decrease_radius_to_center() -> None:
-    points = _circle_spiral_points(2.0, 3.0, outer_radius=4.0, pitch=1.0)
-    radii = [math.hypot(x - 2.0, y - 3.0) for x, y in points]
+def test_circle_ring_radii_hug_the_wall_then_fill_from_a_global_grid() -> None:
+    # The outermost revolution follows the material edge (max distance minus
+    # half a bead); the fill rings inside it sit on the (j + 1/2) * fil grid
+    # shared by every layer, so interior rings stack instead of aliasing.
+    disc = MultiPolygon([Point(2.0, 3.0).buffer(4.2, quad_segs=64)])
+    radii, walls = _circle_ring_radii(disc, 2.0, 3.0, 0.8)
 
-    assert radii[0] == 4.0
-    assert radii[-1] == 0.0
-    assert all(
-        current <= previous + 1e-9
-        for previous, current in zip(radii, radii[1:])
+    assert radii == sorted(radii, reverse=True)
+    assert walls == (radii[0],)
+    assert abs(radii[0] - (4.2 - 0.4)) < 1e-2  # wall hugs the material edge
+    for radius in radii[1:]:
+        ring = radius / 0.8 - 0.5
+        assert abs(ring - round(ring)) < 1e-9  # fill stays on the global grid
+        assert radius <= radii[0] - 0.4 + 1e-9  # no overlap with the wall bead
+    assert min(radii) == 0.4  # material at the centre keeps the innermost ring
+
+
+def test_circle_ring_radii_skip_rings_outside_the_material() -> None:
+    # An annulus gets an outer wall, an inner wall hugging the hole, and fill
+    # rings only where circles can cross material.
+    annulus = MultiPolygon(
+        [
+            Point(0.0, 0.0)
+            .buffer(6.0, quad_segs=64)
+            .difference(Point(0.0, 0.0).buffer(3.0, quad_segs=64))
+        ]
     )
+    radii, walls = _circle_ring_radii(annulus, 0.0, 0.0, 0.8)
+
+    assert radii
+    assert len(walls) == 2
+    assert abs(max(walls) - (6.0 - 0.4)) < 1e-2  # outer wall at the edge
+    assert abs(min(walls) - (3.0 + 0.4)) < 1e-2  # inner wall at the hole
+    assert min(radii) >= 3.0 - 1e-2
+    assert max(radii) <= 6.0 + 1e-9
 
 
-def test_circle_spiral_steps_radius_by_whole_pitches() -> None:
+def test_circle_rings_polyline_steps_radius_by_whole_pitches() -> None:
     # Each revolution is a true circle at a constant radius; the radius drops
     # by exactly one pitch in a single radial jump between revolutions.
-    points = _circle_spiral_points(2.0, 3.0, outer_radius=4.0, pitch=0.8)
+    ring_radii = [3.6, 2.8, 2.0, 1.2, 0.4]
+    points = _circle_rings_polyline(2.0, 3.0, ring_radii, 0.8)
     radii = [math.hypot(x - 2.0, y - 3.0) for x, y in points]
 
     distinct = sorted({round(radius, 6) for radius in radii})
-    assert distinct == [0.0, 0.8, 1.6, 2.4, 3.2, 4.0]
+    assert distinct == [0.4, 1.2, 2.0, 2.8, 3.6]
 
     ring_transitions = sum(
         1
         for previous, current in zip(radii, radii[1:])
         if abs(current - previous) > 1e-9
     )
-    assert ring_transitions == 5
+    assert ring_transitions == 4
+
+
+def test_circle_spiral_dome_has_no_travel_rings_and_monotone_radii(tmp_path) -> None:
+    # A dome (shrinking discs): motion must stay near each layer's material
+    # instead of sweeping the full frame, and the outermost printed radius
+    # must never grow with height.
+    from gcode_viewer import parse_gcode_path
+
+    center = (5.0, 5.0)
+    layer_radii = [5.0, 4.3, 3.4, 2.2]
+    layers = [Point(*center).buffer(r, quad_segs=64) for r in layer_radii]
+    gcode_path = generate_vector_gcode(
+        _stack(*layers),
+        shape_name="dome",
+        pressure=25,
+        valve=7,
+        port=3,
+        fil_width=0.8,
+        layer_height=1.0,
+        raster_pattern=RASTER_PATTERN_CIRCLE_SPIRAL,
+        output_dir=tmp_path,
+    )
+
+    parsed = parse_gcode_path(gcode_path.read_text())
+    origin_x, origin_y = parsed["path_origin"]
+
+    def layer_of(z: float) -> int:
+        return max(0, min(len(layer_radii) - 1, int(round(z))))
+
+    motion_max = [0.0] * len(layer_radii)
+    print_max = [0.0] * len(layer_radii)
+    for kind in ("print_segments", "travel_segments"):
+        for segment in parsed[kind]:
+            for x, y, z in segment:
+                radius = math.hypot(x + origin_x - center[0], y + origin_y - center[1])
+                index = layer_of(z)
+                motion_max[index] = max(motion_max[index], radius)
+                if kind == "print_segments":
+                    print_max[index] = max(print_max[index], radius)
+
+    for index, layer_radius in enumerate(layer_radii):
+        # No motion meaningfully beyond this layer's own material edge.
+        assert motion_max[index] <= layer_radius + 0.8, (index, motion_max[index])
+        assert print_max[index] <= layer_radius + 1e-6
+    # Outermost printed ring shrinks (or holds) as the dome narrows.
+    for lower, upper in zip(print_max, print_max[1:]):
+        assert upper <= lower + 1e-9
 
 
 def test_circle_spiral_ring_steps_travel_with_valve_shut(tmp_path) -> None:
@@ -1400,3 +1474,148 @@ def test_split_layer_stack_grid_overlap_alternates_between_layers() -> None:
     # Nominal bounds stay the un-shifted cells.
     assert left.bounds == ((0.0, 0.0, 0.0), (2.0, 2.0, 2.0))
     assert right.bounds == ((2.0, 0.0, 0.0), (4.0, 2.0, 2.0))
+
+
+def test_group_frame_reference_keeps_modeled_positions(tmp_path) -> None:
+    # Multi-material group (shapes sharing a nozzle): parts carry one shared
+    # align_frame, so they are NOT centered individually — each keeps its
+    # modeled position relative to the others, and a part that has no
+    # material on the lower layers just travels there (empty valve layers).
+    from gcode_viewer import parse_gcode_path
+
+    lower = _stack(box(0.0, 0.0, 4.0, 4.0), box(0.0, 0.0, 4.0, 4.0), name="lower")
+    # `upper` sits 6 mm to the right and only exists on layer 1.
+    upper = _stack(None, box(6.0, 0.0, 10.0, 4.0), name="upper")
+    group_frame = (0.0, 0.0, 10.0, 4.0)
+    lower.align_frame = group_frame
+    upper.align_frame = group_frame
+    # A regular shape (own nozzle, no frame) modeled far away prints in the
+    # same job: it gets centered onto the reference like always.
+    solo = _stack(box(100.0, 100.0, 104.0, 104.0), box(100.0, 100.0, 104.0, 104.0), name="solo")
+    reference = build_reference_stack([lower, upper, solo], grid=1.0)
+
+    # The group holding the first stack anchors the reference (no
+    # translation); solo lands centered on the frame centre (5, 2): x 3..7.
+    assert reference.layers[0].bounds == (0.0, 0.0, 7.0, 4.0)
+    assert reference.layers[1].bounds == (0.0, 0.0, 10.0, 4.0)
+    # Layer 0 = lower box (0..4) union solo centered to (3..7): 16+16-4 overlap.
+    assert abs(reference.layers[0].area - 28.0) < 1e-6
+
+    def _world_motion_polyline(text: str) -> list[tuple[float, float, float]]:
+        # Ordered nozzle path in world coordinates, simplified so points that
+        # only mark valve changes (collinear, same direction) drop out.
+        origin_line = next(line for line in text.splitlines() if "PathOrigin" in line)
+        tokens = origin_line.split()
+        origin_x, origin_y = float(tokens[-2][1:]), float(tokens[-1][1:])
+        moves = _moves_with_colors(text)
+        points = [moves[0]["start"]] + [move["end"] for move in moves]
+        world = [(x + origin_x, y + origin_y, z) for x, y, z in points]
+        simplified = [world[0]]
+        for point in world[1:]:
+            if len(simplified) >= 2:
+                ax, ay, az = simplified[-2]
+                bx, by, bz = simplified[-1]
+                d1 = (bx - ax, by - ay, bz - az)
+                d2 = (point[0] - bx, point[1] - by, point[2] - bz)
+                cross = (
+                    d1[1] * d2[2] - d1[2] * d2[1],
+                    d1[2] * d2[0] - d1[0] * d2[2],
+                    d1[0] * d2[1] - d1[1] * d2[0],
+                )
+                same_dir = all(abs(c) < 1e-9 for c in cross) and (
+                    d1[0] * d2[0] + d1[1] * d2[1] + d1[2] * d2[2] >= 0
+                )
+                if same_dir:
+                    simplified[-1] = point
+                    continue
+            simplified.append(point)
+        return [(round(x, 6), round(y, 6), round(z, 6)) for x, y, z in simplified]
+
+    prints: dict[str, list] = {}
+    motions: dict[str, list] = {}
+    for stack in (lower, upper):
+        gcode_path = generate_vector_gcode(
+            stack,
+            shape_name=stack.name,
+            pressure=25,
+            valve=7,
+            port=3,
+            fil_width=1.0,
+            layer_height=1.0,
+            motion=reference,
+            output_dir=tmp_path,
+        )
+        text = gcode_path.read_text()
+        parsed = parse_gcode_path(text)
+        origin_x, origin_y = parsed["path_origin"]
+        prints[stack.name] = [
+            [(x + origin_x, y + origin_y, z) for x, y, z in segment]
+            for segment in parsed["print_segments"]
+        ]
+        motions[stack.name] = _world_motion_polyline(text)
+
+    # Shared motion: both heads trace exactly the same world path.
+    assert motions["lower"] == motions["upper"]
+
+    # `upper` never dispenses on layer 0 and prints only inside x 6..10.
+    for segment in prints["upper"]:
+        for x, y, z in segment:
+            assert z > 0.5
+            assert 6.0 - 1e-6 <= x <= 10.0 + 1e-6
+    # `lower` prints only inside x 0..4 (its modeled position, not recentered).
+    for segment in prints["lower"]:
+        for x, y, z in segment:
+            assert 0.0 - 1e-6 <= x <= 4.0 + 1e-6
+
+
+def test_group_contour_paths_exclude_material_interfaces() -> None:
+    from vector_toolpath import group_contour_paths
+
+    # Two materials abutting at x=4 assemble into one 8x4 shape: the shared
+    # edge is an internal interface, so each member contours only its three
+    # outer sides.
+    left = _stack(box(0.0, 0.0, 4.0, 4.0), name="left")
+    right = _stack(box(4.0, 0.0, 8.0, 4.0), name="right")
+    paths = group_contour_paths(left, [right], tolerance=0.4)
+
+    assert len(paths) == 1
+    total = sum(
+        math.dist(a, b)
+        for path in paths[0]
+        for a, b in zip(path, path[1:])
+    )
+    # 3 outer sides of the 4x4 box; boundary within tolerance (0.4) of the
+    # sibling also counts as interface, so the top/bottom edges stop 0.4
+    # short of the seam: 12 - 2*0.4. The seam edge itself is gone entirely.
+    assert abs(total - 11.2) < 1e-6
+    for path in paths[0]:
+        for x, _y in path:
+            assert x <= 3.6 + 1e-9  # nothing at or past the seam
+
+    # A fit-tolerance gap smaller than the tolerance still counts as an
+    # interface; a distant shape does not.
+    gapped = _stack(box(4.2, 0.0, 8.0, 4.0), name="gapped")
+    paths_gapped = group_contour_paths(left, [gapped], tolerance=0.4)
+    total_gapped = sum(
+        math.dist(a, b)
+        for path in paths_gapped[0]
+        for a, b in zip(path, path[1:])
+    )
+    # Seam edge excluded; top/bottom trimmed where within 0.4 of the sibling
+    # (which starts at 4.2): 12 - 2*0.2.
+    assert abs(total_gapped - 11.6) < 1e-6
+
+    far = _stack(box(9.0, 0.0, 12.0, 4.0), name="far")
+    paths_far = group_contour_paths(left, [far], tolerance=0.4)
+    total_far = sum(
+        math.dist(a, b)
+        for path in paths_far[0]
+        for a, b in zip(path, path[1:])
+    )
+    assert abs(total_far - 16.0) < 1e-6  # full ring: nothing nearby
+
+    # A material fully embedded in the assembly has no outer surface at all.
+    core = _stack(box(1.0, 1.0, 3.0, 3.0), name="core")
+    shell_layer = box(0.0, 0.0, 4.0, 4.0).difference(box(1.0, 1.0, 3.0, 3.0))
+    shell = _stack(shell_layer, name="shell")
+    assert group_contour_paths(core, [shell], tolerance=0.4) == [[]]

uv.lock

@@ -1429,6 +1429,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/14/25/b208c5683343959b670dc001595f2f3737e051da617f66c31f7c4fa93abc/rich-14.3.3-py3-none-any.whl", hash = "sha256:793431c1f8619afa7d3b52b2cdec859562b950ea0d4b6b505397612db8d5362d", size = 310458, upload-time = "2026-02-19T17:23:13.732Z" },
 ]
 
+[[package]]
+name = "rtree"
+version = "1.4.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/95/09/7302695875a019514de9a5dd17b8320e7a19d6e7bc8f85dcfb79a4ce2da3/rtree-1.4.1.tar.gz", hash = "sha256:c6b1b3550881e57ebe530cc6cffefc87cd9bf49c30b37b894065a9f810875e46", size = 52425, upload-time = "2025-08-13T19:32:01.413Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/d9/108cd989a4c0954e60b3cdc86fd2826407702b5375f6dfdab2802e5fed98/rtree-1.4.1-py3-none-macosx_10_9_x86_64.whl", hash = "sha256:d672184298527522d4914d8ae53bf76982b86ca420b0acde9298a7a87d81d4a4", size = 468484, upload-time = "2025-08-13T19:31:50.593Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/cf/2710b6fd6b07ea0aef317b29f335790ba6adf06a28ac236078ed9bd8a91d/rtree-1.4.1-py3-none-macosx_11_0_arm64.whl", hash = "sha256:a7e48d805e12011c2cf739a29d6a60ae852fb1de9fc84220bbcef67e6e595d7d", size = 436325, upload-time = "2025-08-13T19:31:52.367Z" },
+    { url = "https://files.pythonhosted.org/packages/55/e1/4d075268a46e68db3cac51846eb6a3ab96ed481c585c5a1ad411b3c23aad/rtree-1.4.1-py3-none-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:efa8c4496e31e9ad58ff6c7df89abceac7022d906cb64a3e18e4fceae6b77f65", size = 459789, upload-time = "2025-08-13T19:31:53.926Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/75/e5d44be90525cd28503e7f836d077ae6663ec0687a13ba7810b4114b3668/rtree-1.4.1-py3-none-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:12de4578f1b3381a93a655846900be4e3d5f4cd5e306b8b00aa77c1121dc7e8c", size = 507644, upload-time = "2025-08-13T19:31:55.164Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/85/b8684f769a142163b52859a38a486493b05bafb4f2fb71d4f945de28ebf9/rtree-1.4.1-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:b558edda52eca3e6d1ee629042192c65e6b7f2c150d6d6cd207ce82f85be3967", size = 1454478, upload-time = "2025-08-13T19:31:56.808Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/a4/c2292b95246b9165cc43a0c3757e80995d58bc9b43da5cb47ad6e3535213/rtree-1.4.1-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:f155bc8d6bac9dcd383481dee8c130947a4866db1d16cb6dff442329a038a0dc", size = 1555140, upload-time = "2025-08-13T19:31:58.031Z" },
+    { url = "https://files.pythonhosted.org/packages/74/25/5282c8270bfcd620d3e73beb35b40ac4ab00f0a898d98ebeb41ef0989ec8/rtree-1.4.1-py3-none-win_amd64.whl", hash = "sha256:efe125f416fd27150197ab8521158662943a40f87acab8028a1aac4ad667a489", size = 389358, upload-time = "2025-08-13T19:31:59.247Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/50/0a9e7e7afe7339bd5e36911f0ceb15fed51945836ed803ae5afd661057fd/rtree-1.4.1-py3-none-win_arm64.whl", hash = "sha256:3d46f55729b28138e897ffef32f7ce93ac335cb67f9120125ad3742a220800f0", size = 355253, upload-time = "2025-08-13T19:32:00.296Z" },
+]
+
 [[package]]
 name = "safehttpx"
 version = "0.1.7"
@@ -1622,6 +1638,7 @@ dependencies = [
     { name = "numpy" },
     { name = "pillow" },
     { name = "plotly" },
+    { name = "rtree" },
     { name = "scipy" },
     { name = "shapely" },
     { name = "trimesh" },
@@ -1640,6 +1657,7 @@ requires-dist = [
     { name = "numpy", specifier = ">=2.2.0" },
     { name = "pillow", specifier = ">=11.1.0" },
     { name = "plotly", specifier = ">=6.7.0" },
+    { name = "rtree", specifier = ">=1.4.1" },
     { name = "scipy", specifier = ">=1.15.2" },
     { name = "shapely", specifier = ">=2.0.7" },
     { name = "trimesh", specifier = ">=4.6.5" },

vector_toolpath.py

@@ -670,27 +670,87 @@ def _rectangular_spiral_polyline(
     return _extend_polyline_ends(points, half)
 
 
-def _circle_spiral_points(
+def _circle_ring_radii(
+    motion: MultiPolygon,
+    center_x: float,
+    center_y: float,
+    fil_width: float,
+) -> tuple[list[float], tuple[float, ...]]:
+    """Ring radii for one layer, outermost first: perimeter walls + grid fill.
+
+    The outermost revolution is a PERIMETER WALL hugging the layer's material
+    edge (its farthest boundary distance minus half a bead), so the printed
+    silhouette follows the shape smoothly instead of staircasing by whole
+    grid steps. If the layer has a central hole, a matching inner wall hugs
+    the hole edge. The fill between the walls comes from a global grid —
+    ring j at (j + 1/2) * fil_width from the frame centre, the same grid on
+    every layer (and every split sibling) so interior rings stack vertically.
+    Grid rings that would overlap a wall bead, or whose circle cannot cross
+    the layer's material at all, are skipped instead of traveled.
+
+    Returns (radii outermost-first, wall radii). Walls always dispense even
+    under partial infill, like contour tracing.
+    """
+    if motion is None or motion.is_empty:
+        return [], ()
+
+    max_dist = 0.0
+    for polygon in motion.geoms:
+        for ring in (polygon.exterior, *polygon.interiors):
+            for x, y in ring.coords:
+                max_dist = max(max_dist, math.hypot(x - center_x, y - center_y))
+    if max_dist <= 0.0:
+        return [], ()
+    min_dist = float(motion.distance(Point(center_x, center_y)))
+
+    pitch = max(float(fil_width), 1e-9)
+    half = pitch / 2.0
+
+    outer_wall = max_dist - half
+    if outer_wall <= EPS:
+        # Material thinner than one bead (e.g. the dome cap): one tiny ring
+        # through the middle of it so the layer still gets motion.
+        radius = max(max_dist / 2.0, EPS)
+        return [radius], (radius,)
+
+    walls = [outer_wall]
+    inner_wall: float | None = None
+    if min_dist > pitch / 4.0:
+        candidate = min_dist + half
+        if candidate <= outer_wall - half:
+            inner_wall = candidate
+            walls.append(candidate)
+
+    grid_hi = outer_wall - half
+    grid_lo = (inner_wall + half) if inner_wall is not None else max(min_dist - half, 0.0)
+    j_hi = int(math.floor(grid_hi / pitch - 0.5 + 1e-9))
+    j_lo = max(0, int(math.ceil(grid_lo / pitch - 0.5 - 1e-9)))
+
+    radii = [outer_wall]
+    if j_hi >= j_lo:
+        radii.extend((j + 0.5) * pitch for j in range(j_hi, j_lo - 1, -1))
+    if inner_wall is not None:
+        radii.append(inner_wall)
+    return radii, tuple(walls)
+
+
+def _circle_rings_polyline(
     center_x: float,
     center_y: float,
-    outer_radius: float,
+    radii: list[float],
     pitch: float,
 ) -> list[tuple[float, float]]:
-    """Concentric-ring "spiral": full circles stepping inward by one pitch.
+    """Concentric-ring "spiral": one full circle per radius, in list order.
 
     Each revolution stays at a CONSTANT radius (so the printed walls are true
-    smooth circles) and the radius then drops by exactly one pitch in a short
-    radial jump before the next revolution, ending at the centre. Ring k thus
-    sits exactly at radius outer - k*pitch, which is also what the partial
-    infill revolution index assumes.
+    smooth circles); consecutive rings are joined by a radial jump at theta 0,
+    which the caller classifies as valve-off travel.
     """
-    if outer_radius <= 0.0:
-        return [(center_x, center_y)]
-
     pitch = max(float(pitch), 1e-9)
     points: list[tuple[float, float]] = []
-    radius = outer_radius
-    while radius > 1e-9:
+    for radius in radii:
+        if radius <= 0.0:
+            continue
         # Sample roughly one pitch of arc length per step, at least 20/ring.
         d_theta = min(math.pi / 10.0, pitch / max(radius, pitch))
         steps = max(8, int(math.ceil((2.0 * math.pi) / d_theta)))
@@ -702,34 +762,6 @@ def _circle_spiral_points(
                     center_y + (radius * math.sin(theta)),
                 )
             )
-        radius -= pitch
-
-    if not points or points[-1] != (center_x, center_y):
-        points.append((center_x, center_y))
-    return points
-
-
-def _circle_spiral_polyline(
-    bounds: tuple[float, float, float, float],
-    fil_width: float,
-    reverse: bool = False,
-) -> list[tuple[float, float]]:
-    min_x, min_y, max_x, max_y = bounds
-    center_x = (min_x + max_x) / 2.0
-    center_y = (min_y + max_y) / 2.0
-    outer_radius = max(
-        math.hypot(corner_x - center_x, corner_y - center_y)
-        for corner_x, corner_y in (
-            (min_x, min_y),
-            (max_x, min_y),
-            (max_x, max_y),
-            (min_x, max_y),
-        )
-    )
-
-    points = _circle_spiral_points(center_x, center_y, outer_radius, fil_width)
-    if reverse:
-        points.reverse()
     return points
 
 
@@ -1224,38 +1256,35 @@ def plan_layer_moves(
         if motion is None or motion.is_empty:
             segments: list[Seg] = []
         elif raster_pattern == RASTER_PATTERN_CIRCLE_SPIRAL:
-            points = _circle_spiral_polyline(
-                motion.bounds,
-                fil_width,
-                reverse=layer_number % 2 == 1,
-            )
-            # Rings sit exactly at radius outer - k*fil. Dispense only ON a
-            # ring: the radial step between revolutions (and the final dive
-            # to the centre) travels with the valve shut — otherwise every
-            # step would extrude a radial seam, worst on the outer wall.
-            # Vetoing whole source segments by their radial change also kills
-            # the step pieces the material boundary would otherwise split off.
-            min_x, min_y, max_x, max_y = motion.bounds
-            center_x = (min_x + max_x) / 2.0
-            center_y = (min_y + max_y) / 2.0
-            outer_radius = max(
-                math.hypot(cx - center_x, cy - center_y)
-                for cx, cy in (
-                    (min_x, min_y),
-                    (max_x, min_y),
-                    (max_x, max_y),
-                    (min_x, max_y),
-                )
-            )
-
+            # Rings live on one global radii grid anchored at the frame
+            # centre (ring j at (j + 1/2) * fil): every layer draws from the
+            # same radii, so walls stack across layers instead of aliasing,
+            # and rings that never touch this layer's material are skipped
+            # instead of swept as full travel circles.
+            frame = scan_frame if scan_frame is not None else motion.bounds
+            center_x = (frame[0] + frame[2]) / 2.0
+            center_y = (frame[1] + frame[3]) / 2.0
+            radii, wall_radii = _circle_ring_radii(motion, center_x, center_y, fil_width)
+            points = _circle_rings_polyline(center_x, center_y, radii, fil_width)
+            if layer_number % 2 == 1:
+                points.reverse()
+
+            # Dispense only ON a ring: the radial jump between revolutions
+            # travels with the valve shut — otherwise every jump would
+            # extrude a radial seam, worst on the outer wall. Vetoing whole
+            # source segments by their radial change also kills the step
+            # pieces the material boundary would otherwise split off.
             def keep_segment(x0: float, y0: float, x1: float, y1: float) -> bool:
                 radius_0 = math.hypot(x0 - center_x, y0 - center_y)
                 radius_1 = math.hypot(x1 - center_x, y1 - center_y)
                 if abs(radius_1 - radius_0) > fil_width * 0.25:
-                    return False  # radial step between rings: travel only
+                    return False  # radial jump between rings: travel only
                 if infill_keep is None:
                     return True
-                ring = round((outer_radius - (radius_0 + radius_1) / 2.0) / fil_width)
+                radius_mid = (radius_0 + radius_1) / 2.0
+                if any(abs(radius_mid - wall) <= fil_width * 0.25 for wall in wall_radii):
+                    return True  # perimeter walls always print, like contours
+                ring = round(radius_mid / fil_width - 0.5)
                 return infill_keep(max(0, int(ring)))
 
             segments = _classify_polyline(points, valve, keep_segment=keep_segment)
@@ -1420,6 +1449,17 @@ def _stack_center(stack: LayerStack) -> tuple[float, float]:
     return ((x_min + x_max) / 2.0, (y_min + y_max) / 2.0)
 
 
+def _alignment_center(stack: LayerStack) -> tuple[float, float]:
+    """The point a stack is centred by: its multi-material group frame's
+    centre when it belongs to a group, else its own bbox centre. Group
+    members share one frame, so they all get the same delta and keep their
+    modelled positions relative to each other."""
+    if stack.align_frame is not None:
+        x_min, y_min, x_max, y_max = stack.align_frame
+        return ((x_min + x_max) / 2.0, (y_min + y_max) / 2.0)
+    return _stack_center(stack)
+
+
 def _snap_to_grid(value: float, grid: float | None) -> float:
     if not grid or grid <= 0.0:
         return value
@@ -1446,6 +1486,11 @@ def _centering_delta(stack: LayerStack, reference: LayerStack) -> tuple[float, f
     nozzle spacing — come out uniform across all pieces, whereas snapping the
     centres would wobble by up to one fil where the last cell's width (and so
     its centre phase) differs.
+
+    Multi-material group members (stacks carrying a shared `align_frame`)
+    are aligned by the group frame's centre instead of their own bbox
+    centre: every member gets the same delta, so the group moves as one
+    rigid unit and parts keep their modelled relative positions.
     """
     grid = reference.align_grid
     if (
@@ -1467,7 +1512,7 @@ def _centering_delta(stack: LayerStack, reference: LayerStack) -> tuple[float, f
         reference_x, reference_y = reference.align_center
     else:
         reference_x, reference_y = _stack_center(reference)
-    center_x, center_y = _stack_center(stack)
+    center_x, center_y = _alignment_center(stack)
     return (
         _snap_to_grid(reference_x - center_x, grid),
         _snap_to_grid(reference_y - center_y, grid),
@@ -1498,11 +1543,18 @@ def build_reference_stack(
     stacks: list[LayerStack | None],
     grid: float | None = None,
 ) -> LayerStack | None:
-    """Union all shapes into one shared motion stack, bbox-centres aligned.
+    """Union all shapes into one shared motion stack, alignment-centres aligned.
 
     Vector analog of the old centered "black wins" TIFF merge: every stack is
-    translated so its XY bbox centre lands on the first stack's centre, then
-    each layer is the union of the translated layers.
+    translated so its alignment centre (its own XY bbox centre, or its
+    multi-material group frame's centre — see `_alignment_center`) lands on
+    the first stack's alignment centre, then each layer is the union of the
+    translated layers. Multi-material group members share one frame, so the
+    group translates as a rigid unit and its parts keep their modelled
+    relative positions; the group holding the first stack does not move at
+    all. Group members should be sliced on one common Z grid so layer indices
+    line up; a part that starts higher simply contributes nothing to the
+    lower layers.
 
     `grid` (the fil width) snaps each translation to grid multiples so every
     shape's world scan-grid phase survives the alignment — required for split
@@ -1515,7 +1567,7 @@ def build_reference_stack(
         return None
 
     n_layers = max(len(stack.layers) for stack in valid)
-    reference_x, reference_y = _stack_center(valid[0])
+    reference_x, reference_y = _alignment_center(valid[0])
     target = LayerStack(
         layers=[],
         z_values=[],
@@ -1623,20 +1675,11 @@ def _shifted_split_edges(
     return adjusted
 
 
-def _clip_contour_paths(
-    source_lines: object,
-    cell: object,
-) -> list[list[tuple[float, float]]]:
-    """Contour polylines of a split piece: the parent outline inside the cell.
-
-    Clipping the PARENT's boundary linework (instead of taking the piece
-    polygon's own boundary) excludes the cut seams between sibling pieces —
-    only the true outer surface remains. Results are merged into maximal
-    polylines and ordered/oriented deterministically so pieces sharing
-    reference motion trace them identically.
-    """
-    clipped = source_lines.intersection(cell)
-    pieces = list(_iter_linestrings(clipped))
+def _linework_to_paths(geometry: object) -> list[list[tuple[float, float]]]:
+    """Merge linework into maximal polylines, ordered/oriented
+    deterministically so shapes sharing reference motion trace them
+    identically. Open paths allowed; closed rings keep first == last."""
+    pieces = list(_iter_linestrings(geometry))
     if not pieces:
         return []
     merged = linemerge(MultiLineString(pieces)) if len(pieces) > 1 else pieces[0]
@@ -1661,6 +1704,53 @@ def _clip_contour_paths(
     return paths
 
 
+def _clip_contour_paths(
+    source_lines: object,
+    cell: object,
+) -> list[list[tuple[float, float]]]:
+    """Contour polylines of a split piece: the parent outline inside the cell.
+
+    Clipping the PARENT's boundary linework (instead of taking the piece
+    polygon's own boundary) excludes the cut seams between sibling pieces —
+    only the true outer surface remains.
+    """
+    return _linework_to_paths(source_lines.intersection(cell))
+
+
+def group_contour_paths(
+    member: LayerStack,
+    siblings: list[LayerStack],
+    tolerance: float,
+) -> list[list[list[tuple[float, float]]]]:
+    """Per-layer seam-free contour polylines for one multi-material member.
+
+    Parts sharing a nozzle assemble into ONE shape, so where a member's
+    boundary meets a sibling material — or comes within `tolerance` of it
+    (fit gaps between materials) — that edge is an internal interface, not a
+    printable surface. Only the member boundary on the assembly's true
+    outside is kept; a member fully embedded in the assembly gets no
+    contours at all. Members should share one Z grid so layer indices align.
+    """
+    tolerance = max(float(tolerance), EPS)
+    contour_paths: list[list[list[tuple[float, float]]]] = []
+    for layer_number, layer in enumerate(member.layers):
+        if layer is None or layer.is_empty:
+            contour_paths.append([])
+            continue
+        sibling_parts = [
+            sibling.layers[layer_number]
+            for sibling in siblings
+            if layer_number < len(sibling.layers)
+            and sibling.layers[layer_number] is not None
+            and not sibling.layers[layer_number].is_empty
+        ]
+        boundary = layer.boundary
+        if sibling_parts:
+            boundary = boundary.difference(unary_union(sibling_parts).buffer(tolerance))
+        contour_paths.append(_linework_to_paths(boundary))
+    return contour_paths
+
+
 def split_layer_stack_grid(
     stack: LayerStack,
     columns: int,
@@ -1668,6 +1758,7 @@ def split_layer_stack_grid(
     overlapping_layers: bool = False,
     overlap: float = 0.0,
     grid: float | None = None,
+    frame: tuple[float, float, float, float] | None = None,
 ) -> list[LayerStack]:
     """Split a sliced shape into a rows x columns grid of piece stacks.
 
@@ -1677,10 +1768,17 @@ def split_layer_stack_grid(
     pieces interlock. `grid` (the fil width) sizes the cells in whole grid
     multiples (see `_base_split_edges`). Piece `bounds` are the nominal
     (un-shifted) cell boxes.
+
+    `frame` overrides the XY box the cell grid is computed over. Splitting
+    every member of a multi-material group with the group's combined bounds
+    as the frame clips all materials by the SAME cells (and one shared scan
+    frame), so cell-mates assemble exactly.
     """
     columns = max(1, int(columns))
     rows = max(1, int(rows))
     (x_min, y_min, z_min), (x_max, y_max, z_max) = stack.bounds
+    if frame is not None:
+        x_min, y_min, x_max, y_max = (float(value) for value in frame)
 
     overlap_x = overlap if (overlapping_layers and columns > 1) else 0.0
     overlap_y = overlap if (overlapping_layers and rows > 1) else 0.0