vesskel 1.0.0__tar.gz

vesskel-1.0.0/LICENSE

@@ -0,0 +1,34 @@
+MIT License
+
+Copyright (c) 2026 Simon
+
+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.
+
+---
+
+## HRF Dataset Attribution
+
+This project uses the High-Resolution Fundus (HRF) Image Database, which is
+licensed under the Creative Commons 4.0 Attribution License, cited as:
+
+Budai, Attila; Bock, Rüdiger; Maier, Andreas; Hornegger, Joachim; Michelson, Georg.
+Robust Vessel Segmentation in Fundus Images.
+International Journal of Biomedical Imaging, vol. 2013, 2013
+
+For more information, visit: https://www5.cs.fau.de/research/data/fundus-images/

vesskel-1.0.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: vesskel
+Version: 1.0.0
+Summary: 2D and 3D Skeletonization and Graph-based Analysis
+License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause)
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numba>=0.65.0
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: scipy>=1.17.1
+Requires-Dist: skan>=0.13.1
+Provides-Extra: napari
+Requires-Dist: napari[all]; extra == "napari"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
+Requires-Dist: pooch>=1.9.0; extra == "dev"
+Requires-Dist: scikit-image>=0.26.0; extra == "dev"
+Dynamic: license-file
+
+# VesSkel
+
+Vessel Skeletonization and Graph-Based Phenotype Analysis in Retinal Fundus Images
+
+## Installation
+
+```sh
+uv sync                  # core only
+uv sync --extra dev      # + test tools
+uv sync --extra napari   # + napari GUI
+uv sync --all-extras     # everything
+```
+
+## Napari
+
+```sh
+uv sync --extra napari && uv run napari
+```
+
+Open a `manual1` TIFF from the HRF folder, then run **Lee94 Thinning** from the VesSkel plugin menu to see the skeleton.
+
+## Tests
+
+```sh
+uv sync --extra dev && uv run pytest
+```
+
+- **2D regression** - thinning + feature extraction on all 45 HRF samples, compared against saved baselines
+- **3D regression** - thinning + features on a brain volume (from scikit-image), same baseline approach
+- **3D comparison** - vesskel `lee94_thin` vs `skimage.morphology.skeletonize` on the brain volume, asserting identical output
+
+First run (or `--update-baseline`) generates baselines in `tests/skeletons/` and `tests/features/`.
+
+## Dataset
+
+This project uses the High-Resolution Fundus (HRF) Image Database, established by a collaborative research group to support comparative studies on automatic segmentation algorithms on retinal fundus images.
+
+The database contains 45 images total:
+- 15 images of healthy patients
+- 15 images of patients with diabetic retinopathy
+- 15 images of glaucomatous patients
+
+Binary gold standard vessel segmentation images and field of view (FOV) masks are available for each image.
+
+### License
+
+> Budai, Attila; Bock, Rüdiger; Maier, Andreas; Hornegger, Joachim; Michelson, Georg.
+> Robust Vessel Segmentation in Fundus Images.
+> International Journal of Biomedical Imaging, vol. 2013, 2013
+
+The HRF dataset is released under the **Creative Commons 4.0 Attribution License**.
+
+For more information, visit the [HRF Image Database](https://www5.cs.fau.de/research/data/fundus-images/).
+

vesskel-1.0.0/README.md

@@ -0,0 +1,54 @@
+# VesSkel
+
+Vessel Skeletonization and Graph-Based Phenotype Analysis in Retinal Fundus Images
+
+## Installation
+
+```sh
+uv sync                  # core only
+uv sync --extra dev      # + test tools
+uv sync --extra napari   # + napari GUI
+uv sync --all-extras     # everything
+```
+
+## Napari
+
+```sh
+uv sync --extra napari && uv run napari
+```
+
+Open a `manual1` TIFF from the HRF folder, then run **Lee94 Thinning** from the VesSkel plugin menu to see the skeleton.
+
+## Tests
+
+```sh
+uv sync --extra dev && uv run pytest
+```
+
+- **2D regression** - thinning + feature extraction on all 45 HRF samples, compared against saved baselines
+- **3D regression** - thinning + features on a brain volume (from scikit-image), same baseline approach
+- **3D comparison** - vesskel `lee94_thin` vs `skimage.morphology.skeletonize` on the brain volume, asserting identical output
+
+First run (or `--update-baseline`) generates baselines in `tests/skeletons/` and `tests/features/`.
+
+## Dataset
+
+This project uses the High-Resolution Fundus (HRF) Image Database, established by a collaborative research group to support comparative studies on automatic segmentation algorithms on retinal fundus images.
+
+The database contains 45 images total:
+- 15 images of healthy patients
+- 15 images of patients with diabetic retinopathy
+- 15 images of glaucomatous patients
+
+Binary gold standard vessel segmentation images and field of view (FOV) masks are available for each image.
+
+### License
+
+> Budai, Attila; Bock, Rüdiger; Maier, Andreas; Hornegger, Joachim; Michelson, Georg.
+> Robust Vessel Segmentation in Fundus Images.
+> International Journal of Biomedical Imaging, vol. 2013, 2013
+
+The HRF dataset is released under the **Creative Commons 4.0 Attribution License**.
+
+For more information, visit the [HRF Image Database](https://www5.cs.fau.de/research/data/fundus-images/).
+

vesskel-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "vesskel"
+license = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
+version = "1.0.0"
+description = "2D and 3D Skeletonization and Graph-based Analysis"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "numba>=0.65.0",
+    "numpy>=2.4.4",
+    "pillow>=12.2.0",
+    "scipy>=1.17.1",
+    "skan>=0.13.1",
+]
+
+[project.optional-dependencies]
+napari = ["napari[all]"]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-xdist>=3.8.0",
+    "pooch>=1.9.0",
+    "scikit-image>=0.26.0",
+]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["vesskel*"]
+
+[project.entry-points."napari.manifest"]
+vesskel = "vesskel:napari.yaml"
+
+[tool.pytest.ini_options]
+addopts = "-n auto"

