Metadata-Version: 2.4
Name: napari-UniSPAC
Version: 1.1.0
Summary: A Unified Segmentation framework for Proofreading and Annotation in Connectomics (UniSPAC)!
Home-page: https://github.com/ddd9898/UniSPAC
Classifier: Framework :: napari
License-File: LICENSE
Requires-Dist: napari
Dynamic: license-file

# napari-UniSPAC

`napari-UniSPAC` is a napari plugin for UniSPAC, a unified segmentation framework for proofreading and annotation in connectomics. The plugin provides interactive 2D and 3D neuron segmentation workflows for volume electron microscopy data, including click-based proofreading, 3D tracing, and automatic segmentation modes.

## Overview

UniSPAC is designed for efficient neuron segmentation and proofreading with sparse user interaction. In napari, users can load an image volume, select an output labels layer, load the pretrained checkpoints, and refine segmentations with mouse clicks.

Main features:

- Interactive click-based 2D neuron segmentation
- 3D tracing across adjacent slices
- Automatic "Everything" segmentation mode
- Optional online adaptation of the 2D mask head
- Checkpoint loading from a user-selected local folder

## System Requirements

The plugin requires a Python environment with napari and PyTorch. GPU acceleration is strongly recommended for practical use.

Recommended hardware:

- NVIDIA GPU with CUDA support

Recommended software:

- Python 3.9 or later
- napari
- PyTorch installed for the local CUDA or CPU configuration

## Installation

Install napari:

```shell
pip install -U 'napari[all]'
```

Clone and install this plugin:

```shell
git clone https://github.com/ddd9898/napari-UniSPAC.git
cd napari-UniSPAC
pip install -e .
```

Install the additional runtime dependencies listed in `requirements.txt` when needed:

```shell
pip install -r requirements.txt
```

PyTorch should be installed separately using the command recommended for your CUDA or CPU setup at [pytorch.org](https://pytorch.org/).

## Model Checkpoints

The plugin does not download model weights automatically. Download the pretrained checkpoints manually from the UniSPAC OneDrive folder:

```text
https://1drv.ms/f/c/88a3ba3c5aa53eeb/IgBDDnxcSN9QRKU-3jNDaBF4AdMLvpbbU3FTvKO2ngsWDlQ?e=XtkNDe
```

Download the following four files from the `leave-human-out` experiment and place them in the same local folder:

```text
ACRLSD_2D_leaveout_human_holdoutVal16_neo_Best_in_val.model
ACRLSD_3D_leaveout_human_holdoutVal16_neo_preLSD_Best_in_val.model
segEM2d_plus_leaveout_human_holdoutVal16_neo_wb1.0_wd1.0_wbd0.3_mtp5_sd0.55_Best_in_val.model
segEM3d_trace_leaveout_human_holdoutVal16_neo_wb1.0_wd1.0_wbd0.3_Best_in_val.model
```

Keep all four files together so the plugin can resolve the referenced backbones during model loading.

## Usage

Start napari:

```shell
napari
```

In napari:

1. Open an image or volume.
2. Open the UniSPAC plugin from the napari plugin menu.
3. Click `Load from folder` and select the local folder containing the four checkpoint files.
4. Select the input image layer and output labels layer.
5. Click `Activate` for interactive proofreading, or select `Everything` mode to run automatic segmentation.

## Repository Contents

- `src/napari_UniSPAC/`: napari plugin source code
- `requirements.txt`: runtime dependency list
- `README.md`: installation and usage instructions
- `LICENSE`: software license

Reference scripts and local experimental files may be present in development copies of the repository, but they are not required to run the napari plugin.

## Data and Model Availability

Pretrained UniSPAC checkpoints are distributed separately through the OneDrive link above. Example image data and additional experiment outputs are not bundled with the Python package.

## Citation

If you use UniSPAC or this napari plugin in a publication, please cite the associated UniSPAC manuscript or repository. Citation details will be updated here when the final reference is available.

## License

This project is distributed under the terms described in `LICENSE`.
