toolwake 0.1.0__py3-none-any.whl

toolwake/__init__.py

@@ -0,0 +1,51 @@
+"""toolwake — simulate a depositing tool, accumulate its wake, check against it.
+
+    from toolwake import Toolpath, Needle, simulate, animate
+
+    path = Toolpath.helix(radius=0.02, pitch=0.004, turns=6)
+    res  = simulate(path, Needle(inner_d=90e-6, housing=(0.130, 0.075, 0.072)))
+    print(res.report())
+    animate(res, "wake.mp4")
+
+The wake the video draws and the wake the clearance numbers are measured
+against are the same object, so the picture cannot disagree with the report.
+"""
+from .deposit import Deposit
+from .geometry import (Box, Capsule, rotation_from_rotvec,
+                       rotvec_from_axis)
+from .simulate import Result, simulate
+from .viewer import to_html_str
+from .profile import Section, ToolProfile, blunt_cannula, luer_taper_tip
+from .tool import Needle, ToolPose
+from .toolpath import PRINT, TRAVEL, Toolpath
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Toolpath", "PRINT", "TRAVEL",
+    "Needle", "ToolPose",
+    "Section", "ToolProfile", "blunt_cannula", "luer_taper_tip",
+    "Deposit",
+    "Capsule", "Box", "rotation_from_rotvec", "rotvec_from_axis",
+    "simulate", "Result",
+    "animate", "to_html", "to_html_str", "ToolwakeSession",
+    "__version__",
+]
+
+
+def animate(*args, **kwargs):
+    """Render a Result to video. Imported lazily so matplotlib stays optional."""
+    from .render import animate as _animate
+    return _animate(*args, **kwargs)
+
+
+def ToolwakeSession(*args, **kwargs):
+    """A re-checkable simulation served as HTML, for embedding in another GUI."""
+    from .serve import ToolwakeSession as _S
+    return _S(*args, **kwargs)
+
+
+def to_html(*args, **kwargs):
+    """Write a standalone interactive viewer. No dependencies beyond numpy."""
+    from .viewer import to_html as _to_html
+    return _to_html(*args, **kwargs)

toolwake/cli.py

