pyneuronj 1.0__py3-none-any.whl

pyneuronj/__init__.py

@@ -0,0 +1,31 @@
+"""Two-dimensional fiber tracing from an image and endpoint pairs."""
+
+from .api import PyNeuronJ
+from .detector import DetectionResult, NeuronDetector
+from .io import load_trace, rasterize_path, save_csv, save_trace
+from .ndf import NdfDocument, NdfTracing, load_ndf, save_ndf
+from .path import TraceResult, compare_polylines, polyline_length, smooth_and_subsample
+from .session import LiveWireSession
+from .tracer import NeuronTracer, NoPathError, SearchTree
+
+__all__ = [
+    "PyNeuronJ",
+    "TraceResult",
+    "NoPathError",
+    "DetectionResult",
+    "NeuronDetector",
+    "NeuronTracer",
+    "SearchTree",
+    "LiveWireSession",
+    "polyline_length",
+    "smooth_and_subsample",
+    "load_trace",
+    "save_trace",
+    "save_csv",
+    "NdfDocument",
+    "NdfTracing",
+    "load_ndf",
+    "save_ndf",
+    "rasterize_path",
+    "compare_polylines",
+]

pyneuronj/_search.py

@@ -0,0 +1,194 @@
+"""Independent Dijkstra implementations; the same functions run in Python or Numba.
+
+Weights have shape (8,N). Invalid edges are +inf. A graph node is y*width+x.
+No Euclidean diagonal multiplier is applied. No positive epsilon is added.
+"""
+
+from __future__ import annotations
+import numpy as np
+
+# Fixed row-major neighbor order; this is an implementation choice.
+DX = np.array([-1, 0, 1, -1, 1, -1, 0, 1], dtype=np.int64)
+DY = np.array([-1, -1, -1, 0, 0, 1, 1, 1], dtype=np.int64)
+
+
+def heap_search(weights, offsets, source, target, max_edge):
+    """Indexed binary min-heap; ties are broken by flattened pixel index."""
+    n = weights.shape[1]
+    distance = np.full(n, np.inf, dtype=np.float64)
+    parent = np.full(n, -1, dtype=np.int64)
+    settled = np.zeros(n, dtype=np.bool_)
+    heap = np.empty(n, dtype=np.int64)
+    position = np.full(n, -1, dtype=np.int64)
+    distance[source] = 0.0
+    parent[source] = source
+    heap[0], position[source] = source, 0
+    size = 1
+    while size:
+        u = heap[0]
+        position[u] = -1
+        size -= 1
+        if size:
+            last = heap[size]
+            heap[0], position[last] = last, 0
+            j = 0
+            while True:
+                left = 2 * j + 1
+                if left >= size:
+                    break
+                right = left + 1
+                best = left
+                if right < size:
+                    a, b = heap[left], heap[right]
+                    if distance[b] < distance[a] or (
+                        distance[b] == distance[a] and b < a
+                    ):
+                        best = right
+                a, b = heap[j], heap[best]
+                if distance[a] < distance[b] or (distance[a] == distance[b] and a < b):
+                    break
+                heap[j], heap[best] = b, a
+                position[b], position[a] = j, best
+                j = best
+        settled[u] = True
+        if u == target:
+            break
+        du = distance[u]
+        for k in range(8):
+            w = weights[k, u]
+            if not np.isfinite(w):
+                continue
+            v = u + offsets[k]
+            if settled[v]:
+                continue
+            candidate = du + w
+            if candidate < distance[v]:
+                distance[v], parent[v] = candidate, u
+                j = position[v]
+                if j < 0:
+                    j = size
+                    size += 1
+                    heap[j], position[v] = v, j
+                while j:
+                    p = (j - 1) // 2
+                    a, b = heap[p], heap[j]
+                    if distance[a] < distance[b] or (
+                        distance[a] == distance[b] and a < b
+                    ):
+                        break
+                    heap[p], heap[j] = b, a
+                    position[b], position[a] = p, j
+                    j = p
+    # Unsettled tentative distances are NOT valid completed shortest paths.
+    for u in range(n):
+        if not settled[u]:
+            distance[u], parent[u] = np.inf, -1
+    return distance, parent, settled
+
+
+def dial_search(weights, offsets, source, target, max_edge):
+    """Circular FIFO buckets for nonnegative INTEGER weights, including zero.
+
+    Intrusive linked lists support decrease-key without duplicate queue entries.
+    Quantization levels and FIFO tie rules are not specified by the 2004 paper.
+    """
+    n = weights.shape[1]
+    ring_size = max_edge + 1
+    head = np.full(ring_size, -1, dtype=np.int64)
+    tail = np.full(ring_size, -1, dtype=np.int64)
+    next_node = np.full(n, -1, dtype=np.int64)
+    prev_node = np.full(n, -1, dtype=np.int64)
+    bucket_of = np.full(n, -1, dtype=np.int64)
+    distance = np.full(n, np.inf, dtype=np.float64)
+    parent = np.full(n, -1, dtype=np.int64)
+    settled = np.zeros(n, dtype=np.bool_)
+    distance[source], parent[source] = 0.0, source
+    head[0], tail[0], bucket_of[source] = source, source, 0
+    current, active = 0, 1
+    while active:
+        b = current % ring_size
+        u = head[b]
+        if u < 0:
+            current += 1
+            continue
+        head[b] = next_node[u]
+        if head[b] < 0:
+            tail[b] = -1
+        else:
+            prev_node[head[b]] = -1
+        next_node[u], prev_node[u], bucket_of[u] = -1, -1, -1
+        active -= 1
+        settled[u] = True
+        if u == target:
+            break
+        for k in range(8):
+            w = weights[k, u]
+            if not np.isfinite(w):
+                continue
+            v = u + offsets[k]
+            if settled[v]:
+                continue
+            candidate = current + int(w)
+            if candidate < distance[v]:
+                old_bucket = bucket_of[v]
+                if old_bucket >= 0:
+                    previous, following = prev_node[v], next_node[v]
+                    if previous < 0:
+                        head[old_bucket] = following
+                    else:
+                        next_node[previous] = following
+                    if following < 0:
+                        tail[old_bucket] = previous
+                    else:
+                        prev_node[following] = previous
+                else:
+                    active += 1
+                distance[v], parent[v] = candidate, u
+                new_bucket = candidate % ring_size
+                previous = tail[new_bucket]
+                prev_node[v], next_node[v] = previous, -1
+                if previous < 0:
+                    head[new_bucket] = v
+                else:
+                    next_node[previous] = v
+                tail[new_bucket], bucket_of[v] = v, new_bucket
+    for u in range(n):
+        if not settled[u]:
+            distance[u], parent[u] = np.inf, -1
+    return distance, parent, settled
+
+
+_COMPILED = {}
+
+
+def run_search(
+    weights,
+    width: int,
+    source: int,
+    target: int,
+    *,
+    engine: str,
+    queue: str,
+    max_edge: int,
+):
+    function = heap_search if queue == "heap" else dial_search
+    resolved = engine
+    if engine == "auto":
+        import importlib.util
+
+        resolved = (
+            "numba" if importlib.util.find_spec("numba") is not None else "python"
+        )
+    if resolved == "numba":
+        if queue not in _COMPILED:
+            try:
+                from numba import njit
+            except ImportError as exc:
+                raise ImportError(
+                    "Numba unavailable or incompatible. Install the [fast] extra, or set engine='python'."
+                ) from exc
+            # Keep floating-point arithmetic identical to the Python backend.
+            _COMPILED[queue] = njit(cache=True, nogil=True, fastmath=False)(function)
+        function = _COMPILED[queue]
+    result = function(weights, DY * width + DX, source, target, max_edge)
+    return (*result, resolved)

