Metadata-Version: 2.4
Name: omnipose-viewer
Version: 0.1.0
Summary: Browser-based GUI for Omnipose cell segmentation
License: MIT
Project-URL: Homepage, https://github.com/colauttj/omnipose-viewer
Project-URL: Bug Tracker, https://github.com/colauttj/omnipose-viewer/issues
Keywords: omnipose,cellpose,segmentation,microscopy,GUI
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: omnipose
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: Pillow>=10.0.0
Requires-Dist: tifffile>=2024.1.1
Requires-Dist: numpy>=1.24.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: scikit-image>=0.21.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: torch>=2.0.0
Dynamic: license-file

# Omnipose Viewer

A browser-based GUI for [Omnipose](https://github.com/kevinjohncutler/omnipose) cell segmentation.
Upload a microscopy image, tune parameters, and get a segmentation overlay — no scripting required.

Features include single-image segmentation, batch folder processing, colour-to-greyscale
pre-processing, and per-cell measurements exported as CSV.

---

## Installation

### Requirements

- Python 3.10 or 3.11
- A conda environment is strongly recommended

### 1 — Create a clean environment

```bash
conda create -n omnipose-viewer python=3.10
conda activate omnipose-viewer
```

### 2 — Install

```bash
pip install omnipose-viewer
```

This installs Omnipose, PyTorch, FastAPI, and all other dependencies automatically.

> **GPU support (optional)**
> `pip` installs the CPU version of PyTorch by default, which works fine for most images.
> For faster inference on an NVIDIA GPU, install the CUDA-enabled PyTorch *before* running
> the command above:
>
> ```bash
> # Example for CUDA 12.1 — check https://pytorch.org for your CUDA version
> pip install torch --index-url https://download.pytorch.org/whl/cu121
> pip install omnipose-viewer
> ```

---

## Usage

```bash
omnipose-viewer
```

The server starts and your browser opens automatically at `http://localhost:8000`.

### Options

| Flag | Default | Description |
|------|---------|-------------|
| `--port PORT` | `8000` | Port to listen on |
| `--host HOST` | `127.0.0.1` | Bind address. Use `0.0.0.0` to share on your local network |
| `--no-browser` | — | Don't auto-open the browser |

```bash
# Examples
omnipose-viewer --port 8080
omnipose-viewer --host 0.0.0.0 --port 8000   # accessible to lab colleagues
omnipose-viewer --no-browser
```

---

## GUI walkthrough

### Single image tab

1. **Drop or select** a microscopy image (TIFF, PNG, or JPEG).
2. **Choose a model** from the dropdown — `bact_phase_omni` is the best starting point for
   bacterial phase-contrast images.
3. **Adjust parameters** as needed:

   | Parameter | Default | Description |
   |-----------|---------|-------------|
   | Cell diameter | `0` (auto) | Expected cell diameter in pixels. `0` = auto-detect |
   | Flow threshold | `0.4` | Higher = stricter (fewer false positives, may miss cells) |
   | Mask threshold | `0.0` | Lower = more permissive masks |
   | Min cell size | `15` | Filters out debris smaller than this many px² |

4. Click **▶ Run Segmentation**.
5. The overlay appears in the viewer — each detected cell is uniquely coloured.
6. Click **↓ Save PNG** to download the result, or switch to the **Analysis** tab to see
   per-cell measurements and export a CSV.

### Pre-process tab

Converts colour images (RGB TIFF / PNG / JPEG) to 16-bit greyscale TIFFs ready for Omnipose.
Choose a conversion method (luminance, average, or a single channel) and point it at a folder.

### Batch tab

Run segmentation on an entire folder of TIFFs in one go. Results (overlay PNGs + a combined CSV)
are saved back to the same folder, or to a folder you specify.

---

## Where are my results stored?

Masks and CSVs from single-image jobs are stored in a platform-appropriate directory:

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/omnipose-viewer/results/` |
| Windows | `%LOCALAPPDATA%\omnipose-viewer\omnipose-viewer\results\` |
| Linux | `~/.local/share/omnipose-viewer/results/` |

Batch results are saved directly into the input folder (or the output folder you specify in the UI).

---

## Available models

| ID | Description |
|----|-------------|
| `bact_phase_omni` | Bacterial cells — phase contrast (Omnipose) |
| `bact_fluor_omni` | Bacterial cells — fluorescence (Omnipose) |
| `cyto2_omni` | Eukaryotic cytoplasm (Omnipose) |
| `cyto2` | Eukaryotic cytoplasm (Cellpose) |
| `cyto` | Eukaryotic cytoplasm, original (Cellpose) |
| `nuclei` | Cell nuclei (Cellpose) |

Models are downloaded automatically on first use and cached in `~/.cellpose/models/`.

---

## REST API

The GUI is backed by a FastAPI server you can also call programmatically.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | GPU availability and torch version |
| `GET` | `/models` | List available models |
| `POST` | `/segment` | Segment a single uploaded image |
| `POST` | `/measure` | Measure cells from a previous segment job |
| `GET` | `/results/{job_id}/mask` | Download raw integer mask (`.npy`) |
| `GET` | `/results/{job_id}/csv` | Download measurements CSV |
| `GET` | `/preprocess/preview` | List images in a folder |
| `POST` | `/preprocess/start` | Start colour → 16-bit conversion |
| `GET` | `/preprocess/status/{prep_id}` | Poll conversion progress |
| `GET` | `/batch/preview` | List TIFFs in a folder |
| `POST` | `/batch/start` | Start a batch segmentation job |
| `GET` | `/batch/status/{batch_id}` | Poll batch progress |
| `GET` | `/batch/csv/{batch_id}` | Download combined batch CSV |

### Example: call `/segment` from Python

```python
import requests

with open("my_image.tif", "rb") as f:
    resp = requests.post(
        "http://localhost:8000/segment",
        files={"file": ("my_image.tif", f, "image/tiff")},
        data={
            "model_type":      "bact_phase_omni",
            "diameter":        "0",
            "flow_threshold":  "0.4",
            "mask_threshold":  "0.0",
            "min_size":        "15",
            "use_gpu":         "false",
            "channels":        "0,0",
        },
    )

print("Cells detected:", resp.headers["X-Cell-Count"])
print("Job ID:",         resp.headers["X-Job-Id"])

with open("result.png", "wb") as out:
    out.write(resp.content)
```

---

## Contributing

Pull requests are welcome. For major changes, please open an issue first.

```bash
# Development install (editable)
git clone https://github.com/colauttj/omnipose-viewer
cd omnipose-viewer
pip install -e .

# Then launch as normal
omnipose-viewer
```

---

## License

[MIT](LICENSE)

---

## Acknowledgements

- [Omnipose](https://github.com/kevinjohncutler/omnipose) — Kevin Cutler et al.
- [Cellpose](https://github.com/MouseLand/cellpose) — Carsen Stringer et al.