@@ -0,0 +1,75 @@
+"""Command line: toolwake render <path> -o out.mp4"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .simulate import simulate
+from .tool import Needle
+from .toolpath import Toolpath
+
+
+def _bar(label):
+    def show(i, n):
+        pct = 100.0 * i / n
+        sys.stderr.write(f"\r  {label}: {pct:5.1f}%  ({i}/{n})")
+        if i >= n:
+            sys.stderr.write("\n")
+        sys.stderr.flush()
+    return show
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="toolwake",
+        description="Simulate a depositing tool and the wake it leaves behind.")
+    p.add_argument("source", help="a .gcode file, or 'helix' for the built-in demo")
+    p.add_argument("-o", "--out", default="wake.mp4",
+                   help="video output (.mp4 needs ffmpeg, .gif does not)")
+    p.add_argument("--inner-d", type=float, default=90e-6, help="needle ID, m")
+    p.add_argument("--outer-d", type=float, default=None, help="needle OD, m")
+    p.add_argument("--length", type=float, default=12.7e-3, help="needle length, m")
+    p.add_argument("--housing", type=float, nargs=3, default=None,
+                   metavar=("X", "Y", "Z"), help="end-effector extents, m")
+    p.add_argument("--lag", type=int, default=8,
+                   help="rows of immunity behind the nozzle")
+    p.add_argument("--threshold", type=float, default=5e-4,
+                   help="clearance below which a row is 'close', m")
+    p.add_argument("--max-frames", type=int, default=600)
+    p.add_argument("--fps", type=int, default=30)
+    p.add_argument("--report", default=None, help="write the JSON report here")
+    p.add_argument("--html", default=None,
+                   help="write a standalone interactive viewer here")
+    p.add_argument("--no-video", action="store_true", help="skip the video")
+    a = p.parse_args(argv)
+
+    path = (Toolpath.helix() if a.source == "helix"
+            else Toolpath.from_gcode(a.source))
+    print(f"  {path!r}", file=sys.stderr)
+
+    needle = Needle(inner_d=a.inner_d, outer_d=a.outer_d, length=a.length,
+                    housing=a.housing)
+    res = simulate(path, needle, lag=a.lag, threshold=a.threshold,
+                   progress=_bar("sweep"))
+    rep = res.report()
+    print(json.dumps(rep, indent=2))
+    if a.report:
+        with open(a.report, "w") as fh:
+            json.dump(rep, fh, indent=2)
+
+    if a.html:
+        from .viewer import to_html
+        print(f"  wrote {to_html(res, a.html)}", file=sys.stderr)
+
+    if not a.no_video:
+        from .render import animate
+        out = animate(res, a.out, fps=a.fps, max_frames=a.max_frames,
+                      progress=_bar("render"))
+        print(f"  wrote {out}", file=sys.stderr)
+
+    return 2 if rep["status"] == "collision" else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

toolwake/deposit.py

@@ -0,0 +1,150 @@
+"""The wake: material already laid down, and how to ask what is near it.
+
+Two-phase by design.
+
+  Broad phase  — a uniform spatial hash (a voxel grid holding segment indices).
+                 O(1) lookup, answers "which beads could possibly be near here".
+  Narrow phase — exact capsule distance to those candidate beads only.
+
+A plain occupancy grid would give a binary answer quantised to the voxel size;
+keeping the segments and measuring against them means the clearance number in
+the report is a real distance, not a voxel count. The grid exists purely to
+avoid testing every bead against every tool pose.
+
+Time ordering is the other reason this class exists. Material can only obstruct
+the tool if it was deposited EARLIER, and not so recently that it is still
+under the nozzle. `add` appends in path order and `query` takes the frame index,
+so the trailing-window rule lives in one place instead of at every call site.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["Deposit"]
+
+
+class Deposit:
+    """Accumulates deposited bead segments and answers clearance queries.
+
+    Args:
+        bead_radius: radius of the laid bead, metres. For a well-tuned print
+            this is about half the needle inner diameter.
+        cell: spatial-hash cell size, metres. This wants to be on the order of
+            the QUERY radius, not the bead. Sized to the bead (45 um) against a
+            20 mm search, a single lookup walks 41^3 = 69k cells and the sweep
+            crawls; at 5 mm it walks 9^3 = 729. Callers that know their search
+            radius should pass `search / 4`.
+    """
+
+    def __init__(self, bead_radius: float, cell: float | None = None):
+        if bead_radius < 0:
+            raise ValueError("bead_radius must be >= 0")
+        self.bead_radius = float(bead_radius)
+        self.cell = float(cell) if cell else max(8.0 * self.bead_radius, 5e-3)
+        self._a: list[np.ndarray] = []       # segment starts
+        self._b: list[np.ndarray] = []       # segment ends
+        self._t: list[int] = []              # frame index each was laid at
+        self._grid: dict[tuple, list[int]] = {}
+
+    # ---------------------------------------------------------------- build
+    def __len__(self) -> int:
+        return len(self._a)
+
+    def _cells_for(self, a: np.ndarray, b: np.ndarray):
+        """Every grid cell the segment's padded AABB touches."""
+        lo = np.minimum(a, b) - self.bead_radius
+        hi = np.maximum(a, b) + self.bead_radius
+        lo_i = np.floor(lo / self.cell).astype(int)
+        hi_i = np.floor(hi / self.cell).astype(int)
+        for i in range(lo_i[0], hi_i[0] + 1):
+            for j in range(lo_i[1], hi_i[1] + 1):
+                for k in range(lo_i[2], hi_i[2] + 1):
+                    yield (i, j, k)
+
+    def add(self, a, b, frame: int) -> None:
+        """Record one deposited segment, laid at `frame`."""
+        a = np.asarray(a, dtype=float)
+        b = np.asarray(b, dtype=float)
+        idx = len(self._a)
+        self._a.append(a)
+        self._b.append(b)
+        self._t.append(int(frame))
+        for c in self._cells_for(a, b):
+            self._grid.setdefault(c, []).append(idx)
+
+    # ---------------------------------------------------------------- query
+    def _candidates(self, lo: np.ndarray, hi: np.ndarray) -> np.ndarray:
+        lo_i = np.floor(lo / self.cell).astype(int)
+        hi_i = np.floor(hi / self.cell).astype(int)
+        out: set[int] = set()
+        for i in range(lo_i[0], hi_i[0] + 1):
+            for j in range(lo_i[1], hi_i[1] + 1):
+                for k in range(lo_i[2], hi_i[2] + 1):
+                    hit = self._grid.get((i, j, k))
+                    if hit:
+                        out.update(hit)
+        return np.fromiter(out, dtype=int, count=len(out))
+
+    def clearance(self, shape, frame: int, lag: int = 0,
+                  search: float = 0.02) -> tuple[float, int]:
+        """Smallest gap between `shape` and material laid before `frame - lag`.
+
+        Args:
+            shape: anything with `.distance(points)` and `.bounds(pad)` —
+                a Capsule or a Box from `toolwake.geometry`.
+            frame: the current frame index.
+            lag: how many frames back to start counting material as an
+                obstacle. Without this the tool always collides with the bead
+                it is extruding right now.
+            search: broad-phase radius, metres. Beads further away than this
+                are not measured at all; the returned distance is clipped to it.
+
+        Returns:
+            (clearance, segment_index). `inf` and -1 when nothing is in range.
+        """
+        if not self._a:
+            return float("inf"), -1
+
+        lo, hi = shape.bounds(pad=search)
+        cand = self._candidates(lo, hi)
+        if cand.size == 0:
+            return float("inf"), -1
+
+        t = np.asarray(self._t)[cand]
+        cand = cand[t < frame - lag]              # earlier material only
+        if cand.size == 0:
+            return float("inf"), -1
+
+        A = np.asarray(self._a)[cand]
+        B = np.asarray(self._b)[cand]
+        # Sample each candidate bead along its axis; with beads this short
+        # relative to the tool, endpoints plus midpoint bound the true
+        # segment-to-segment distance closely and stay fully vectorised.
+        pts = np.vstack([A, B, 0.5 * (A + B)])
+        d = shape.distance(pts) - self.bead_radius
+        n = len(cand)
+        d = np.min(d.reshape(3, n), axis=0)
+        j = int(np.argmin(d))
+        return float(d[j]), int(cand[j])
+
+    # ---------------------------------------------------------------- views
+    def segments(self, upto: int | None = None) -> np.ndarray:
+        """(N, 2, 3) array of laid segments, for drawing. `upto` filters by frame."""
+        if not self._a:
+            return np.zeros((0, 2, 3))
+        A = np.asarray(self._a)
+        B = np.asarray(self._b)
+        if upto is not None:
+            keep = np.asarray(self._t) <= upto
+            A, B = A[keep], B[keep]
+        return np.stack([A, B], axis=1)
+
+    def bounds(self):
+        if not self._a:
+            return None
+        pts = np.vstack([np.asarray(self._a), np.asarray(self._b)])
+        return pts.min(axis=0) - self.bead_radius, pts.max(axis=0) + self.bead_radius
+
+    def __repr__(self):
+        return (f"Deposit({len(self)} segments, bead_r={self.bead_radius:.4g}, "
+                f"cell={self.cell:.4g}, {len(self._grid)} cells)")

