DICOMweb plugin

This official plugin extends Orthanc with support of the DICOMweb protocols. More precisely, the plugin introduces a basic, reference implementation of WADO-URI, WADO-RS, QIDO-RS and STOW-RS, following DICOM PS3.18. The plugin simultaneously turns Orthanc into a DICOMweb server and into a DICOMweb client.

For general information, check out the official homepage of the plugins.

The full standard is not implemented yet, the supported features are tracked in the repository.

Compilation

The procedure to compile this plugin is similar of that for the core of Orthanc. The following commands should work for most UNIX-like distribution (including GNU/Linux):

$ mkdir Build
$ cd Build
$ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
$ make

The compilation will produce a shared library OrthancDicomWeb that contains the DICOMweb plugin. Pre-compiled binaries for Microsoft Windows are also available, and are included in the Windows installers. A package for Apple’s Mac OS X is available courtesy of Orthanc Team.

Remark: Some older build instructions are also available in the source distribution.

Installation

You of course first have to install Orthanc. Once Orthanc is installed, you must change the configuration file to tell Orthanc where it can find the plugin: This is done by properly modifying the Plugins option. For GNU/Linux, you could for instance use the following configuration file:

{
  "Name" : "MyOrthanc",
  [...]
  "Plugins" : [
    "/home/user/OrthancDicomWeb/Build/libOrthancDicomWeb.so"
  ]
}

Or, for Windows:

{
  "Name" : "MyOrthanc",
  [...]
  "Plugins" : [
    "c:/Temp/OrthancDicomWeb.dll"
  ]
}

Note that the DICOMweb server will share all the parameters of the Orthanc HTTP server, notably wrt. authentication and HTTPS encryption. For this reason, you will most probably have to enable the remote access to the Orthanc HTTP server:

{
  [...]
  "RemoteAccessAllowed" : true,
  [...]
}

Once Orthanc has restarted, the root of the DICOMweb REST API is accessible at http://localhost:8042/dicom-web/.

Options

Fine-tuning server for WADO-RS Retrieve Metadata

The options StudiesMetadata and SeriesMetadata were introduced in release 1.1 of the DICOMweb plugin. These options specify how the calls to /dicom-web/studies/.../metadata and /dicom-web/studies/.../series/.../metadata (i.e. WADO-RS Retrieve Metadata) are processed:

  • If Full mode is used, the plugin will read all the DICOM instances of the study/series of interest from the storage area, which gives fully accurate results but requires all the individual instances to be read and parsed from the filesystem, leading to slow performance for earliers version of the plugin. From version 1.15 of the plugin in which we have introduced caching, this mode is the most accurate and fastest one provided that you have run the Housekeeper plugin on data ingested with prior versions of the plugin - otherwise, the first access to the route might still be slow to populate the cache while later accesses will be much faster.

  • Starting from version 1.15 of the plugin and provided that the cache has been populated for all prior studies, you should favor the Full mode. The following recommandations are kept for prior version of the plugin only.

  • The metadata caching can be disabled by setting EnableMetadataCache to false.

  • If MainDicomTags mode is used, the plugin will only report the main DICOM tags that are indexed by the Orthanc database. The DICOM files are not read from the disk, which provides good performance. However, this is a small subset of all the tags that would be retrieved if using the Full mode: A DICOMweb viewer might need more tags. Important Note: From Orthanc 1.11.0 and DICOMweb plugin 1.8, you may store more MainDicomTags in DB. By correctly setting these tags, the MainDicomTags mode can become faster than the Extrapolate mode with the same accuracy as the Full mode. Note that, if the ExtraMainDicomTags are not set correctly or have not been collected on all instances, the Stone Web viewer will not work correctly.

  • If Extrapolate mode is used, the plugin will read up to 3 DICOM instances at random that belong to the study/series of interest. It will then test whether the majority of these instances share the same value for a predefined subset of DICOM tags. If so, this value is added to the metadata response; otherwise, the tag is not reported. In other words, this mode extrapolates the value of some predefined tags by assuming that these tags should be constant across all the instances of the study/series. This mode is a compromise between MainDicomTags (focus on speed) and Full (focus on accuracy).

  • If you are using a DICOMweb viewer (such as Stone Web viewer or OHIF viewer) in a setup where performance and accuracy are both important, you should configure ExtraMainDicomTags and configure StudiesMetadata to MainDicomTags and SeriesMetadata to MainDicomTags as demonstrated in this sample.

  • If using the Extrapolate mode, the predefined tags are provided using the StudiesMetadataExtrapolatedTags and SeriesMetadataExtrapolatedTags configuration options as follows

