OHIF plugin

Contents

• OHIF plugin

  • Orthanc project vs. OHIF project

  • Usage

  • Compilation

  • Configuration

    • Using DICOMweb

    • User configuration of OHIF

    • Router basename

    • Preloading

    • HTTPS encryption

  • For developers

    • Extensions to the REST API

    • Preloading existing studies

This official plugin by the ICTEAM institute of UCLouvain extends Orthanc with the OHIF extensible Web imaging platform.

The plugin greatly simplifies the deployment of OHIF, as it does not necessitate the setup of any reverse proxy.

If you face difficulties in using OHIF, please get in touch with the OHIF community in the first place. Indeed, the OHIF and Orthanc communities are entirely distinct.

For researchers: Please cite this paper.

Orthanc project vs. OHIF project

The Orthanc server and the OHIF viewer are fully separate projects, with distinct communities. The OHIF plugin for Orthanc only aims at facilitating the deployment of OHIF through Orthanc.

As a consequence, the OHIF plugin for Orthanc only packages official releases of OHIF.

Furthermore, any question or issue that is related to OHIF must be directly asked to the OHIF community, not to the Orthanc discussion group.

Usage

This plugin adds a dedicated button to Orthanc Explorer, which provides an easy, fast access to the OHIF viewers (click on the image to view a demo video):

Compilation

Official releases can be downloaded from the Orthanc homepage. As an alternative, the repository containing the source code can be accessed using Mercurial.

The procedure to compile this plugin is similar of that for the core of Orthanc. The following commands should work on most GNU/Linux distributions, provided Docker is installed:

$ mkdir Build
$ cd Build
$ ../Resources/CreateOHIFDist.sh
$ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
$ make

The compilation will produce a shared library libOrthancOHIF.so that contains the OHIF plugin for Orthanc.

Pre-compiled Linux Standard Base (LSB) binaries are available for download.

Pre-compiled binaries for Microsoft Windows and macOS are available as well.

Furthermore, the Docker images jodogne/orthanc-plugins and orthancteam/orthanc also contain the plugin. Debian and Ubuntu packages can be found in the standalone repository https://debian.orthanc-labs.com/.

Configuration

Here is a minimal sample configuration file to use this plugin:

{
  "Plugins" : [
    "/home/user/orthanc-ohif/Build/libOrthancOHIF.so"
  ]
}

Orthanc must of course be restarted after the modification of its configuration file.

Using DICOMweb

By default, the plugin uses the DICOM JSON data source of OHIF. This data source is optimized to provide the fastest access to the DICOM images, while requiring no additional plugin. However, in order to deliver fast access, the OHIF plugin will cache additional information about each DICOM instance as metadata in the Orthanc database, which results in a larger size of the Orthanc database (an additional 1KB is roughly needed per instance).

As an alternative, it is possible to enable the DICOMweb data source. In this case, the DICOMweb plugin of Orthanc must also be loaded. It can also be useful to load the GDCM plugin if the DICOM images are encoded using a JPEG2k compressed transfer syntax.

The advantages of using DICOMweb over the default DICOM JSON are:

• More standard-compliant.

• More robust (e.g. this issue only happens with the json data source)

• The OHIF study list is accessible, notably as a button on the welcome screen of Orthanc Explorer. The study list is not available if using the DICOM JSON data source.

• No additional space is used in the Orthanc database.

Here is a minimal configuration file to use DICOMweb:

{
  "Plugins" : [
    "/home/user/orthanc-ohif/Build/libOrthancOHIF.so",
    "/home/user/orthanc-dicomweb/Build/libOrthancDicomWeb.so"
  ],
  "OHIF" : {
    "DataSource" : "dicom-web"
  }
}

User configuration of OHIF

OHIF comes with a number of configuration options that can be fine-tuned by the user. User settings can be injected using the UserConfiguration option as follows:

{
  "Plugins" : [
    "/home/user/orthanc-ohif/Build/libOrthancOHIF.so"
  ],
  "OHIF" : {
    "UserConfiguration" : "ohif.js"
  }
}

A minimal ohif.js would be:

window.config = {
  extensions: [],
  modes: []
}

Note that the following configuration options will be overridden by the OHIF plugin to properly configure the data source and the integration with the Orthanc Web server:

