Metadata-Version: 2.4
Name: napari-em-assistant
Version: 0.1.0
Summary: Task-based EM image processing assistant for napari.
Author: Wulin Teo
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: tifffile
Requires-Dist: qtpy
Requires-Dist: napari
Requires-Dist: opencv-python-headless
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x; extra == "gpu"

# napari-em-assistant

Task-based electron microscopy image processing tools for napari.

`napari-em-assistant` is organized around small, explicit processing tasks that
can be used interactively on an active napari layer or applied to folders of EM
images. The first task is ImageJ/Fiji-style local contrast enhancement with
CLAHE.

## Current Task

### Enhance Local Contrast CLAHE

The CLAHE task provides a napari widget for 2D grayscale EM images and 3D
grayscale stacks. It follows the ImageJ/Fiji dialog shape and default values:

- block size: `127`
- histogram bins: `256`
- maximum slope: `3.00`
- mask: `*None*`
- fast: checked

The widget can:

- show a top CUDA status bar for CuPy CUDA and OpenCV CUDA CLAHE availability
- preview CLAHE on the active image layer
- apply CLAHE to the active 2D image layer or 3D grayscale stack
- create a new layer named `<source_layer_name>_CLAHE`
- batch process TIFF folders to an output folder
- show batch progress with load/process checks, status, and output path

## Backends

- `opencv_cpu`: fast CPU approximation using `cv2.createCLAHE`.
- `imagej_reference`: Python implementation ported from Fiji's
  `mpicbg.ij.clahe.PlugIn` 2D grayscale CLAHE path. 3D stacks are processed
  slice-by-slice.
- `gpu_cupy`: optional CuPy/CUDA batch backend. If CuPy or a CUDA device is not
  available, it falls back to `opencv_cpu`.

The CUDA status bar is diagnostic: `CuPy` indicates whether the GPU CuPy backend
can run on CUDA now, while `OpenCV CUDA CLAHE` reports whether the installed
OpenCV build exposes CUDA CLAHE support.

OpenCV CLAHE parameters are not identical to ImageJ/Fiji CLAHE parameters.
Use `imagej_reference` when Fiji-style output is the priority. Current OpenCV
and CuPy paths should be treated as practical approximations.

## Install

From this repository:

```bash
pip install -e .
```

Optional CuPy support depends on the workstation CUDA stack. A convenience extra
is provided:

```bash
pip install -e ".[gpu]"
```

If that wheel does not match the local CUDA runtime, install the correct CuPy
package manually and keep the base plugin install CPU-only.

## Use In napari

After installation, open napari and choose:

```text
Plugins > Enhance Local Contrast CLAHE
```

For interactive use, select a 2D grayscale image layer or 3D grayscale stack and
use `Preview` or `Apply to Active Layer`.

For batch use, choose an input folder containing 2D images or 3D grayscale
stacks saved as `.tif` or `.tiff` files, choose an output folder, select a
backend, and run the batch. Outputs are saved as:

```text
<stem>_clahe.tif
```

## Validation

The current implementation is tested for:

- widget and backend imports
- Fiji-derived `imagej_reference` fast and exact paths
- OpenCV CLAHE on synthetic `uint8` and `uint16` images
- shape preservation
- dtype preservation where possible
- 3D stack support
- GPU stub behavior
- `gpu_cupy` CPU fallback behavior
- batch result and progress reporting

Run tests with:

```bash
python3 -m pytest tests/tasks/test_enhance_local_contrast_clahe.py
```
