SkelHub

SkelHub is a Python framework for 3D skeletonization.

It brings several skeletonization methods into one package, with:

• one shared CLI
• one backend registry
• common result objects
• algorithm-agnostic evaluation
• optional graph generation and visualization tools

The goal is simple: keep each algorithm backend isolated, while giving users one clean way to run, compare, and inspect skeleton outputs.

Overview

Current status:

• Supported backends: laplacian, mcp, lee94, l1_skeleton, palagyi_kuba, flux
• CLI entrypoints: skelhub run, skelhub evaluate, skelhub graphgen, skelhub feature, skelhub graphviz, skelhub gui
• Evaluation: v2 metrics include voxel-based coverage (precision/recall/F1 per tolerance), displacement, Betti-number topology, endpoint diagnostics and an optional foreground EDT-sum agreement (with a shared foreground mask) for paired 3D binary skeleton volumes
• Visualization: PyVista-based viewer for GraphML graphs with selectable straight, continuous-centreline, or voxel-path edges, plus binary NIfTI volumes

SkelHub is organized around four layers:

• I/O: read, validate, normalize, and write volumes.
• Algorithms: run isolated backend implementations.
• Evaluation: compare standardized skeleton outputs.
• CLI/API: provide stable user-facing entrypoints.

Installation

Conda environment

Recommended for HPC and desktop environments that need the graph viewer.

conda create -n skelhub python=3.11
conda activate skelhub
python -m pip install -e .

For the PyVista graph viewer, some HPC systems need an updated C++ runtime:

conda install -c conda-forge libstdcxx-ng

If the viewer still reports runtime library issues, prefer a clean module stack:

module unload Miniconda3
module load Miniconda3
conda activate skelhub
conda install -c conda-forge libstdcxx-ng
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"

Python venv

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

You can also install dependencies with:

python -m pip install -r requirements.txt

The console command skelhub is exposed by the package install. If skelhub points to a different environment than python, use:

python -m skelhub --help

For the standalone Linux Graph Tools GUI, install the optional desktop dependencies and launch it:

python -m pip install -e '.[gui]'
skelhub gui

The GUI is under active development and currently separate from skelhub graphviz. See GUI.

CLI Usage

Use the focused docs below:

• Algorithms
• Evaluation
• Postprocessing
• Visualization
• GUI
• Python API

Repository Structure

SkelHub/
├── docs/
│   ├── API.md
│   ├── GUI.md
│   ├── StructuredOutput.md
│   ├── algorithms.md
│   ├── architecture.md
│   ├── evaluation.md
│   └── visualization.md
├── skelhub/
│   ├── cli/
│   ├── core/
│   ├── io/
│   ├── algorithms/
│   │   ├── laplacian/
│   │   ├── mcp/
│   │   ├── lee94/
│   │   ├── l1_skeleton/
│   │   ├── palagyi_kuba/
│   │   └── flux/
│   ├── evaluation/
│   ├── preprocessing/
│   ├── postprocessing/
│   │   ├── graphgen/
│   │   ├── feature/
│   │   └── protograph_cleaner.py
│   ├── visualization/
│   └── datasets/
├── tests/
└── pyproject.toml

Key locations:

• skelhub.core defines shared data models, interfaces, and the backend registry.
• skelhub.algorithms contains isolated backend adapters and implementations.
• skelhub.evaluation contains the voxel-based evaluator.
• skelhub.postprocessing.graphgen converts skeleton NIfTI volumes into GraphML.
• skelhub.postprocessing.feature writes Voreen-style edge and node CSV features from vessel foreground, skeleton, and compatible GraphML inputs.
• skelhub.postprocessing.protograph_cleaner contracts degree-2 GraphML nodes into ordered centreline paths; scripts/protograph_cleaner.sh exposes the workflow through the active Python environment.
• skelhub.visualization powers skelhub graphviz.
• skelhub.gui powers skelhub gui, while topology calculations and report output stay separate from the desktop widgets.
• skelhub.postprocessing.edt and skelhub.postprocessing.surface_distance compute voxel-EDT and surface-distance samples for the EDT Heat tab; skelhub.visualization.heatmap and skelhub.visualization.edt_heat handle its colours, rendering, and picking.
• skelhub.evaluation.centeredness computes the local EDT ratio, a first centeredness indicator (EDT at a skeleton point ÷ largest EDT within α × EDT in the same 26-connected component; α 1.0–3.0, default 1.5). EDT Heat can colour by it; see GUI.

Structured Output

SkelHub uses typed result containers for skeletons, graphs, and evaluation reports. See Structured Output for the current contract.

Review pending: this output structure is stable enough to use, but it will be reviewed as the framework matures.

Pull Requests and Releases

The PR template includes a change summary, testing notes, and one version choice: bugfix / refactoring (+0.0.1), minor (+0.1.0), major (+1.0.0), or no release. Only dev → main merges trigger automatic releases. Leave the package version unchanged in PRs; automation updates pyproject.toml when releasing. Merge main back into dev after each release. See release workflow and setup.