Skip to main content

napari/OMERO interoperability

Project description

napari-omero

License PyPI Python Version CI codecov conda-forge

This package provides interoperability between the OMERO image management platform, and napari: a fast, multi-dimensional image viewer for python.

It provides a GUI interface for browsing an OMERO instance from within napari, as well as command line interface extensions for both OMERO and napari CLIs.

demo

Features

  • GUI interface to browse remote OMERO data, with thumbnail previews.
  • Loads remote nD images from an OMERO server into napari
  • Upload annotsations (``Labels, Shapes` and `Points`) to OMERO.
  • Planes are loading on demand as sliders are moved ("lazy loading").
  • Loading of pyramidal images as napari multiscale layers
  • session management (login memory)
  • OMERO rendering settings (contrast limits, colormaps, active channels, current Z/T position) are applied in napari

[!NOTE] The user experience when working with remote images, particularly large multiscale (pyramidal) ones, like whole slide images, can be significantly improved by using napari 0.5.0 or newer and enabling the experimental asynchronous mode (n the GUI in Preferences > Experimental > Render Images Asynchronously or with the environmental variable NAPARI_ASYNC=1).

as a napari dock widget

To launch napari with the OMERO browser added, install this package and run:

napari-omero

The OMERO browser widget can also be manually added to the napari viewer using the Plugins menu or programmatically using:

import napari

viewer = napari.Viewer()
viewer.window.add_plugin_dock_widget('napari-omero')

napari.run()

as a napari reader contribution

This package provides a napari reader contribution that accepts OMERO resources as "proxy strings" (e.g. omero://Image:<ID>) or as OMERO webclient URLS.

import napari
viewer = napari.Viewer()

# omero object identifier string
viewer.open("omero://Image:1", plugin="napari-omero")

# or URLS: https://help.openmicroscopy.org/urls-to-data.html
viewer.open("http://yourdomain.example.org/omero/webclient/?show=image-314", plugin="napari-omero")

these will also work on the napari command line interface, e.g.:

# quotes are needed if using zsh
napari "omero://Image:1"
# or
napari "http://yourdomain.example.org/omero/webclient/?show=image-314"

as an OMERO CLI plugin

This package also serves as a plugin to the OMERO CLI

omero napari view Image:1
  • ROIs created in napari can be saved back to OMERO via a "Save ROIs" button.
  • napari viewer console has BlitzGateway 'conn' and 'omero_image' in context.

installation

While this package supports anything above python 3.9, In practice, python support is limited by omero-py and zeroc-ice, compatibility, which is limited to python <=3.12 at the time of writing.

from conda

It's easiest to install omero-py from conda, so the recommended procedure is to install everything from conda, using the conda-forge channel. For example, to install the plugin, napari, and the default Qt backend, use:

conda install -c conda-forge napari-omero pyqt

from pip

napari-omero itself can be installed from pip, but you will still need omero-py

conda create -n omero -c conda-forge python=3.10 omero-py
conda activate omero
pip install napari-omero[all]  # the [all] here is the same as `napari[all]`

issues

This is alpha software & some things will be broken or sub-optimal!
  • experimental & definitely still buggy! Bug reports are welcome!
  • remote loading can be very slow still... though this is not strictly an issue of this plugin. Datasets are wrapped as delayed dask stacks, and remote data fetching time can be significant. Enabling asynchronous rendering in napari improves the subjective performance... but remote data loading will likely always be a limitation here. To try asyncronous loading, start the program with NAPARI_ASYNC=1 napari-omero or look in the Preferences on the Experimental tab. Also, keep an eye on the napari progressive loading implementation progress.
  • For plugin developers: As napari-OMERO provides images as lazily-loaded dask arrays, napari-plugins need to account for this when retrieving data from napari layers. Keep in mind that forwarding the data to processing steps in plugins may lead to signficant loading and processing times.

contributing

Contributions are welcome! To get setup with a development environment:

# clone this repo:
git clone https://github.com/tlambert03/napari-omero.git
# change into the new directory
cd napari-omero
# create conda environment
conda env create -n napari-omero python=3.10 omero-py
# activate the new env
conda activate napari-omero

# install in editable mode with dev dependencies
pip install -e ".[dev]"      # quotes are needed on zsh

To maintain good code quality, this repo uses ruff, mypy.

To enforce code quality when you commit code, you can install pre-commit

# install pre-commit which will run code checks prior to commits
pre-commit install

The original OMERO data loader and CLI extension was created by Will Moore.

The napari reader plugin and GUI browser was created by Talley Lambert

release

To psuh a release to PyPI, one of the maintainers needs to do, for example:

git tag -a v0.2.0 -m v0.2.0
git push upstream --follow-tags

Then, the workflow should handle everything!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

napari_omero-0.5.1.tar.gz (10.2 MB view details)

Uploaded Source

Built Distribution

napari_omero-0.5.1-py3-none-any.whl (30.4 kB view details)

Uploaded Python 3

File details

Details for the file napari_omero-0.5.1.tar.gz.

File metadata

  • Download URL: napari_omero-0.5.1.tar.gz
  • Upload date:
  • Size: 10.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for napari_omero-0.5.1.tar.gz
Algorithm Hash digest
SHA256 b06e00577371588e7dd21e35e221f37800b36da6f062fe9316544986923ef6df
MD5 f3e41967ab34f398d8c8e82034e38e70
BLAKE2b-256 1500728bc22a3d4bb3f4744170310091c1339b04968a98ee0946f84f331cabbb

See more details on using hashes here.

Provenance

The following attestation bundles were made for napari_omero-0.5.1.tar.gz:

Publisher: ci.yml on tlambert03/napari-omero

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file napari_omero-0.5.1-py3-none-any.whl.

File metadata

  • Download URL: napari_omero-0.5.1-py3-none-any.whl
  • Upload date:
  • Size: 30.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for napari_omero-0.5.1-py3-none-any.whl
Algorithm Hash digest
SHA256 95714a793dee58fa331993ce03db42856e1dc119200a445ed67661001cbdeb2c
MD5 68e1d46fcf96e2c4e104bf583c61e04d
BLAKE2b-256 5537cef120875a9680619ed7f59e35a25a26301c3804c9ee1ac03c740a3afbbb

See more details on using hashes here.

Provenance

The following attestation bundles were made for napari_omero-0.5.1-py3-none-any.whl:

Publisher: ci.yml on tlambert03/napari-omero

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page