pyneuronj/_validation.py

@@ -0,0 +1,67 @@
+"""Validation shared by the public interfaces. Coordinates always mean (x, y)."""
+
+from __future__ import annotations
+import numbers
+import numpy as np
+
+
+def integer(value, name: str, minimum: int = 0) -> int:
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, numbers.Integral):
+        raise ValueError(f"{name} must be an integer >= {minimum}")
+    value = int(value)
+    if value < minimum:
+        raise ValueError(f"{name} must be >= {minimum}")
+    return value
+
+
+def real(value, name: str) -> float:
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, numbers.Real):
+        raise ValueError(f"{name} must be a finite real number")
+    value = float(value)
+    if not np.isfinite(value):
+        raise ValueError(f"{name} must be finite")
+    return value
+
+
+def image_array(image) -> np.ndarray:
+    a = np.asarray(image)
+    if a.ndim != 2 or min(a.shape, default=0) < 1:
+        raise ValueError(
+            "image must be a nonempty 2D grayscale array; select a channel explicitly"
+        )
+    if a.dtype.kind not in "buif":
+        raise ValueError("image must have a real numeric dtype")
+    a = np.array(a, dtype=np.float64, order="C", copy=True)
+    if not np.isfinite(a).all():
+        raise ValueError("image contains NaN or infinity")
+    return a
+
+
+def pixel(point, shape: tuple[int, int], name: str = "point") -> tuple[int, int]:
+    a = np.asarray(point)
+    if a.shape != (2,) or a.dtype.kind not in "uif" or not np.isfinite(a).all():
+        raise ValueError(f"{name} must be a finite integer (x, y) pair")
+    if np.any(a != np.floor(a)):
+        raise ValueError(
+            f"{name} must be on the integer pixel grid; round cursor coordinates explicitly"
+        )
+    x, y = int(a[0]), int(a[1])
+    if not (0 <= x < shape[1] and 0 <= y < shape[0]):
+        raise ValueError(f"{name} {(x, y)} is outside image shape {shape}")
+    return x, y
+
+
+def points_array(points, *, integer_only: bool = False) -> np.ndarray:
+    a = np.asarray(points)
+    if a.ndim != 2 or a.shape[1] != 2 or a.shape[0] < 1 or a.dtype.kind not in "uif":
+        raise ValueError("path must be a nonempty N x 2 real array in (x, y) order")
+    if not np.isfinite(a).all():
+        raise ValueError("path contains NaN or infinity")
+    if integer_only and np.any(a != np.floor(a)):
+        raise ValueError("raw pixel path must have integer coordinates")
+    return np.array(a, dtype=np.int64 if integer_only else np.float64, copy=True)
+
+
+def readonly(a: np.ndarray) -> np.ndarray:
+    a.setflags(write=False)
+    return a

