microvasc: segmentation and skeletonization of large-scale microvascular networks
Code for the paper Segmentation and modeling of large-scale microvascular networks: a survey (Frontiers in Bioinformatics, 2025).
Pipeline
The code covers the three stages compared in the paper:
- Binarize a 3D volume:
binarize otsu2d,otsu3d,frangi,bfrangi. - Skeletonize the binary volume:
skeleton lee,palagyi,kline, andkerautret(a wrapper around the external CDCVAM program). - Evaluate the results against a ground truth: Jaccard, Dice, precision and recall for binary volumes, NetMets precision and recall for skeletons.
The other methods in the paper (Optimally Oriented Flux, U-Net, nnU-Net, Tagliasacchi, Antiga) are not implemented here. The documentation pages link to their implementations.
Installation
Python 3.9 or newer. The test workflow runs on Python 3.12 and 3.14.
git clone https://github.com/helia77/MicroVasc-Review.git
cd MicroVasc-Review
pip install -e .
The core install needs only NumPy, SciPy and scikit-image. Optional parts are installed as extras:
| Extra | Installs | Needed for |
|---|---|---|
kline |
scikit-fmm | skeleton kline |
io |
opencv-python, pynrrd, SimpleITK | image stacks, NRRD files and resampling in microvasc.data |
test |
pytest | running the tests |
all |
all of the above |
pip install -e ".[kline]"
pip install -e ".[all]"
On some platforms pip builds scikit-fmm from source, which needs a compiler and the Python development headers.
Quick start
Binarize, skeletonize and evaluate a synthetic tube:
import numpy as np
from scipy import ndimage
from microvasc.binarize import Binarizer
from microvasc.skeleton import Skeletonizer
from microvasc.metrics.geometry import SegmentationMetrics
from microvasc.metrics.network import netmets, voxel_skeleton_to_segments
# a bright tube along axis 0 on a dark, noisy background
_, y, x = np.mgrid[:32, :32, :32]
truth = (y - 16) ** 2 + (x - 16) ** 2 <= 4 ** 2
rng = np.random.default_rng(0)
volume = truth + 0.2 * rng.standard_normal(truth.shape)
mask = Binarizer(volume, background="black").otsu3d()
# keep the largest connected component, then fill the holes left by the noise
labels, _ = ndimage.label(mask)
mask = ndimage.binary_fill_holes(labels == np.bincount(labels.ravel())[1:].argmax() + 1)
print("Jaccard", SegmentationMetrics(truth, mask).jaccard())
skeleton = Skeletonizer().lee(mask)
centerline = [[[0, 16, 16], [31, 16, 16]]] # the true centerline as one segment
precision, recall = netmets(centerline, voxel_skeleton_to_segments(skeleton), sigma=1.0)
print("NetMets precision", precision, "recall", recall)
The same steps from the command line, on .npy files:
binarize otsu3d --input volume.npy --output mask.npy
skeleton lee --input mask.npy --output skeleton.npy
Documentation
| Page | Contents |
|---|---|
| Binarization | Otsu, Frangi and Beyond Frangi, binarize options, external methods |
| Skeletonization | Lee, Palágyi, Kline and Kerautret, skeleton options, settings used in the paper |
| Metrics | Jaccard, Dice, precision, recall, and NetMets with per-input scales |
| Parameter optimization | Slurm sweeps for alpha, c, beta and tau, and J = F / (2 - F) |
| Data conversion | NWT, OBJ, OFF, NRRD and image stack helpers in microvasc.data |
Development setup and tests: CONTRIBUTING.md.
Data availability
Data availability: TODO
The imaging data and annotations used in the paper are not included in this repository.
Citation
If you use this code or the paper, please cite the paper:
@article{goharbavang2025segmentation,
title={Segmentation and modeling of large-scale microvascular networks: a survey},
author={Goharbavang, Helya and Ashitkov, Artem T and Pillai, Athira and Wythe, Joshua D and Chen, Guoning and Mayerich, David},
journal={Frontiers in Bioinformatics},
volume={5},
pages={1645520},
year={2025},
publisher={Frontiers Media SA},
doi={10.3389/fbinf.2025.1645520}
}
The same information is in CITATION.cff, which GitHub shows as "Cite this repository".
License
MIT License, see LICENSE. Skeletonizer.kline is derived from poreture (BSD 3-clause),
see THIRD_PARTY_NOTICES.md.
Metadata
Release files for microvasc 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| microvasc-0.2.0.tar.gz | 505.9 kB | With provenance | Details for microvasc-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| microvasc-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for microvasc-0.2.0-py3-none-any.whl |
Total release size: 541.5 kB
Release files / microvasc-0.2.0.tar.gz
| Download URL | microvasc-0.2.0.tar.gz |
|---|---|
| Size | 505.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
10b73d8a766910c5dabf3b3eeaba661f0d80d07033576765573d389795eeba4f
|
|
BLAKE2b-256 checksum How to use checksums |
6bfbf91d3f42388fa69ca900b2effb02cd3394b3b811ff3fa28cc495887d6902
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logRelease files / microvasc-0.2.0-py3-none-any.whl
| Download URL | microvasc-0.2.0-py3-none-any.whl |
|---|---|
| Size | 35.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f7a1991a847566308b6b72ff69b01e43fd1b9878ff31c199d1cdc66c14867ef
|
|
BLAKE2b-256 checksum How to use checksums |
058aa7727af502ffc34f505f3e08d2540d2e42da7800f0f9679de07be01d568f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logSecurity for microvasc 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for microvasc-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.