vessqc 1.0.0

Quality control plugin for vessel segmentation in napari

VessQC: Uncertainty-Guided Curation for 3D Segmentation

Table of Contents

1. Overview
2. Input Data Requirements
3. Installation and Launch
4. Curation Workflow
5. Save Behavior
6. Citation
7. Contributing
8. License
9. Issues

Overview

Overview This repository provides the implementation of VessQC, introduced in the manuscript "Bridging 3D Deep Learning and Uncertainty-Guided Curation for Analysis and High-Quality Segmentation Ground Truth", submitted to ISBI 2026.

VessQC is an open-source, human-in-the-loop tool for efficient, uncertainty-guided curation of large 3D volumetric segmentations, with a particular emphasis on complex vascular structures. By leveraging e.g. pixel-wise or topology-aware uncertainty estimation, VessQC prioritizes regions most likely to contain segmentation errors, thereby significantly improving error recall and reducing manual effort.

This napari plugin was generated using Cookiecutter and the @napari cookiecutter-napari-plugin template.

Input Data Requirements

VessQC requires three core input files per volume, all of which must be perfectly aligned and of identical spatial dimensions. Supported file formats include .tiff and .nii and all related variants (e.g., .ome.tif, .tif, .nii.gz).

1. Raw Image Volume: The original 3D image data (e.g., lightsheet microscopy stack).
2. Segmentation Mask: A binary segmentation mask of the target structures.
3. Uncertainty Map: A voxel-wise uncertainty map highlighting regions of potential segmentation error.

File Naming Conventions

VessQC automatically detects corresponding files based on naming patterns. Each file type must follow the conventions below:

File Type	Required Suffix	Example Filename
Raw Image Volume	_IM	sample01_IM.tiff
Segmentation Mask	_segPred	sample01_segPred.tiff
Uncertainty Map	_uncertainty	sample01_uncertainty.tiff

Ensure that all files belonging to the same sample share the same prefix (e.g., sample01) to allow automatic matching during loading.

Generating Uncertainty Maps

Uncertainty maps can be generated using models provided in our supplementary repository: VessQC-Supplementary

This repository includes both pixel-wise and topology-aware uncertainty pipelines. Please follow its documentation to produce the required uncertainty maps before running VessQC.

Installation and Launch

VessQC is a plugin that runs within the, open-source image viewer, napari. Please follow the steps below to install both napari and the VessQC plugin.

1. Install napari

VessQC requires a working installation of napari (Python 3.10-3.13 recommended). For the latest and most detailed instructions, always refer to the official napari installation guide.

Option A: Python/pip Installation

If you are familiar with Python environments, you can install napari via pip inside a clean virtual environment:

1. Create a virtual environment:

   conda create -y -n napari-env -c conda-forge python=3.11
   conda activate napari-env
   

2. Install napari:

   python -m pip install 'napari[all]'
   

Option B: Bundled App

For a simple installation without managing Python environments, download the bundled application for your operating system (e.g., version 0.6.7):

• Linux: napari-0.6.7-Linux-x86_64.sh
• macOS (Intel): napari-0.6.7-macOS-x86_64.pkg
• macOS (Apple Silicon): napari-0.6.7-macOS-arm64.pkg
• Windows: napari-0.6.7-Windows-x86_64.exe

Other artifacts can be found on the napari Releases page.

2. Install VessQC

Once napari is installed and your environment is active (for Option A), you can install VessQC via pip:

pip install VessQC

Or install the latest development version directly from GitHub:

pip install git+https://github.com/MMV-Lab/VessQC.git

Once installation is complete, launch napari and start VessQC through the Plugins menu.

Curation Workflow

The typical workflow involves loading the three required files and then iterating through the following steps:

1. Load Data: Use the File menu to load the Image, Segmentation, and Uncertainty Map.

2. Navigate to High-Uncertainty segments: VessQC shows a ranked list of segmented branches sorted by their associated uncertainty scores and allows direct selection of a branch from the list to automatically crop the area and center to that location

3. Review and Edit: Examine the 3D and 2D views at the high-uncertainty location. If an error is identified, use the provided annotation tools to correct the segmentation mask in the 2D viewer.

4. Iterate: Continue navigating to the next highest uncertain location and repeat the review and edit process.

5. Save: Once the curation process is complete, save the updated segmentation according to your chosen save mode (see below).

Save Behavior

VessQC offers two save modes to manage the progress and finalization of curated segmentations:

1. Temporary Save

• The folder structure remains unchanged.
• Newly curated files are saved with the suffix _temp. Example: sample01_segPred_temp.tiff
• When the same dataset is reloaded, VessQC automatically prioritizes the _tempversion for continued editing.

2. Final Save

• The finalized image, segmentation, uncertainty map, and curated segmentation are moved to a new done/ subdirectory.

• The moved items are removed from the main directory, ensuring they no longer appear in the list of available images during subsequent sessions.

• This two-tier saving mechanism supports both iterative refinement and systematic completion tracking during large-scale curation projects.

Citation

If you use the VessQC tool or the methodologies, please cite the corresponding paper:

TODO

Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

License

Distributed under the terms of the BSD-3 license, "VessQC" is free and open source software

Issues

If you encounter any problems, please file an issue along with a detailed description.