Maskel

Vessel Skeletonization and Graph-Based Phenotype Analysis in Retinal Fundus Images and other tubular structures.

Maskel is the core algorithm package: thinning, feature extraction, and the batch CLI. For the napari plugin, see napari-maskel. For benchmarks and the HRF-based analysis notebooks, see maskel-evaluations.

Installation

uv sync                  # core only
uv sync --extra dev      # + test tools

CLI

maskel init config.json
maskel validate config.json
maskel run --input /path/to/images --config config.json --out outputs

A config JSON can also be exported from the napari-maskel plugin's Save Config button and used here directly — both consume the same schema (see below).

CLI outputs:

• outputs/summary.csv with one feature row per image
• Optional per-image skeleton outputs (default: .npy)
• Optional per-image branch tables when output.write_branch_csv=true
• Optional per-image node tables when output.write_node_csv=true
• Optional per-image skeleton graphs when output.write_graphml=true

Configuration

Extraction and output settings are defined in a JSON config file (e.g. the one exported from napari or written by hand).

{
  "schema_version": 3,
  "extraction": {
    "branches": false,
    "branch_color_property": "tortuosity",
    "branch_text": false,
    "nodes": false,
    "summary": true,
    "fractal_dimension": false,
    "vessel_radius": false,
    "junction_cleanup": false,
    "cleanup_threshold_factor": 2.5,
    "prune_spurs": false,
    "min_spur_length": 10.0,
    "spur_iterations": 1,
    "closing_iterations": 0,
    "fill_holes": false,
    "max_hole_size": 0,
    "show_preprocessed": false
  },
  "output": {
    "write_skeleton_npy": true,
    "write_skeleton_png": false,
    "write_summary_csv": true,
    "write_branch_csv": false,
    "write_node_csv": false,
    "write_radius": false,
    "write_graphml": false
  }
}

Shell completions

# zsh
eval "$(maskel completions zsh)"

# bash
eval "$(maskel completions bash)"

# PowerShell
maskel completions powershell | Out-String | Invoke-Expression

Add the appropriate line to your shell rc for persistent tab-completion.

Tests

uv sync --extra dev && pytest                     # all tests
uv sync --extra dev && pytest -m "not slow"       # skip regression tests

• 3D regression - thinning + features on a brain volume (from scikit-image), compared against saved baselines
• 3D comparison - maskel 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/.

Real-data regression tests against the HRF dataset (2D thinning + feature extraction on all 45 samples) live in maskel-evaluations, since they depend on that external dataset.

License

Maskel is released under the MIT License. See LICENSE for details.