ocdkit 0.0.3__tar.gz → 0.0.4__tar.gz

{ocdkit-0.0.3/src/ocdkit.egg-info → ocdkit-0.0.4}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: ocdkit
-Version: 0.0.3
+Version: 0.0.4
 Summary: Obsessive Coder's Dependency Toolkit — Python utilities for array manipulation, GPU dispatch, image I/O, morphology, and plotting.
 License: BSD-3-Clause
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy
+Requires-Dist: numpy>=2.0
 Requires-Dist: scipy
 Requires-Dist: scikit-image>=0.26
 Requires-Dist: tifffile

ocdkit-0.0.4/badges/coverage.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 43.71%"><title>coverage: 43.71%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#e05d44"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">43.71%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">43.71%</text></g></svg>

ocdkit-0.0.4/badges/tests.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="68" height="20" role="img" aria-label="tests: 400"><title>tests: 400</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="68" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="37" height="20" fill="#555"/><rect x="37" width="31" height="20" fill="#4c1"/><rect width="68" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="195" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">tests</text><text x="195" y="140" transform="scale(.1)" fill="#fff" textLength="270">tests</text><text aria-hidden="true" x="515" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="210">400</text><text x="515" y="140" transform="scale(.1)" fill="#fff" textLength="210">400</text></g></svg>

ocdkit-0.0.4/docs/plot-backend-roadmap.md

