Metadata-Version: 2.4
Name: vessqc
Version: 0.9.11
Summary: Napari plugin for uncertainty-based quality control of 3D vessel segmentations
Author-email: Peter Lampen <lampen@isas.de>
License: 
        Copyright (c) 2024, Peter Lampen
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of copyright holder nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/MMV-Lab/VessQC
Project-URL: Bug Tracker, https://github.com/MMV-Lab/VessQC/issues
Project-URL: Documentation, https://github.com/MMV-Lab/VessQC
Project-URL: Source Code, https://github.com/MMV-Lab/VessQC
Project-URL: User Support, https://github.com/MMV-Lab/VessQC/issues
Keywords: napari,segmentation,vessel segmentation,uncertainty,image processing,3D imaging
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Framework :: napari
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: joblib>=1.2
Requires-Dist: napari>=0.6.0
Requires-Dist: numpy>=1.23
Requires-Dist: qtpy>=2.3
Requires-Dist: scipy>=1.9
Requires-Dist: SimpleITK>=2.2
Requires-Dist: tifffile>=2023.2.28
Provides-Extra: qt
Requires-Dist: pyqt5; extra == "qt"
Provides-Extra: testing
Requires-Dist: tox; extra == "testing"
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Requires-Dist: pytest-qt; extra == "testing"
Dynamic: license-file

# VessQC

[![License BSD-3](https://img.shields.io/pypi/l/VessQC.svg?color=green)](https://github.com/MMV-Lab/VessQC/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/VessQC.svg?color=green)](https://pypi.org/project/VessQC)
[![Python Version](https://img.shields.io/pypi/pyversions/VessQC.svg?color=green)](https://python.org)
[![tests](https://github.com/MMV-Lab/VessQC/workflows/tests/badge.svg)](https://github.com/MMV-Lab/VessQC/actions)
[![codecov](https://codecov.io/gh/MMV-Lab/VessQC/branch/main/graph/badge.svg)](https://codecov.io/gh/MMV-Lab/VessQC)
[![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/VessQC)](https://napari-hub.org/plugins/VessQC)

A napari plugin for uncertainty-based quality control and manual correction of 3D blood vessel segmentations.

---

## Overview

VessQC is a plugin for the image viewer [napari](https://github.com/napari/napari).
It is designed for the inspection and correction of 3D vessel segmentations generated by machine-learning pipelines.

The plugin combines:

- visualization of image, segmentation, and uncertainty data,
- automatic grouping of uncertain regions into segments,
- interactive review of suspicious regions,
- manual correction of segmentation masks,
- export of corrected segmentation results.

The plugin is particularly useful for workflows in which:

- a neural network generates vessel segmentations,
- uncertainty maps are available,
- only uncertain regions should be reviewed manually.

---

## Screenshot

![VessQC user interface](https://raw.githubusercontent.com/MMV-Lab/VessQC/main/docs/images/vessqc_screenshot.png)

---

## Installation

Install the released version from PyPI:

```bash
pip install VessQC
```

Install the latest development version from GitHub:

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

---

## Input Data

VessQC expects three volumetric datasets:

1. Original image data
2. Predicted vessel segmentation (`*_segPred`)
3. Uncertainty map (`*_uncertainty`)

Supported file formats:

- TIFF (`.tif`, `.tiff`)
- NIfTI (`.nii`, `.nii.gz`)

Example:

```text
Sample_IM.tif
Sample_segPred.tif
Sample_uncertainty.tif
```

---

## Usage

### 1. Load the image

Press:

```text
Load image
```

and select the original 3D image.

---

### 2. Load segmentation and uncertainty data

Press:

```text
Read segPred file
```

The plugin automatically searches for matching:

- `*_segPred`
- `*_uncertainty`

files in the same directory.

The uncertainty map is segmented into connected uncertain regions.

---

### 3. Review uncertain segments

Press:

```text
Show list of segments
```

A separate window displays all detected uncertain regions.

For each segment the following information is shown:

- segment name,
- uncertainty value,
- voxel count,
- processing state.

---

### 4. Inspect a segment

Click a segment button to:

- zoom into the corresponding region,
- crop the surrounding image data,
- display the local segmentation,
- center the viewer on the selected segment.

---

### 5. Correct the segmentation

Use the standard napari label editing tools to:

- add missing vessel voxels,
- remove incorrect voxels,
- refine the segmentation mask.

After correction press:

```text
done
```

The modifications are transferred back into:

- the segmentation volume,
- the uncertainty map,
- the internal label representation.

---

### 6. Save the result

Press:

```text
Save final result
```

The corrected segmentation is written to disk as:

```text
*_segPred_New.tif
```

Optionally the corrected uncertainty map can also be saved.

---

## Intermediate Data

VessQC can store intermediate processing results in the temporary directory.

The following data are saved:

- segmentation volume,
- uncertainty volume,
- label volume,
- segment metadata.

This allows interrupted curation sessions to be resumed later.

---

## Development

Run the test suite with:

```bash
pytest
```

---

## Contributing

Contributions and bug reports are welcome.

Please include:

- a detailed problem description,
- steps to reproduce the issue,
- example data if possible.

---

## License

Distributed under the terms of the BSD-3 license.

---

## Repository

GitHub repository:

https://github.com/MMV-Lab/VessQC
