bioimage-cpp 0.5.0__tar.gz → 0.6.0__tar.gz

{bioimage_cpp-0.5.0 → bioimage_cpp-0.6.0}/MIGRATION_GUIDE.md

@@ -2188,6 +2188,98 @@ Important differences:
   pairwise distance matrix; threshold the distance map first to keep the
   candidate count modest.
 
+## scikit-fmm
+
+`scikit-fmm` computes geodesic distances on regular grids with the fast
+marching method. `bioimage-cpp` groups geodesic distances under `bic.distance`
+with two operations — a **distance field** to a set of sources, and the full
+**pairwise distance matrix** between a set of points — for two geometry types:
+regular-grid **masks** (the scikit-fmm equivalent) and triangle **meshes**
+(which scikit-fmm does not support; the reference for those is the exact MMP
+algorithm in `pygeodesic`).
+
+Both are solved with a first-order fast marching method (Godunov/Eikonal on the
+grid, Kimmel–Sethian on triangles). Masks match scikit-fmm's `order=1` scheme;
+mesh distances are first-order approximations of the exact surface geodesics.
+
+scikit-fmm:
+
+```python
+import numpy as np
+import skfmm
+
+# Distance from a set of seed voxels, constrained to a mask (domain).
+phi = np.ones(mask.shape)
+phi[tuple(sources.T)] = -1            # zero contour marks the seeds
+phi = np.ma.MaskedArray(phi, ~mask)   # obstacles / outside-domain
+field = np.abs(skfmm.distance(phi, dx=sampling))
+# Weighted (travel-time) variant:
+tt = skfmm.travel_time(phi, speed, dx=sampling)
+```
+
+bioimage-cpp:
+
+```python
+import bioimage_cpp as bic
+
+# masks (regular grid); sources/points are (n, ndim) int64 voxel coordinates
+field = bic.distance.geodesic_distance_field(mask, sources, sampling=None,
+                                             speed=None)      # -> mask.shape, float64
+matrix = bic.distance.geodesic_distances(mask, points)       # -> (N, N) float64
+
+# optional per-axis gradient of the field (like vector_difference_transform)
+field, grad = bic.distance.geodesic_distance_field(mask, sources,
+                                                   return_gradient=True)
+# grad: (*mask.shape, ndim) float32, d(field)/d(axis), points away from source
+gradient = bic.distance.geodesic_gradient_field(mask, sources)  # just the gradient
+
+# surfaces (triangle mesh); sources/points are 1-D int64 vertex indices
+field = bic.distance.geodesic_distance_field_mesh(vertices, faces, sources,
+                                                  speed=None) # -> (n_vertices,) float64
+matrix = bic.distance.geodesic_distances_mesh(vertices, faces, points)  # -> (N, N) float64
+```
+
+Name mapping:
+
+| scikit-fmm / pygeodesic | bioimage-cpp name |
+| --- | --- |
+| `skfmm.distance` / `skfmm.travel_time` (from seed voxels, masked) | `geodesic_distance_field` |
+| gradient of the distance field (per-axis) | `geodesic_distance_field(..., return_gradient=True)` / `geodesic_gradient_field` |
+| pairwise via repeated `skfmm.distance` | `geodesic_distances` |
+| `pygeodesic … geodesicDistances(sources, None)` | `geodesic_distance_field_mesh` |
+| `pygeodesic … geodesicDistances` (pairwise) | `geodesic_distances_mesh` |
+
+Important differences:
+
+- Explicit, geometry-specific functions rather than a level-set encoding: the
+  domain is passed directly as a `mask` (nonzero = inside) or as a
+  `(vertices, faces)` mesh, and the sources are given as coordinates / vertex
+  indices instead of being baked into a signed `phi`.
+- Outputs are `float64`. Voxels outside the mask and points/vertices
+  unreachable from any source are `+inf`; pairwise matrices are symmetric with
+  a zero diagonal.
+- `sampling` (per-axis voxel spacing, scalar or per-axis) maps to scikit-fmm's
+  `dx` and applies to masks only — meshes carry real vertex coordinates.
+- `speed` is optional (`None` = unit-speed geodesic distance). When supplied it
+  generalizes to a weighted travel time, matching `skfmm.travel_time`; for
+  masks it has the mask's shape, for meshes it is per-vertex.
+- `number_of_threads` follows the `bic.distance` convention (`1` default,
+  `0` = hardware concurrency); the pairwise solves parallelize over sources.
+- `geodesic_distance_field(..., return_gradient=True)` also returns the per-axis
+  gradient `∇T` of the field (or use `geodesic_gradient_field` for the gradient
+  alone), analogous to `vector_difference_transform`. It is `float32` with shape
+  `(*mask.shape, ndim)` (channel-last, NumPy axis order); component `i` is
+  `d(field)/d(axis_i)`, pointing **away** from the nearest source with
+  `‖∇T‖ ≈ 1/speed`. Negate it to trace back toward the source — e.g. feed
+  `-grad` (transposed to channel-first) to `bic.flow.compute_flow_density`. It
+  is zero at sources, background, and unreachable voxels. Masks only.
+- Mesh geodesics are surface (2-manifold) distances from the Kimmel–Sethian
+  triangle fast-marching method — a first-order approximation (a few % mean
+  error vs the exact `pygeodesic` MMP algorithm, larger on very obtuse
+  triangles, since obtuse-angle unfolding is not done yet). Like the mask
+  solver it slightly overestimates. See `development/distance/` for the
+  reference oracles and `benchmark_geodesic.py` for timings.
+
 ## I/O and Build Dependencies
 
 `bioimage-cpp` intentionally does not replace nifty or affogato I/O helpers.

