eiko-skelfm 0.1.0__tar.gz

eiko_skelfm-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: eiko-skelfm
+Version: 0.1.0
+Summary: Fast Marching Method - Python port of Kroon's toolbox
+Author: Fernando Julian Chaure
+License: BSD-2-Clause
+Keywords: fast marching method,skeleton
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: C
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.19
+Requires-Dist: scipy>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: matplotlib>=3.5; extra == "dev"
+
+# eiko_skelfm
+
+Fast-marching skeleton extraction for 2D and 3D binary images.  
+Port of Kroon's MATLAB/MEX FastMarching toolbox to standalone C + Python/NumPy.
+
+![Skeleton extraction result](docs/figures/skeleton_2d_result.png)
+
+## Installation
+
+```bash
+pip install -e .
+
+# with dev dependencies (pytest, matplotlib)
+pip install -e ".[dev]"
+```
+
+## Quick Example — 2D skeleton
+
+```python
+import numpy as np
+from scipy.ndimage import gaussian_filter
+import matplotlib.pyplot as plt
+from eiko_skelfm.skeleton import skeleton
+
+# 1. Create a thin skeleton: center dot + 4 radiating lines
+shape = (100, 100)
+skel = np.zeros(shape, dtype=bool)
+cy, cx = 50, 50
+skel[cy, cx] = True
+for t in range(1, 40):
+    skel[cy + int(4 * (1 - np.cos(t / 4.0))), cx + t] = True  # line → +x (cosine)
+    skel[cy + t, cx - t // 5] = True   # line → +y
+    skel[cy - t, cx + t // 5] = True   # line → −y
+for t in range(1, 30):
+    skel[cy - t // 4, cx - t] = True                 # line → −x (seg 1)
+    skel[cy - 7 - t, cx - 29 - t // 3] = True        # line → −x (seg 2)
+for t in range(1, 20):
+    skel[cy + int(4 * (1 - np.cos(5.0))) + t, cx + 20 + t // 2] = True # branch 1
+    skel[cy - 7 + t // 3, cx - 29 - t] = True                          # branch 2
+    skel[cy + 20 + t // 3, cx - 4 + t] = True                          # branch 3
+    skel[cy - 20 - t // 3, cx + 4 - t] = True                          # branch 4
+
+# 2. Convolve with a Gaussian to create a tubular binary mask
+convolved = gaussian_filter(skel.astype(float), sigma=3.0)
+binary_mask = convolved > convolved.max() * 0.15
+
+# 3. Extract the skeleton
+segments = skeleton(binary_mask, verbose=True)
+
+# 4. Plot the result
+fig, axes = plt.subplots(1, 4, figsize=(18, 4.5))
+axes[0].imshow(skel, cmap="gray", origin="lower")
+axes[0].set_title("Ground-truth skeleton")
+
+axes[1].imshow(convolved, cmap="inferno", origin="lower")
+axes[1].set_title("After Gaussian blur (σ=3)")
+
+axes[2].imshow(binary_mask, cmap="gray", origin="lower")
+axes[2].set_title("Binary mask")
+
+axes[3].imshow(binary_mask, cmap="gray", origin="lower", alpha=0.35)
+for seg in segments:
+    axes[3].plot(seg[:, 1], seg[:, 0], linewidth=2)
+axes[3].set_title("Extracted skeleton")
+
+plt.tight_layout()
+plt.savefig("skeleton_2d.png", dpi=150)
+plt.show()
+```
+
+![Four-panel overview](docs/figures/skeleton_2d_overview.png)
+
+See [`docs/example_skeleton_2d.py`](docs/example_skeleton_2d.py) for the full runnable script.
+
+## Build Standalone C Library
+
+### Linux (GCC)
+```bash
+gcc -O2 -std=c99 -c src/common.c src/msfm2d.c src/msfm3d.c -lm
+ar rcs libeiko_skelfm.a common.o msfm2d.o msfm3d.o
+```
+
+### macOS (Clang)
+```bash
+clang -O2 -std=c99 -c src/common.c src/msfm2d.c src/msfm3d.c
+ar rcs libeiko_skelfm.a common.o msfm2d.o msfm3d.o
+```
+
+### Windows (MSVC)
+```cmd
+cl /O2 /c src\common.c src\msfm2d.c src\msfm3d.c
+lib /OUT:fastmarching.lib common.obj msfm2d.obj msfm3d.obj
+```
+
+### Windows (MinGW)
+```bash
+gcc -O2 -std=c99 -c src/common.c src/msfm2d.c src/msfm3d.c 
+ar rcs libeiko_skelfm.a common.o msfm2d.o msfm3d.o
+```
+
+### CMake
+```bash
+cmake -B build -S .
+cmake --build build
+```
+

eiko_skelfm-0.1.0/README.md