pyneuronj/api.py

@@ -0,0 +1,225 @@
+"""Trace an image, or reuse a search tree while the endpoint moves."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from ._validation import pixel
+from .detector import NeuronDetector
+from .path import TraceResult, compare_polylines
+from .tracer import NeuronTracer
+
+
+class PyNeuronJ:
+    """Trace between integer (x, y) endpoints in a 2D grayscale image.
+
+    Image features and graph weights are computed at construction. ``trace``
+    searches between two endpoints; ``set_start`` prepares a full search tree
+    for repeated ``trace_to`` calls. Endpoints are used exactly as supplied.
+
+    ``paper`` uses the paper formulas and calibrated discretization.
+    ``practical`` also fixes numerical edge cases and checks a shorter route.
+    """
+
+    CANDIDATE_LENGTH_PENALTY = 0.02
+    COST_TOLERANCE = 0.005
+    MIN_LENGTH_REDUCTION = 0.01
+    MAX_LENGTH_REDUCTION = 0.10
+    MIN_SEPARATION_PX = 5.0
+
+    def __init__(
+        self,
+        image: ArrayLike,
+        *,
+        start: ArrayLike | None = None,
+        mode: Literal["paper", "practical"] = "practical",
+        sigma: float = 2.0,
+        gamma: float = 0.7,
+        p: int = 5,
+        s: int = 5,
+        bright_ridges: bool = True,
+        interior_only: bool = True,
+        engine: Literal["auto", "python", "numba"] = "auto",
+    ) -> None:
+        if mode not in ("paper", "practical"):
+            raise ValueError("mode must be 'paper' or 'practical'")
+        if not isinstance(interior_only, (bool, np.bool_)):
+            raise ValueError("interior_only must be boolean")
+        practical = mode == "practical"
+
+        # A constant image must have zero response in practical mode. Otherwise,
+        # a small derivative-kernel residual can be normalized into rho = 1.
+        image_array = np.asarray(image)
+        constant = (
+            image_array.ndim == 2
+            and image_array.size > 0
+            and np.all(image_array == image_array.flat[0])
+        )
+        detection = NeuronDetector(
+            sigma=sigma,
+            bright_ridges=bright_ridges,
+            boundary="mirror",
+            zero_dc=bool(practical and constant),
+            derivative_normalization="continuous",
+            smoothing_truncate=3.0,
+        )(image)
+
+        allowed = np.ones(detection.response.shape, dtype=bool)
+        if interior_only:
+            allowed[[0, -1], :] = False
+            allowed[:, [0, -1]] = False
+        options = dict(
+            gamma=gamma,
+            p=p,
+            s=s,
+            engine=engine,
+            allowed_mask=allowed,
+            stable_angles=practical,
+            queue="dial",
+            cost_levels=255,
+            quantization="floor",
+            coordinate_grid="pixel",
+        )
+        self._primary = NeuronTracer(detection, **options)
+        self._candidate = (
+            NeuronTracer(
+                detection, length_penalty=self.CANDIDATE_LENGTH_PENALTY, **options
+            )
+            if practical
+            else None
+        )
+        self._mode = mode
+        self._start: tuple[int, int] | None = None
+        self._tree = None
+        self._candidate_tree = None
+        if start is not None:
+            self.set_start(start)
+
+    @property
+    def mode(self) -> str:
+        """Tracing mode selected when the object was constructed."""
+        return self._mode
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """Image shape in ``(height, width)`` order."""
+        return self._primary.shape
+
+    @property
+    def start(self) -> tuple[int, int] | None:
+        """The cached start point, or ``None`` before ``set_start``."""
+        return self._start
+
+    @property
+    def response(self) -> np.ndarray:
+        """Read-only fiber response in [0, 1]."""
+        return self._primary.response
+
+    @property
+    def orientation(self) -> np.ndarray:
+        """Read-only unit tangents in (vx, vy) order."""
+        return self._primary.orientation
+
+    @property
+    def parameters(self) -> dict:
+        """A copy of the numerical configuration."""
+        parameters = {**self._primary.parameters, "mode": self.mode}
+        if self._candidate is not None:
+            parameters.update(
+                profile="practical",
+                refinement={
+                    "candidate_length_penalty": self.CANDIDATE_LENGTH_PENALTY,
+                    "cost_tolerance": self.COST_TOLERANCE,
+                    "min_raw_length_reduction": self.MIN_LENGTH_REDUCTION,
+                    "max_raw_length_reduction": self.MAX_LENGTH_REDUCTION,
+                    "min_sampled_separation_px": self.MIN_SEPARATION_PX,
+                },
+            )
+        return parameters
+
+    def trace(self, start: ArrayLike, end: ArrayLike) -> TraceResult:
+        """Return coordinates and pixel length between the exact endpoints."""
+        primary = self._primary.trace(start, end, snap=False)
+        if self._candidate is None:
+            return primary
+        candidate = self._candidate.trace(start, end, snap=False)
+        return self._choose_path(primary, candidate)
+
+    def set_start(self, start: ArrayLike) -> PyNeuronJ:
+        """Prepare a search tree; reuse it if the start has not changed.
+
+        Invalid coordinates leave an existing cached start and tree intact.
+        Returns ``self`` so ``tracer.set_start(start).trace_to(end)`` is valid.
+        """
+        point = pixel(start, self.shape, "start")
+        if point != self._start:
+            tree = self._primary.compute_tree(point, snap=False)
+            candidate_tree = (
+                self._candidate.compute_tree(point, snap=False)
+                if self._candidate is not None
+                else None
+            )
+            # Replace the cache only after both searches succeed.
+            self._tree, self._candidate_tree, self._start = tree, candidate_tree, point
+        return self
+
+    def trace_to(self, end: ArrayLike) -> TraceResult:
+        """Trace to an endpoint using the tree prepared by ``set_start``."""
+        if self._tree is None:
+            raise RuntimeError("call set_start(start) before trace_to(end)")
+        primary = self._primary.path_from_tree(self._tree, end, snap=False)
+        if self._candidate is None:
+            return primary
+        candidate = self._candidate.path_from_tree(
+            self._candidate_tree, end, snap=False
+        )
+        return self._choose_path(primary, candidate)
+
+    def clear_start(self) -> None:
+        """Release the cached tree while retaining the image detector field."""
+        self._tree, self._candidate_tree, self._start = None, None, None
+
+    def _choose_path(self, primary: TraceResult, candidate: TraceResult) -> TraceResult:
+        """Accept the shorter route only within the documented bounds."""
+        baseline_length = primary.raw_length_pixels
+        reduction = (
+            0.0
+            if baseline_length == 0
+            else (baseline_length - candidate.raw_length_pixels) / baseline_length
+        )
+        candidate_cost = self._primary.raw_path_cost(candidate.raw_xy)
+        gap = max(0.0, candidate_cost - primary.graph_cost) / max(
+            primary.graph_cost, 1e-12
+        )
+        use_candidate = False
+        separation = None
+        if (
+            self.MIN_LENGTH_REDUCTION <= reduction <= self.MAX_LENGTH_REDUCTION
+            and gap <= self.COST_TOLERANCE
+        ):
+            separation = compare_polylines(
+                primary.points_xy, candidate.points_xy, step=0.5
+            )["symmetric_mean_sample_distance_px"]
+            use_candidate = separation >= self.MIN_SEPARATION_PX
+        chosen = candidate if use_candidate else primary
+        metadata = {
+            **primary.metadata,
+            **self.parameters,
+            "correction_applied": bool(use_candidate),
+            "refinement_diagnostics": {
+                "candidate_paper_cost": candidate_cost,
+                "relative_paper_cost_increase": gap,
+                "raw_length_reduction": reduction,
+                "sampled_separation_px": separation,
+            },
+        }
+        # Report the original graph cost even when choosing the shorter route.
+        return TraceResult(
+            chosen.raw_xy,
+            chosen.points_xy,
+            candidate_cost if use_candidate else primary.graph_cost,
+            metadata,
+        )