{bioimage_cpp-0.5.0 → bioimage_cpp-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: bioimage-cpp
-Version: 0.5.0
+Version: 0.6.0
 Summary: Dependency-light C++ bioimage analysis algorithms with Python bindings
 Author: bioimage-cpp contributors
 License: MIT

bioimage_cpp-0.6.0/development/distance/PERFORMANCE_NOTES.md

@@ -0,0 +1,103 @@
+# Geodesic FMM performance notes
+
+Optimization of the two geodesic Fast Marching Method solvers, with the
+before/after measurements that justify the changes. Both changes are pure
+reorganizations of identical arithmetic — the solved fields are **bitwise
+identical** to the pre-optimization solvers on every code path tested.
+
+## What changed
+
+- **Lead A — mask/grid solver** (`distance/detail/fast_marching.hxx`): the FMM
+  march no longer calls `detail::valid_offset_target` (one integer division +
+  modulo *per axis, per call*, ~42 calls / popped voxel in 3D). Each popped voxel
+  is decoded **once** with the new `detail::coords_from_index` (divide-and-subtract,
+  no modulo); axis neighbours are reached with a single `p ± strides_[d]` add and an
+  integer bounds compare, and the neighbour's coordinates are handed to
+  `solve_eikonal` so it never re-decodes. The `offsets_` `vector<vector>` is gone.
+- **Lead B — mesh solver** (`distance/detail/mesh_fast_marching.hxx`): when a
+  vertex `v` freezes, each incident face relaxes its other corners from *that face
+  alone* instead of calling `update_vertex`, which rescanned every incident face of
+  every touched vertex. `dist_[w]` is a running minimum that already reflects the
+  other faces' contributions (applied when their corners froze), so the single-face
+  update reaches the same value. `update_vertex` was removed. Operands are passed to
+  `triangle_update` in face-storage order so the acute update is bit-identical, not
+  just equal to within rounding.
+
+## Measurement setup
+
+8-core machine, `powersave` governor (frequency-scaling noise present; `perf`
+unavailable, `perf_event_paranoid=4`). Mitigations: 1 warmup call + 20 timed
+repeats, **min** used as the headline estimator (least-interference), spread
+reported. Single-source **field** solve, `--threads 1` — the single-source solve is
+the whole kernel (pairwise = N × field). Baseline and optimized were built
+separately; the **`mesh/field` case is a null control for Lead A** (its code is
+untouched between the baseline and A-only builds) and moved <1%, bounding machine
+drift below the measured mask gains. Lead A's mask numbers also reproduced within
+~1% across two independent builds (A-only and A+B).
+
+Reproduce (from `development/distance/`):
+
+```
+python benchmark_geodesic.py --large  --only field --threads 1 --repeats 20 --no-ref --json base.json
+python benchmark_geodesic.py --xlarge --only field --threads 1 --repeats 20 --no-ref --json opt.json
+python /path/to/compare.py base.json opt.json      # or diff the JSON directly
+```
+
+## Wall-clock: baseline → optimized (single-thread field, min of 20)
+
+| case | baseline min | optimized min | speedup |
+|---|---|---|---|
+| mask2d/field (1024²)      |  294.0 ms |  208.9 ms | **1.41×** |
+| mask2d/field (1536²)      |  685.6 ms |  492.7 ms | **1.39×** |
+| mask3d/field (64·128²)    |  745.1 ms |  370.2 ms | **2.01×** |
+| mask3d/field (128³)       | 1811.6 ms |  912.4 ms | **1.99×** |
+| mesh/field (V=20000)      |   23.2 ms |    7.9 ms | **2.94×** |
+| mesh/field (V=40000)      |   49.1 ms |   17.5 ms | **2.81×** |
+
+Lead A: ~2.0× in 3D (matches the div/mod arithmetic dominating 3 axes), ~1.4× in
+2D. Lead B: ~2.8–2.9× on the mesh. Both exceed the pre-work predictions (A: 1.5–2×
+3D; B: ~2×).
+
+## Mechanism confirmation (BIOIMAGE_PROFILE=ON, one field solve)
+
+Coarse phases in `solve()`: `pop` (heap pop, untouched by either change) vs `relax`
+(the neighbour/face loop where the removed work lived).
+
+| solve | phase | baseline | optimized | change |
+|---|---|---|---|---|
+| mask 128³ | pop   | 0.319 s | 0.316 s | unchanged |
+| mask 128³ | relax | 1.700 s | 0.762 s | **2.23× smaller** |
+| mesh 40k  | pop   | 0.0035 s | 0.0034 s | unchanged |
+| mesh 40k  | relax | 0.0500 s | 0.0163 s | **3.07× smaller** |
+
+The heap phase is invariant; the targeted `relax` phase shrank by 2.2× (mask) and
+3.1× (mesh). `pop`'s *share* rose (15.8%→29.3% mask; 6.5%→17.1% mesh) only because
+`relax` shrank around it — the gain came from exactly the phase each change targeted.
+
+## Versus reference (single-thread field, min of 10)
+
+| case | bioimage-cpp | reference | speedup |
+|---|---|---|---|
+| mask2d/field (1024²)   | 210.5 ms | scikit-fmm 331.8 ms | **1.58×** |
+| mask3d/field (64·128²) | 368.9 ms | scikit-fmm 761.4 ms | **2.06×** |
+| mesh/field (V=20000)   |   8.4 ms | pygeodesic 1745 ms  | 208× (apples-to-oranges: pygeodesic is *exact* MMP, ours is first-order) |
+
+The mask solver went from parity with scikit-fmm's compiled C (pre-work ~1.0–1.1×)
+to a clear lead (1.58× in 2D, 2.06× in 3D).
+
+## Correctness (all green on the shipping build)
+
+- `pytest tests/distance/ -q` — 64 passed. The tight external cross-checks ran
+  (not skipped): `test_mask_matches_scikit_fmm` (residual < 1e-6),
+  `test_mesh_matches_pygeodesic` (mean rel < 0.06, p95 < 0.12).
+- `python check_geodesic_distance.py` — all 6 cases OK, exit 0 (mask residuals
+  ~1e-12 vs scikit-fmm; mesh rel mean 0.027).
+- **Bitwise equivalence**: 13 solver outputs (2D/3D field, anisotropic `sampling`,
+  `speed`, gradient, mask + mesh pairwise, mesh `speed`) are exactly equal
+  (`np.array_equal`) between the baseline and optimized builds. Determinism verified
+  (repeat solves identical). This is the dev-time check behind the "bitwise
+  identical" claim; the pytest suite guards correctness against the external
+  references on every run.
+
+The profiler instrumentation (`BIOIMAGE_PROFILE_SCOPE` "pop"/"relax") is left in both
+solvers; it is a no-op unless built with `-C cmake.define.BIOIMAGE_PROFILE=ON`.

bioimage_cpp-0.6.0/development/distance/_geodesic_reference.py

@@ -0,0 +1,155 @@
+"""Reference geodesic-distance implementations for development cross-checks.
+
+These are the oracles that ``bic.distance`` geodesic functions are validated
+against. There is one backend per geometry, because scikit-fmm only supports
+regular Cartesian grids:
+
+- **masks**  -> scikit-fmm (``skfmm``): fast marching / Eikonal solver.
+- **meshes** -> pygeodesic: exact Mitchell-Mount-Papadimitriou (MMP) geodesics.
+
+Not part of the pytest suite; requires ``scikit-fmm`` and/or ``pygeodesic``.
+Importing this module is cheap (numpy only); each function imports its backend
+lazily and raises a clear ``ImportError`` if the backend is missing.
+
+Note on the scikit-fmm point-source idiom: to get the distance to a set of
+seed voxels, we set ``phi = +1`` everywhere and ``phi = -1`` at the seeds and
+take ``|skfmm.distance(phi)|``. The zero contour then sits roughly half a cell
+away from each seed, so the reference is offset from a "distance is exactly 0 at
+the seed" convention by ~0.5 * dx near the sources. Compare with a tolerance,
+or exclude the immediate neighbourhood of the seeds, when checking against an
+implementation that initialises the seeds to exactly 0.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+# --------------------------------------------------------------------------- #
+# masks: scikit-fmm
+# --------------------------------------------------------------------------- #
+
+
+def _skfmm():
+    try:
+        import skfmm
+    except ImportError as error:  # pragma: no cover - dev script
+        raise ImportError(
+            "scikit-fmm is required for the mask geodesic reference "
+            "(`pip install scikit-fmm`)"
+        ) from error
+    return skfmm
+
+
+def _normalize_dx(sampling, ndim):
+    if sampling is None:
+        return 1.0
+    if np.isscalar(sampling):
+        return float(sampling)
+    dx = [float(s) for s in sampling]
+    if len(dx) != ndim:
+        raise ValueError(f"sampling must have length {ndim}, got {len(dx)}")
+    return dx
+
+
+def reference_geodesic_field_mask(mask, sources, sampling=None, speed=None):
+    """Geodesic distance field within a mask from a set of source coordinates.
+
+    Mirrors ``bic.distance.geodesic_distance_field``: for every voxel, the
+    shortest-path distance to the nearest source, constrained to the nonzero
+    region of ``mask``. Voxels outside the mask (and voxels unreachable from any
+    source) are returned as ``+inf``.
+    """
+    skfmm = _skfmm()
+    mask = np.ascontiguousarray(mask) != 0
+    sources = np.atleast_2d(np.asarray(sources, dtype=np.int64))
+    dx = _normalize_dx(sampling, mask.ndim)
+
+    phi = np.ones(mask.shape, dtype=np.float64)
+    phi[tuple(sources.T)] = -1.0
+    phi = np.ma.MaskedArray(phi, mask=~mask)
+
+    # order=1 matches bioimage-cpp's first-order Godunov scheme (so agreement is
+    # limited only by the ~0.5-cell seed offset documented above, not by the
+    # stencil order).
+    if speed is None:
+        field = np.ma.abs(skfmm.distance(phi, dx=dx, order=1))
+    else:
+        speed = np.ascontiguousarray(speed, dtype=np.float64)
+        field = skfmm.travel_time(phi, speed, dx=dx, order=1)
+
+    out = np.full(mask.shape, np.inf, dtype=np.float64)
+    field_data = np.ma.getdata(field)
+    valid = ~np.ma.getmaskarray(field)
+    out[valid] = field_data[valid]
+    return out
+
+
+def reference_geodesic_distances_mask(mask, points, sampling=None, speed=None):
+    """Full pairwise geodesic distance matrix between points within a mask.
+
+    Runs the field solve once per point and reads the field at the other
+    points. The result is symmetrized (per-source solves can differ by a tiny
+    numerical amount) with a zero diagonal.
+    """
+    points = np.atleast_2d(np.asarray(points, dtype=np.int64))
+    n = len(points)
+    out = np.full((n, n), np.inf, dtype=np.float64)
+    index = tuple(points.T)
+    for i in range(n):
+        field = reference_geodesic_field_mask(mask, points[i][None, :], sampling, speed)
+        out[i] = field[index]
+    out = 0.5 * (out + out.T)
+    np.fill_diagonal(out, 0.0)
+    return out
+
+
+# --------------------------------------------------------------------------- #
+# meshes: pygeodesic (exact MMP)
+# --------------------------------------------------------------------------- #
+
+
+def _pygeodesic():
+    try:
+        import pygeodesic.geodesic as geodesic
+    except ImportError as error:  # pragma: no cover - dev script
+        raise ImportError(
+            "pygeodesic is required for the mesh geodesic reference "
+            "(`pip install pygeodesic`)"
+        ) from error
+    return geodesic
+
+
+def _mesh_algorithm(vertices, faces):
+    geodesic = _pygeodesic()
+    vertices = np.ascontiguousarray(vertices, dtype=np.float64)
+    faces = np.ascontiguousarray(faces, dtype=np.int32)
+    return geodesic.PyGeodesicAlgorithmExact(vertices, faces)
+
+
+def reference_geodesic_field_mesh(vertices, faces, sources):
+    """Geodesic distance field on a triangle mesh from a set of source vertices.
+
+    Mirrors ``bic.distance.geodesic_distance_field_mesh``. Returns a
+    ``(n_vertices,)`` array of surface geodesic distance to the nearest source.
+    """
+    algo = _mesh_algorithm(vertices, faces)
+    sources = np.atleast_1d(np.asarray(sources, dtype=np.int32))
+    distances, _ = algo.geodesicDistances(sources, None)
+    return np.asarray(distances, dtype=np.float64)
+
+
+def reference_geodesic_distances_mesh(vertices, faces, points):
+    """Full pairwise geodesic distance matrix between mesh vertices."""
+    algo = _mesh_algorithm(vertices, faces)
+    points = np.atleast_1d(np.asarray(points, dtype=np.int32))
+    n = len(points)
+    out = np.full((n, n), np.inf, dtype=np.float64)
+    for i in range(n):
+        # Read the full single-source field and index the targets; passing an
+        # explicit target array to pygeodesic can overflow on some meshes.
+        distances, _ = algo.geodesicDistances(points[i : i + 1], None)
+        out[i] = np.asarray(distances, dtype=np.float64)[points]
+    out = 0.5 * (out + out.T)
+    np.fill_diagonal(out, 0.0)
+    return out

bioimage_cpp-0.6.0/development/distance/benchmark_geodesic.py

@@ -0,0 +1,243 @@
+"""Benchmark geodesic distances: bioimage-cpp vs scikit-fmm / pygeodesic.
+
+Times the ``bic.distance`` geodesic entry points against their reference oracles
+(scikit-fmm for masks, pygeodesic exact for meshes) on a range of mask grids and
+sphere meshes, reporting per-call statistics and (optionally) the speedup versus
+the reference. Reference columns are skipped when the backend is not installed or
+when ``--no-ref`` is passed.
+
+For each case it reports the min, median and spread (p75-p25) of the timed calls
+plus ``ns/unit`` — nanoseconds per element processed (voxels for a field solve,
+sources x voxels for a pairwise matrix), a size-independent throughput number that
+is directly comparable across sizes and dimensionalities and is the right metric
+for before/after optimization comparisons.
+
+For rigorous before/after measurement use a high ``--repeats`` (>=15), pin
+``--threads 1`` on the field cases, run on a quiet machine, and dump ``--json`` for
+each build so the two runs can be diffed. Interleave baseline/optimized builds to
+cancel slow thermal/scheduler drift.
+
+Not part of the pytest suite; requires scikit-fmm, pygeodesic and scipy (the last
+only for the sphere-mesh construction; ``--no-ref`` still needs scipy for meshes).
+
+Run::
+
+    python benchmark_geodesic.py --small
+    python benchmark_geodesic.py --large --threads 0
+    python benchmark_geodesic.py --xlarge --only field --threads 1 --repeats 20 \\
+        --no-ref --json /tmp/baseline.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import sys
+from statistics import median
+from time import perf_counter
+
+import numpy as np
+
+import bioimage_cpp as bic
+
+from _geodesic_reference import (
+    reference_geodesic_distances_mask,
+    reference_geodesic_distances_mesh,
+    reference_geodesic_field_mask,
+    reference_geodesic_field_mesh,
+)
+
+
+def available(name: str) -> bool:
+    return importlib.util.find_spec(name) is not None
+
+
+def time_call(fn, repeats: int, warmup: int = 1) -> list[float]:
+    """Return the list of per-call wall-clock times (seconds), after warmup."""
+    for _ in range(warmup):
+        fn()
+    timings = []
+    for _ in range(repeats):
+        start = perf_counter()
+        fn()
+        timings.append(perf_counter() - start)
+    return timings
+
+
+def stats(timings: list[float]) -> dict:
+    ordered = sorted(timings)
+    n = len(ordered)
+    p25 = ordered[max(0, (n - 1) // 4)]
+    p75 = ordered[min(n - 1, (3 * (n - 1)) // 4)]
+    return {
+        "min": ordered[0],
+        "median": median(ordered),
+        "max": ordered[-1],
+        "spread": p75 - p25,
+    }
+
+
+def make_sphere(n_points: int, radius: float = 5.0, seed: int = 0):
+    from scipy.spatial import ConvexHull
+
+    rng = np.random.default_rng(seed)
+    pts = rng.standard_normal((n_points, 3))
+    pts /= np.linalg.norm(pts, axis=1, keepdims=True)
+    pts *= radius
+    verts = np.ascontiguousarray(pts, dtype=np.float64)
+    faces = np.ascontiguousarray(ConvexHull(pts).simplices, dtype=np.int64)
+    return verts, faces
+
+
+def scattered_points(n_axis_points: int, ndim: int, extent: int) -> np.ndarray:
+    coords = np.linspace(1, extent - 2, num=n_axis_points, dtype=np.int64)
+    grids = np.meshgrid(*([coords] * ndim), indexing="ij")
+    return np.stack([g.ravel() for g in grids], axis=1).astype(np.int64)
+
+
+def build_cases(args):
+    """Return a list of (name, bic_fn, ref_fn, n_units) tuples for the size.
+
+    ``n_units`` is the number of elements processed by one call: the voxel/vertex
+    count for a field solve, or ``n_sources * count`` for a pairwise matrix. It is
+    the denominator for the ns/unit throughput metric.
+    """
+    if args.small:
+        mask2d_shape, mask3d_shape, mesh_n = (256, 256), (24, 48, 48), 1500
+    elif args.large:
+        mask2d_shape, mask3d_shape, mesh_n = (1024, 1024), (64, 128, 128), 20000
+    elif args.xlarge:
+        mask2d_shape, mask3d_shape, mesh_n = (1536, 1536), (128, 128, 128), 40000
+    else:
+        mask2d_shape, mask3d_shape, mesh_n = (512, 512), (32, 96, 96), 5000
+
+    def prod(shape):
+        n = 1
+        for s in shape:
+            n *= s
+        return n
+
+    cases = []
+
+    mask2d = np.ones(mask2d_shape, np.uint8)
+    src2d = np.array([[mask2d_shape[0] // 2, mask2d_shape[1] // 2]], np.int64)
+    pts2d = scattered_points(args.n_pairwise, 2, min(mask2d_shape))
+    cases.append((
+        f"mask2d/field {mask2d_shape}",
+        lambda: bic.distance.geodesic_distance_field(mask2d, src2d, number_of_threads=args.threads),
+        lambda: reference_geodesic_field_mask(mask2d, src2d),
+        prod(mask2d_shape),
+    ))
+    cases.append((
+        f"mask2d/pairwise N={len(pts2d)}",
+        lambda: bic.distance.geodesic_distances(mask2d, pts2d, number_of_threads=args.threads),
+        lambda: reference_geodesic_distances_mask(mask2d, pts2d),
+        len(pts2d) * prod(mask2d_shape),
+    ))
+
+    mask3d = np.ones(mask3d_shape, np.uint8)
+    src3d = np.array([[s // 2 for s in mask3d_shape]], np.int64)
+    pts3d = scattered_points(args.n_pairwise, 3, min(mask3d_shape))
+    cases.append((
+        f"mask3d/field {mask3d_shape}",
+        lambda: bic.distance.geodesic_distance_field(mask3d, src3d, number_of_threads=args.threads),
+        lambda: reference_geodesic_field_mask(mask3d, src3d),
+        prod(mask3d_shape),
+    ))
+    cases.append((
+        f"mask3d/pairwise N={len(pts3d)}",
+        lambda: bic.distance.geodesic_distances(mask3d, pts3d, number_of_threads=args.threads),
+        lambda: reference_geodesic_distances_mask(mask3d, pts3d),
+        len(pts3d) * prod(mask3d_shape),
+    ))
+
+    verts, faces = make_sphere(mesh_n, seed=args.seed)
+    src_v = np.array([0], np.int64)
+    pts_v = np.linspace(0, len(verts) - 1, num=args.n_pairwise, dtype=np.int64)
+    cases.append((
+        f"mesh/field V={len(verts)}",
+        lambda: bic.distance.geodesic_distance_field_mesh(verts, faces, src_v, number_of_threads=args.threads),
+        lambda: reference_geodesic_field_mesh(verts, faces, src_v),
+        len(verts),
+    ))
+    cases.append((
+        f"mesh/pairwise N={len(pts_v)}",
+        lambda: bic.distance.geodesic_distances_mesh(verts, faces, pts_v, number_of_threads=args.threads),
+        lambda: reference_geodesic_distances_mesh(verts, faces, pts_v),
+        len(pts_v) * len(verts),
+    ))
+
+    if args.only:
+        cases = [c for c in cases if args.only in c[0]]
+    return cases
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repeats", type=int, default=7)
+    parser.add_argument("--small", action="store_true")
+    parser.add_argument("--large", action="store_true")
+    parser.add_argument("--xlarge", action="store_true")
+    parser.add_argument("--threads", type=int, default=1, help="0 = hardware concurrency")
+    parser.add_argument("--n-pairwise", type=int, default=8, dest="n_pairwise",
+                        help="points per axis (mask) / total points (mesh) for pairwise")
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--no-ref", action="store_true", help="skip reference timings")
+    parser.add_argument("--only", type=str, default="",
+                        help="substring filter on case name, e.g. 'field' or 'mask3d'")
+    parser.add_argument("--json", type=str, default="", help="dump results to this JSON path")
+    args = parser.parse_args()
+    n_sizes = sum(bool(x) for x in (args.small, args.large, args.xlarge))
+    if n_sizes > 1:
+        print("choose at most one of --small / --large / --xlarge", file=sys.stderr)
+        return 2
+
+    have_mask_ref = available("skfmm") and not args.no_ref
+    have_mesh_ref = available("pygeodesic") and not args.no_ref
+    if not args.no_ref:
+        if not available("skfmm"):
+            print("scikit-fmm not installed: mask reference column skipped", file=sys.stderr)
+        if not available("pygeodesic"):
+            print("pygeodesic not installed: mesh reference column skipped", file=sys.stderr)
+
+    cases = build_cases(args)
+
+    header = (f"{'case':>26} {'bic_min':>10} {'bic_med':>10} {'spread':>9} "
+              f"{'ns/unit':>9} {'ref_med':>10} {'speedup':>9}")
+    print(f"threads={args.threads} repeats={args.repeats}")
+    print(header)
+    print("-" * len(header))
+    results = []
+    for name, bic_fn, ref_fn, n_units in cases:
+        bic_t = time_call(bic_fn, args.repeats)
+        bs = stats(bic_t)
+        ns_per_unit = bs["median"] / n_units * 1e9
+        is_mesh = name.startswith("mesh")
+        has_ref = have_mesh_ref if is_mesh else have_mask_ref
+        entry = {"case": name, "n_units": n_units, "threads": args.threads,
+                 "bic_s": bs, "ns_per_unit": ns_per_unit}
+        if has_ref:
+            ref_t = time_call(ref_fn, args.repeats)
+            rs = stats(ref_t)
+            speed = rs["median"] / bs["median"]
+            entry["ref_s"] = rs
+            entry["speedup"] = speed
+            ref_col, speed_col = f"{rs['median']*1e3:10.2f}", f"{speed:6.2f}x"
+        else:
+            ref_col, speed_col = f"{'n/a':>10}", f"{'n/a':>9}"
+        print(f"{name:>26} {bs['min']*1e3:10.2f} {bs['median']*1e3:10.2f} "
+              f"{bs['spread']*1e3:9.2f} {ns_per_unit:9.1f} {ref_col} {speed_col:>9}")
+        results.append(entry)
+
+    if args.json:
+        with open(args.json, "w") as fh:
+            json.dump({"threads": args.threads, "repeats": args.repeats,
+                       "results": results}, fh, indent=2)
+        print(f"wrote {args.json}", file=sys.stderr)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())