Install & configure

OMERO-Screen needs three things: the software, a configuration that names your OMERO server and user, and your password. One command installs the software and walks you through the rest. Budget ten minutes the first time, most of it downloading.

Quick install (macOS and Linux)

Open Terminal and paste:

curl -LsSf https://raw.githubusercontent.com/HocheggerLab/omero-screen/main/install.sh | sh

The installer:

  1. installs uv, which brings its own Python, if it is missing;
  2. downloads the latest release and installs exactly the tested versions of everything, including napari, CellView, cellclass and the plotting library, into ~/.local/share/omero-screen;
  3. puts the commands (omero-screen, cellview, cellclass, napari, …) in uv’s command directory (normally ~/.local/bin) and adds that directory to your shell PATH automatically if needed;
  4. runs omero-screen setup and omero-screen doctor (below).

Run the same line again to update; your settings and data are kept. If the installer says it updated your PATH, open a new Terminal window once before running the commands. You do not need to edit .zshrc or another shell file manually.

Note

If you work with Claude, continue with Working with Claude once the installer has finished.

Set up your OMERO login

omero-screen setup

It asks for:

  • the site profile: a ready-made description of your server and microscopes. Choose sussex for the Hochegger lab OMERO, or none to type in a server name;
  • your OMERO user name and password. The password is checked against the server, then stored in your computer’s keychain (macOS Keychain), never in a file.

Your answers are saved in ~/.config/omero-screen/config.toml. Run setup again at any time to change them.

Check the installation

omero-screen doctor

doctor checks everything OMERO-Screen needs (the software, your login, the connection to the server, CellView, napari, the GPU and disk space) and says how to fix anything that fails. If something does not work, run it first. A failed connection is usually the VPN.

omero-screen config show      # the settings in effect, and where each came from
omero-screen --version        # the installed version

Hardware

Segmentation and tracking are the expensive steps. Everything runs on a laptop; some combinations need the right hardware.

Apple silicon (MPS) NVIDIA (CUDA) CPU only
Default segmentation stock Cellpose 3 models (nuclei, cyto3) Cellpose 4 (cpsam) stock Cellpose 3, slow
Cellpose 4 (--cp4) not in practice: too slow and too large yes impractical
Tracking (--track) falls back to CPU yes slow
Classifier inference yes yes workable
  • Segmentation models. With no models configured, OMERO-Screen picks the best default for the machine and says so in the log. The stock Cellpose 3 models segment most cells reasonably; a model trained on your own cells and microscope does better: see Make a model for your cells.
  • The models used are recorded on every plate. Each run writes the version, settings, device and models onto the plate in OMERO, so you can always tell how a plate was segmented.
  • Tracking has no MPS backend. On Apple silicon, --track runs on the CPU: correct, but slow.

Device selection is automatic: CUDA if present, then MPS, then CPU. Force CPU with OMERO_SCREEN_USE_GPU=0.

The configuration in detail

Settings come from several places. A value set higher up in this list wins:

  1. command-line flags (e.g. --cp4);
  2. environment variables (HOST, USERNAME, OMERO_SCREEN_*);
  3. a .env file in a source checkout (developers, see below);
  4. your user config, ~/.config/omero-screen/config.toml;
  5. the site profile it names;
  6. built-in defaults.

A user config written by setup looks like this:

site = "sussex"

[omero]
username = "ab123"
# group = "my-lab-group"          # default: your OMERO default group

[segmentation]
# model_set = "hocheggerlab"      # the lab's custom models (omero-screen models pull)

[paths]
# cache = "~/omero-cache"         # downloaded images
# cellview_db = "~/.cellview/cellview.duckdb"

[env]
# any OMERO_SCREEN_* variable, e.g.
# OMERO_SCREEN_USE_GPU = "0"

A site profile holds what everyone at a site shares: the OMERO server and port, the stitch calibrations of its microscopes, its model sets. sussex is built in. For another site, write one as a TOML file, set site = "/path/to/your-site.toml", and send it to us so it can be included.

On a machine without a keychain (an HPC cluster), put the password in a file only you can read and name it in the user config:

umask 077 && echo 'your-password' > ~/.omero-password
[omero]
password_file = "~/.omero-password"

The PASSWORD environment variable works too, and takes precedence.

Working in another user’s screens

To analyse plates that belong to someone else, you need at least read access to their OMERO group. Your OMERO administrator sets this. Masks and results are written to your own Screens project.

Developer install

To work on the code, clone the repository and install the workspace with the development tools:

git clone https://github.com/HocheggerLab/omero-screen.git
cd omero-screen
uv sync --dev
uv run omero-screen doctor

uv sync installs all six packages (the core pipeline, cellview, omero-screen-plots, omero-screen-napari, cellclass and omero-utils). Configure with uv run omero-screen setup as above. A .env.development (or .env.production, selected with ENV=production) at the repository root is still read and takes precedence over the user config:

USERNAME="your-omero-login"
PASSWORD="your-omero-password"
HOST="omero.your-institution.ac.uk"
Warning

.env.* files hold your password in plain text. They are gitignored; keep it that way, and never paste one into an issue or a pull request.

Run uv run omero-integration-test e2e_connection to check the connection to a test server.

Next

You are ready to analyse your first plate.