@@ -0,0 +1,106 @@
+# eiko_skelfm
+
+Fast-marching skeleton extraction for 2D and 3D binary images.  
+Port of Kroon's MATLAB/MEX FastMarching toolbox to standalone C + Python/NumPy.
+
+![Skeleton extraction result](docs/figures/skeleton_2d_result.png)
+
+## Installation
+
+```bash
+pip install -e .
+
+# with dev dependencies (pytest, matplotlib)
+pip install -e ".[dev]"
+```
+
+## Quick Example — 2D skeleton
+
+```python
+import numpy as np
+from scipy.ndimage import gaussian_filter
+import matplotlib.pyplot as plt
+from eiko_skelfm.skeleton import skeleton
+
+# 1. Create a thin skeleton: center dot + 4 radiating lines
+shape = (100, 100)
+skel = np.zeros(shape, dtype=bool)
+cy, cx = 50, 50
+skel[cy, cx] = True
+for t in range(1, 40):
+    skel[cy + int(4 * (1 - np.cos(t / 4.0))), cx + t] = True  # line → +x (cosine)
+    skel[cy + t, cx - t // 5] = True   # line → +y
+    skel[cy - t, cx + t // 5] = True   # line → −y
+for t in range(1, 30):
+    skel[cy - t // 4, cx - t] = True                 # line → −x (seg 1)
+    skel[cy - 7 - t, cx - 29 - t // 3] = True        # line → −x (seg 2)
+for t in range(1, 20):
+    skel[cy + int(4 * (1 - np.cos(5.0))) + t, cx + 20 + t // 2] = True # branch 1
+    skel[cy - 7 + t // 3, cx - 29 - t] = True                          # branch 2
+    skel[cy + 20 + t // 3, cx - 4 + t] = True                          # branch 3
+    skel[cy - 20 - t // 3, cx + 4 - t] = True                          # branch 4
+
+# 2. Convolve with a Gaussian to create a tubular binary mask
+convolved = gaussian_filter(skel.astype(float), sigma=3.0)
+binary_mask = convolved > convolved.max() * 0.15
+
+# 3. Extract the skeleton
+segments = skeleton(binary_mask, verbose=True)
+
+# 4. Plot the result
+fig, axes = plt.subplots(1, 4, figsize=(18, 4.5))
+axes[0].imshow(skel, cmap="gray", origin="lower")
+axes[0].set_title("Ground-truth skeleton")
+
+axes[1].imshow(convolved, cmap="inferno", origin="lower")
+axes[1].set_title("After Gaussian blur (σ=3)")
+
+axes[2].imshow(binary_mask, cmap="gray", origin="lower")
+axes[2].set_title("Binary mask")
+
+axes[3].imshow(binary_mask, cmap="gray", origin="lower", alpha=0.35)
+for seg in segments:
+    axes[3].plot(seg[:, 1], seg[:, 0], linewidth=2)
+axes[3].set_title("Extracted skeleton")
+
+plt.tight_layout()
+plt.savefig("skeleton_2d.png", dpi=150)
+plt.show()
+```
+
+![Four-panel overview](docs/figures/skeleton_2d_overview.png)
+
+See [`docs/example_skeleton_2d.py`](docs/example_skeleton_2d.py) for the full runnable script.
+
+## Build Standalone C Library
+
+### Linux (GCC)
+```bash
+gcc -O2 -std=c99 -c src/common.c src/msfm2d.c src/msfm3d.c -lm
+ar rcs libeiko_skelfm.a common.o msfm2d.o msfm3d.o
+```
+
+### macOS (Clang)
+```bash
+clang -O2 -std=c99 -c src/common.c src/msfm2d.c src/msfm3d.c
+ar rcs libeiko_skelfm.a common.o msfm2d.o msfm3d.o
+```
+
+### Windows (MSVC)
+```cmd
+cl /O2 /c src\common.c src\msfm2d.c src\msfm3d.c
+lib /OUT:fastmarching.lib common.obj msfm2d.obj msfm3d.obj
+```
+
+### Windows (MinGW)
+```bash
+gcc -O2 -std=c99 -c src/common.c src/msfm2d.c src/msfm3d.c 
+ar rcs libeiko_skelfm.a common.o msfm2d.o msfm3d.o
+```
+
+### CMake
+```bash
+cmake -B build -S .
+cmake --build build
+```
+

eiko_skelfm-0.1.0/eiko_skelfm/__init__.py

@@ -0,0 +1,3 @@
+from .msfm import msfm
+
+__all__ = ['msfm']

eiko_skelfm-0.1.0/eiko_skelfm/msfm.py

