Metadata-Version: 2.1
Name: hrm-omero
Version: 0.4.0.dev5
Summary: A connector between the Huygens Remote Manager (HRM) and OMERO.
Home-page: https://pypi.org/project/hrm-omero/
License: GPLv3
Keywords: hrm,huygens,omero,openmicroscopy,ome,deconvolution
Author: Niko Ehrenfeuchter
Author-email: nikolaus.ehrenfeuchter@unibas.ch
Requires-Python: >=3.6.2,<4.0.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: Pillow (>=8.3.2,<9.0.0)
Requires-Dist: beautifulsoup4 (>=4.10.0,<5.0.0)
Requires-Dist: loguru (>=0.5.3,<0.6.0)
Requires-Dist: omero-py (>=5.9.0,<6.0.0)
Project-URL: Documentation, https://imcf.one/apidocs/hrm-omero/hrm_omero.html
Project-URL: Repository, https://github.com/imcf/hrm-omero
Description-Content-Type: text/markdown

# The HRM-OMERO connector

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

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.

## Setup

### Installing requirements

#### CentOS / RHEL 7 and 8

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

# define the target path for the virtual environment:
HRM_OMERO_VENV="/opt/venvs/hrm-omero"

# create a Python 3.6 virtual environment:
python3 -m venv $HRM_OMERO_VENV

# upgrade pip, install wheel:
$HRM_OMERO_VENV/bin/pip install --upgrade pip wheel
```

#### Ubuntu 20.04

```bash
apt install -y python3.8-venv

# define the target path for the virtual environment:
HRM_OMERO_VENV="/opt/venvs/hrm-omero"

# create a Python 3.6 virtual environment:
python3 -m venv $HRM_OMERO_VENV

# upgrade pip, install wheel:
$HRM_OMERO_VENV/bin/pip install --upgrade pip wheel

# install the pre-built Ice wheel from the OME project:
$ICE_WHEEL="zeroc_ice-3.6.5-cp38-cp38-linux_x86_64.whl"
wget "https://github.com/ome/zeroc-ice-ubuntu2004/releases/download/0.2.0/$ICE_WHEEL"
$HRM_OMERO_VENV/bin/pip install $ICE_WHEEL
```

### Installing the HRM-OMERO package

```bash
# install the connector - please note that it takes quite a while (~15min) as it needs
# to build (compile) the ZeroC Ice bindings:
$HRM_OMERO_VENV/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:
$HRM_OMERO_VENV/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 "$HRM_OMERO_VENV/bin/ome-hrm" "ome_hrm.py"
```

### Configuration

Add the following lines to `/etc/hrm.conf` and fill in the desired values:

```bash
# Interaction with OMERO (if switched on in hrm/config).
OMERO_HOSTNAME="omero.example.xy"
# OMERO_PORT="4064"
OMERO_CONNECTOR_LOGLEVEL="DEBUG"
# OMERO_CONNECTOR_LOGFILE_DISABLED="true"
OMERO_USERDIR="/var/cache/omero"
```

## Debugging

The connector will try to place log messages in a file in the location specified as
`$HRM_LOG` in the HRM configuration file **unless** a configuration option named
`$OMERO_CONNECTOR_LOGFILE_DISABLED` is present and non-empty. In a standard setup this
will result in the log file being `/var/log/hrm/omero-connector.log`.

In addtion, log messages produced by the connector when called by HRM will be sent to
`stderr`, which usually means they will end up in the web server's *error log*.

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.

Since this is not useful when being operated through the HRM web interface (which is
the default) it's also possible to set the verbosity level by adjusting the
`OMERO_CONNECTOR_LOGLEVEL` in `/etc/hrm.conf`.

Valid settings are `"SUCCESS"`, `"INFO"`, `"DEBUG"` and `"TRACE"`. If the option is
commented out in the configuration file, the level will be set to `WARNING`.

## Example Usage

Store username and password in variables, export the OMERO_PASSWORD variable:

```bash
read OMERO_USER
read -s OMERO_PASSWORD
export OMERO_PASSWORD   # use 'set --export OMERO_PASSWORD $OMERO_PASSWORD' for fish
```

### Verifying Credentials

```bash
ome-hrm \
    --user $OMERO_USER \
    checkCredentials
```

### Fetching OMERO tree information

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

```bash
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:

```bash
ome-hrm \
    --user $OMERO_USER \
    retrieveChildren \
    --id "$OMERO_ID"
```

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

```json
[
    {
        "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/`:

```bash
ome-hrm \
    --user $OMERO_USER \
    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:

```bash
ome-hrm \
    --user $OMERO_USER \
    HRMtoOMERO \
    --dset "G:4:Dataset:65432" \
    --file test-image.tif
```

[hrm]: https://huygens-rm.org/
[omero]: https://www.openmicroscopy.org/omero/