toolwake/geometry.py

@@ -0,0 +1,179 @@
+"""Exact distance primitives for the tool side of the check.
+
+The tool is modelled with primitives rather than meshes on purpose. On the rig
+this was written for, the end-effector's collision geometry in the URDF is
+already a box and the needle is a thin cylinder, so a capsule and an oriented
+box reproduce the real collision volume exactly — nothing is approximated away,
+and there is no mesh library to depend on.
+
+All functions are vectorised over a set of query points, because the caller
+tests one tool pose against many deposited points at once.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["Capsule", "Box", "rotation_from_rotvec", "rotvec_from_axis",
+           "rpy_from_rotation"]
+
+
+def rotation_from_rotvec(rotvec) -> np.ndarray:
+    """Rotation matrix from a rotation vector (axis * angle), via Rodrigues.
+
+    Matches the convention UR controllers use for pose orientation, so a pose
+    row read straight off the robot can be passed in unchanged.
+    """
+    r = np.asarray(rotvec, dtype=float)
+    theta = float(np.linalg.norm(r))
+    if theta < 1e-12:
+        return np.eye(3)
+    k = r / theta
+    K = np.array([[0.0, -k[2], k[1]],
+                  [k[2], 0.0, -k[0]],
+                  [-k[1], k[0], 0.0]])
+    return np.eye(3) + np.sin(theta) * K + (1.0 - np.cos(theta)) * (K @ K)
+
+
+def rotvec_from_axis(u, reference=(0.0, 0.0, 1.0)) -> np.ndarray:
+    """Rotation vector taking `reference` onto `u` by the shortest arc.
+
+    The inverse of what `Needle.at` needs: give it the direction the tool
+    should point (tip-to-body, so "up the tool") and it returns the rotation
+    vector to store on the toolpath.
+
+    The shortest arc leaves the roll about the tool axis unconstrained, which
+    is correct here — a round needle laying a round bead has no meaningful
+    roll, so pinning one would be inventing a constraint.
+    """
+    a = np.asarray(reference, dtype=float)
+    b = np.asarray(u, dtype=float)
+    na, nb = np.linalg.norm(a), np.linalg.norm(b)
+    if na < 1e-15 or nb < 1e-15:
+        raise ValueError("rotvec_from_axis needs two non-zero vectors")
+    a, b = a / na, b / nb
+    c = np.cross(a, b)
+    s = float(np.linalg.norm(c))
+    d = float(np.dot(a, b))
+    if s < 1e-12:
+        if d > 0:
+            return np.zeros(3)
+        # Antiparallel: any perpendicular axis gives a 180 deg flip.
+        perp = np.array([1.0, 0.0, 0.0])
+        if abs(a[0]) > 0.9:
+            perp = np.array([0.0, 1.0, 0.0])
+        axis = np.cross(a, perp)
+        return axis / np.linalg.norm(axis) * np.pi
+    return c / s * float(np.arctan2(s, d))
+
+
+def rpy_from_rotation(R) -> np.ndarray:
+    """(roll, pitch, yaw) in radians from a rotation matrix, ZYX convention.
+
+    Yaw about Z, then pitch about the new Y, then roll about the new X — the
+    convention robot controllers and teach pendants report, so the numbers here
+    match what an operator reads off the machine.
+
+    At pitch = +/-90 deg roll and yaw describe the same rotation (gimbal lock);
+    there the split is arbitrary and roll is pinned to 0 so the result stays
+    deterministic rather than amplifying numerical noise.
+    """
+    R = np.asarray(R, dtype=float)
+    sp = -R[2, 0]
+    if abs(sp) > 1.0 - 1e-9:                     # gimbal lock
+        pitch = np.pi / 2 * np.sign(sp)
+        return np.array([0.0, pitch, float(np.arctan2(-R[0, 1], R[1, 1]))])
+    return np.array([float(np.arctan2(R[2, 1], R[2, 2])),
+                     float(np.arcsin(np.clip(sp, -1.0, 1.0))),
+                     float(np.arctan2(R[1, 0], R[0, 0]))])
+
+
+def _seg_point_distance(pts: np.ndarray, a: np.ndarray, b: np.ndarray) -> np.ndarray:
+    """Distance from each point to the SEGMENT ab (not the infinite line)."""
+    pts = np.atleast_2d(pts)
+    ab = b - a
+    denom = float(ab @ ab)
+    if denom < 1e-18:                      # degenerate segment -> a point
+        return np.linalg.norm(pts - a, axis=1)
+    t = np.clip((pts - a) @ ab / denom, 0.0, 1.0)
+    closest = a + t[:, None] * ab
+    return np.linalg.norm(pts - closest, axis=1)
+
+
+class Capsule:
+    """A cylinder with hemispherical caps: the needle, or a deposited bead.
+
+    Defined by its axis segment and a radius. A capsule is used rather than a
+    plain cylinder because the distance function stays exact and smooth at the
+    ends, which matters when a bead is one short segment.
+    """
+
+    __slots__ = ("a", "b", "radius")
+
+    def __init__(self, a, b, radius: float):
+        self.a = np.asarray(a, dtype=float)
+        self.b = np.asarray(b, dtype=float)
+        self.radius = float(radius)
+        if self.a.shape != (3,) or self.b.shape != (3,):
+            raise ValueError("capsule endpoints must be 3-vectors")
+        if self.radius < 0:
+            raise ValueError("capsule radius must be >= 0")
+
+    def distance(self, pts) -> np.ndarray:
+        """Signed distance from points to the capsule surface (negative = inside)."""
+        return _seg_point_distance(pts, self.a, self.b) - self.radius
+
+    @property
+    def length(self) -> float:
+        return float(np.linalg.norm(self.b - self.a))
+
+    def bounds(self, pad: float = 0.0):
+        lo = np.minimum(self.a, self.b) - self.radius - pad
+        hi = np.maximum(self.a, self.b) + self.radius + pad
+        return lo, hi
+
+    def __repr__(self):
+        return f"Capsule(len={self.length:.4g}, r={self.radius:.4g})"
+
+
+class Box:
+    """An oriented box — the end-effector housing.
+
+    `R` maps BOX-local coordinates into world. Distance is exact for points
+    outside; for points inside it returns a negative penetration depth (the
+    distance to the nearest face), which is the usual convention and is enough
+    to rank how bad a collision is.
+    """
+
+    __slots__ = ("center", "half", "R")
+
+    def __init__(self, center, half_extents, R=None):
+        self.center = np.asarray(center, dtype=float)
+        self.half = np.asarray(half_extents, dtype=float)
+        self.R = np.eye(3) if R is None else np.asarray(R, dtype=float)
+        if self.center.shape != (3,) or self.half.shape != (3,):
+            raise ValueError("box center and half_extents must be 3-vectors")
+        if np.any(self.half < 0):
+            raise ValueError("box half_extents must be >= 0")
+
+    def distance(self, pts) -> np.ndarray:
+        pts = np.atleast_2d(np.asarray(pts, dtype=float))
+        local = (pts - self.center) @ self.R          # world -> box frame
+        excess = np.abs(local) - self.half
+        outside = np.linalg.norm(np.maximum(excess, 0.0), axis=1)
+        # Inside on every axis -> the closest face is the least-negative excess.
+        inside = np.minimum(excess.max(axis=1), 0.0)
+        return outside + inside
+
+    def corners(self) -> np.ndarray:
+        """The 8 world-space corners, for drawing a wireframe."""
+        signs = np.array([[sx, sy, sz]
+                          for sx in (-1, 1) for sy in (-1, 1) for sz in (-1, 1)],
+                         dtype=float)
+        return self.center + (signs * self.half) @ self.R.T
+
+    def bounds(self, pad: float = 0.0):
+        c = self.corners()
+        return c.min(axis=0) - pad, c.max(axis=0) + pad
+
+    def __repr__(self):
+        return f"Box(half={np.round(self.half, 4).tolist()})"

toolwake/profile.py

@@ -0,0 +1,181 @@
+"""Tool profiles: a coaxial stack of sections, the way CAM describes a tool.
+
+A dispensing needle is not a single cylinder. A luer-lock tip is a thin cannula
+that steps up to a hub several tens of times its diameter, and the hub is what
+actually fouls a tall part — exactly the holder-vs-flute distinction a CAM
+simulation draws.
+
+Sections are listed from the TIP upward, each with a length and a radius at
+each end, so a straight cylinder and a taper are the same primitive.
+
+For collision each section becomes a capsule at its LARGEST radius. That is
+deliberately conservative: on a bioprinter a false stop costs a reprint and a
+missed collision costs the part and possibly the needle. Tapers can be sliced
+into sub-capsules when the loose fit matters more than the caution.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .geometry import Capsule
+
+__all__ = ["Section", "ToolProfile", "luer_taper_tip", "blunt_cannula"]
+
+
+@dataclass(frozen=True)
+class Section:
+    """One coaxial piece of the tool.
+
+    Args:
+        length: axial length, metres.
+        r0: radius at the lower (tip-ward) end, metres.
+        r1: radius at the upper end, metres. Defaults to `r0` (a cylinder).
+        name: label, used in reports so a collision says which part hit.
+    """
+
+    length: float
+    r0: float
+    r1: float | None = None
+    name: str = ""
+
+    @property
+    def r_top(self) -> float:
+        return self.r0 if self.r1 is None else self.r1
+
+    @property
+    def r_max(self) -> float:
+        return max(self.r0, self.r_top)
+
+    def __post_init__(self):
+        if self.length < 0:
+            raise ValueError(f"section {self.name!r}: length must be >= 0")
+        if self.r0 < 0 or self.r_top < 0:
+            raise ValueError(f"section {self.name!r}: radii must be >= 0")
+
+
+class ToolProfile:
+    """An ordered stack of sections, tip first.
+
+    The profile is expressed in the TOOL frame with +Z running back up the tool
+    away from the tip, and placed into the world by `capsules()`.
+    """
+
+    def __init__(self, sections):
+        self.sections = list(sections)
+        if not self.sections:
+            raise ValueError("a tool profile needs at least one section")
+
+    # ------------------------------------------------------------- geometry
+    @property
+    def length(self) -> float:
+        return float(sum(s.length for s in self.sections))
+
+    @property
+    def r_max(self) -> float:
+        return float(max(s.r_max for s in self.sections))
+
+    @property
+    def tip_radius(self) -> float:
+        """Radius right at the tip — what lays the bead."""
+        return float(self.sections[0].r0)
+
+    def stations(self) -> np.ndarray:
+        """(M, 2) of (z, r) along the silhouette, from tip upward.
+
+        A step between sections appears as two samples at the same z, so the
+        outline drawn from this has square shoulders rather than ramps.
+        """
+        z, out = 0.0, [(0.0, self.sections[0].r0)]
+        for s in self.sections:
+            if abs(s.r0 - out[-1][1]) > 1e-12:      # step change in radius
+                out.append((z, s.r0))
+            z += s.length
+            out.append((z, s.r_top))
+        return np.asarray(out, dtype=float)
+
+    def capsules(self, tip, axis, slices: int = 1):
+        """World-space capsules for collision, one (or `slices`) per section.
+
+        Args:
+            tip: world position of the tool tip.
+            axis: unit vector pointing from the tip back up the tool.
+            slices: subdivisions per tapered section. 1 keeps each section at
+                its largest radius (conservative); higher follows the taper
+                more tightly at proportional cost.
+
+        Returns:
+            list of (name, Capsule).
+        """
+        tip = np.asarray(tip, dtype=float)
+        axis = np.asarray(axis, dtype=float)
+        axis = axis / np.linalg.norm(axis)
+        out, z = [], 0.0
+        for s in self.sections:
+            if s.length <= 0:
+                continue
+            n = max(1, int(slices)) if s.r1 is not None and s.r1 != s.r0 else 1
+            for k in range(n):
+                t0, t1 = k / n, (k + 1) / n
+                za, zb = z + s.length * t0, z + s.length * t1
+                ra = s.r0 + (s.r_top - s.r0) * t0
+                rb = s.r0 + (s.r_top - s.r0) * t1
+                out.append((s.name or "section",
+                            Capsule(tip + axis * za, tip + axis * zb,
+                                    max(ra, rb))))
+            z += s.length
+        return out
+
+    def surface(self, tip, R, n_theta: int = 24):
+        """(X, Y, Z) arrays for drawing the tool as a surface of revolution."""
+        st = self.stations()
+        th = np.linspace(0.0, 2 * np.pi, n_theta)
+        zz = st[:, 0][:, None]
+        rr = st[:, 1][:, None]
+        local = np.stack([rr * np.cos(th), rr * np.sin(th),
+                          np.broadcast_to(zz, (len(st), n_theta))], axis=-1)
+        world = local @ R.T + np.asarray(tip, dtype=float)
+        return world[..., 0], world[..., 1], world[..., 2]
+
+    def __repr__(self):
+        names = ", ".join(s.name or "?" for s in self.sections)
+        return (f"ToolProfile({len(self.sections)} sections: {names}; "
+                f"len={self.length*1e3:.1f} mm, r_max={self.r_max*1e3:.2f} mm)")
+
+
+# ------------------------------------------------------------------ presets
+#
+# NOMINAL dimensions. Hub sizes in particular vary between manufacturers and
+# these are close enough to reason about clearance but not a substitute for
+# calipers on the tip you are actually running.
+
+def blunt_cannula(gauge_od=0.19e-3, length=12.7e-3, inner_d=90e-6) -> ToolProfile:
+    """Just the metal tube — no hub. The optimistic model, for comparison."""
+    return ToolProfile([Section(length, gauge_od / 2.0, name="cannula")])
+
+
+def luer_taper_tip(cannula_od=0.19e-3, cannula_len=12.7e-3,
+                   hub_d=9.0e-3, hub_len=13.0e-3,
+                   taper_len=3.0e-3, collar_d=11.0e-3,
+                   collar_len=4.0e-3) -> ToolProfile:
+    """A luer-lock dispensing tip: cannula, taper, hub, locking collar.
+
+    Defaults approximate a 34G half-inch tip. The hub is roughly 47x the
+    cannula diameter, which is the entire reason this class exists — a check
+    that models only the cannula is looking at the thinnest 2% of the tool.
+
+    Args:
+        cannula_od: needle outer diameter, metres (34G ~ 0.19 mm).
+        cannula_len: exposed needle length, metres (0.5 in = 12.7 mm).
+        hub_d: widest diameter of the plastic hub, metres.
+        hub_len: straight hub length, metres.
+        taper_len: cone joining cannula to hub, metres.
+        collar_d, collar_len: the luer locking collar above the hub.
+    """
+    return ToolProfile([
+        Section(cannula_len, cannula_od / 2.0, name="cannula"),
+        Section(taper_len, cannula_od / 2.0, hub_d / 2.0, name="taper"),
+        Section(hub_len, hub_d / 2.0, name="hub"),
+        Section(collar_len, collar_d / 2.0, name="luer collar"),
+    ])