• window.config.dataSources

• window.config.defaultDataSourceName

• window.config.routerBasename

• window.config.showStudyList (set to false if using the DICOM JSON data source)

Router basename

If Orthanc is not branched at the root of a Web server thanks of the presence of a reverse proxy, the configuration option RouterBasename must be adapted.

For instance, if Orthanc is running at address https://host.com/imaging/demo/orthanc/, the following configuration file must be used for OHIF to work:

{
  "Plugins" : [
    "/home/user/orthanc-ohif/Build/libOrthancOHIF.so"
  ],
  "OHIF" : {
    "RouterBasename" : "/imaging/demo/orthanc/ohif/"
  }
}

The default value of RouterBasename is /ohif/.

Preloading

If using the DICOM JSON data source, whenever a new DICOM instance is received by Orthanc, the OHIF plugin will compute a summary of the DICOM tags of interest to OHIF, and will store it as metadata in the Orthanc database. This process has the advantage of speeding up even the first opening of the DICOM study by OHIF, which probably corresponds to the expectations of most radiologists.

However, if your Orthanc deployment is focused on speed, this preloading might be undesirable, as it slows down the ingestion of new DICOM instances by Orthanc. Furthermore, if your Orthanc server will contain a large number of DICOM studies that will never be displayed using OHIF, this can result in a waste of space in the Orthanc database because of the metadata that will be preloaded, but that will never be read.

It is consequently possible to turn off the automated preloading of metadata using the following configuration:

{
  "Plugins" : [
    "/home/user/orthanc-ohif/Build/libOrthancOHIF.so"
  ],
  "OHIF" : {
    "DataSource" : "dicom-json",
    "Preload" : false
  }
}

If the Preload option is set to false, the first display of a DICOM study can take several seconds because of the computation of the metadata, but subsequent displays will run much faster.

Note that preloading is only applied to the newly received instances: The DICOM instances that were stored in the Orthanc server before the installation of the OHIF plugin will only benefit from the optimization starting with their second display using OHIF.

HTTPS encryption

In order to use the built-in HTTPS encryption of Orthanc together with the OHIF plugin, first generate a proper X.509 certificate for the localhost:

$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
          -subj "/C=BE/CN=localhost" -keyout /tmp/private.key -out /tmp/certificate.crt
$ cat /tmp/private.key /tmp/certificate.crt > /tmp/certificate.pem

Secondly, create the following configuration file:

{
  "Plugins" : [
    "/home/user/orthanc-ohif/Build/libOrthancOHIF.so"
  ],
  "SslEnabled" : true,
  "SslCertificate" : "/tmp/certificate.pem",
  "OHIF" : {
    "DataSource" : "dicom-json",
    "RouterBasename" : "/ohif/"
  }
}

If more complex scenarios with reverse proxies are involved, make sure to properly setup CORS in your reverse proxy and to adapt the router basename. If you face difficulties, while the simple setup with the built-in HTTPS encryption described above works, your issue is related to OHIF, so please get in touch with the OHIF community.

For developers

Extensions to the REST API

The content of the DICOM JSON data source for a DICOM study of interest can be retrieved as follows:

$ curl https://orthanc.uclouvain.be/demo/studies/6b9e19d9-62094390-5f9ddb01-4a191ae7-9766b715/ohif-dicom-json

This data source is constructed from the metadata 4202 associated with the individual DICOM instances of the DICOM study. The metadata corresponds to the Base64 encoding of a gzipped JSON file. For debugging, the JSON file associated with a DICOM instance can be inspected using:

$ curl https://orthanc.uclouvain.be/demo/instances/1f3c00bd-49df10b7-f416a598-1b3bb5a2-cb791b52/metadata/4202 | base64 -d | gunzip -c

Preloading existing studies

As explained above, the metadata associated with DICOM instances are only preloaded for the newly ingested DICOM instances. Using the REST API of Orthanc, it is easy to create a script that would preload the metadata for the already existing DICOM studies, hereby greatly speeding up the first opening of those studies as well.

This script would loop over the the DICOM studies that are stored by Orthanc using GET /studies. For each study whose Orthanc identifier is id, the script would simply call GET /studies/{id}/ohif-dicom-json.