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% |