vesskel-1.0.0/setup.cfg

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

vesskel-1.0.0/tests/test_2d_thinning_regression.py

@@ -0,0 +1,151 @@
+"""Regression test suite.
+
+On first run (or when --update-baseline is passed), skeletons and features are
+generated and saved as baseline reference files.
+
+On subsequent runs, skeletons and features are regenerated and compared against
+saved baselines. Any difference is reported as a test failure, indicating a
+regression (or an intentional algorithm change).
+"""
+
+import csv
+import hashlib
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from vesskel.features import extract_vessel_features
+from vesskel.hrf import HRFDataset, preprocess_segmentation
+from vesskel.thin import lee94_thin
+
+BASELINE_DIR = Path(__file__).parent / "skeletons"
+FEATURE_DIR = Path(__file__).parent / "features"
+HRF_PATH = "HRF"
+
+
+def _skeleton_path(name: str) -> Path:
+    return BASELINE_DIR / f"skeleton_{name}.npz"
+
+
+def _feature_path(name: str) -> Path:
+    return FEATURE_DIR / f"features_{name}.csv"
+
+
+def _compute_skeleton(dataset: HRFDataset, index: int) -> np.ndarray:
+    _, seg, mask, _ = dataset.load_sample(index)
+    cleaned = preprocess_segmentation(seg, mask)
+    return lee94_thin(cleaned)
+
+
+def _write_feature_csv(path: Path, features: dict[str, float]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["feature", "value"])
+        for key in sorted(features):
+            writer.writerow([key, f"{features[key]:.17g}"])
+
+
+def _read_feature_csv(path: Path) -> dict[str, float]:
+    loaded: dict[str, float] = {}
+    with path.open(newline="") as f:
+        reader = csv.reader(f)
+        header = next(reader, None)
+        if header != ["feature", "value"]:
+            raise ValueError("invalid feature csv header")
+        for row in reader:
+            if len(row) != 2:
+                raise ValueError("invalid feature csv row")
+            key, value = row
+            loaded[key] = float(value)
+    return loaded
+
+
+def _hash_array(arr: np.ndarray) -> str:
+    return hashlib.sha256(arr.tobytes()).hexdigest()
+
+
+@pytest.fixture(scope="module")
+def dataset():
+    return HRFDataset(HRF_PATH)
+
+
+class TestThinningRegression:
+    """Run thinning on every HRF sample and compare against saved baselines."""
+
+    @pytest.mark.parametrize(
+        "index",
+        range(len(HRFDataset(HRF_PATH))),
+        ids=[info["name"] for info in HRFDataset(HRF_PATH).image_list],
+    )
+    def test_skeleton_matches_baseline(self, dataset, index, request):
+        info = dataset.image_list[index]
+        name = info["name"]
+        skeleton = _compute_skeleton(dataset, index)
+        features = extract_vessel_features(skeleton)
+        baseline_file = _skeleton_path(name)
+        feature_file = _feature_path(name)
+
+        baseline_changed = False
+
+        if request.config.getoption("--update-baseline") or not baseline_file.exists():
+            BASELINE_DIR.mkdir(parents=True, exist_ok=True)
+            np.savez_compressed(baseline_file, skeleton=skeleton)
+            baseline_changed = True
+
+        features_changed = False
+        if request.config.getoption("--update-baseline") or not feature_file.exists():
+            _write_feature_csv(feature_file, features)
+            features_changed = True
+
+        if baseline_changed or features_changed:
+            baseline_action = (
+                "updated"
+                if request.config.getoption("--update-baseline")
+                else "created"
+            )
+            artifacts = []
+            if baseline_changed:
+                artifacts.append("skeleton baseline")
+            if features_changed:
+                artifacts.append("feature baseline")
+            pytest.skip(f"{', '.join(artifacts)} {baseline_action} for sample {name}")
+
+        with np.load(baseline_file) as data:
+            baseline = data["skeleton"]
+
+        try:
+            baseline_features = _read_feature_csv(feature_file)
+        except (OSError, ValueError) as exc:
+            pytest.fail(f"Sample {name}: invalid feature baseline CSV: {exc}")
+
+        assert skeleton.shape == baseline.shape, (
+            f"Sample {name}: shape mismatch "
+            f"got {skeleton.shape}, expected {baseline.shape}"
+        )
+        assert np.array_equal(skeleton, baseline), (
+            f"Sample {name}: skeleton differs from baseline "
+            f"(hash {_hash_array(skeleton)} vs {_hash_array(baseline)})"
+        )
+
+        feature_keys = sorted(features)
+        baseline_feature_keys = sorted(baseline_features)
+        assert feature_keys == baseline_feature_keys, (
+            f"Sample {name}: feature set differs from baseline "
+            f"(got {feature_keys}, expected {baseline_feature_keys})"
+        )
+
+        feature_values = np.array(
+            [features[key] for key in feature_keys], dtype=np.float64
+        )
+        baseline_feature_values = np.array(
+            [baseline_features[key] for key in feature_keys], dtype=np.float64
+        )
+        np.testing.assert_allclose(
+            feature_values,
+            baseline_feature_values,
+            rtol=1e-8,
+            atol=1e-10,
+            err_msg=f"Sample {name}: feature values differ from baseline",
+        )