@@ -0,0 +1,96 @@
+# Plot backend roadmap
+
+**Status:** Design discussion / pending decision.
+**Owner:** kevin@kanvasbio.com
+**Driver:** matplotlib accounts for ~80% of warm-call time in `hiprpy.plot.plot_spectra` (~115 ms of ~140 ms) and ~1.5 s of cold-import overhead. We also want native hover/tooltip behavior like the classification-debugger GUI, which matplotlib can't deliver inline.
+
+## Context
+
+`ocdkit.plot` and `hiprpy.plot` already own ~10 K LOC of plotting code:
+
+| Package | LOC |
+|---|---|
+| `ocdkit.plot` (figure, grid, label, color, defaults, display, contour, export) | 1,935 |
+| `hiprpy.plot` non-WGPU (datashade, cell, text, barcode, line, background, …) | 4,641 |
+| `hiprpy.plot.wgpu` (lines, scatter, aggregators — already custom GPU primitives) | 4,783 |
+
+What we still depend on matplotlib for is narrow: 2D Cartesian axes, ticks, labels, legends, image display, save-to-PNG/PDF/SVG, inline-in-Jupyter. **Not** 3D, animation, multi-backend abstraction (Qt/GTK/MacOSX), most chart types, complex tick locators/formatters, or any of the other ~180 K LOC of matplotlib's surface.
+
+The driver question: replace matplotlib with what?
+
+## Library survey (2026-05-07)
+
+Shallow-cloned each candidate, counted Python LOC excluding tests, sphinx, sample data, and auto-generated validators:
+
+| Library | Repo | Relevant Py LOC | Native code | Notes |
+|---|---|---|---|---|
+| matplotlib | — | 186 K | C extensions | What we're replacing |
+| bokeh | 120 MB | 64 K | 150 K TypeScript | UI lives in TS frontend; Py is scene graph + serialization |
+| plotly | 66 MB | 13 K relevant (+ ~600 K autogen) | JS bundle as data | Most LOC is auto-generated trait validators |
+| datoviz | 137 MB | 8 K Py wrapper | 140 K C++ Vulkan engine | Heaviest binary footprint, fastest renderer |
+| vispy | 11 MB | 32 K | None — pure Py + OpenGL | OpenGL stack, not WGPU |
+| pygfx | 84 MB | 20 K | None — uses `wgpu-py` | Same backend ocdkit/hiprpy already use |
+
+## Tradeoff summary
+
+**Bokeh** — toolbar/logo *can* be removed (`figure(toolbar_location=None)`, `fig.toolbar.logo = None`), but the interaction model lives in a separate TypeScript frontend. To customize hover/zoom UX we'd be writing or forking TypeScript, not Python. The 150 K-LOC TS frontend is essentially the part we'd want to control, and it's the part we can't easily touch.
+
+**Plotly** — same shape. Most LOC is auto-generated validators; the actual rendering and interaction is in the JS bundle. `displayModeBar=False` removes the toolbar but customizing hover beyond what their config exposes means reaching into JS.
+
+**Datoviz** — Vulkan engine is fast and well-architected, but adds a 137 MB binary dependency and a different graphics stack from our existing wgpu-py code. Two graphics backends to maintain instead of one.
+
+**Vispy** — pure Python and has scene + visuals modules that overlap heavily with what we want. But it's OpenGL via PyOpenGL, not WebGPU. We'd be running a second graphics stack alongside our wgpu-py code.
+
+**pygfx** — uses *exactly* the `wgpu-py` we already depend on. Its `gfx.Lines`, `gfx.Mesh`, `gfx.Text`, `gfx.OrthographicCamera` primitives compose directly with our `DensityLineRenderer`. The most architecturally compatible third-party option.
+
+**Roll our own** — given that we already have ~10 K LOC of plotting infrastructure, including a working WGPU line/scatter rasterizer, the increment to "complete 2D plotting library covering our actual needs" is roughly 3–5 K LOC. The scope is well-defined: axes, ticks, labels, legend, image display, hover, export.
+
+## Recommendation
+
+**Two-step.**
+
+### Step 1: pygfx prototype (1 day)
+
+Spike a `plot_spectra_pygfx` that uses `pygfx.Lines` + `pygfx.Text` + an `OrthographicCamera` to reproduce the current spectra layout. This is cheap because pygfx and our existing WGPU code share the same `wgpu-py` device — they can literally run in the same process without backend conflict.
+
+What to evaluate:
+- Visual quality vs. our current WGPU-rendered density lines (especially anti-aliasing)
+- Text rendering quality (pygfx uses FreeType-rendered SDFs)
+- Hover/picking — does pygfx's built-in picking suffice for our tooltip needs?
+- Export — pygfx renders to a wgpu canvas; PNG export is straightforward, PDF/SVG would need our own rasterize-and-vectorize path
+
+If pygfx covers ≥80% of our needs at ≥80% of the visual quality, **adopt pygfx**. We get hover, zoom, pan, picking essentially for free, plus the `pygfx` ecosystem (geometries, materials, post-processing).
+
+### Step 2 (only if pygfx is insufficient): roll our own
+
+Estimated scope, building on existing `hiprpy.plot.wgpu.lines`:
+
+| Module | LOC est. | Notes |
+|---|---|---|
+| `ocdkit.plot.figure_v2` | 400 | New `Figure` class owning the wgpu canvas + axes layout; coexists with current matplotlib `figure()` so migration is piecewise |
+| `ocdkit.plot.axis` | 800 | `LinearAxis`, `LogAxis` — tick locator + formatter + render-time placement. The matplotlib equivalent is ~3 K LOC; we don't need most of it |
+| `hiprpy.plot.wgpu.text` | 600 | FreeType-rendered glyph atlas + WGSL textured-quad shader. The one piece of genuinely new rasterization work |
+| `ocdkit.plot.legend` | 200 | Boxed layout: text + marker swatches |
+| `ocdkit.plot.hover` | 300 | Mouse → data-coord lookup → DOM/Jupyter tooltip overlay. Generalize the classification-debugger pattern |
+| `ocdkit.plot.export` | 400 | PNG (numpy→PIL), SVG (string templates), maybe PDF (skip if PIL→PNG covers science exports) |
+| Migration: rewrite `plot_spectra`, `plot_image_grid`, `key_slice_grid`, `label_axes` against new primitives | ~600 | Mostly drop-in replacements at the call sites |
+| **Total** | **~3.3 K** | New code, all in our control |
+
+Plus: deletion of matplotlib-specific code paths in `hiprpy.plot` (~1 K LOC saved) and removal of matplotlib runtime dep.
+
+### Why not pygfx + own axes?
+
+A hybrid path is also viable: use pygfx for the rasterization layer (lines/text/transform/camera) and write our own axis/tick/legend/hover layer on top. That'd be the best of both — pygfx handles the rendering substrate, we own the plotting semantics. Estimated ~1.5 K LOC of new code on top of pygfx.
+
+## Open questions
+
+1. **Hover semantics** — does the classification-debugger tooltip pattern generalize cleanly, or do different plots need different hover content models?
+2. **Export fidelity** — do we need true vector PDF, or is high-DPI PNG enough? Vector requires re-rasterizing axes/text on the CPU side, which is non-trivial.
+3. **Notebook + standalone parity** — pygfx renders to a wgpu canvas that displays inline in Jupyter via `wgpu_jupyter`. Does that path work in VS Code's Jupyter extension and in standalone scripts (`savefig`-equivalent)?
+4. **Remoting** — if we ever want a server-side render pipeline (for cloud GUIs), pygfx's WGPU backend can render headlessly; matplotlib `Agg` does the same. Bokeh/plotly's JS-frontend assumption is harder to remote.
+
+## Concrete next action
+
+Spike `plot_spectra_pygfx` using `scope.mixed_spectra[-1]` from `notebooks/hiprpy_demo_notebook.ipynb` as the test case. Compare visual output side-by-side with `plot_spectra_wgpu` and `plot_spectra_cpu`. Decide pygfx-vs-roll-own from that single comparison.
+
+If the answer ends up being "pygfx + own axis layer", the new module structure would live in `ocdkit.plot.gfx_*` (parallel to the current matplotlib-based modules) so the migration is a per-call-site flip rather than a big-bang rewrite.

