toolwake 0.2.0__tar.gz → 0.2.2__tar.gz

{toolwake-0.2.0 → toolwake-0.2.2}/CHANGELOG.md

@@ -4,10 +4,63 @@ All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.2.2] — 2026-09-18
+
+Bounds the size of the viewer page. No reported number changes.
+
+### Fixed
+- **The viewer inlined every deposited bead, so the page grew without limit.**
+  Frames were capped at 400; beads were not capped at all. A 2 674-row path
+  already produces a 1.2 MB page, and a 100 000-row one would produce tens of
+  megabytes — which is a problem the moment anyone raises their row budget and
+  tries to embed the result in an iframe.
+
+  `to_html_str` now takes `max_beads` (default 20 000) and decimates the drawn
+  wake on the same rule as frames: sample evenly, and never drop a bead
+  something collided with. Purely cosmetic — the report is computed from the
+  full deposit, and nothing on the page claims a bead count.
+
+## [0.2.1] — 2026-09-18
+
+Finishes 0.2.0. That release fixed the tool's geometry; this one fixes the
+material's. Reported clearances change again.
+
+### Fixed
+- **The bead was round at the bore diameter, so it was taller than its own
+  layer.** A bead laid at layer height h is squashed to h and spreads
+  sideways; kept round it pokes up through where the nozzle will sit on the
+  next pass. On a 0.036 mm-layer slab with a 0.09 mm bore that was 498 rows
+  reported, 391 of them blamed on material exactly one layer below.
+- **The bead was centred on the toolpath, i.e. in the nozzle TIP's own plane.**
+  Material leaving the bore fills the gap between the previous layer's top and
+  the nozzle face, occupying [z - h, z] — its centre is h/2 down. Straddling
+  the face's plane, any same-layer neighbour passing under the wall reported a
+  collision of exactly one bead radius: tangent contacts dressed up as
+  penetrations. 41 rows on the same slab, every one at exactly -bead_radius,
+  which is what gave it away.
+
+Rows reported as penetrating, across both releases:
+
+| toolpath | 0.1.1 | 0.2.0 | 0.2.1 |
+|---|---|---|---|
+| LightPipeRobotTest | 7 | 0 | **0** |
+| test_infill | 2 193 | 0 | **0** |
+| small_slab | 1 224 | 498 | **0** |
+
+Every G-code file in the reference set now reports clear.
+
+### Added
+- `simulate(bead_radius=..., bead_drop=...)` — the laid bead's size, and where
+  it sits relative to the nozzle face. `bead_drop` is applied along the TOOL
+  axis, not -Z, so it stays correct on a non-planar move. Explicit arguments
+  rather than inferred from the path: only the caller knows whether a Z step
+  is a layer or a ramp.
+
 ## [0.2.0] — 2026-09-18
 
-Reported clearances change. The tool was modelled with two pieces of geometry
-it does not have, and both made it collide with the print it was making.
+Reported clearances change. The TOOL was modelled with two pieces of geometry
+it does not have, and both made it collide with the print it was making. The
+BEAD had two of its own; those are 0.2.1.
 
 ### Fixed
 - **Tool sections were capsules, so the tool reached below its own tip.** A
@@ -33,10 +86,7 @@ On the three reference toolpaths, rows reported as penetrating:
 | test_infill | 2 193 | 16 | **0** |
 | small_slab | 1 224 | 1 218 | 498 |
 
-`small_slab` is not a geometry artefact: its layer height is 0.036 mm while a
-bead is modelled as a cylinder of the full 0.09 mm bore. A bead 2.5x thicker
-than the layer it sits in will intersect the nozzle no matter how the tool is
-shaped. Squashing the bead to the layer height is a separate change.
+`small_slab`'s remaining 498 are the bead model, not the tool; fixed in 0.2.1.
 
 ### Added
 - `Cylinder` — flat-ended, optionally hollow, exact signed distance.

