hrm-omero 0.3.1

A connector between the Huygens Remote Manager (HRM) and OMERO.

The HRM-OMERO connector

This project provides a connector to allow for communication between an HRM (Huygens Remote Manager) and an OMERO server.

Its purpose is to simplify the data transfer by allowing raw images to be downloaded from OMERO as well as uploading deconvolution results back to OMERO directly from within the HRM web interface.

Installation

Distributions that include Python 3.6 or newer (e.g. Ubuntu 20.04)

pip install hrm-omero

CentOS 6

CentOS 6 is EOL since 2020-11-30, so you should really consider upgrading to a newer release. However, we know that sometimes this is not easily doable due to dependencies, hardware support or whatever reason - so here are instructions to make the connector work on that old distribution.

It's strongly recommended to use pyenv for installing Python 3.6, which is the absolute minimum for using the HRM-OMERO connector (or its actual dependencies, to be fully correct). In case you don't want pyenv to mess with your system setup, you can simply ask it to install that version somewhere and then only create a virtual environment from it using the --copies flag - this will result in a standalone setup that won't affect anything else on the system.

# install the build-time requirements for Python 3.6 and Java 1.8 for Bio-Formats
sudo yum install openssl-devel readline-devel gcc-c++ java-1.8.0-openjdk

# get pyenv and put it into your home directory or wherever you prefer it to be
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

# activate pyenv *FOR THIS SHELL ONLY* (needs to be done whenever you want to use it)
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

# ask pyenv to install Python 3.6.15 (will end up in "~/.pyenv/versions/3.6.15/")
pyenv install 3.6.15  # takes a bit (compiling...)

# create a bare, stand-alone Python 3.6 virtual environment
~/.pyenv/versions/3.6.15/bin/python -m venv --copies /opt/venvs/hrm-omero

# now you can install the connector into this virtual environment - please note that the
# installation takes quite a while (~15min) as it needs to build the ZeroC Ice bindings
/opt/venvs/hrm-omero/bin/pip install hrm-omero

# from now on you can simply call the connector using its full path, there is no need
# to pre-activate the virtual environment - you could even drop your pyenv completely:
/opt/venvs/hrm-omero/bin/ome-hrm --help

# this is even usable as a drop-in replacement for the legacy `ome_hrm.py` script:
cd $PATH_TO_YOUR_HRM_INSTALLATION/bin
mv "ome_hrm.py" "__old__ome_hrm.py"
ln -s "/opt/venvs/hrm-omero/bin/ome-hrm" "ome_hrm.py"

Debugging

By default the connector will be rather silent as otherwise the log files will be cluttered up quite a bit on a production system. However, it is possible to increase the log level by specifying -v, -vv and so on.

Currently it is not yet possible to ajust the log level that is being used when operated through the HRM web interface (which is the default). To do so, have a look in the hrm_omero.cli.run_task() function. Log messages produced by the connector when called by HRM will usually end up in the web server's error log (as they go to stderr).

Example Usage

Store you username and password in variables:

read OMEROUSER
read OMEROPW

Verifying Credentials

ome-hrm \
    --user $OMEROUSER \
    --password $OMEROPW \
    checkCredentials

Fetching OMERO tree information

Set the --id parameter according to what part of the tree should be retrieved:

OMERO_ID="ROOT"                # fetches the base tree view for the current user
OMERO_ID="G:4:Experimenter:9"  # fetches the projects of user '9' in group '4'
OMERO_ID="G:4:Project:12345"   # fetches the datasets of project '12345'
OMERO_ID="G:4:Dataset:65432"   # lists the images of dataset '65432'

Then run the actual command to fetch the information, the result will be a JSON tree:

ome-hrm \
    --user $OMEROUSER \
    --password $OMEROPW \
    retrieveChildren \
    --id "$OMERO_ID"

For example this could be the output when requesting "G:4:Dataset:65432":

[
    {
        "children": [],
        "class": "Image",
        "id": "G:4:Image:1311448",
        "label": "4321_mko_ctx_77.tif",
        "owner": "somebody"
    },
    {
        "children": [],
        "class": "Image",
        "id": "G:4:Image:1566150",
        "label": "test-image.tif",
        "owner": "somebody"
    }
]

Downloading an image from OMERO

This will fetch the second image from the example tree above and store it in /tmp/:

ome-hrm \
    --user $OMEROUSER \
    --password $OMEROPW \
    OMEROtoHRM \
    --imageid "G:4:Image:1566150" \
    --dest /tmp/

Uploading an image from the local file system to OMERO

The command below will import a local image file into the example dataset from above:

ome-hrm \
    --user $OMEROUSER \
    --password $OMEROPW \
    HRMtoOMERO \
    --dset "G:4:Dataset:65432" \
    --file test-image.tif