Step circle spiral by whole rings and make lead-in per shape

- Circle spiral prints concentric circles: each revolution holds a constant
radius (smooth walls) and steps inward by exactly one fil width; the step
segments and the final dive to the centre travel with the valve shut,
including step pieces clipped by the material boundary at the edges
- Lead-in gains a direction option (Left/Right/Up/Down) and a return route
that exits the patch laterally and comes home through the clearance lane,
never dragging the primed nozzle across the wet purge lines
- For grid splits the lead-in clearance auto-extends by the assembly's
remaining extent along the purge axis, so under shared reference motion
every nozzle's purge patch lands clear of the whole assembled part
- Lead-in is now controlled solely by a per-shape "Lead In" column in Shape
Settings (opt-in): unchecked heads traverse the shared patch valve-off to
stay in sync, or skip it entirely when printing without shared motion;
the global checkbox is replaced by an always-available options accordion

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

README.md

@@ -92,9 +92,10 @@ The **Multi-Nozzle Split** accordion on the **Shapes & Slicing** tab can split o
 - Generated files include pressure preset commands and WAGO valve commands based on the selected pressure, valve, and port; the nozzle number controls layout/spacing assignment.
 - Pressure increases by `0.1` psi per layer by default.
 - **Use G1 for all moves**: when enabled, every movement line is emitted as `G1` (no `G0` rapid travel); the WAGO valve still marks where material is dispensed. Applies to all shapes.