@@ -0,0 +1,46 @@
+import numpy as np
+from . import _msfm
+
+def msfm(speed, source_points, use_second=True, use_cross=True, return_y=False):
+    """
+    Fast Marching Method solver.
+
+    Parameters
+    ----------
+    speed : ndarray (2D or 3D), float64
+        Speed image. Must be Fortran-contiguous.
+    source_points : ndarray, shape (ndim, N), float64
+        Source points (0-indexed). Must be Fortran-contiguous with
+        2 rows for 2D or 3 rows for 3D.
+    use_second : bool
+        Use second-order derivatives.
+    use_cross : bool
+        Use cross/diagonal stencils.
+    return_y : bool
+        Also return Euclidean distance (for skeleton extraction).
+
+    Returns
+    -------
+    T : ndarray, same shape as speed (distance field, Fortran order)
+    Y : ndarray or None (Euclidean distance, Fortran order)
+    """
+    speed = np.asfortranarray(speed, dtype=np.float64)
+    speed = np.clip(speed, 1e-8, None)
+    source_points = np.asfortranarray(source_points, dtype=np.float64)
+
+    if speed.ndim == 3:
+        if source_points.shape[0] != 3:
+            raise ValueError("source_points must be 3xN for 3D speed")
+        result = _msfm.msfm3d(speed, source_points,
+                              use_second,use_cross,
+                              return_y)
+    elif speed.ndim == 2:
+        if source_points.shape[0] != 2:
+            raise ValueError("source_points must be 2xN for 2D speed")
+        result = _msfm.msfm2d(speed, source_points,
+                               use_second,use_cross,
+                               return_y)
+    else:
+        raise ValueError("speed must be 2D or 3D")
+
+    return result

eiko_skelfm-0.1.0/eiko_skelfm/shortestpath.py