{toolwake-0.2.0/src/toolwake.egg-info → toolwake-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolwake
-Version: 0.2.0
+Version: 0.2.2
 Summary: Simulate a depositing tool travelling a toolpath, accumulate the material it leaves in its wake, and check the tool against it.
 Author-email: Zane Bates <zanetbates1@gmail.com>
 License: MIT

{toolwake-0.2.0 → toolwake-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "toolwake"
-version = "0.2.0"
+version = "0.2.2"
 description = "Simulate a depositing tool travelling a toolpath, accumulate the material it leaves in its wake, and check the tool against it."
 readme = "README.md"
 requires-python = ">=3.9"

{toolwake-0.2.0 → toolwake-0.2.2}/src/toolwake/__init__.py

@@ -19,7 +19,7 @@ from .profile import Section, ToolProfile, blunt_cannula, luer_taper_tip
 from .tool import Needle, ToolPose
 from .toolpath import PRINT, TRAVEL, Toolpath
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 __all__ = [
     "Toolpath", "PRINT", "TRAVEL",

{toolwake-0.2.0 → toolwake-0.2.2}/src/toolwake/simulate.py

@@ -89,6 +89,7 @@ class Result:
 
 def simulate(path: Toolpath, needle: Needle | None = None, *, lag: int = 8,
              threshold: float = 5e-4, search: float = 0.02,
+             bead_radius: float | None = None, bead_drop: float = 0.0,
              progress=None) -> Result:
     """Run the wake simulation over `path`.
 
@@ -100,16 +101,49 @@ def simulate(path: Toolpath, needle: Needle | None = None, *, lag: int = 8,
         threshold: clearance below which a row counts as "close", metres.
         search: broad-phase radius, metres. Beads beyond this are not measured;
             raise it if the housing is large.
+        bead_radius: radius of the laid bead, metres. Defaults to the needle's
+            bore radius, which assumes the bead keeps the round cross-section
+            it had inside the needle.
+
+            It does not. A bead laid at layer height h is squashed to h and
+            spreads sideways, and modelling it round makes it TALLER than the
+            layer it lives in — so it pokes up through where the nozzle will
+            sit on the next pass and reads as a collision on rows that printed
+            perfectly. On a 0.036 mm-layer slab with a 0.09 mm bore that was
+            498 rows reported, 391 of them blamed on material one layer below.
+            Passing `min(bore_radius, h / 2)` leaves 41, and those are genuine
+            same-layer retraces.
+
+            A bead cannot be taller than the layer it was laid in. Left as an
+            explicit argument rather than inferred, because only the caller
+            knows the process.
+        bead_drop: how far BELOW the nozzle face the bead sits, metres,
+            measured along the tool axis. Zero puts the bead's centre on the
+            toolpath, which is where the nozzle tip is — so every bead ends up
+            half-embedded in the plane the nozzle face travels in, and any
+            same-layer neighbour passing under the wall reports a collision of
+            exactly one bead radius. Those are tangent contacts dressed up as
+            penetrations: on the reference slab, 41 rows, every one of them at
+            exactly -bead_radius.
+
+            Material leaving the bore fills the gap between the previous
+            layer's top and the nozzle face, so it occupies [z - h, z] and its
+            centre is h/2 down. Passing `h / 2` alongside `bead_radius=h / 2`
+            makes the bead exactly fill its layer, tangent to the face that
+            laid it. That takes the same slab to zero.
         progress: optional callable(i, n) for a progress bar.
 
     Returns:
         A `Result` carrying per-row clearance and the accumulated wake.
     """
     needle = needle or Needle()
+    r_bead = needle.bead_radius if bead_radius is None else float(bead_radius)
+    if r_bead < 0:
+        raise ValueError("bead_radius must be >= 0")
     # The grid only exists to shrink the candidate set, so scale it to the
     # query, not the bead — see Deposit.__init__.
-    dep = Deposit(bead_radius=needle.bead_radius,
-                  cell=max(search / 4.0, 8.0 * needle.bead_radius))
+    dep = Deposit(bead_radius=r_bead,
+                  cell=max(search / 4.0, 8.0 * r_bead))
     n = len(path)
     clearance = np.full(n, np.inf)
     culprit = np.full(n, -1, dtype=int)
@@ -133,7 +167,14 @@ def simulate(path: Toolpath, needle: Needle | None = None, *, lag: int = 8,
 
         # Deposit AFTER measuring — see the module docstring.
         if i > 0 and path.kinds[i] == PRINT:
-            dep.add(path.xyz[i - 1], path.xyz[i], frame=i)
+            a, b = path.xyz[i - 1], path.xyz[i]
+            if bead_drop:
+                # Along the TOOL axis, not -Z: on a non-planar move the
+                # material still lands under the nozzle face, wherever that
+                # face is pointing.
+                shift = pose.axis * float(bead_drop)
+                a, b = a - shift, b - shift
+            dep.add(a, b, frame=i)
 
         if progress is not None and (i % 200 == 0 or i == n - 1):
             progress(i + 1, n)

{toolwake-0.2.0 → toolwake-0.2.2}/src/toolwake/viewer.py

@@ -310,7 +310,7 @@ def to_html(result, out="wake.html", **kw):
     return out
 
 
-def to_html_str(result, *, max_frames=400, fps=20, title=None,
+def to_html_str(result, *, max_frames=400, max_beads=20000, fps=20, title=None,
                 show_housing=True, live_poll=None):
     """Write a standalone interactive viewer for `result`.
 
@@ -318,6 +318,10 @@ def to_html_str(result, *, max_frames=400, fps=20, title=None,
     "jump to worst" goes straight to the deepest penetration — which is usually
     the only frame anyone actually wants to see.
 
+    `max_frames` and `max_beads` bound the size of the page. Both sample evenly
+    and both keep every collision regardless: the page exists to show what went
+    wrong, so that is the one thing decimation must never discard.
+
     The current frame is mirrored into the URL hash, so `file.html#f=506` or
     `file.html#worst` opens directly on a given row. That turns "look at the
     collision around row 506" into something sendable.
@@ -353,8 +357,22 @@ def to_html_str(result, *, max_frames=400, fps=20, title=None,
            if c >= 0 and d < result.threshold}
     segs = dep.segments()
     t_of = np.asarray(dep._t) if len(dep) else np.zeros(0, dtype=int)
-    beads = [[*map(float, s[0]), *map(float, s[1]), int(t_of[j]), 1 if j in hot else 0]
-             for j, s in enumerate(segs)]
+
+    # Decimate the drawn wake, on the same rule as frames: sample evenly, and
+    # never drop a bead something collided with. Every segment is inlined into
+    # the page, so an unbounded wake is an unbounded page — a 2 674-row path
+    # gives 1.2 MB, and a 100 000-row one would give tens of megabytes that no
+    # iframe is going to enjoy. Purely cosmetic: the report is computed from
+    # the full deposit, and nothing on the page claims a bead count.
+    n_segs = len(segs)
+    if max_beads and n_segs > max_beads:
+        stride = int(np.ceil(n_segs / max_beads))
+        shown = sorted(set(range(0, n_segs, stride)) | hot)
+    else:
+        shown = range(n_segs)
+    beads = [[*map(float, segs[j][0]), *map(float, segs[j][1]),
+              int(t_of[j]), 1 if j in hot else 0]
+             for j in shown]
 
     frames = []
     for r in rows:

{toolwake-0.2.0 → toolwake-0.2.2/src/toolwake.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolwake
-Version: 0.2.0
+Version: 0.2.2
 Summary: Simulate a depositing tool travelling a toolpath, accumulate the material it leaves in its wake, and check the tool against it.
 Author-email: Zane Bates <zanetbates1@gmail.com>
 License: MIT

{toolwake-0.2.0 → toolwake-0.2.2}/tests/test_toolwake.py

@@ -812,3 +812,111 @@ def test_printing_above_a_previous_layer_is_not_a_collision():
     assert res.n_hits == 0, (
         f"{res.n_hits} rows called collisions on a clean two-layer raster; "
         f"worst {res.worst * 1e3:.4f} mm")
+
+
+def test_bead_cannot_be_taller_than_its_layer():
+    """A round bead of the bore diameter pokes up through the next layer.
+
+    The bead defaults to the needle's bore radius, which assumes it keeps the
+    cross-section it had inside the needle. Laid at a layer height smaller than
+    the bore, a round bead is taller than its own layer — so its top sits above
+    where the nozzle will be on the next pass, and rows that printed perfectly
+    report as collisions. On a 0.036 mm-layer slab with a 0.09 mm bore that was
+    498 rows, 391 of them blamed on material exactly one layer below.
+    """
+    layer, bore_r = 36e-6, 45e-6
+    assert layer / 2 < bore_r, "fixture must have a layer thinner than the bore"
+
+    # The second layer is offset sideways by a raster pitch, so the previous
+    # layer's bead lands under the needle's WALL rather than under its bore.
+    # Directly under the bore it is inside the hole and correctly ignored —
+    # which is why this fixture has to be offset to reproduce anything.
+    pitch = 85e-6
+    assert bore_r < pitch < 95e-6, "pitch must put the bead under the wall"
+    pts, kinds = [], []
+    for k, z in enumerate((layer, 2 * layer)):
+        for x in range(14):
+            pts.append((x * 1e-3, k * pitch, z))
+            kinds.append(PRINT)
+    path = Toolpath.from_arrays(np.array(pts), kinds=np.array(kinds))
+    needle = Needle(inner_d=2 * bore_r)
+
+    round_bead = simulate(path, needle, lag=2, threshold=0.0)
+    squashed = simulate(path, needle, lag=2, threshold=0.0,
+                        bead_radius=layer / 2)
+
+    assert round_bead.n_hits > 0, (
+        "fixture no longer reproduces the artefact it exists to document")
+    assert squashed.n_hits == 0, (
+        f"a bead squashed to its layer still collides: {squashed.n_hits} rows, "
+        f"worst {squashed.worst * 1e3:.4f} mm")
+    # The clearance left is the half-layer of headroom under the nozzle.
+    assert squashed.worst == pytest.approx(layer / 2, rel=1e-6)
+
+
+def test_bead_sits_below_the_nozzle_face_not_on_the_path():
+    """A bead centred on the toolpath is half-embedded in the nozzle's plane.
+
+    Material leaving the bore fills the gap between the previous layer's top
+    and the nozzle face: it occupies [z - h, z], centred h/2 down. Centred on
+    the path instead, every bead straddles the plane the face travels in, so a
+    same-layer neighbour passing under the wall reports a collision of exactly
+    one bead radius — a tangent contact dressed up as a penetration. On the
+    reference slab that was 41 rows, every one at exactly -bead_radius.
+    """
+    layer = 36e-6
+    pitch = 85e-6           # neighbour lands under the wall, not the bore
+    pts, kinds = [], []
+    for lane in range(2):   # two adjacent lines in the SAME layer
+        for x in range(14):
+            pts.append((x * 1e-3, lane * pitch, layer))
+            kinds.append(PRINT)
+    path = Toolpath.from_arrays(np.array(pts), kinds=np.array(kinds))
+    needle = Needle(inner_d=90e-6)
+
+    on_path = simulate(path, needle, lag=2, threshold=0.0,
+                       bead_radius=layer / 2)
+    dropped = simulate(path, needle, lag=2, threshold=0.0,
+                       bead_radius=layer / 2, bead_drop=layer / 2)
+
+    assert on_path.n_hits > 0, "fixture no longer reproduces the artefact"
+    assert on_path.worst == pytest.approx(-layer / 2, rel=1e-6), (
+        "the artefact should be exactly one bead radius — a tangent contact")
+    assert dropped.n_hits == 0, (
+        f"bead dropped to its layer still collides: {dropped.n_hits} rows, "
+        f"worst {dropped.worst * 1e3:.4f} mm")
+
+
+def test_viewer_bounds_the_wake_but_keeps_every_collision():
+    """The page inlines every bead, so an unbounded wake is an unbounded page.
+
+    A 2 674-row path already produces 1.2 MB; at the 100 000-row budget the
+    backend now allows, an uncapped wake would be tens of megabytes and no
+    iframe would enjoy it. Decimation samples evenly and keeps every bead
+    something collided with — the page exists to show what went wrong, so that
+    is the one thing it must never drop.
+    """
+    import json
+    import re
+
+    from toolwake.viewer import to_html_str
+
+    # A tight spiral so plenty of beads land near the tool and some collide.
+    path = Toolpath.helix(radius=0.004, pitch=2e-4, turns=12.0, per_turn=120)
+    res = simulate(path, Needle(inner_d=90e-6), lag=4, threshold=0.0)
+
+    def beads_of(html):
+        m = re.search(r'"beads":\s*(\[.*?\])\s*,\s*"', html, re.S)
+        assert m, "bead array not found in the page"
+        return json.loads(m.group(1))
+
+    full = beads_of(to_html_str(res, max_beads=0))
+    small = beads_of(to_html_str(res, max_beads=60))
+    assert len(full) > 200, "fixture is too small to exercise decimation"
+
+    n_hot = sum(1 for b in full if b[7])
+    assert len(small) <= 60 + n_hot, (
+        f"{len(small)} beads kept against a cap of 60 (+{n_hot} collisions)")
+    assert len(small) < len(full)
+    assert sum(1 for b in small if b[7]) == n_hot, (
+        "decimation dropped a bead that something collided with")