# napari-omero
[](https://github.com/tlambert03/napari-omero/raw/main/LICENSE)
[](https://pypi.org/project/napari-omero)
[](https://python.org)
[](https://github.com/tlambert03/napari-omero/actions/workflows/ci.yml)
[](https://codecov.io/gh/tlambert03/napari-omero)
[](https://anaconda.org/conda-forge/napari-omero)
This package provides interoperability between the
[OMERO](https://www.openmicroscopy.org/omero/) image management platform, and
[napari](https://github.com/napari/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.
## Features
- GUI interface to browse remote OMERO data, with thumbnail previews.
- Loads remote nD images from an OMERO server into napari
- Planes are loading on demand as sliders are moved ("lazy loading").
- session management (login memory)
- OMERO rendering settings (contrast limits, colormaps, active channels, current
Z/T position) are applied in napari
### as a napari dock widget
To launch napari with the OMERO browser added, [install](#installation) this
package and run:
```bash
napari-omero
```
The OMERO browser widget can also be manually added to the napari viewer:
```python
import napari
viewer = napari.Viewer()
viewer.window.add_plugin_dock_widget('napari-omero')
napari.run()
```
### as a napari plugin
This package provides a napari reader plugin that accepts OMERO resources as
"proxy strings" (e.g. `omero://Image:<ID>`) or as [OMERO webclient
URLS](https://help.openmicroscopy.org/urls-to-data.html).
```python
viewer = napari.Viewer()
# omero object identifier string
viewer.open("omero://Image:1")
# or URLS: https://help.openmicroscopy.org/urls-to-data.html
viewer.open("http://yourdomain.example.org/omero/webclient/?show=image-314")
```
these will also work on the napari command line interface, e.g.:
```bash
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
```bash
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.10 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
```sh
conda install -c conda-forge napari-omero
```
### from pip
`napari-omero` itself can be installed from pip, but you will still need
`omero-py`
```sh
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](https://github.com/tlambert03/napari-omero/issues/new) 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. Plans for [asynchronous
rendering](https://napari.org/guides/stable/rendering.html) in
napari and
[tiled loading from OMERO](https://github.com/tlambert03/napari-omero/pull/1)
may eventually improve 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`.
## contributing
Contributions are welcome! To get setup with a development environment:
```bash
# 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](https://github.com/astral-sh/ruff),
[mypy](https://github.com/python/mypy).
To enforce code quality when you commit code, you can install pre-commit
```bash
# 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](https://github.com/will-moore).
The napari reader plugin and GUI browser was created by [Talley
Lambert](https://github.com/tlambert03/)
## release
To psuh a release to PyPI, one of the maintainers needs to do, for example:
```sh
git tag -a v0.2.0 -m v0.2.0
git push upstream --follow-tags
```
Then, the workflow should handle everything!
Raw data
{
"_id": null,
"home_page": null,
"name": "napari-omero",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "OMERO.CLI, napari, napari-plugin, plugin",
"author": "Peter Sobolewski",
"author_email": "Talley Lambert <talley.lambert@gmail.com>, Will Moore <w.moore@dundee.ac.uk>, Johannes Soltwedel <johannes_richard.soltwedel@tu-dresden.de>",
"download_url": "https://files.pythonhosted.org/packages/c0/af/d8aefe667128b9b945135b7b22b64d9014ca97ac39400fb4beb9f69f5775/napari_omero-0.3.0.tar.gz",
"platform": null,
"description": "# napari-omero\n\n[](https://github.com/tlambert03/napari-omero/raw/main/LICENSE)\n[](https://pypi.org/project/napari-omero)\n[](https://python.org)\n[](https://github.com/tlambert03/napari-omero/actions/workflows/ci.yml)\n[](https://codecov.io/gh/tlambert03/napari-omero)\n[](https://anaconda.org/conda-forge/napari-omero)\n\nThis package provides interoperability between the\n[OMERO](https://www.openmicroscopy.org/omero/) image management platform, and\n[napari](https://github.com/napari/napari): a fast, multi-dimensional image\nviewer for python.\n\nIt provides a GUI interface for browsing an OMERO instance from within napari,\nas well as command line interface extensions for both OMERO and napari CLIs.\n\n\n\n## Features\n\n- GUI interface to browse remote OMERO data, with thumbnail previews.\n- Loads remote nD images from an OMERO server into napari\n- Planes are loading on demand as sliders are moved (\"lazy loading\").\n- session management (login memory)\n- OMERO rendering settings (contrast limits, colormaps, active channels, current\n Z/T position) are applied in napari\n\n### as a napari dock widget\n\nTo launch napari with the OMERO browser added, [install](#installation) this\npackage and run:\n\n```bash\nnapari-omero\n```\n\nThe OMERO browser widget can also be manually added to the napari viewer:\n\n```python\nimport napari\n\nviewer = napari.Viewer()\nviewer.window.add_plugin_dock_widget('napari-omero')\n\nnapari.run()\n```\n\n### as a napari plugin\n\nThis package provides a napari reader plugin that accepts OMERO resources as\n\"proxy strings\" (e.g. `omero://Image:<ID>`) or as [OMERO webclient\nURLS](https://help.openmicroscopy.org/urls-to-data.html).\n\n```python\nviewer = napari.Viewer()\n\n# omero object identifier string\nviewer.open(\"omero://Image:1\")\n\n# or URLS: https://help.openmicroscopy.org/urls-to-data.html\nviewer.open(\"http://yourdomain.example.org/omero/webclient/?show=image-314\")\n```\n\nthese will also work on the napari command line interface, e.g.:\n\n```bash\nnapari omero://Image:1\n# or\nnapari http://yourdomain.example.org/omero/webclient/?show=image-314\n```\n\n### as an OMERO CLI plugin\n\nThis package also serves as a plugin to the OMERO CLI\n\n```bash\nomero napari view Image:1\n```\n\n- ROIs created in napari can be saved back to OMERO via a \"Save ROIs\" button.\n- napari viewer console has BlitzGateway 'conn' and 'omero_image' in context.\n\n## installation\n\nWhile this package supports anything above python 3.9,\nIn practice, python support is limited by `omero-py` and `zeroc-ice`,\ncompatibility, which is limited to python <=3.10 at the time of writing.\n\n### from conda\n\nIt's easiest to install `omero-py` from conda, so the recommended procedure\nis to install everything from conda, using the `conda-forge` channel\n\n```sh\nconda install -c conda-forge napari-omero\n```\n\n### from pip\n\n`napari-omero` itself can be installed from pip, but you will still need\n`omero-py`\n\n```sh\nconda create -n omero -c conda-forge python=3.10 omero-py\nconda activate omero\npip install napari-omero[all] # the [all] here is the same as `napari[all]`\n```\n\n## issues\n\n| \u2757 | This is alpha software & some things will be broken or sub-optimal! |\n| --- | -------------------------------------------------------------------- |\n\n- experimental & definitely still buggy! [Bug\n reports](https://github.com/tlambert03/napari-omero/issues/new) are welcome!\n- remote loading can be very slow still... though this is not strictly an issue\n of this plugin. Datasets are wrapped as delayed dask stacks, and remote data\n fetching time can be significant. Plans for [asynchronous\n rendering](https://napari.org/guides/stable/rendering.html) in\n napari and\n [tiled loading from OMERO](https://github.com/tlambert03/napari-omero/pull/1)\n may eventually improve the subjective performance... but remote data loading\n will likely always be a limitation here.\n To try asyncronous loading, start the program with `NAPARI_ASYNC=1 napari-omero`.\n\n## contributing\n\nContributions are welcome! To get setup with a development environment:\n\n```bash\n# clone this repo:\ngit clone https://github.com/tlambert03/napari-omero.git\n# change into the new directory\ncd napari-omero\n# create conda environment\nconda env create -n napari-omero python=3.10 omero-py\n# activate the new env\nconda activate napari-omero\n\n# install in editable mode with dev dependencies\npip install -e \".[dev]\" # quotes are needed on zsh\n```\n\nTo maintain good code quality, this repo uses\n[ruff](https://github.com/astral-sh/ruff),\n[mypy](https://github.com/python/mypy).\n\nTo enforce code quality when you commit code, you can install pre-commit\n\n```bash\n# install pre-commit which will run code checks prior to commits\npre-commit install\n```\n\nThe original OMERO data loader and CLI extension was created by [Will\nMoore](https://github.com/will-moore).\n\nThe napari reader plugin and GUI browser was created by [Talley\nLambert](https://github.com/tlambert03/)\n\n## release\n\nTo psuh a release to PyPI, one of the maintainers needs to do, for example:\n```sh\ngit tag -a v0.2.0 -m v0.2.0\ngit push upstream --follow-tags\n```\nThen, the workflow should handle everything!\n",
"bugtrack_url": null,
"license": "GPL-2.0-or-later",
"summary": "napari/OMERO interoperability",
"version": "0.3.0",
"project_urls": {
"homepage": "https://github.com/tlambert03/napari-omero",
"repository": "https://github.com/tlambert03/napari-omero"
},
"split_keywords": [
"omero.cli",
" napari",
" napari-plugin",
" plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2f4bad2cf2e3bf7f3053acb30d5539c207f0c8a12e83330536c428ebabe3e2e2",
"md5": "158ad68480433c58b131be809627e8b9",
"sha256": "8497049affb04331bdf8bfff4b437aaae96ce32825d88309195b2478de5ae11c"
},
"downloads": -1,
"filename": "napari_omero-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "158ad68480433c58b131be809627e8b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 27911,
"upload_time": "2025-01-08T15:08:35",
"upload_time_iso_8601": "2025-01-08T15:08:35.709277Z",
"url": "https://files.pythonhosted.org/packages/2f/4b/ad2cf2e3bf7f3053acb30d5539c207f0c8a12e83330536c428ebabe3e2e2/napari_omero-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c0afd8aefe667128b9b945135b7b22b64d9014ca97ac39400fb4beb9f69f5775",
"md5": "f951730f92a01e49be2b5c2072c4f3d5",
"sha256": "c1650718c1923984f4df510dccb35d3d4ee80c8bfe28f61b3806460f0dbbffe8"
},
"downloads": -1,
"filename": "napari_omero-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "f951730f92a01e49be2b5c2072c4f3d5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 10224452,
"upload_time": "2025-01-08T15:08:39",
"upload_time_iso_8601": "2025-01-08T15:08:39.586268Z",
"url": "https://files.pythonhosted.org/packages/c0/af/d8aefe667128b9b945135b7b22b64d9014ca97ac39400fb4beb9f69f5775/napari_omero-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-08 15:08:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tlambert03",
"github_project": "napari-omero",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "napari-omero"
}
JSON
