Installation¶
OMERO 5.4.x/5.6.x¶
Set up access to the Glencoe Software provided PathViewer PyPI compatible repository for use with pip. This repository acts as both a PyPI cache and datastore for PathViewer packages. An example $HOME/.pip/pip.conf follows:
[global] index-url = https://username:password@repo.glencoesoftware.com/repository/pathviewer-group/simple trusted-host = repo.glencoesoftware.com [search] index = https://username:password@repo.glencoesoftware.com/repository/pathviewer-group/pypi
Note
Credentials to access this repository are available from Glencoe Software customer support and are tied to your active Software Maintenance Agreement.
With your OMERO virtualenv activated, or sufficient permissions, install the PathViewer:
pip install -U pathviewer
Enable the PathViewer OMERO.web plugin:
omero config append omero.web.apps '"pathviewer"' # Option 1: configure PathViewer as the default, with an optional secondary viewer # to be used for untiled images instead of the built-in image viewer: omero config set omero.web.viewer.view \ pathviewer.views.viewer_redirect # optionally: omero config set omero.web.pathviewer.untiled_viewer.view \ omeroweb.webclient.views.image_viewer # Option 2: configure PathViewer for all images, tiled or not: omero config set omero.web.viewer.view \ pathviewer.views.viewer_always
Enable the right-click menu plugins:
omero pathviewer install menu
Install the export view script:
Option 1, script import with available admin user:
install_dir="`python -c 'import pathviewer as p;print(p.__path__[0])'`" ( cd ${install_dir}/scripts && omero script upload --official PathViewer/Export_View.py ) ( cd ${install_dir}/scripts && omero script upload --official PathViewer/Export_Capabilities.py )
Option 2, direct placement if no admin user is available:
install_dir="`python -c 'import pathviewer as p;print(p.__path__[0])'`" ln -s ${install_dir}/scripts/PathViewer -t $OMERODIR/lib/scripts
Add a static file stanza to your web server configuration:
# For nginx; same path as your existing /static location ... location /pathviewer/viewer/static { alias /same/path/OMERO.web/var/static; } ...
# For Apache; same path as your existing /static alias ... Alias /pathviewer/viewer/static /same/path/OMERO.web/var/static ...
Add custom logo, favicon, JavaScript and CSS stylesheet:
# Custom logo, should be 150x40 pixels omero config set omero.web.pathviewer.logo \ '//full/url/to/custom/logo.png' # Custom favicon, should be 32x32 pixels omero config set omero.web.pathviewer.favicon \ '//full/url/to/custom/favicon.png' # Custom JavaScript, loaded after all built-in scripts omero config set omero.web.pathviewer.js \ '//full/url/to/custom/javascript.js' # Custom CSS stylesheet, loaded after all built-in stylesheets omero config set omero.web.pathviewer.css \ '//full/url/to/custom/stylesheet.css'
Note: It is recommended not to specify a scheme (“http” or “https”) to allow the browser to load the files using the same scheme as the application. It is also possible to use relative references (“/absolute/path/to/file” or “relative/path/to/file”) if the files are placed on the application server.
Example: if a file ‘logo.png’ is placed in the static directory referred to in the previous section, the URL to configure is ‘/pathviewer/viewer/static/logo.png’ (absolute path) or ‘static/logo.png’ (relative path).
Optionally configure keepalive frequency
# Custom keepalive frequency, in milliseconds omero config set omero.web.pathviewer.keepalive 60000
Optionally configure channel toolbar
The channel toolbar is only enabled for images with at most 8 channels by default. To allow for more or fewer channels, set the maximum number:
# Custom maximum number of image channels for enabled channel toolbar omero config set omero.web.pathviewer.toolbar_max_channels 6
Optionally install poppler-utils package
For full functionality of the export script, the program pdftoppm is recommended. It can be found in the poppler-utils package; installation is dependent on your operating system and package manager.
Restart OMERO.web:
omero web restart
Upgrading¶
PathViewer 3.3.5+¶
PathViewer versions 3.3.0 to 3.3.4 may have created invalid shape annotations in the database. A new maintenance command can be used to find and correct these annotations.
omero pathviewer maint fix_shape_annotations
PathViewer 2.1+¶
PathViewer 3.1.0 fixes an issue with right-click menu plugins. Use the following script to remove existing right-click menu plugins when upgrading, then follow the installation instructions to re-install the new right-click menu plugins:
VAL=`omero config get omero.web.open_with | python -c 'import sys,json;print(json.dumps( [x for x in json.loads(sys.stdin.read()) if x[1]!="/pathviewer"]))'` omero config set omero.web.open_with "$VAL"
PathViewer 1.0.5+¶
From PathViewer 1.0.5 upgrades are handled via pip and a PathViewer PyPI compatible repository. You can check which version of the PathViewer you currently have installed as follows:
$ pip list importlib (1.0.4) omero-marshal (0.3.0) pathviewer (1.0.5) pip (9.0.1) setuptools (28.8.0) wheel (0.30.0a0)
Performing an upgrade is then as simple as:
pip install -U pathviewer
Please check the above instructions for the installations of new plugins and scripts.
PathViewer <= 1.0.4¶
If you currently have PathViewer 1.0.4 or earlier installed you will have done so via a precompiled .egg package applying to your particular Python version. From PathViewer 1.0.5, installation and upgrade is handled via pip and a PathViewer PyPI compatible repository. You can check which version of the PathViewer you currently have installed as follows:
$ pip list importlib (1.0.4) omero-marshal (0.3.0) pathviewer (1.0.4) pip (8.1.2) setuptools (28.6.1) wheel (0.30.0a0)
In order to utilize the new installation method you will first need to uninstall both the pathviewer and omero-marshal packages. An exception traceback during uninstallation of omero-marshal is possible but is safe to ignore. An example follows:
$ pip uninstall pathviewer Uninstalling pathviewer-1.0.4: /home/example/my-virtualenv/lib/python2.7/site-packages/pathviewer-1.0.4-py2.7.egg Proceed (y/n)? y Successfully uninstalled pathviewer-1.0.4 $ pip uninstall omero-marshal Uninstalling omero-marshal-0.3.0: /home/example/my-virtualenv/lib/python2.7/site-packages/omero_marshal-0.3.0-py2.7.egg Proceed (y/n)? y Successfully uninstalled omero-marshal-0.3.0 Traceback (most recent call last): File "/home/example/my-virtualenv/bin/pip", line 11, in <module> sys.exit(main()) File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/__init__.py", line 221, in main return command.main(cmd_args) File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/basecommand.py", line 252, in main pip_version_check(session) File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/utils/outdated.py", line 102, in pip_version_check installed_version = get_installed_version("pip") File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/utils/__init__.py", line 848, in get_installed_version working_set = pkg_resources.WorkingSet() File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/_vendor/pkg_resources/__init__.py", line 619, in __init__ self.add_entry(entry) File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/_vendor/pkg_resources/__init__.py", line 675, in add_entry for dist in find_distributions(entry, True): File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/_vendor/pkg_resources/__init__.py", line 1942, in find_eggs_in_zip if metadata.has_metadata('PKG-INFO'): File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/_vendor/pkg_resources/__init__.py", line 1463, in has_metadata return self.egg_info and self._has(self._fn(self.egg_info, name)) File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/_vendor/pkg_resources/__init__.py", line 1824, in _has return zip_path in self.zipinfo or zip_path in self._index() File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/_vendor/pkg_resources/__init__.py", line 1704, in zipinfo return self._zip_manifests.load(self.loader.archive) File "/home/example/my-virtualenv/local/lib/python2.7/site-packages/pip/_vendor/pkg_resources/__init__.py", line 1644, in load mtime = os.stat(path).st_mtime OSError: [Errno 2] No such file or directory: '/home/example/my-virtualenv/lib/python2.7/site-packages/omero_marshal-0.3.0-py2.7.egg' $ pip uninstall omero-marshal Cannot uninstall requirement omero-marshal, not installedNote
It is essential that pip uninstall omero-marshal be run twice to ensure that the package is completely removed from your Python installation. See the warning below for more details on how to confirm this.
You can then follow the installation procedure as outlined in OMERO 5.4.x/5.6.x as required to complete your upgrade.
Warning
You must ensure that no pathviewer or omero-marshal packages are present in your site-packages before proceeding with the installation of a new PathViewer version via pip. This can be performed as follows:
$ pip list importlib (1.0.4) pip (8.1.2) setuptools (28.6.1) wheel (0.30.0a0) $ ls -l ~/my-virtualenv/lib/python2.7/site-packages/ total 44 -rw-rw-r-- 1 example example 28 Oct 26 13:22 easy-install.pth -rw-rw-r-- 1 example example 126 Oct 26 13:04 easy_install.py -rw-rw-r-- 1 example example 315 Oct 26 13:04 easy_install.pyc -rw-rw-r-- 1 example example 1483 Oct 26 13:06 importlib-1.0.4-py2.7.egg drwxrwxr-x 10 example example 4096 Oct 26 13:04 pip drwxrwxr-x 2 example example 4096 Oct 26 13:04 pip-8.1.2.dist-info drwxrwxr-x 4 example example 4096 Oct 26 13:04 pkg_resources drwxrwxr-x 4 example example 4096 Oct 26 13:04 setuptools drwxrwxr-x 2 example example 4096 Oct 26 13:04 setuptools-28.6.1.dist-info drwxrwxr-x 5 example example 4096 Oct 26 13:04 wheel drwxrwxr-x 2 example example 4096 Oct 26 13:04 wheel-0.30.0a0.dist-infoNo references to either package should be visible in the output of these two commands.
