Skip to main content

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).

Overview Diagram

Pipeline

The code covers the three stages compared in the paper:

  1. Binarize a 3D volume: binarize otsu2d, otsu3d, frangi, bfrangi.
  2. Skeletonize the binary volume: skeleton lee, palagyi, kline, and kerautret (a wrapper around the external CDCVAM program).
  3. 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)

Source distribution for microvasc 0.2.0
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)

Table of built distributions (wheels) for microvasc 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page