@@ -0,0 +1,198 @@
+"""
+shortestpath.py
+---------------
+Python port of the MATLAB shortestpath function by Dirk-Jan Kroon.
+
+Traces the shortest path from a start point to a source point in a 2D or 3D
+distance map using Runge-Kutta 4 (RK4) on the negative gradient field.
+
+Design decisions
+----------------
+Normalisation (two-stage):
+    Gradients are normalised on the integer grid *before* building the
+    interpolators (stability in flat regions where raw values are tiny),
+    then re-normalised after each interpolation call (because bilinear/
+    trilinear interpolation of unit vectors does not preserve unit length).
+
+Termination (four independent guards, checked in order):
+    1. Source proximity  — Euclidean distance <= stepsize.
+    2. Out-of-bounds     — next point lies outside the map extents.
+    3. Velocity collapse — interpolated velocity norm < 1e-6 (stuck /
+                           left the map into the fill_value=0 region).
+    4. Monotone descent  — distance stops decreasing by more than a small
+                           epsilon (1e-12).  The epsilon avoids a spurious
+                           stop on quantisation plateaux in low-resolution
+                           or integer-valued maps.
+
+Final step:
+    When the source-proximity guard fires, the last appended point is a
+    proportional micro-step toward source_point rather than a hard teleport,
+    so the path length and direction are physically consistent at the end.
+
+Performance note:
+    Each RK4 iteration calls the interpolators 4 times (once per sub-step),
+    once per spatial dimension.  For a single path this is negligible.
+    For thousands of paths in a tight loop, consider vectorising the
+    interpolation calls or pre-building a raw gradient array and using
+    scipy.ndimage.map_coordinates, which has lower per-call overhead.
+
+RK4 vs simpler integrators:
+    RK4 is technically overkill for a smooth distance map.  Euler or RK2
+    would converge too, but RK4 produces noticeably smoother paths in
+    curved corridors and near saddle points, at a cost of 4x the
+    interpolation calls per step.
+"""
+
+import numpy as np
+from scipy.interpolate import RegularGridInterpolator
+
+
+def shortestpath(
+    distance_map,
+    start_point,
+    source_point=None,
+    stepsize: float = 0.5,
+    max_iter: int = 10_000,
+) -> np.ndarray:
+    """
+    Trace the shortest path in a 2-D or 3-D distance map using RK4 integration
+    on the normalised negative gradient field.
+
+    Parameters
+    ----------
+    distance_map : array-like, shape (R, C) or (R, C, D)
+        Distance map produced by a fast-marching / eikonal solver.
+        Axis order: (row, col) for 2-D, (row, col, depth) for 3-D.
+    start_point : array-like, length ndim
+        Starting position in index coordinates, e.g. [row, col].
+    source_point : array-like, length ndim, optional
+        End position.  Integration stops when the path arrives within
+        `stepsize` of this point.  If None, the monotone-descent guard
+        acts as the termination criterion.
+    stepsize : float, optional
+        RK4 step size in pixels.  Default 0.5.
+        Large values (e.g. 2.0) speed up tracing but produce a coarser
+        path and a more visible "snap" at the very end.
+    max_iter : int, optional
+        Hard iteration cap. Default 10 000.
+
+    Returns
+    -------
+    path : np.ndarray, shape (M, ndim)
+        Ordered positions from start_point to source_point (inclusive).
+    """
+    # ------------------------------------------------------------------
+    # 0. Validate & coerce inputs
+    # ------------------------------------------------------------------
+    distance_map = np.asarray(distance_map, dtype=float)
+    ndim = distance_map.ndim
+    if ndim not in (2, 3):
+        raise ValueError("distance_map must be 2-D or 3-D.")
+
+    start_point = np.asarray(start_point, dtype=float).ravel()
+    if start_point.size != ndim:
+        raise ValueError(f"start_point must have {ndim} elements.")
+
+    source_point = (
+        np.asarray(source_point, dtype=float).T  # (K, ndim), K>=1
+        if source_point is not None
+        else None
+    )
+
+    shape  = distance_map.shape
+    axes   = tuple(np.arange(s) for s in shape)
+    bounds = np.array([[0.0, s - 1.0] for s in shape])   # (ndim, 2)
+
+    # ------------------------------------------------------------------
+    # 1. Precompute normalised gradient field on the integer grid
+    # ------------------------------------------------------------------
+    grads    = np.gradient(distance_map)
+    if isinstance(grads, np.ndarray):        # guard: ndim==1 edge case
+        grads = [grads]
+
+    grad_mag = np.sqrt(sum(g ** 2 for g in grads))
+    grad_mag[grad_mag < 1e-10] = 1.0        # avoid division by zero in flat zones
+
+    norm_grads = [-g / grad_mag for g in grads]   # point toward decreasing distance
+
+    # ------------------------------------------------------------------
+    # 2. Build interpolators
+    #    fill_value=0.0  →  velocity collapses to zero outside the map,
+    #    which is caught by the norm < 1e-6 guard (termination guard 3).
+    # ------------------------------------------------------------------
+    vel_interps = [
+        RegularGridInterpolator(axes, ng, method="linear",
+                                bounds_error=False, fill_value=0.0)
+        for ng in norm_grads
+    ]
+
+    dist_interp = RegularGridInterpolator(
+        axes, distance_map, method="linear",
+        bounds_error=False, fill_value=np.inf
+    )
+
+    # ------------------------------------------------------------------
+    # 3. Velocity helper
+    #    Re-normalise after interpolation: bilinear/trilinear interpolation
+    #    of unit vectors does NOT preserve unit length; the re-normalisation
+    #    keeps the trace speed constant throughout integration.
+    # ------------------------------------------------------------------
+    def velocity(p: np.ndarray) -> np.ndarray:
+        q   = p[np.newaxis, :]                        # shape (1, ndim)
+        v   = np.array([f(q)[0] for f in vel_interps])
+        mag = np.linalg.norm(v)
+        return v / mag if mag > 1e-6 else np.zeros(ndim)
+
+    # ------------------------------------------------------------------
+    # 4. RK4 integration
+    # ------------------------------------------------------------------
+    path    = [start_point.copy()]
+    current = start_point.copy()
+    h       = stepsize
+    prev_dist = dist_interp(current[np.newaxis, :])[0]
+
+    for _ in range(max_iter):
+
+        # RK4 sub-steps -------------------------------------------------------
+        k1 = velocity(current)
+
+        # Guard 3 — velocity collapse ---------
+        if np.linalg.norm(k1) < 1e-6:
+            break
+
+        k2 = velocity(current + 0.5 * h * k1)
+        k3 = velocity(current + 0.5 * h * k2)
+        k4 = velocity(current +        h * k3)
+
+        next_point = current + (h / 6.0) * (k1 + 2*k2 + 2*k3 + k4)
+
+        # Guard 2 — out-of-bounds check (on the NEW point, like MATLAB) -------
+        if not np.all((next_point >= bounds[:, 0]) & (next_point <= bounds[:, 1])):
+            break
+
+        # Guard 4 — monotone descent, evaluated on the NEW point --------------
+        curr_dist = dist_interp(next_point[np.newaxis, :])[0]
+        if curr_dist > prev_dist + 1e-12:
+            break
+        prev_dist = curr_dist
+
+        current = next_point
+        path.append(current.copy())
+
+        # Guard 1 — source proximity
+        if source_point is not None:
+            deltas = source_point - current[np.newaxis, :]   # (K, ndim)
+            dists  = np.linalg.norm(deltas, axis=1)
+            idx    = np.argmin(dists)
+            dist_to_source = dists[idx]
+
+            if dist_to_source <= h:
+                nearest_source = source_point[idx]
+                direction = nearest_source - current
+                dir_norm  = np.linalg.norm(direction)
+                if dir_norm > 1e-10:
+                    path.append(current + direction * (dist_to_source / dir_norm))
+                else:
+                    path.append(nearest_source.copy())
+                break
+    return np.array(path)