vesskel-1.0.0/tests/test_3d_skimage_comparison.py

@@ -0,0 +1,27 @@
+"""Regression test comparing vesskel.thin with scikit-image skeletonize on brain image."""
+
+import numpy as np
+import pytest
+from skimage import data
+from skimage.morphology import skeletonize
+
+from vesskel.thin import lee94_thin
+
+
+class TestSkeletonizeComparison:
+    """Compare vesskel.thin with scikit-image skeletonize on brain image."""
+
+    @pytest.fixture(scope="class")
+    def image(self):
+        return data.brain()
+
+    def test_vesskel_vs_scikit_skeletonize(self, image):
+        vesskel_skel = lee94_thin(image)
+        scikit_skel = skeletonize(image)
+
+        assert (
+            vesskel_skel.shape == scikit_skel.shape
+        ), f"shape mismatch: vesskel {vesskel_skel.shape} vs scikit {scikit_skel.shape}"
+        assert np.array_equal(
+            vesskel_skel, scikit_skel
+        ), "skeleton mismatch: algorithms produce different results"

vesskel-1.0.0/tests/test_3d_thinning_regression.py

@@ -0,0 +1,119 @@
+"""Regression test for 3D thinning using brain image from scikit-image."""
+
+import csv
+import hashlib
+from pathlib import Path
+
+import numpy as np
+import pytest
+from skimage import data
+
+from vesskel.features import extract_vessel_features
+from vesskel.thin import lee94_thin
+
+BASELINE_DIR = Path(__file__).parent / "skeletons"
+FEATURE_DIR = Path(__file__).parent / "features"
+
+
+def _skeleton_path(name: str) -> Path:
+    return BASELINE_DIR / f"skeleton_{name}.npz"
+
+
+def _feature_path(name: str) -> Path:
+    return FEATURE_DIR / f"features_{name}.csv"
+
+
+def _compute_skeleton(image: np.ndarray) -> np.ndarray:
+    return lee94_thin(image)
+
+
+def _write_feature_csv(path: Path, features: dict[str, float]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["feature", "value"])
+        for key in sorted(features):
+            writer.writerow([key, f"{features[key]:.17g}"])
+
+
+def _read_feature_csv(path: Path) -> dict[str, float]:
+    loaded: dict[str, float] = {}
+    with path.open(newline="") as f:
+        reader = csv.reader(f)
+        header = next(reader, None)
+        if header != ["feature", "value"]:
+            raise ValueError("invalid feature csv header")
+        for row in reader:
+            if len(row) != 2:
+                raise ValueError("invalid feature csv row")
+            key, value = row
+            loaded[key] = float(value)
+    return loaded
+
+
+def _hash_array(arr: np.ndarray) -> str:
+    return hashlib.sha256(arr.tobytes()).hexdigest()
+
+
+class Test3DThinningRegression:
+    """Run 3D thinning on brain image and compare against saved baselines."""
+
+    @pytest.fixture(scope="class")
+    def image(self):
+        return data.brain()
+
+    def test_skeleton_matches_baseline(self, image, request):
+        skeleton = _compute_skeleton(image)
+        features = extract_vessel_features(skeleton)
+        name = "brain"
+        baseline_file = _skeleton_path(name)
+        feature_file = _feature_path(name)
+
+        baseline_changed = False
+        if request.config.getoption("--update-baseline") or not baseline_file.exists():
+            BASELINE_DIR.mkdir(parents=True, exist_ok=True)
+            np.savez_compressed(baseline_file, skeleton=skeleton)
+            baseline_changed = True
+
+        features_changed = False
+        if request.config.getoption("--update-baseline") or not feature_file.exists():
+            FEATURE_DIR.mkdir(parents=True, exist_ok=True)
+            _write_feature_csv(feature_file, features)
+            features_changed = True
+
+        if baseline_changed or features_changed:
+            artifacts = []
+            if baseline_changed:
+                artifacts.append("skeleton baseline")
+            if features_changed:
+                artifacts.append("feature baseline")
+            pytest.skip(f"{', '.join(artifacts)} created for baseline")
+
+        with np.load(baseline_file) as data:
+            baseline = data["skeleton"]
+
+        assert (
+            skeleton.shape == baseline.shape
+        ), f"shape mismatch got {skeleton.shape}, expected {baseline.shape}"
+        assert np.array_equal(
+            skeleton, baseline
+        ), f"skeleton differs (hash {_hash_array(skeleton)} vs {_hash_array(baseline)})"
+
+        baseline_features = _read_feature_csv(feature_file)
+        feature_keys = sorted(features)
+        baseline_feature_keys = sorted(baseline_features)
+        assert (
+            feature_keys == baseline_feature_keys
+        ), f"feature set differs (got {feature_keys}, expected {baseline_feature_keys})"
+
+        feature_values = np.array([features[k] for k in feature_keys], dtype=np.float64)
+        baseline_feature_values = np.array(
+            [baseline_features[k] for k in feature_keys], dtype=np.float64
+        )
+        np.testing.assert_allclose(
+            feature_values,
+            baseline_feature_values,
+            rtol=1e-8,
+            atol=1e-10,
+            err_msg="feature values differ from baseline",
+        )