Sample configuration for the Extrapoate mode:

{
  [...]
  "DicomWeb" : {
    [...]
    "StudiesMetadata" : "Extrapolate",
    "StudiesMetadataExtrapolatedTags" : [
      "AcquisitionDate"
    ],
    "SeriesMetadata" : "Extrapolate",
    "SeriesMetadataExtrapolatedTags" : [
      "BitsAllocated",
      "BitsStored",
      "Columns",
      "HighBit",
      "PhotometricInterpretation",
      "PixelSpacing",
      "PlanarConfiguration",
      "RescaleIntercept",
      "RescaleSlope",
      "Rows",
      "SOPClassUID",
      "SamplesPerPixel",
      "SliceThickness"
    ]
  }
}

Quickstart - DICOMweb client

Starting with version 1.0 of the DICOMweb plugin, a Web interface is provided to use Orthanc as a DICOMweb client. Simply click on the “Open DICOMweb client” button at the bottom of the welcome screen of Orthanc Explorer.

Here is a direct link to the DICOMweb client running on our demo server: https://orthanc.uclouvain.be/demo/dicom-web/app/client/index.html

Quickstart - DICOMweb server

Once your Orthanc server is properly configured (see above), you can make REST calls to the API of the DICOMweb server. For demonstration purpose, this section makes the assumption that the VIX dataset provided by OsiriX has been uploaded to Orthanc.

WADO-URI

Here is a proper WADO-URI (previously known simply as WADO) request to render one slice of the VIX dataset as a JPEG image:

http://localhost:8042/wado?objectUID=1.3.12.2.1107.5.1.4.54693.30000006100507010800000005466&requestType=WADO

The objectUID corresponds to the SOPInstanceUID DICOM tag of some instance in the VIX dataset. Given the Orthanc identifier of an instance from VIX (e.g. 14b4db2c-065edecb-6a767936-7068293a-92fcb080), the latter tag can be obtained from the MainDicomTags field:

$ curl http://localhost:8042/instances/14b4db2c-065edecb-6a767936-7068293a-92fcb080

QIDO-RS

Regarding QIDO-RS (querying the content of a remote DICOMweb server), here is how to obtain the list of studies stored by Orthanc:

$ curl http://localhost:8042/dicom-web/studies

Note that the /dicom-web/ prefix comes from the configuration option Root of the DicomWeb section. Filtering the studies is possible as follows:

$ curl http://localhost:8042/dicom-web/studies?PatientName=VIX

WADO-RS

A study can be retrieved through WADO-RS. Here is a sample using the VIX dataset:

$ curl http://localhost:8042/dicom-web/studies/2.16.840.1.113669.632.20.1211.10000315526/

