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

Input images can be either a plain binary segmentation mask, or a multi-object instance segmentation map (more than one distinct nonzero value). In the latter case, every object is skeletonized independently — touching-but-distinct objects are correctly kept separate rather than merged into one skeleton — and every output row is tagged with the object_id it came from (the mask's own label value; 1 for a plain binary mask).

CLI outputs:

• outputs/summary.csv with one feature row per object per image
• Optional per-image skeleton outputs (default: .npy)
• Optional per-image branch tables when output.write_branch_csv=true (includes an object_id column)
• Optional per-image node tables when output.write_node_csv=true (includes an object_id column)
• Optional per-object skeleton graphs when output.write_graphml=true (one _<object_id>_graph.graphml file per object)
• Optional per-object pickled networkx graphs when output.write_networkx_graph=true (one _<object_id>_graph.pkl file per object; richer than GraphML - keeps NaN attributes and native Python types)

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": 6,
  "extraction": {
    "branches": false,
    "branch_color_property": "tortuosity",
    "branch_text": false,
    "nodes": false,
    "summary": true,
    "fractal_dimension": false,
    "mask_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,
    "spacing": null
  },
  "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,
    "write_networkx_graph": 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 the slow 3D comparison test

• 3D comparison - maskel lee94_thin vs skimage.morphology.skeletonize on a brain volume (from scikit-image), asserting identical output

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.