# 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:

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

The installer:

1.  installs [uv](https://docs.astral.sh/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: Note**
>
> If you work with Claude, continue with [Working with Claude](claude.md) once the installer has finished.


# Set up your OMERO login

``` bash
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

``` bash
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.

``` bash
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](models.md).
- **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:

``` toml
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:

``` bash
umask 077 && echo 'your-password' > ~/.omero-password
```

``` toml
[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:

``` bash
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:

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

> **Warning: 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](first-plate.md).