This answer is a multipart stream of application/dicom DICOM instances, so a Web browser will not be able to display it (. You will have to use either AJAX (JavaScript) or a command-line tool (such as cURL).

You can render one individual frame as a plain PNG image as follows:

$ curl http://localhost:8042/dicom-web/studies/2.16.840.1.113669.632.20.1211.10000315526/series/1.3.12.2.1107.5.1.4.54693.30000006100507010800000005268/instances/1.3.12.2.1107.5.1.4.54693.30000006100507010800000005466/frames/1/rendered -H 'accept: image/png'

Other endpoints

This page only provides some very basic examples about the use of a DICOMweb server. Please check out the full reference of the DICOMweb API for more information.

Also, check out the section about additional samples that notably provides example of STOW-RS clients in JavaScript and Python.

REST API of the Orthanc DICOMweb client

Listing the available servers

The list of the remote DICOMweb servers that are known to the DICOMweb plugin can be obtained as follows:

$ curl http://localhost:8042/dicom-web/servers/
[ "sample" ]

In this case, a single server called sample is configured.

Making a call to QIDO-RS or WADO-RS

In Orthanc, the URI /{dicom-web-root}/servers/{name}/get allows to make a HTTP GET call against a DICOMweb server. This can be used to issue a QIDO-RS or WADO-RS command. Orthanc will take care of properly encoding the URL and authenticating the client. For instance, here is a sample QIDO-RS search to query all the studies (using a bash command-line):

$ curl http://localhost:8042/dicom-web/servers/sample/get -d @- << EOF
{
  "Uri" : "/studies"
}
EOF

The result of this call is a JSON document formatted according to the DICOMweb standard. You do not have to specify the base URL of the remote DICOMweb server, as it is encoded in the configuration file.

As a more advanced example, here is how to search all the series associated with a given patient name, while requesting to use an XML format:

$ curl http://localhost:8042/dicom-web/servers/sample/get -d @- << EOF
{
  "Uri" : "/series",
  "HttpHeaders" : {
    "Accept" : "application/dicom+xml"
  },
  "Arguments" : {
    "00100010" : "KNIX"
  }
}
EOF

The result of the command above is a multipart stream of XML documents describing each series.

Note how all the GET arguments to the QIDO-RS request must be specified in the Arguments field. Orthanc will take care of properly encoding it as an URL.

An user-friendly reference of the features available in QIDO-RS and WADO-RS can be found on this site.

Sending DICOM resources to a STOW-RS server

STOW-RS allows to send local DICOM resources to a remote DICOMweb server. In Orthanc, the STOW-RS client primitive is available at URI /{dicom-web-root}/servers/{name}/stow. Here is a sample call:

$ curl http://localhost:8042/dicom-web/servers/sample/stow -X POST -d @- << EOF
{
  "Resources" : [
    "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228"
  ]
}
EOF

Note that this primitive takes as its input a list of Orthanc identifiers corresponding to the resources (patients, studies, series and/or instances) to be exported.

Additional HTTP headers can be added with an optional HttpHeaders argument as for QIDO-RS and WADO-RS. This might be useful e.g. for cookie-based session management.

Internally, this call results in creating an Orthanc job that is executed synchronously (the REST call only returns once the STOW-RS request is finished). You can run the job in asynchronous mode as follows:

$ curl http://localhost:8042/dicom-web/servers/sample/stow -X POST -d @- << EOF
{
  "Resources" : [
    "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228"
  ],
  "Synchronous" : false,
  "Priority" : 10
}
EOF

{
  "ID" : "a7bd2a5c-291d-4ca5-977a-66502cab22a1",
  "Path" : ".././../jobs/a7bd2a5c-291d-4ca5-977a-66502cab22a1"
}

Such a call ends immediately, and returns the ID of the job created by Orthanc. The status of the job can then be monitored using the Orthanc REST API.

Retrieving DICOM resources from a WADO-RS server

Once DICOM resources of interest have been identified through a QIDO-RS call to a remote DICOMweb server (cf. above), it is interesting to download them locally with a WADO-RS call. You could do it manually with a second call to the /{dicom-web-root}/servers/{name}/get URI, but Orthanc provides another primitive .../retrieve to automate this process, in order to avoid the manual parsing of the multipart stream.

Here is how you would download one study, one series and one instance whose StudyInstanceUID (0020,000d), SeriesInstanceUID (0020,000e) are SOPInstanceUID (0008,0018) have been identified through a former QIDO-RS call:

$ curl http://localhost:8042/dicom-web/servers/sample/retrieve -X POST -d @- << EOF
{
  "Resources" : [
    {
      "Study" : "1.3.51.0.1.1.192.168.29.133.1688840.1688819"
    },
    {
      "Study" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732",
      "Series" : "1.3.12.2.1107.5.2.33.37097.2012041613040617636372171.0.0.0"
    },
    {
      "Study" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732",
      "Series" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0",
      "Instance" : "1.3.12.2.1107.5.2.33.37097.2012041612485540185869716"
    }
  ]
}
EOF

Orthanc will reply with the list of the Orthanc identifiers of all the DICOM instances that were downloaded from the remote server.

Remark 1: Contrarily to the .../stow URI that uses Orthanc identifiers, the .../retrieve URI uses DICOM identifiers.

Remark 2: The HttpHeaders and Arguments arguments are also available, as for QIDO-RS, to fine-tune the parameters of the WADO-RS request.

Remark 3: As for QIDO-RS, the request is run synchronously by default. The Synchronous and Priority arguments can be used to asynchronously run the request.

Additional samples

Samples of how to call DICOMweb services from standalone applications are available for Python and for JavaScript.

Integration tests are available separately, and provide samples for more advanced features of the REST API (such as dynamically adding/updating/removing remote DICOMweb servers using HTTP PUT and DELETE methods).