+- **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` uses a shrinking circular spiral from the layer bounds toward the center, 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 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.
 - **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).
 

app.py

@@ -37,6 +37,8 @@ from stl_slicer import (
 )
 from vector_gcode import generate_vector_gcode
 from vector_toolpath import (
+    LEAD_IN_DIRECTION_CHOICES,
+    LEAD_IN_DIRECTION_LEFT,
     RASTER_PATTERN_CHOICES,
     RASTER_PATTERN_SAME_DIRECTION,
     RASTER_PATTERN_Y_DIRECTION,
@@ -1362,6 +1364,7 @@ SHAPE_SETTINGS_HEADERS = [
     "Color",
     "Infill %",
     "Contour Tracing",
+    "Lead In",
     "Delete",
 ]
 SHAPE_SETTINGS_DATATYPES = [
@@ -1377,6 +1380,7 @@ SHAPE_SETTINGS_DATATYPES = [
     "str",
     "number",
     "bool",
+    "bool",
     "str",
 ]
 ADVANCED_NOZZLE_SPACING_HEADERS = [
@@ -1525,6 +1529,7 @@ def _records_from_files(files: Any, previous_records: list[dict] | None = None)
             "color": previous.get("color", _default_color(index)),
             "infill": previous.get("infill", 100.0),
             "contour_tracing": previous.get("contour_tracing", False),
+            "lead_in": previous.get("lead_in", False),
             "layer_stack": previous.get("layer_stack"),
             "slice_params": previous.get("slice_params"),
             "gcode_path": previous.get("gcode_path"),
@@ -1556,6 +1561,7 @@ def _shape_settings_rows(records: list[dict]) -> list[list[Any]]:
             record.get("color", _default_color(record["idx"])),
             _coerce_float(record.get("infill", 100.0), 100.0),
             bool(record.get("contour_tracing", False)),
+            bool(record.get("lead_in", False)),
             "Delete",
         ]
         for record in records
@@ -1624,6 +1630,11 @@ def _apply_shape_settings(records: list[dict], settings_table: Any) -> list[dict
                 copy["contour_tracing"] = _coerce_bool(row[contour_pos], bool(copy.get("contour_tracing", False)))
             except IndexError:
                 copy["contour_tracing"] = bool(copy.get("contour_tracing", False))
+            lead_in_pos = contour_pos + 1
+            try:
+                copy["lead_in"] = _coerce_bool(row[lead_in_pos], bool(copy.get("lead_in", False)))
+            except IndexError:
+                copy["lead_in"] = bool(copy.get("lead_in", False))
         updated.append(copy)
     return updated
 
@@ -1991,10 +2002,6 @@ def update_nozzle_grid_preset(
     return gr.update(value=max(1, _coerce_int(columns, 1))), gr.update(value=max(1, _coerce_int(rows, 1)))
 
 
-def update_lead_in_options_visibility(enabled: bool | None) -> dict[str, Any]:
-    return gr.update(visible=bool(enabled))
-
-
 def _dropdown_update(records: list[dict], selected: str | None = None) -> dict[str, Any]:
     choices = [_shape_choice(record) for record in records]
     value = selected if selected in choices else (choices[0] if choices else None)
@@ -2449,6 +2456,35 @@ def _ensure_records_sliced(
     return resliced
 
 
+def _lead_in_assembly_extension(records: list[dict], direction: str | None) -> float:
+    """Extra lead-in clearance so split pieces purge clear of the assembly.
+
+    Under shared reference motion every head executes the same lead-in
+    offset, so head k's purge patch lands one cell over from head k-1's -
+    right on a sibling's print area - unless the clearance exceeds the
+    assembly's remaining extent along the purge axis. The split cells are
+    equal sized, so that extent is (count - 1) * cell for the deepest piece.
+    Returned as one batch-wide value (the max over all split pieces) so
+    every shape's lead-in stays identical and the shared motion stays in
+    sync.
+    """
+    axis = 0 if (direction or LEAD_IN_DIRECTION_LEFT) in ("Left", "Right") else 1
+    extension = 0.0
+    for record in records:
+        if not record.get("split_group_id"):
+            continue
+        stack = record.get("layer_stack")
+        if stack is None:
+            continue
+        (min_x, min_y, _z_min), (max_x, max_y, _z_max) = stack.bounds
+        cell = (max_x - min_x) if axis == 0 else (max_y - min_y)
+        count = _coerce_int(
+            record.get("split_columns" if axis == 0 else "split_rows"), 1
+        )
+        extension = max(extension, cell * max(0, count - 1))
+    return extension
+
+
 def generate_dynamic_gcode(
     records: list[dict] | None,
     settings_table: Any,
@@ -2456,10 +2492,10 @@ def generate_dynamic_gcode(
     use_reference_motion: bool,
     raster_pattern: str | None,
     pressure_ramp_enabled: bool,
-    lead_in_enabled: bool,
     lead_in_length: float,
     lead_in_clearance: float,
     lead_in_lines: float,
+    lead_in_direction: str | None,
     ref_layers: LayerStack | None,
     layer_height: float,
     fil_width: float,
@@ -2478,6 +2514,19 @@ def generate_dynamic_gcode(
     if contour_sources:
         enabled = ", ".join(f"Shape {source.owner_idx}" for source in contour_sources)
         messages.append(f"Contour tracing enabled for {enabled}.")
+    # Lead-in is driven entirely by the per-shape "Lead In" column: the
+    # purge motion exists whenever any shape dispenses it (all heads must
+    # share the motion), and each shape's own flag gates its valve.
+    lead_in_enabled = any(record.get("lead_in") for record in records)
+    effective_lead_in_clearance = float(lead_in_clearance or 0.0)
+    if lead_in_enabled:
+        lead_in_extension = _lead_in_assembly_extension(records, lead_in_direction)
+        if lead_in_extension > 0.0:
+            effective_lead_in_clearance += lead_in_extension
+            messages.append(
+                f"Lead-in clearance extended by {lead_in_extension:.1f} mm so every "
+                "nozzle's purge patch lands clear of the split assembly."
+            )
     for record in records:
         stack = record.get("layer_stack")
         if stack is None or not getattr(stack, "layers", None):
@@ -2505,8 +2554,10 @@ def generate_dynamic_gcode(
                 infill=_coerce_float(record.get("infill", 100.0), 100.0) / 100.0,
                 lead_in_enabled=bool(lead_in_enabled),
                 lead_in_length=float(lead_in_length),
-                lead_in_clearance=float(lead_in_clearance),
+                lead_in_clearance=effective_lead_in_clearance,
                 lead_in_lines=max(1, _coerce_int(lead_in_lines, 3)),
+                lead_in_direction=lead_in_direction or LEAD_IN_DIRECTION_LEFT,
+                lead_in_dispense=bool(record.get("lead_in", True)),
             )
             record["gcode_path"] = str(gcode_path)
             messages.append(f"Shape {record['idx']}: wrote `{gcode_path.name}`.")
@@ -2842,12 +2893,18 @@ def build_dynamic_demo() -> gr.Blocks:
                 value=RASTER_PATTERN_SAME_DIRECTION,
                 allow_custom_value=False,
             )
-            gcode_lead_in_enabled = gr.Checkbox(label="Lead In", value=False)
-            with gr.Group(visible=False) as gcode_lead_in_options_group:
+            with gr.Accordion("Lead In Options", open=False, elem_classes=["settings-accordion"]):
+                gr.Markdown("Applies to shapes with **Lead In** checked in the Shape Settings table.")
                 with gr.Row():
                     gcode_lead_in_length = gr.Number(label="Lead In Length (mm)", value=5.0, minimum=0.1, step=0.1)
                     gcode_lead_in_clearance = gr.Number(label="Lead In Clearance (mm)", value=5.0, minimum=0.0, step=0.1)
                     gcode_lead_in_lines = gr.Number(label="Lead In Raster Lines", value=3, minimum=1, step=1)
+                    gcode_lead_in_direction = gr.Dropdown(
+                        label="Lead In Direction",
+                        choices=list(LEAD_IN_DIRECTION_CHOICES),
+                        value=LEAD_IN_DIRECTION_LEFT,
+                        allow_custom_value=False,
+                    )
             gcode_button = gr.Button("Generate G-Code", variant="primary")
             gcode_downloads = gr.File(label="Download G-Code Files", file_count="multiple", interactive=False, elem_classes=["gcode-download"])
             gcode_status = gr.Markdown("")
@@ -3119,10 +3176,10 @@ def build_dynamic_demo() -> gr.Blocks:
                 gcode_use_ref_motion,
                 gcode_raster_pattern,
                 gcode_pressure_ramp_enabled,
-                gcode_lead_in_enabled,
                 gcode_lead_in_length,
                 gcode_lead_in_clearance,
                 gcode_lead_in_lines,
+                gcode_lead_in_direction,
                 ref_layers,
                 layer_height,
                 fil_width,
@@ -3134,12 +3191,6 @@ def build_dynamic_demo() -> gr.Blocks:
             inputs=[shape_records, gcode_text_source],
             outputs=[gcode_text],
         )
-        gcode_lead_in_enabled.change(
-            fn=update_lead_in_options_visibility,
-            inputs=[gcode_lead_in_enabled],
-            outputs=[gcode_lead_in_options_group],
-            queue=False,
-        )
         gcode_text_source.change(fn=load_selected_gcode_text, inputs=[shape_records, gcode_text_source], outputs=[gcode_text])
         refresh_gcode_text_button.click(fn=load_selected_gcode_text, inputs=[shape_records, gcode_text_source], outputs=[gcode_text])
         auto_align_split_parts_button.click(

tests/test_nozzle_spacing.py

@@ -111,18 +111,24 @@ def test_shape_settings_round_trip_contour_tracing_column() -> None:
 
     rows = _shape_settings_rows(records)
     assert SHAPE_SETTINGS_HEADERS[6:9] == ["Valve", "Nozzle", "Port"]
-    assert SHAPE_SETTINGS_HEADERS[-2:] == ["Contour Tracing", "Delete"]
+    assert SHAPE_SETTINGS_HEADERS[-3:] == ["Contour Tracing", "Lead In", "Delete"]
+    contour_pos = SHAPE_SETTINGS_HEADERS.index("Contour Tracing")
+    lead_in_pos = SHAPE_SETTINGS_HEADERS.index("Lead In")
     assert rows[0][6:9] == [4, 1, 1]
-    assert rows[0][-2:] == [False, "Delete"]
+    assert rows[0][contour_pos] is False
+    assert rows[0][lead_in_pos] is False  # lead-in is opt-in per shape
+    assert rows[0][-1] == "Delete"
 
     rows[0][7] = 3
     rows[0][8] = 2
-    rows[0][-2] = True
+    rows[0][contour_pos] = True
+    rows[0][lead_in_pos] = True
     updated = _apply_shape_settings(records, rows)
 
     assert updated[0]["nozzle"] == 3
     assert updated[0]["port"] == 2
     assert updated[0]["contour_tracing"] is True
+    assert updated[0]["lead_in"] is True
 
 
 def test_shape_settings_round_trip_infill_column() -> None:
@@ -158,6 +164,45 @@ def test_shape_settings_round_trip_infill_column() -> None:
     assert _apply_shape_settings(records, rows)[0]["infill"] == 0.0
 
 
+def test_lead_in_assembly_extension_covers_the_split_extent() -> None:
+    from shapely.geometry import MultiPolygon, box
+
+    from app import _lead_in_assembly_extension
+    from stl_slicer import LayerStack
+    from vector_toolpath import split_layer_stack_grid
+
+    layer = MultiPolygon([box(0.0, 0.0, 9.0, 4.0)])
+    stack = LayerStack(
+        layers=[layer],
+        z_values=[0.5],
+        bounds=((0.0, 0.0, 0.0), (9.0, 4.0, 1.0)),
+        layer_height=1.0,
+        name="bar",
+    )
+    pieces = split_layer_stack_grid(stack, 3, 1, grid=1.0)
+    records = [
+        {
+            "idx": index + 1,
+            "layer_stack": piece,
+            "split_group_id": "g",
+            "split_columns": 3,
+            "split_rows": 1,
+        }
+        for index, piece in enumerate(pieces)
+    ]
+
+    # Purging along the split axis must clear (count-1) cells; there is only
+    # one row, so the perpendicular directions need no extension.
+    cell_width = pieces[0].bounds[1][0] - pieces[0].bounds[0][0]
+    assert _lead_in_assembly_extension(records, "Left") == cell_width * 2
+    assert _lead_in_assembly_extension(records, "Right") == cell_width * 2
+    assert _lead_in_assembly_extension(records, "Up") == 0.0
+    assert _lead_in_assembly_extension(records, "Down") == 0.0
+
+    # Whole (unsplit) shapes never extend.
+    assert _lead_in_assembly_extension([{"idx": 1}], "Left") == 0.0
+
+
 def test_contour_tracing_sources_use_sliced_layer_stacks() -> None:
     from shapely.geometry import MultiPolygon, box
 

tests/test_vector_gcode.py

@@ -219,25 +219,136 @@ def test_gcode_lead_in_runs_once_before_first_layer(tmp_path) -> None:
 
     moves = _moves_with_colors(gcode_path.read_text())
 
-    assert moves[:7] == [
+    assert moves[:9] == [
         {"start": (0.0, 0.0, 0.0), "end": (-7.0, 0.0, 0.0), "color": 0},
         {"start": (-7.0, 0.0, 0.0), "end": (-4.0, 0.0, 0.0), "color": 255},
         {"start": (-4.0, 0.0, 0.0), "end": (-4.0, 0.5, 0.0), "color": 0},
         {"start": (-4.0, 0.5, 0.0), "end": (-7.0, 0.5, 0.0), "color": 255},
         {"start": (-7.0, 0.5, 0.0), "end": (-7.0, 1.0, 0.0), "color": 0},
         {"start": (-7.0, 1.0, 0.0), "end": (-4.0, 1.0, 0.0), "color": 255},
-        {"start": (-4.0, 1.0, 0.0), "end": (0.0, 0.0, 0.0), "color": 0},
+        # Return route: exit the patch one spacing to the outside, travel
+        # home through the clearance lane, then step onto the start point —
+        # never dragging the primed nozzle back across the purge lines.
+        {"start": (-4.0, 1.0, 0.0), "end": (-4.0, -0.5, 0.0), "color": 0},
+        {"start": (-4.0, -0.5, 0.0), "end": (0.0, -0.5, 0.0), "color": 0},
+        {"start": (0.0, -0.5, 0.0), "end": (0.0, 0.0, 0.0), "color": 0},
     ]
-    assert all(move["end"][2] == 0.0 for move in moves[:7])
+    assert all(move["end"][2] == 0.0 for move in moves[:9])
 
     first_z_index = next(index for index, move in enumerate(moves) if move["end"][2] > 0.0)
-    assert first_z_index > 7
+    assert first_z_index > 9
     assert not any(
         move["start"][0] < -3.0 or move["end"][0] < -3.0
         for move in moves[first_z_index:]
     )
 
 
+def test_gcode_lead_in_direction_points_the_purge_patch(tmp_path) -> None:
+    from vector_toolpath import LEAD_IN_DIRECTION_UP
+
+    gcode_path = generate_vector_gcode(
+        _stack(box(0.0, 0.0, 0.5, 0.5)),
+        shape_name="lead_in_up",
+        pressure=25,
+        valve=7,
+        port=3,
+        fil_width=0.5,
+        lead_in_enabled=True,
+        lead_in_length=3.0,
+        lead_in_clearance=4.0,
+        lead_in_lines=2,
+        lead_in_direction=LEAD_IN_DIRECTION_UP,
+        output_dir=tmp_path,
+    )
+
+    moves = _moves_with_colors(gcode_path.read_text())
+    # Patch is ABOVE the start: first travel goes +7 in Y, purge strokes are
+    # vertical and sit in y in [4, 7]; only the half-fil-wide return lane
+    # dips to the negative lateral side.
+    assert moves[0]["end"] == (0.0, 7.0, 0.0)
+    lead_prints = [m for m in moves[:6] if m["color"] == 255]
+    assert lead_prints
+    assert all(abs(m["end"][0] - m["start"][0]) < 1e-9 for m in lead_prints)
+    assert all(
+        3.9 <= min(m["start"][1], m["end"][1]) and max(m["start"][1], m["end"][1]) <= 7.1
+        for m in lead_prints
+    )
+    assert all(m["end"][0] >= -0.5 - 1e-9 for m in moves[:9])
+
+
+def test_lead_in_opt_out_travels_shared_patch_but_skips_it_solo(tmp_path) -> None:
+    small = _stack(box(0.0, 0.0, 2.0, 2.0), name="small")
+    big = _stack(box(0.0, 0.0, 4.0, 4.0), name="big")
+    reference = build_reference_stack([small, big])
+
+    def _generate(stack: LayerStack, dispense: bool, motion, label: str):
+        path = generate_vector_gcode(
+            stack,
+            shape_name=label,
+            pressure=25,
+            valve=7,
+            port=3,
+            fil_width=1.0,
+            motion=motion,
+            lead_in_enabled=True,
+            lead_in_length=3.0,
+            lead_in_clearance=4.0,
+            lead_in_lines=3,
+            lead_in_dispense=dispense,
+            output_dir=tmp_path / label,
+        )
+        return _moves_with_colors(path.read_text())
+
+    # Shared motion: the opted-out head traverses the identical patch with
+    # the valve shut; totals and endpoints match the dispensing head exactly.
+    priming = _generate(big, True, reference, "priming")
+    passive = _generate(small, False, reference, "passive")
+    assert priming[-1]["end"] == passive[-1]["end"]
+    assert abs(_total_length(priming) - _total_length(passive)) < 1e-6
+    assert any(m["color"] == 255 for m in priming[:6])
+    assert all(m["color"] == 0 for m in passive[:9])
+
+    # Solo (no shared motion): the opted-out shape skips the lead-in
+    # entirely — its first move is the raster approach, not the purge travel.
+    solo = _generate(small, False, None, "solo")
+    with_lead = _generate(small, True, None, "with_lead")
+    assert len(solo) < len(with_lead)
+    assert solo[0]["end"] != (-7.0, 0.0, 0.0)
+    assert with_lead[0]["end"] == (-7.0, 0.0, 0.0)
+
+
+def test_gcode_lead_in_return_never_crosses_the_purge_lines(tmp_path) -> None:
+    for lines in (1, 2, 3, 4):
+        gcode_path = generate_vector_gcode(
+            _stack(box(0.0, 0.0, 0.5, 0.5)),
+            shape_name=f"lead_return_{lines}",
+            pressure=25,
+            valve=7,
+            port=3,
+            fil_width=0.5,
+            lead_in_enabled=True,
+            lead_in_length=3.0,
+            lead_in_clearance=4.0,
+            lead_in_lines=lines,
+            output_dir=tmp_path / str(lines),
+        )
+        moves = _moves_with_colors(gcode_path.read_text())
+        lead_end = next(i for i, m in enumerate(moves) if m["end"] == (0.0, 0.0, 0.0))
+        prints = [m for m in moves[: lead_end + 1] if m["color"] == 255]
+        travels = [m for m in moves[: lead_end + 1] if m["color"] == 0]
+        # No travel move's interior crosses a printed purge line: every
+        # printed line sits on a lane y = k*0.5, and travels only run along
+        # x = const (lane changes at line ends) or at y = -0.5 / y <= 0.
+        for travel in travels[1:]:
+            y0, y1 = travel["start"][1], travel["end"][1]
+            x0, x1 = travel["start"][0], travel["end"][0]
+            if abs(y1 - y0) < 1e-9 and abs(x1 - x0) > 1e-9:
+                # Horizontal travel: must be outside the printed lanes.
+                assert y0 < -1e-9 or not any(
+                    abs(p["start"][1] - y0) < 1e-9 for p in prints
+                ), (lines, travel)
+
+
 def test_gcode_pressure_ramp_can_be_disabled(tmp_path) -> None:
     stack = _stack(box(0.0, 0.0, 1.0, 1.0), box(0.0, 0.0, 1.0, 1.0))
 
@@ -561,6 +672,56 @@ def test_circle_spiral_points_decrease_radius_to_center() -> None:
     )
 
 
+def test_circle_spiral_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)
+    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]
+
+    ring_transitions = sum(
+        1
+        for previous, current in zip(radii, radii[1:])
+        if abs(current - previous) > 1e-9
+    )
+    assert ring_transitions == 5
+
+
+def test_circle_spiral_ring_steps_travel_with_valve_shut(tmp_path) -> None:
+    from gcode_viewer import parse_gcode_path
+    from vector_toolpath import RASTER_PATTERN_CIRCLE_SPIRAL
+
+    layer = box(0.0, 0.0, 10.0, 10.0)
+    gcode_path = generate_vector_gcode(
+        _stack(layer, layer),
+        shape_name="ring_steps",
+        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"]
+    center_x = center_y = 5.0
+
+    # Print moves stay on a constant-radius ring (within chord flattening);
+    # the inward steps between rings — including pieces clipped by the
+    # material boundary at the edges — are always valve-off travel.
+    worst = 0.0
+    for segment in parsed["print_segments"]:
+        for a, b in zip(segment, segment[1:]):
+            radius_a = math.hypot(a[0] + origin_x - center_x, a[1] + origin_y - center_y)
+            radius_b = math.hypot(b[0] + origin_x - center_x, b[1] + origin_y - center_y)
+            worst = max(worst, abs(radius_b - radius_a))
+    assert worst < 0.11
+
+
 def test_circle_spiral_raster_reverses_between_layers(tmp_path) -> None:
     layer = box(0.0, 0.0, 5.0, 5.0)
     gcode_path = generate_vector_gcode(

vector_gcode.py

@@ -15,6 +15,8 @@ from textwrap import wrap
 
 from stl_slicer import LayerStack
 from vector_toolpath import (
+    LEAD_IN_DIRECTION_CHOICES,
+    LEAD_IN_DIRECTION_LEFT,
     RASTER_PATTERN_CHOICES,
     RASTER_PATTERN_CIRCLE_SPIRAL,
     RASTER_PATTERN_DIAGONAL_WOODPILE,
@@ -32,6 +34,8 @@ from vector_toolpath import (
 )
 
 __all__ = [
+    "LEAD_IN_DIRECTION_CHOICES",
+    "LEAD_IN_DIRECTION_LEFT",
     "RASTER_PATTERN_CHOICES",
     "RASTER_PATTERN_CIRCLE_SPIRAL",
     "RASTER_PATTERN_DIAGONAL_WOODPILE",
@@ -205,6 +209,8 @@ def generate_vector_gcode(
     lead_in_length: float = 5.0,
     lead_in_clearance: float = 5.0,
     lead_in_lines: int = 3,
+    lead_in_direction: str = LEAD_IN_DIRECTION_LEFT,
+    lead_in_dispense: bool = True,
     output_dir: str | Path | None = None,
 ) -> Path:
     """Generate G-code for one sliced shape.
@@ -274,14 +280,18 @@ def generate_vector_gcode(
         delta_x = delta_y = 0.0
     path_origin = (toolpath_origin[0] - delta_x, toolpath_origin[1] - delta_y)
 
+    # A shape that opts out of the lead-in still TRAVELS the purge patch when
+    # motion is shared (all heads must move identically) but keeps its valve
+    # shut; printing solo, it skips the lead-in moves entirely.
     lead_in = _lead_in_moves(
-        lead_in_enabled,
+        lead_in_enabled and (lead_in_dispense or motion is not None),
         lead_in_length,
         lead_in_clearance,
         lead_in_lines,
         fil_width,
-        255,
+        255 if lead_in_dispense else 0,
         0,
+        direction=lead_in_direction,
     )
     if lead_in:
         gcode_list = [*lead_in, *gcode_list]

vector_toolpath.py

@@ -246,6 +246,7 @@ def _classify_polyline(
     valve: MultiPolygon,
     eps: float = EPS,
     keep_point=None,
+    keep_segment=None,
 ) -> list[Seg]:
     """Split a motion polyline at valve-boundary crossings and color the pieces.
 
@@ -253,7 +254,10 @@ def _classify_polyline(
     Pieces on the boundary count as printing (`covers`), matching the raster
     convention that boundary-grazing sweeps dispense. `keep_point(x, y)` can
     additionally veto dispensing for a piece (evaluated at its midpoint) —
-    used for partial infill; the motion is unaffected.
+    used for partial infill. `keep_segment(x0, y0, x1, y1)` vetoes a whole
+    source segment BEFORE it is split, so a vetoed transition move stays
+    valve-off even where the material boundary cuts through it. The motion
+    is unaffected by either gate.
     """
     segments: list[Seg] = []
     has_valve = valve is not None and not valve.is_empty
@@ -268,7 +272,9 @@ def _classify_polyline(
         if seg_len <= eps:
             continue
 
-        if not has_valve:
+        if not has_valve or (
+            keep_segment is not None and not keep_segment(x0, y0, x1, y1)
+        ):
             _append_colored_segment(segments, x0, y0, x1, y1, 0)
             continue
 
@@ -670,28 +676,35 @@ def _circle_spiral_points(
     outer_radius: float,
     pitch: float,
 ) -> list[tuple[float, float]]:
+    """Concentric-ring "spiral": full circles stepping inward by one pitch.
+
+    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.
+    """
     if outer_radius <= 0.0:
         return [(center_x, center_y)]
 
     pitch = max(float(pitch), 1e-9)
-    sample_spacing = pitch
-    theta_max = (outer_radius / pitch) * 2.0 * math.pi
-    theta = 0.0
-    points = [(center_x + outer_radius, center_y)]
-
-    while theta < theta_max:
-        radius = max(outer_radius - (pitch * theta / (2.0 * math.pi)), 0.0)
-        d_theta = min(math.pi / 10.0, sample_spacing / max(radius, pitch))
-        theta = min(theta + d_theta, theta_max)
-        radius = max(outer_radius - (pitch * theta / (2.0 * math.pi)), 0.0)
-        points.append(
-            (
-                center_x + (radius * math.cos(theta)),
-                center_y + (radius * math.sin(theta)),
+    points: list[tuple[float, float]] = []
+    radius = outer_radius
+    while radius > 1e-9:
+        # 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)))
+        for index in range(steps + 1):
+            theta = (2.0 * math.pi) * index / steps
+            points.append(
+                (
+                    center_x + (radius * math.cos(theta)),
+                    center_y + (radius * math.sin(theta)),
+                )
             )
-        )
+        radius -= pitch
 
-    if points[-1] != (center_x, center_y):
+    if not points or points[-1] != (center_x, center_y):
         points.append((center_x, center_y))
     return points
 
@@ -1074,6 +1087,31 @@ def _append_layer_contours(
     return current_x, current_y
 
 
+LEAD_IN_DIRECTION_LEFT = "Left"
+LEAD_IN_DIRECTION_RIGHT = "Right"
+LEAD_IN_DIRECTION_UP = "Up"
+LEAD_IN_DIRECTION_DOWN = "Down"
+LEAD_IN_DIRECTION_CHOICES = (
+    LEAD_IN_DIRECTION_LEFT,
+    LEAD_IN_DIRECTION_RIGHT,
+    LEAD_IN_DIRECTION_UP,
+    LEAD_IN_DIRECTION_DOWN,
+)
+# Away-from-the-part axis and the lateral line-stepping axis per direction.
+_LEAD_IN_AXES = {
+    LEAD_IN_DIRECTION_LEFT: ((-1.0, 0.0), (0.0, 1.0)),
+    LEAD_IN_DIRECTION_RIGHT: ((1.0, 0.0), (0.0, 1.0)),
+    LEAD_IN_DIRECTION_UP: ((0.0, 1.0), (1.0, 0.0)),
+    LEAD_IN_DIRECTION_DOWN: ((0.0, -1.0), (1.0, 0.0)),
+}
+
+
+def _normalize_lead_in_direction(direction: str | None) -> str:
+    if direction in _LEAD_IN_AXES:
+        return direction
+    return LEAD_IN_DIRECTION_LEFT
+
+
 def _lead_in_moves(
     enabled: bool,
     length: float,
@@ -1082,7 +1120,17 @@ def _lead_in_moves(
     line_spacing: float,
     print_color: int,
     off_color: int,
+    direction: str | None = LEAD_IN_DIRECTION_LEFT,
 ) -> list[dict]:
+    """Purge patch printed before layer 1, in the chosen direction.
+
+    The patch sits `clearance` away from the toolpath start along the purge
+    direction and snakes `line_count` strokes of `length`, stepping one
+    `line_spacing` laterally between strokes. The return route exits the
+    patch one lateral step to the OUTSIDE and comes home through virgin
+    ground, so the freshly primed nozzle never drags back across the wet
+    purge lines.
+    """
     if not enabled:
         return []
     lead_length = max(0.0, float(length))
@@ -1091,27 +1139,43 @@ def _lead_in_moves(
     lead_clearance = max(0.0, float(clearance))
     pass_count = max(1, int(line_count))
     spacing = max(0.0, float(line_spacing))
+    away, lateral = _LEAD_IN_AXES[_normalize_lead_in_direction(direction)]
 
     moves: list[dict] = []
-    current_x = 0.0
-    current_y = 0.0
+    # Patch-local frame: `a` runs along the away axis, `v` along the lateral.
+    current_a = 0.0
+    current_v = 0.0
 
-    def append_move(dx: float, dy: float, color: int) -> None:
-        nonlocal current_x, current_y
-        if dx == 0.0 and dy == 0.0:
+    def append_move(delta_a: float, delta_v: float, color: int) -> None:
+        nonlocal current_a, current_v
+        if delta_a == 0.0 and delta_v == 0.0:
             return
-        moves.append({"X": dx, "Y": dy, "Color": color})
-        current_x += dx
-        current_y += dy
+        moves.append(
+            {
+                "X": delta_a * away[0] + delta_v * lateral[0],
+                "Y": delta_a * away[1] + delta_v * lateral[1],
+                "Color": color,
+            }
+        )
+        current_a += delta_a
+        current_v += delta_v
 
-    append_move(-(lead_clearance + lead_length), 0.0, off_color)
-    direction = 1.0
+    append_move(lead_clearance + lead_length, 0.0, off_color)
+    stroke = -1.0  # first stroke prints back toward the part
     for pass_index in range(pass_count):
-        append_move(direction * lead_length, 0.0, print_color)
-        direction *= -1.0
+        append_move(stroke * lead_length, 0.0, print_color)
+        stroke *= -1.0
         if pass_index < pass_count - 1:
             append_move(0.0, spacing, off_color)
-    append_move(-current_x, -current_y, off_color)
+
+    # Return: step one spacing outside the patch laterally, travel home
+    # through the clearance lane, then step back onto the start point.
+    if spacing > 0.0:
+        append_move(0.0, -(current_v + spacing), off_color)
+        append_move(-current_a, 0.0, off_color)
+        append_move(0.0, -current_v, off_color)
+    else:
+        append_move(-current_a, -current_v, off_color)
     return moves
 
 
@@ -1165,30 +1229,36 @@ def plan_layer_moves(
                 fil_width,
                 reverse=layer_number % 2 == 1,
             )
-            keep_point = None
-            if infill_keep is not None:
-                # A spiral "line" is one revolution: revolution k lies at
-                # radius outer - k*fil from the bbox-circumscribed circle.
-                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 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),
                 )
+            )
 
-                def keep_point(x: float, y: float) -> bool:
-                    radius = math.hypot(x - center_x, y - center_y)
-                    return infill_keep(
-                        max(0, int(round((outer_radius - radius) / fil_width)))
-                    )
-
-            segments = _classify_polyline(points, valve, keep_point=keep_point)
+            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
+                if infill_keep is None:
+                    return True
+                ring = round((outer_radius - (radius_0 + radius_1) / 2.0) / fil_width)
+                return infill_keep(max(0, int(ring)))
+
+            segments = _classify_polyline(points, valve, keep_segment=keep_segment)
         elif raster_pattern == RASTER_PATTERN_RECTANGULAR_SPIRAL:
             points = _rectangular_spiral_polyline(
                 motion.bounds,