vesskel-1.0.0/vesskel/_napari.py

@@ -0,0 +1,25 @@
+import time
+
+import numpy as np
+from napari.layers import Image
+from napari.types import LayerDataTuple
+from napari.utils.notifications import show_info
+
+from vesskel.thin import lee94_thin
+
+
+def lee94_thin_widget(
+    img: Image,
+) -> LayerDataTuple:
+    data = img.data
+    binary = (data > 0).astype(np.uint8)
+    n_fg = int(binary.sum())
+    t0 = time.perf_counter()
+    result = lee94_thin(binary)
+    elapsed = time.perf_counter() - t0
+    n_skel = int(result.sum())
+    show_info(
+        f"Thinned {img.name}: {n_fg} -> {n_skel} pixels "
+        f"({100 * n_skel / n_fg:.1f}% of foreground) in {elapsed:.1f}s"
+    )
+    return (result, {"name": f"{img.name}_thinned"}, "labels")

vesskel-1.0.0/vesskel/features.py

@@ -0,0 +1,111 @@
+import numpy as np
+from scipy.sparse import coo_matrix
+from scipy.sparse.csgraph import connected_components
+from skan import Skeleton, summarize
+
+
+def build_vessel_graph(skeleton: np.ndarray) -> Skeleton:
+    """Build a graph representation from a binary vessel skeleton."""
+    return Skeleton((skeleton > 0).astype(np.uint8))
+
+
+def extract_vessel_features(
+    skeleton: np.ndarray,
+) -> dict[str, float]:
+    """Extract graph-topology and segment statistics from a vessel skeleton."""
+    graph = build_vessel_graph(skeleton)
+    branch_data = summarize(graph, separator="-")
+
+    if branch_data.empty:
+        return {
+            "num_nodes": 0.0,
+            "num_edges": 0.0,
+            "num_endpoints": 0.0,
+            "num_bifurcations": 0.0,
+            "total_length": 0.0,
+            "mean_length": 0.0,
+            "std_length": 0.0,
+            "max_length": 0.0,
+            "min_length": 0.0,
+            "mean_tortuosity": 0.0,
+            "std_tortuosity": 0.0,
+            "num_components": 0.0,
+            "mean_degree": 0.0,
+            "max_degree": 0.0,
+        }
+
+    src_nodes = branch_data["node-id-src"].to_numpy(dtype=np.int64)
+    dst_nodes = branch_data["node-id-dst"].to_numpy(dtype=np.int64)
+    edge_nodes = np.concatenate((src_nodes, dst_nodes))
+    unique_nodes = np.unique(edge_nodes)
+
+    num_edges = int(len(branch_data))
+    num_nodes = int(unique_nodes.size)
+
+    max_node_id = int(np.max(unique_nodes))
+    degrees = np.bincount(edge_nodes, minlength=max_node_id + 1)
+    node_degrees = degrees[unique_nodes]
+
+    num_endpoints = int(np.count_nonzero(node_degrees == 1))
+    num_bifurcations = int(np.count_nonzero(node_degrees >= 3))
+    mean_degree = float(np.mean(node_degrees)) if node_degrees.size else 0.0
+    max_degree = float(np.max(node_degrees)) if node_degrees.size else 0.0
+
+    node_to_index = {node: idx for idx, node in enumerate(unique_nodes)}
+    src_idx = np.fromiter((node_to_index[src] for src in src_nodes), dtype=np.int64)
+    dst_idx = np.fromiter((node_to_index[dst] for dst in dst_nodes), dtype=np.int64)
+    adjacency = coo_matrix(
+        (
+            np.ones(src_idx.size * 2, dtype=np.uint8),
+            (
+                np.concatenate((src_idx, dst_idx)),
+                np.concatenate((dst_idx, src_idx)),
+            ),
+        ),
+        shape=(num_nodes, num_nodes),
+    ).tocsr()
+    num_components = int(
+        connected_components(adjacency, directed=False, return_labels=False)
+    )
+
+    lengths = branch_data["branch-distance"].to_numpy(dtype=float)
+    euclidean = branch_data["euclidean-distance"].to_numpy(dtype=float)
+
+    if lengths.size:
+        total_length = float(np.sum(lengths))
+        mean_length = float(np.mean(lengths))
+        std_length = float(np.std(lengths))
+        max_length = float(np.max(lengths))
+        min_length = float(np.min(lengths))
+    else:
+        total_length = 0.0
+        mean_length = 0.0
+        std_length = 0.0
+        max_length = 0.0
+        min_length = 0.0
+
+    valid_tortuosity = euclidean > 0
+    tortuosity = lengths[valid_tortuosity] / euclidean[valid_tortuosity]
+    if tortuosity.size:
+        mean_tortuosity = float(np.mean(tortuosity))
+        std_tortuosity = float(np.std(tortuosity))
+    else:
+        mean_tortuosity = 0.0
+        std_tortuosity = 0.0
+
+    return {
+        "num_nodes": float(num_nodes),
+        "num_edges": float(num_edges),
+        "num_endpoints": float(num_endpoints),
+        "num_bifurcations": float(num_bifurcations),
+        "total_length": total_length,
+        "mean_length": mean_length,
+        "std_length": std_length,
+        "max_length": max_length,
+        "min_length": min_length,
+        "mean_tortuosity": mean_tortuosity,
+        "std_tortuosity": std_tortuosity,
+        "num_components": float(num_components),
+        "mean_degree": mean_degree,
+        "max_degree": max_degree,
+    }