Omnipose Viewer

A browser-based GUI for 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

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

2 — Install

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:

# 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

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

# 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

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.

# 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

---

Acknowledgements

• Omnipose — Kevin Cutler et al.
• Cellpose — Carsen Stringer et al.