pyneuronj 1.0__tar.gz

pyneuronj-1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PyNeuronJ contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyneuronj-1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md README.zh-CN.md LICENSE
+recursive-include examples *.py *.png
+recursive-include tests *.py

pyneuronj-1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: pyneuronj
+Version: 1.0
+Summary: 2D nerve-fiber tracing with NeuronJ-compatible NDF annotations
+License-Expression: MIT
+Project-URL: Repository, https://github.com/SummerColdWind/PyNeuronJ
+Project-URL: Issues, https://github.com/SummerColdWind/PyNeuronJ/issues
+Keywords: neuronj,neurite,nerve-fiber,live-wire,microscopy,ndf
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: fast
+Requires-Dist: numba>=0.60; extra == "fast"
+Provides-Extra: examples
+Requires-Dist: Pillow; extra == "examples"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: numba>=0.60; extra == "dev"
+Requires-Dist: Pillow; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Dynamic: license-file
+
+# PyNeuronJ
+
+[English](https://github.com/SummerColdWind/PyNeuronJ/blob/main/README.md) | [简体中文](https://github.com/SummerColdWind/PyNeuronJ/blob/main/README.zh-CN.md)
+
+## What is this?
+
+A Python implementation of [NeuronJ](https://imagescience.org/meijering/software/neuronj/)
+for tracing nerve fibers in 2D grayscale images. Give it a start and an end point;
+it returns the centerline and its length. NDF files can be read, edited and saved
+for use in NeuronJ.
+
+The algorithm follows [Meijering et al. (2004)](https://doi.org/10.1002/cyto.a.20022).
+The default `practical` mode includes numerical corrections.
+Use `mode="paper"` for the paper formulas.
+
+## Installation
+
+Python 3.10 or newer:
+
+```bash
+python -m pip install "pyneuronj[fast,examples]"
+```
+
+Requires NumPy and SciPy. The command also installs Numba for acceleration
+and Pillow for the example. For the library alone, use `python -m pip install pyneuronj`.
+To install from source, run `python -m pip install -e ".[fast,examples]"` in the repository.
+
+## Quick start
+
+Results on the bundled image, using the same endpoints:
+
+| PyNeuronJ | NeuronJ 1.4.3 |
+|:---:|:---:|
+| ![PyNeuronJ result](https://raw.githubusercontent.com/SummerColdWind/PyNeuronJ/main/examples/pyneuronj.png) | ![Official NeuronJ result](https://raw.githubusercontent.com/SummerColdWind/PyNeuronJ/main/examples/neuronj.png) |
+
+Red: centerline. Green: start. Blue: end.
+
+```python
+from importlib.resources import files
+
+import numpy as np
+from PIL import Image
+from pyneuronj import PyNeuronJ, load_ndf, save_ndf
+
+with files("pyneuronj").joinpath("data/test.jpg").open("rb") as image_file:
+    with Image.open(image_file) as source:
+        image = np.asarray(source.convert("L"))
+
+tracer = PyNeuronJ(image)
+result = tracer.trace(start=(104, 156), end=(149, 316))
+
+print(result.points_xy)       # Centerline coordinates
+print(result.length_pixels)   # Length in pixels
+save_ndf("test.ndf", result)
+
+document = load_ndf("test.ndf")
+document.tracings[0].label = "Fiber 1"
+save_ndf("edited.ndf", document)
+```
+
+Coordinates are `(x, y)` pixel centers. For calibrated lengths, use
+`result.length(pixel_size=(sx, sy))`. Replace the image and endpoints to trace
+your own data.
+
+NDF supports versions 1.0.0–1.4.3 and saves as 1.4.3. Types, colors, clusters,
+labels and segment boundaries are preserved. To load the saved annotation
+in NeuronJ, open the same image first.
+
+The complete example can also be run from the command line:
+
+```bash
+python examples/basic.py
+```
+
+## Validation
+
+Compared with NeuronJ 1.4.3 on 196 images and 9,305 segments, using the same endpoints.
+
+| Difference from NeuronJ | `paper` | `practical` |
+|---|---:|---:|
+| Mean centerline distance | 0.026199 px | 0.006588 px |
+| F1 within 2 px | 99.9260% | 99.9823% |
+| Identical displayed vertices | 8,826 / 9,305 | 8,828 / 9,305 |
+| Segments with mean distance > 5 px | 2 | 0 |
+| Segment length MAE | 0.01140 px | 0.00788 px |
+| Complete-tracing length MAPE | 0.01714% | 0.01489% |

pyneuronj-1.0/README.md

@@ -0,0 +1,86 @@
+# PyNeuronJ
+
+[English](https://github.com/SummerColdWind/PyNeuronJ/blob/main/README.md) | [简体中文](https://github.com/SummerColdWind/PyNeuronJ/blob/main/README.zh-CN.md)
+
+## What is this?
+
+A Python implementation of [NeuronJ](https://imagescience.org/meijering/software/neuronj/)
+for tracing nerve fibers in 2D grayscale images. Give it a start and an end point;
+it returns the centerline and its length. NDF files can be read, edited and saved
+for use in NeuronJ.
+
+The algorithm follows [Meijering et al. (2004)](https://doi.org/10.1002/cyto.a.20022).
+The default `practical` mode includes numerical corrections.
+Use `mode="paper"` for the paper formulas.
+
+## Installation
+
+Python 3.10 or newer:
+
+```bash
+python -m pip install "pyneuronj[fast,examples]"
+```
+
+Requires NumPy and SciPy. The command also installs Numba for acceleration
+and Pillow for the example. For the library alone, use `python -m pip install pyneuronj`.
+To install from source, run `python -m pip install -e ".[fast,examples]"` in the repository.
+
+## Quick start
+
+Results on the bundled image, using the same endpoints:
+
+| PyNeuronJ | NeuronJ 1.4.3 |
+|:---:|:---:|
+| ![PyNeuronJ result](https://raw.githubusercontent.com/SummerColdWind/PyNeuronJ/main/examples/pyneuronj.png) | ![Official NeuronJ result](https://raw.githubusercontent.com/SummerColdWind/PyNeuronJ/main/examples/neuronj.png) |
+
+Red: centerline. Green: start. Blue: end.
+
+```python
+from importlib.resources import files
+
+import numpy as np
+from PIL import Image
+from pyneuronj import PyNeuronJ, load_ndf, save_ndf
+
+with files("pyneuronj").joinpath("data/test.jpg").open("rb") as image_file:
+    with Image.open(image_file) as source:
+        image = np.asarray(source.convert("L"))
+
+tracer = PyNeuronJ(image)
+result = tracer.trace(start=(104, 156), end=(149, 316))
+
+print(result.points_xy)       # Centerline coordinates
+print(result.length_pixels)   # Length in pixels
+save_ndf("test.ndf", result)
+
+document = load_ndf("test.ndf")
+document.tracings[0].label = "Fiber 1"
+save_ndf("edited.ndf", document)
+```
+
+Coordinates are `(x, y)` pixel centers. For calibrated lengths, use
+`result.length(pixel_size=(sx, sy))`. Replace the image and endpoints to trace
+your own data.
+
+NDF supports versions 1.0.0–1.4.3 and saves as 1.4.3. Types, colors, clusters,
+labels and segment boundaries are preserved. To load the saved annotation
+in NeuronJ, open the same image first.
+
+The complete example can also be run from the command line:
+
+```bash
+python examples/basic.py
+```
+
+## Validation
+
+Compared with NeuronJ 1.4.3 on 196 images and 9,305 segments, using the same endpoints.
+
+| Difference from NeuronJ | `paper` | `practical` |
+|---|---:|---:|
+| Mean centerline distance | 0.026199 px | 0.006588 px |
+| F1 within 2 px | 99.9260% | 99.9823% |
+| Identical displayed vertices | 8,826 / 9,305 | 8,828 / 9,305 |
+| Segments with mean distance > 5 px | 2 | 0 |
+| Segment length MAE | 0.01140 px | 0.00788 px |
+| Complete-tracing length MAPE | 0.01714% | 0.01489% |

pyneuronj-1.0/README.zh-CN.md

@@ -0,0 +1,83 @@
+# PyNeuronJ
+
+[English](https://github.com/SummerColdWind/PyNeuronJ/blob/main/README.md) | [简体中文](https://github.com/SummerColdWind/PyNeuronJ/blob/main/README.zh-CN.md)
+
+## 这是什么
+
+[NeuronJ](https://imagescience.org/meijering/software/neuronj/) 的 Python 实现，
+用于追踪二维灰度图中的神经纤维。给定起点和终点，返回中心线坐标及长度。
+支持读取、编辑和保存 NeuronJ 的 NDF 标注文件。
+
+算法依据 [Meijering 等人（2004）的论文](https://doi.org/10.1002/cyto.a.20022)。
+默认的 `practical` 模式包含数值修正；使用 `mode="paper"` 可采用论文公式。
+
+## 安装
+
+需要 Python 3.10 或更高版本：
+
+```bash
+python -m pip install "pyneuronj[fast,examples]"
+```
+
+依赖 NumPy 和 SciPy。上述命令还会安装用于加速的 Numba 和读取示例图像的 Pillow。
+只使用库时，执行 `python -m pip install pyneuronj`。
+从源码安装时，在仓库目录执行 `python -m pip install -e ".[fast,examples]"`。
+
+## 快速开始
+
+同一张示例图像、相同端点的追踪结果：
+
+| PyNeuronJ | 原版 NeuronJ 1.4.3 |
+|:---:|:---:|
+| ![PyNeuronJ 结果](https://raw.githubusercontent.com/SummerColdWind/PyNeuronJ/main/examples/pyneuronj.png) | ![原版 NeuronJ 结果](https://raw.githubusercontent.com/SummerColdWind/PyNeuronJ/main/examples/neuronj.png) |
+
+红线为中心线，绿点为起点，蓝点为终点。
+
+```python
+from importlib.resources import files
+
+import numpy as np
+from PIL import Image
+from pyneuronj import PyNeuronJ, load_ndf, save_ndf
+
+with files("pyneuronj").joinpath("data/test.jpg").open("rb") as image_file:
+    with Image.open(image_file) as source:
+        image = np.asarray(source.convert("L"))
+
+tracer = PyNeuronJ(image)
+result = tracer.trace(start=(104, 156), end=(149, 316))
+
+print(result.points_xy)       # 中心线坐标
+print(result.length_pixels)   # 长度，单位为像素
+save_ndf("test.ndf", result)
+
+document = load_ndf("test.ndf")
+document.tracings[0].label = "Fiber 1"
+save_ndf("edited.ndf", document)
+```
+
+坐标顺序为 `(x, y)`，表示像素中心。已知像素尺寸时，用
+`result.length(pixel_size=(sx, sy))` 计算实际长度。
+处理自己的图像时，替换图像并选择相应端点即可。
+
+NDF 支持读取 1.0.0–1.4.3，保存为 1.4.3。类型、颜色、分组、标签和分段信息均会保留。
+在 NeuronJ 中打开同一张图像后，即可加载保存的标注。
+
+也可以直接运行完整示例：
+
+```bash
+python examples/basic.py
+```
+
+## 验证
+
+在 196 张图像、9,305 个分段上，与 NeuronJ 1.4.3 使用相同端点进行对照。
+
+| 与 NeuronJ 的差异 | `paper` | `practical` |
+|---|---:|---:|
+| 平均中心线距离 | 0.026199 px | 0.006588 px |
+| F1@2px | 99.9260% | 99.9823% |
+| 显示顶点完全相同 | 8,826 / 9,305 | 8,828 / 9,305 |
+| 单段平均距离 >5 px | 2 | 0 |
+| 分段长度 MAE | 0.01140 px | 0.00788 px |
+| 完整追踪长度 MAPE | 0.01714% | 0.01489% |

pyneuronj-1.0/examples/basic.py

@@ -0,0 +1,47 @@
+"""Trace the bundled real image and save an editable NeuronJ annotation."""
+
+import argparse
+from importlib.resources import files
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+from pyneuronj import PyNeuronJ, save_ndf
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--image", type=Path, help="JPEG/TIFF/PNG; defaults to the bundled test.jpg"
+    )
+    parser.add_argument(
+        "--start", type=int, nargs=2, default=(104, 156), metavar=("X", "Y")
+    )
+    parser.add_argument(
+        "--end", type=int, nargs=2, default=(149, 316), metavar=("X", "Y")
+    )
+    parser.add_argument("--mode", choices=("paper", "practical"), default="practical")
+    parser.add_argument("--output", type=Path, default=Path(".local/example/test.ndf"))
+    args = parser.parse_args()
+
+    image_path = args.image or files("pyneuronj").joinpath("data/test.jpg")
+    with image_path.open("rb") as image_file, Image.open(image_file) as source:
+        image = np.asarray(source.convert("L"))
+    tracer = PyNeuronJ(image, mode=args.mode)
+    result = tracer.trace(args.start, args.end)
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    save_ndf(args.output, result)
+    print(f"Image: {image_path} ({image.shape[1]} x {image.shape[0]})")
+    print(f"Path: {len(result.points_xy)} points, {result.length_pixels:.2f} px")
+    print(f"Saved: {args.output}")
+
+    # Reuse the same search tree for endpoint updates.
+    tracer.set_start(args.start)
+    cached = tracer.trace_to(args.end)
+    assert np.array_equal(cached.points_xy, result.points_xy)
+    print("Fixed-start query matches the direct query")
+
+
+if __name__ == "__main__":
+    main()

pyneuronj-1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyneuronj"
+version = "1.0"
+description = "2D nerve-fiber tracing with NeuronJ-compatible NDF annotations"
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["neuronj", "neurite", "nerve-fiber", "live-wire", "microscopy", "ndf"]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Typing :: Typed",
+]
+dependencies = ["numpy>=1.24", "scipy>=1.10"]
+
+[project.urls]
+Repository = "https://github.com/SummerColdWind/PyNeuronJ"
+Issues = "https://github.com/SummerColdWind/PyNeuronJ/issues"
+
+[project.optional-dependencies]
+fast = ["numba>=0.60"]
+examples = ["Pillow"]
+dev = ["pytest>=7", "ruff", "numba>=0.60", "Pillow", "build>=1.2", "twine>=6.1"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pyneuronj = ["py.typed", "data/test.jpg"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"

pyneuronj-1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyneuronj-1.0/src/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-1.0/src/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)