Metadata-Version: 2.4
Name: biomero-zarr-viewer
Version: 0.1.10
Summary: Authenticated OME-Zarr viewer for BIOMERO and OMERO.web
Author: NL-BioImaging
License: GNU AFFERO GENERAL PUBLIC LICENSE
        Version 3, 19 November 2007
        
        Copyright (C) 2026 NL-BioImaging
        
        This program is free software: you can redistribute it and/or modify it under
        the terms of the GNU Affero General Public License as published by the Free
        Software Foundation, either version 3 of the License, or (at your option) any
        later version.
        
        This program is distributed in the hope that it will be useful, but WITHOUT
        ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
        FOR A PARTICULAR PURPOSE. See <https://www.gnu.org/licenses/>.
        
        
Project-URL: Repository, https://github.com/NL-BioImaging/BIOMERO.ZarrViewer
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: omero-web>=5.6.0
Provides-Extra: test
Requires-Dist: Django<6,>=3.2; extra == "test"
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-django>=4.8; extra == "test"
Requires-Dist: build>=1.2; extra == "test"
Dynamic: license-file

# BIOMERO OME-Zarr Viewer

BIOMERO OME-Zarr Viewer is a read-only
[OMERO.web](https://omero.readthedocs.io/en/stable/developers/Web.html)
extension for opening physical OME-Zarr stores that are registered in OMERO.
It supports multichannel images, integer segmentation labels, Z stacks, and
HCS plates.

The viewer does not import data or convert ordinary OMERO images to OME-Zarr.
Use BIOMERO, or another compatible importer, to create and register the
OME-Zarr data first.

## Install into OMERO.web

The viewer uses the Nginx that already fronts the selected OMERO deployment.
It does not require a second proxy:

- [`omero-deployment-kit` instructions](docs/deployment-omero-deployment-kit.md):
  extend the host Nginx installed by its Ansible role;
- [`NL-BIOMERO` instructions](docs/deployment-nl-biomero.md): extend the
  existing Nginx container in its production SSL scenario.

Both deployment paths install the same wheel and
[`docker/90-biomero-zarr-viewer.omero`](docker/90-biomero-zarr-viewer.omero)
configuration. They differ only in how the existing Nginx sees the in-place
storage.

### Prerequisites

- OMERO.web 5.6 or newer, running on Python 3.10–3.12;
- a BIOMERO in-place OME-Zarr import, or an equivalent OMERO-to-store link;
- the OME-Zarr storage visible to OMERO.web and read-only to Nginx;
- one of the supported Nginx-fronted deployment paths above.

The current data backend requires Nginx to process `X-Accel-Redirect`.
Connecting directly to Gunicorn can load capabilities but cannot deliver
metadata or chunks because Django deliberately does not stream file bodies.

### Build the wheel

Use a pinned release wheel, or build one from this repository:

```bash
python -m pip install build
python scripts/build_frontend.py
python -m build --wheel
python scripts/verify_wheel.py dist/<wheel-file>.whl
```

Building requires Node.js 22 and Python 3.10–3.12. The resulting wheel already
contains the compiled frontend, so Node.js is not required in the production
OMERO.web container.

### Temporary installation in a running local stack

For development or a quick installation into an already running Compose
service named `omeroweb`, use:

```powershell
.\scripts\manage-docker-plugin.ps1 install
.\scripts\manage-docker-plugin.ps1 status
```

Use `-Container <name>` when the container is not part of a service named
`omeroweb`. Updates and removal are available as:

```powershell
.\scripts\manage-docker-plugin.ps1 update
.\scripts\manage-docker-plugin.ps1 remove
```

This installation is lost when the container is replaced. Use a derived image
or the deployment-kit integration for a persistent deployment. The local
stack must still be opened through an Nginx endpoint.

To build a persistent image without removing other installed OMERO.web
plugins, use:

```powershell
.\scripts\build-docker-image.ps1
```

The script uses the currently deployed OMERO.web image as its base by default,
so plugins already baked into that image are retained. It refuses to continue
when it detects plugin configuration files that exist only in the running
container and would therefore disappear after recreation. This protects
co-installed extensions such as OMERO.JupyterLite.

Never update this viewer by rebuilding directly from the vendor OMERO.web
image when the deployment already uses a combined plugin image. Layer the
updated viewer onto the current combined image instead.

### Storage path model

`source_root` is the path prefix recorded by the importer in OMERO.
`mount_root` is the corresponding path inside OMERO.web. The Nginx `alias` is
the same underlying storage as seen from Nginx's own host or container
namespace.

For example, if OMERO records
`/archive/alice/example.ome.zarr`, OMERO.web sees it as
`/data/alice/example.ome.zarr`, and host Nginx sees it as
`/srv/biomero/alice/example.ome.zarr`, configure:

```bash
omero config set omero.web.zarr_viewer.source_root /archive
omero config set omero.web.zarr_viewer.mount_root /data
omero config set omero.web.zarr_viewer.internal_prefix /_biomero_zarr_internal/
```

When the recorded and mounted paths are both under `/data`, the defaults in
[`docker/90-biomero-zarr-viewer.omero`](docker/90-biomero-zarr-viewer.omero)
are already correct.

The roots may differ, but the relative suffix
`alice/example.ome.zarr` must be identical. Nginx only needs read access.

### Verify the installation

1. Sign in to OMERO.web.
2. Select a BIOMERO-imported OME-Zarr Image or Plate.
3. Open **Open With → OME-Zarr Viewer**.
4. Confirm that image requests below
   `/biomero_zarr_viewer/data/images/...` return HTTP 200 or 206.
5. Confirm that directly requesting
   `/_biomero_zarr_internal/...` returns 404. This proves that the storage
   location cannot be accessed without Django authorization.

For a local Docker installation:

```powershell
.\scripts\manage-docker-plugin.ps1 status
```

If the menu entry is disabled, first confirm that the selected OMERO object is
readable and linked to one unambiguous `.zarr` store. If the viewer opens but
reports **Failed to fetch**, check the Nginx route, the shared read-only mount,
and the relative path below the OMERO.web and Nginx roots.

## Is BIOMERO required?

BIOMERO is not installed as a Python dependency of this viewer. It normally
runs earlier in the workflow as the importer that creates or preserves the
OME-Zarr store and registers where that store belongs in OMERO.

| Component | Responsibility |
| --- | --- |
| BIOMERO or another importer | Create/import the physical OME-Zarr and associate it with OMERO |
| OMERO | Users, groups, permissions, Images, Plates, and provenance |
| BIOMERO OME-Zarr Viewer | Validate access, interpret NGFF metadata, and render the data |
| Nginx | Serve only the files authorized by the viewer |

The viewer can locate a store in either of these ways:

1. the readable OMERO Image has a Fileset/OriginalFile path inside a `.zarr`
   directory; or
2. the Image or its readable Dataset/Plate/Screen ancestry has a structured
   `biomero.import` map annotation containing `UUID`, `Filepath`,
   `DestinationType`, and `Files`.

The BIOMERO importer produces the second form for in-place imports, including
plate imports whose individual OMERO Images are named with NGFF field paths
such as `A/1/0`.

Another importer can therefore be used, but it must provide one of those
links. Its recorded store path must be below `source_root`, and the matching
store must exist below `mount_root`.

### OME-Zarr metadata requirements

BIOMERO provenance tells the viewer where the store is; the actual image,
channel, label, and plate descriptions come from standard OME-NGFF metadata
inside the store.

Supported data:

- OME-Zarr 0.4 with Zarr v2;
- OME-Zarr 0.5 with Zarr v3;
- multiscale images with declared axes and datasets;
- HCS plates with plate, well, acquisition, and field metadata;
- labels declared through the NGFF label group and stored as integer arrays.

Channel names, colors, and display windows are read from NGFF `omero`
metadata when present. Missing or incomplete values receive safe viewer
defaults. The viewer does not repair malformed metadata or generate an
OME-Zarr store from conventional OMERO pixels.

## Viewer features

- one image canvas with pan, mouse-wheel zoom, minimap, scale bar, and
  fullscreen mode;
- channel visibility, color, dual-ended display range, sampled histogram, and
  Auto/Fit/Hist controls;
- middle Z slice by default, T and Z navigation, and MIP, mean, or minimum
  intensity projection across Z;
- multiple independently visible and reordered label layers with 30% default
  opacity, nearest-neighbor sampling, and fill or outline display;
- deterministic GPU label colors without a JavaScript color table
  proportional to the number of label IDs;
- Field, Well, and Plate views with plate-grid navigation and field selection;
- versioned URL state for viewport, planes, projection, channels, labels, and
  the selected field.

The viewer is read-only. It does not provide annotation editing,
OMERO.tables, CSV measurements, expression data, or embedding panels.

## Security model

1. OMERO.web supplies an authenticated OMERO connection and active group.
2. The backend resolves the selected readable Image or Plate to one store.
3. Canonical path checks reject traversal, ambiguous roots, and symlink
   escapes outside the configured mount.
4. The capability endpoint reads only bounded JSON metadata and returns a
   short-lived signed context bound to the OMERO user, group, Image, store,
   and read operation.
5. The frontend attaches that context as `X-OMERO-Zarr-Context`. An expired
   context is refreshed and retried once.
6. Django validates each key and returns `X-Accel-Redirect`; Nginx reads the
   file body.

The URL contains viewer state and an OMERO object ID, but no signed storage
context or filesystem path. Opening the URL still requires a valid OMERO
session and permission to read the selected object.

Optional limits:

```bash
omero config set omero.web.zarr_viewer.context_ttl_seconds 900
omero config set omero.web.zarr_viewer.max_metadata_bytes 4194304
omero config set omero.web.zarr_viewer.max_hierarchy_entries 20000
```

## Development

Install and run the backend tests:

```bash
python -m pip install -e ".[test]"
python -m pytest
```

Run the frontend checks:

```bash
cd frontend
npm ci
npm test
npm run typecheck
npm run build
```

Build and validate a release wheel:

```bash
python scripts/build_frontend.py --skip-install
python -m build --wheel
python scripts/verify_wheel.py dist/<wheel-file>.whl
```

Before a release, run the live compatibility matrix in
[`docs/compatibility-spike.md`](docs/compatibility-spike.md). An authenticated
deployment can be checked with:

```powershell
.\scripts\smoke-test.ps1 `
  -BaseUrl https://omero.example.org `
  -ImageId 123 `
  -Cookie "sessionid=..."
```

## API

All routes are below the standard `/biomero_zarr_viewer/` application mount.

```text
GET /?image=<omero-image-id>
GET /?plate=<omero-plate-id>

GET /api/images/<id>/capabilities/
GET /api/plates/<id>/capabilities/

GET|HEAD /data/images/<id>/<zarr-key>
X-OMERO-Zarr-Context: <signed-context>
```

Unreadable OMERO objects return 404. Unsupported or malformed stores return a
stable JSON error code. Successful data responses have an empty Django body
and contain an `X-Accel-Redirect` for Nginx.

## Relationship to `ome/omero-web-zarr`

[`ome/omero-web-zarr`](https://github.com/ome/omero-web-zarr) presents
conventional OMERO-managed pixels through a virtual OME-Zarr hierarchy. It
reads pixels through OMERO and serializes requested chunks in Python.

This project serves an existing physical OME-Zarr store, including NGFF 0.5,
labels, and HCS metadata. OMERO authorizes access, but Nginx serves the stored
bytes directly. `ome/omero-web-zarr` is therefore complementary rather than a
dependency of this viewer.

## License

GNU Affero General Public License v3.0 or later. See [`LICENSE`](LICENSE).
