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.

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 these plugins is similar of that for the core of Orthanc. The following commands should work for every 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. A package for Apple’s Mac OS X is available courtesy of Osimis.

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

Usage

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:

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

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

Options

Quickstart

Once your Orthanc is properly configured (see above), you can make REST calls to the DICOMweb API. 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

WADO-RS

Regarding WADO-RS (i.e. DICOMweb RESTful services), here is how to obtain the tags of all the instances stored by Orthanc:

# curl http://localhost:8042/dicom-web/instances

Note that, as the MIME type of this answer is a multipart application/dicom+xml, 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).

Here is how to generate a JPEG preview of one instance with WADO-RS (through the RetrieveFrames primitive):

# 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 -H 'accept: multipart/related; type=image/dicom+jpeg'

Querying a remote DICOMweb server with Orthanc

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" ]

Here, 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

You do not have to specify the base URL of the remote DICOMweb server, as it is encoded in the configuration file.

The result of the command above is a multipart application/dicom+xml document. It is possible to request a more human-friendly JSON answer by adding the Accept HTTP header. Here is how to search for a given patient name, while requesting a JSON answer and pretty-printing through the json_pp command-line tool:

# curl http://localhost:8042/dicom-web/servers/sample/get -d @- << EOF | json_pp
{
  "Uri" : "/studies",
  "HttpHeaders" : {
    "Accept" : "application/json"
  },
  "Arguments" : {
    "00100010" : "*JODOGNE*"
  }
}
EOF

Note how all the GET arguments for the QIDO-RS request must be specified in the Arguments field. Orthanc will take care of properly encoding it to a 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.

Remark 1: 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.

Remark 2: One call to this .../stow primitive will possibly result in several HTTP requests to the DICOMweb server, in order to limit the size of the HTTP messages. The configuration options DicomWeb.StowMaxInstances and DicomWeb.StowMaxSize can be used to tune this behavior (set both options to 0 to send one single request).

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.

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.

Additional samples

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

Some integration tests are also available separately (work in progress).