{ocdkit-0.0.3 → ocdkit-0.0.4}/pyproject.toml

@@ -10,7 +10,11 @@ readme = "README.md"
 license = {text = "BSD-3-Clause"}
 requires-python = ">=3.11"
 dependencies = [
-    "numpy",
+    # numpy >= 2.0 — np.unique was reworked / sped up in the 2.0 cycle
+    # and matches fastremap.unique on label arrays. Helpers like
+    # array.ops.unique_nonzero / is_sequential rely on that parity to
+    # avoid hard-importing fastremap.
+    "numpy>=2.0",
     "scipy",
     "scikit-image>=0.26",
     "tifffile",

ocdkit-0.0.4/scripts/bench_contour_alignment.py

@@ -0,0 +1,82 @@
+"""Synthetic single-cell test for contour alignment.
+
+Plots a small mask with grid lines at integer pixel boundaries so we can
+see exactly where each pipeline puts its outline relative to:
+  - the pixels of the cell  (filled gray squares spanning [j-.5, j+.5] x [i-.5, i+.5])
+  - the cell boundary       (gridline at half-integer y and x at the cell edge)
+
+The three pipelines are:
+  - current (B-spline through pixel centers)
+  - tier 1  (Gaussian-smoothed pixel-center walk)
+  - tier 2  (marching squares; geometric cell boundary)
+
+Also tests the new `offset` knob in tier 2.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from bench_vector_contours import vector_contours_fast
+from bench_vector_contours_tier2 import vector_contours_marching
+from ocdkit.plot.contour import vector_contours
+
+
+def make_mask():
+    m = np.zeros((20, 20), dtype=np.int32)
+    m[5:11, 5:11] = 1   # 6x6 square cell
+    m[14:17, 13:18] = 2  # 3x5 rectangle cell
+    return m
+
+
+def add_grid(ax, shape):
+    H, W = shape
+    for x in np.arange(-0.5, W, 1):
+        ax.axvline(x, color='cyan', linewidth=0.3, alpha=0.35, zorder=0)
+    for y in np.arange(-0.5, H, 1):
+        ax.axhline(y, color='cyan', linewidth=0.3, alpha=0.35, zorder=0)
+
+
+def main():
+    mask = make_mask()
+
+    fig, axes = plt.subplots(2, 2, figsize=(12, 12))
+
+    titles = [
+        "Current vector_contours (splprep) — note up-left bias",
+        "Tier 1 (gaussian on pixel-center walk)",
+        "Tier 2 default offset=0 (geometric cell boundary)",
+        "Tier 2 offset=0.5 (through pixel centers, no bias)",
+    ]
+    for ax, title in zip(axes.flat, titles):
+        ax.imshow(mask, cmap='gray_r', interpolation='nearest', vmin=0, vmax=2)
+        add_grid(ax, mask.shape)
+        ax.set_title(title, fontsize=10)
+        ax.set_xticks(range(mask.shape[1]))
+        ax.set_yticks(range(mask.shape[0]))
+        ax.tick_params(labelsize=6)
+
+    vector_contours(fig, axes[0, 0], mask, smooth_factor=5,
+                    color='red', linewidth=1.5)
+    vector_contours_fast(fig, axes[0, 1], mask, smooth_sigma=1.0,
+                         color='red', linewidth=1.5)
+    vector_contours_marching(fig, axes[1, 0], mask, smooth_sigma=1.0,
+                             color='red', linewidth=1.5)
+    # Tier 2 with offset (still need to add the knob — we'll do that next)
+    vector_contours_marching(fig, axes[1, 1], mask, smooth_sigma=1.0,
+                             color='red', linewidth=1.5)
+
+    fig.tight_layout()
+    out = Path('/Volumes/DataDrive/ocdkit/scripts/bench_contour_alignment.png')
+    fig.savefig(out, dpi=150, bbox_inches='tight')
+    print(f"saved: {out}")
+
+
+if __name__ == '__main__':
+    main()

ocdkit-0.0.4/scripts/bench_vector_contours.py

@@ -0,0 +1,311 @@
+"""Benchmark current vector_contours pipeline vs a vectorized prototype.
+
+Loads the ncolor example mask and renders both the current
+ocdkit.plot.contour.vector_contours output and a prototype implementation
+side by side, with timings.
+
+Run:
+    python scripts/bench_vector_contours.py
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import matplotlib.patches as mpatches
+import matplotlib.path as mpath
+import matplotlib.pyplot as plt
+import numpy as np
+import skimage.io
+from matplotlib.collections import LineCollection
+from numba import njit
+from scipy.ndimage import gaussian_filter1d
+
+from ocdkit.array.spatial import (
+    boundary_to_masks,
+    get_neighbors,
+    kernel_setup,
+    masks_to_affinity,
+)
+from ocdkit.plot.contour import vector_contours
+from skimage.segmentation import find_boundaries
+
+
+# ---------------------------------------------------------------------------
+# Faster numba contour walker — fixes the O(N^2) `i in contour` list lookup
+# in ocdkit.array.spatial.parametrize_contours by using a global boolean
+# `seen` array indexed by pixel id (O(1) membership check).
+# ---------------------------------------------------------------------------
+
+@njit(cache=True, fastmath=True)
+def _parametrize_contours_fast(steps, labs, unique_L, neigh_inds, step_ok, csum):
+    sign = np.sum(np.abs(steps), axis=1)  # noqa: F841 (kept for parity)
+    s0 = 4  # center index for 2D (3**2 // 2)
+    npix = neigh_inds.shape[1]
+    seen = np.zeros(npix, dtype=np.bool_)
+
+    contours = []
+    for l in unique_L:
+        sel = labs == l
+        indices = np.argwhere(sel).flatten()
+        if len(indices) == 0:
+            continue
+        index = indices[np.argmin(csum[sel])]
+
+        # local list to record this contour (numba reflected-list, OK)
+        contour = [np.int64(0)]
+        contour.clear()
+
+        n_iter = 0
+        max_iter = len(indices) + 1
+        while n_iter < max_iter:
+            here = neigh_inds[s0, index]
+            contour.append(here)
+            seen[here] = True
+
+            neighbor_inds = neigh_inds[:, index]
+            step_ok_here = step_ok[:, index]
+
+            # find best unseen neighbor
+            best_select = -1
+            best_cost = 1 << 30
+            best_count = 0
+            for k in range(neighbor_inds.shape[0]):
+                if not step_ok_here[k]:
+                    continue
+                ni = neighbor_inds[k]
+                if ni < 0 or seen[ni]:
+                    continue
+                # directional cost = sum(steps[k] * steps[3])
+                cost = 0
+                for d in range(steps.shape[1]):
+                    cost += steps[k, d] * steps[3, d]
+                if cost < best_cost:
+                    best_cost = cost
+                    best_select = k
+                best_count += 1
+
+            if best_select < 0:
+                # closed
+                break
+            index = neighbor_inds[best_select]
+            n_iter += 1
+
+        # reset seen flags for THIS contour only (so other labels can reuse)
+        for px in contour:
+            seen[px] = False
+        contours.append(contour)
+
+    return contours
+
+
+def _get_contour_fast(labels, affinity_graph, coords, neighbors, cardinal_only=True):
+    """Drop-in replacement for ocdkit.array.spatial.get_contour using the
+    fast walker above. Still builds the affinity graph the same way upstream."""
+    from ocdkit.array.spatial import get_neigh_inds  # late import
+
+    dim = labels.ndim
+    steps, inds, idx, fact, sign = kernel_setup(dim)
+    if cardinal_only:
+        allowed_inds = np.concatenate(inds[1:2])
+    else:
+        allowed_inds = np.concatenate(inds[1:])
+
+    indexes, neigh_inds, ind_matrix = get_neigh_inds(neighbors, coords, labels.shape)
+    csum = np.sum(affinity_graph, axis=0)
+    step_ok = np.zeros(affinity_graph.shape, bool)
+    for s in allowed_inds:
+        step_ok[s] = np.logical_and.reduce((
+            affinity_graph[s] > 0,
+            csum[neigh_inds[s]] < (3 ** dim - 1),
+            neigh_inds[s] > -1,
+        ))
+
+    labs = labels[coords]
+    import fastremap
+    unique_L = fastremap.unique(labs)
+    contours = _parametrize_contours_fast(
+        steps, np.int32(labs), np.int32(unique_L), neigh_inds, step_ok, csum
+    )
+    return contours, unique_L
+
+
+# ---------------------------------------------------------------------------
+# Vectorized Chaikin corner-cutting (replaces per-cell scipy.splprep loop).
+# ---------------------------------------------------------------------------
+
+def _chaikin_closed(P, iterations=2):
+    """Chaikin corner-cutting on a closed polygon (vectorized, no Python loop)."""
+    P = np.asarray(P, dtype=np.float64)
+    for _ in range(iterations):
+        Pn = np.roll(P, -1, axis=0)
+        Q = 0.75 * P + 0.25 * Pn
+        R = 0.25 * P + 0.75 * Pn
+        out = np.empty((2 * len(P), 2), dtype=np.float64)
+        out[0::2] = Q
+        out[1::2] = R
+        P = out
+    return P
+
+
+def _gaussian_smooth_closed(P, sigma=2.0):
+    """Periodic Gaussian smoothing of a closed polygon (low-pass filter).
+
+    Treats x and y as 1D periodic signals along the contour parameter and
+    applies a Gaussian filter — this is the linear low-pass equivalent of
+    scipy.interpolate.splprep with a smoothing factor, but ~50x cheaper.
+    """
+    if len(P) < 3 or sigma <= 0:
+        return P
+    x = gaussian_filter1d(P[:, 0], sigma=sigma, mode='wrap')
+    y = gaussian_filter1d(P[:, 1], sigma=sigma, mode='wrap')
+    return np.column_stack([x, y])
+
+
+# ---------------------------------------------------------------------------
+# Prototype: vectorized vector outlines
+# ---------------------------------------------------------------------------
+
+def vector_contours_fast(fig, ax, mask, smooth_sigma=2.0, color='r', linewidth=1,
+                         x_offset=0, y_offset=0, pad=2, zorder=1,
+                         skip_despur=False):
+    """Prototype.
+
+    - Reuses the affinity-graph machinery (it is already vectorized/numba'd).
+    - Uses a fast contour walker that fixes the O(N^2) Python-list membership
+      check in the original parametrize_contours.
+    - Replaces the per-cell scipy.splprep loop with vectorized Chaikin
+      corner-cutting (2 iterations ~ visually equivalent to a B-spline).
+    - Builds ONE concatenated matplotlib Path with MOVETO/LINETO/CLOSEPOLY for
+      all contours, wrapped in a single PathPatch (instead of N PathPatches).
+    - Optionally skips the boundary_to_masks despur step (cheap labels
+      typically don't need it).
+    """
+    msk = np.pad(mask, pad, mode='edge')
+    msk = np.pad(msk, 1, mode='constant', constant_values=0)
+    dim = msk.ndim
+    shape = msk.shape
+
+    steps, inds, idx, fact, sign = kernel_setup(dim)
+
+    if not skip_despur:
+        bd = find_boundaries(msk, mode='inner', connectivity=2)
+        msk, _, _ = boundary_to_masks(bd, binary_mask=msk > 0,
+                                      connectivity=1, min_size=0)
+
+    coords = np.nonzero(msk)
+    neighbors = get_neighbors(tuple(coords), steps, dim, shape)
+    affinity_graph = masks_to_affinity(msk, coords, steps, inds, idx,
+                                       fact, sign, dim, neighbors)
+    contour_list, unique_L = _get_contour_fast(
+        msk, affinity_graph, coords, neighbors, cardinal_only=True
+    )
+
+    # Build a list of (N, 2) closed polylines; one LineCollection draws them
+    # all at once. Much faster than a Path with N CLOSEPOLY subpaths or N
+    # PathPatches in a PatchCollection.
+    cy, cx = coords
+    polylines = []
+    for contour in contour_list:
+        if len(contour) < 3:
+            continue
+        c = np.asarray(contour, dtype=np.int64)
+        pts = np.column_stack([cx[c], cy[c]]).astype(np.float64)
+        pts[:, 0] -= (pad + 1) - x_offset
+        pts[:, 1] -= (pad + 1) - y_offset
+        pts = _gaussian_smooth_closed(pts, sigma=smooth_sigma)
+        # close the loop by repeating the first point
+        polylines.append(np.vstack([pts, pts[:1]]))
+
+    if not polylines:
+        return
+
+    def _make_lc():
+        return LineCollection(polylines, colors=color, linewidths=linewidth,
+                              zorder=zorder, capstyle='round')
+
+    if isinstance(ax, list):
+        for a in ax:
+            a.add_collection(_make_lc())
+    else:
+        ax.add_collection(_make_lc())
+
+
+# ---------------------------------------------------------------------------
+# Benchmark + figure
+# ---------------------------------------------------------------------------
+
+def _time_call(fn, repeat=3):
+    fn()  # warm-up (incl numba compile)
+    ts = []
+    for _ in range(repeat):
+        t0 = time.perf_counter(); fn(); ts.append(time.perf_counter() - t0)
+    return min(ts), ts
+
+
+def main():
+    mask = skimage.io.imread('/Volumes/DataDrive/ncolor/test_files/example.png')
+    print(f"mask shape={mask.shape} n_labels={len(np.unique(mask)) - 1}")
+
+    def run_current():
+        fig, ax = plt.subplots(figsize=(5, 5))
+        ax.imshow(mask, cmap='gray', interpolation='nearest')
+        vector_contours(fig, ax, mask, smooth_factor=5, color='r', linewidth=1.0)
+        ax.set_axis_off()
+        plt.close(fig)
+
+    def run_fast():
+        fig, ax = plt.subplots(figsize=(5, 5))
+        ax.imshow(mask, cmap='gray', interpolation='nearest')
+        vector_contours_fast(fig, ax, mask, smooth_sigma=2.0, color='r', linewidth=1.0)
+        ax.set_axis_off()
+        plt.close(fig)
+
+    print("\nBenchmarking current pipeline (best of 3) ...")
+    cur_best, cur_all = _time_call(run_current, repeat=3)
+    print(f"  current: {cur_best*1000:.1f} ms (all: {[f'{t*1000:.1f}' for t in cur_all]})")
+
+    print("Benchmarking prototype (best of 3) ...")
+    fast_best, fast_all = _time_call(run_fast, repeat=3)
+    print(f"  proto:   {fast_best*1000:.1f} ms (all: {[f'{t*1000:.1f}' for t in fast_all]})")
+    print(f"\nspeedup: {cur_best / fast_best:.1f}x")
+
+    # Top row: full image. Bottom row: zoomed crop so outline detail is visible.
+    H, W = mask.shape
+    crop_y = slice(H // 3, H // 3 + 80)
+    crop_x = slice(W // 3, W // 3 + 80)
+
+    fig, axes = plt.subplots(2, 2, figsize=(11, 11))
+
+    for a in axes[0]:
+        a.imshow(mask, cmap='gray', interpolation='nearest')
+        a.set_axis_off()
+    vector_contours(fig, axes[0, 0], mask, smooth_factor=5, color='r', linewidth=1.0)
+    vector_contours_fast(fig, axes[0, 1], mask, smooth_sigma=2.0, color='r', linewidth=1.0)
+    axes[0, 0].set_title(f"Current vector_contours\n{cur_best*1000:.1f} ms",
+                         fontsize=11)
+    axes[0, 1].set_title(
+        f"Prototype (fast walker + Gaussian smooth + LineCollection)\n"
+        f"{fast_best*1000:.1f} ms  ({cur_best/fast_best:.1f}x speedup)",
+        fontsize=11)
+
+    for a in axes[1]:
+        a.imshow(mask[crop_y, crop_x], cmap='gray', interpolation='nearest',
+                 extent=(crop_x.start, crop_x.stop, crop_y.stop, crop_y.start))
+        a.set_xlim(crop_x.start, crop_x.stop)
+        a.set_ylim(crop_y.stop, crop_y.start)
+        a.set_axis_off()
+    vector_contours(fig, axes[1, 0], mask, smooth_factor=5, color='r', linewidth=1.5)
+    vector_contours_fast(fig, axes[1, 1], mask, smooth_sigma=2.0, color='r', linewidth=1.5)
+    axes[1, 0].set_title("zoomed crop", fontsize=10)
+    axes[1, 1].set_title("zoomed crop", fontsize=10)
+    fig.tight_layout()
+
+    out = Path('/Volumes/DataDrive/ocdkit/scripts/bench_vector_contours.png')
+    fig.savefig(out, dpi=150, bbox_inches='tight')
+    print(f"\nsaved: {out}")
+
+
+if __name__ == '__main__':
+    main()