DICOMweb plugin¶

Server-related options¶

There are several configuration options that can be set to fine-tune the Orthanc DICOMweb server. Here is the full list of the available options, all of them must be grouped inside the DicomWeb section of the Orthanc configuration file:

{
  [...]
  "DicomWeb" : {
    "Enable" : true,            // Whether DICOMweb support is enabled
    "Root" : "/dicom-web/",     // Root URI of the DICOMweb API (for QIDO-RS, STOW-RS and WADO-RS)
    "EnableWado" : true,        // Whether WADO-URI (previously known as WADO) support is enabled
    "WadoRoot" : "/wado",       // Root URI of the WADO-URI (aka. WADO) API
    "Ssl" : false,              // Whether HTTPS should be used for subsequent WADO-RS requests
    "QidoCaseSensitive" : true, // For QIDO-RS server, whether search is case sensitive (since release 0.5)
    "Host" : "localhost"        // Hard-codes the name of the host for subsequent WADO-RS requests (deprecated)
  }
}

Furthermore, the global option DefaultEncoding specifies the encoding (specific character set) that will be used when answering a QIDO-RS request. It might be a good idea to set this option to Utf8 if you are dealing with an international environment.

The following configuration options were present in releases <= 0.6 of the plugin, but are not used anymore:

{
  [...]
  "DicomWeb" : {
    "StowMaxInstances" : 10,    // For STOW-RS client, the maximum number of instances in one single HTTP query (0 = no limit)
    "StowMaxSize" : 10,         // For STOW-RS client, the maximum size of the body in one single HTTP query (in MB, 0 = no limit)
  }
}

These older configuration options were used to limit the size of the HTTP requests, by issuing multiple calls to STOW-RS (set both options to 0 to send one single request).

Remark: The option Host is deprecated. Starting with release 0.7 of the DICOMweb plugin, its value are computed from the standard HTTP headers Forwarded and Host, as provided by the HTTP clients.

Client-related options¶

If you want to connect Orthanc as a client to remote DICOMweb servers (cf. below), you need to modify the configuration file so as to define each of them in the option DicomWeb.Servers. The syntax is identical to the OrthancPeers option of the configuration of the Orthanc core.

In the most simple case, here is how to instruct Orthanc about the existence of a password-less DICOMweb server that will be referred to as “sample” in Orthanc:

{
  [...]
  "DicomWeb" : {
    "Servers" : {
      "sample" : [ "http://192.168.1.1/dicom-web/" ]
    }
  }
}

You are of course free to add as many DICOMweb servers as you need. If the DICOMweb server is protected by a password (with HTTP Basic access authentication):

{
  [...]
  "DicomWeb" : {
    "Servers" : {
      "sample" : [ "http://192.168.1.1/dicom-web/", "username", "password" ]
    }
  }
}

Two important options can be provided for individual remote DICOMweb servers:

• HasDelete can be set to true to indicate that the HTTP DELETE method can be used to delete remote studies/series/instances. This notably adds a “delete” button on the Web interface of the DICOMweb client, and creates a route /dicom-web/servers/sample/delete in the REST API.
• ChunkedTransfers must be set to false if the remote DICOMweb server does not support HTTP chunked transfer encoding. Setting this option to true is the best choice to reduce memory consumption. However, it must be set to false if the remote DICOMweb server is Orthanc <= 1.5.6, as chunked transfer encoding is only supported starting with Orthanc 1.5.7.

You’ll have to convert the JSON array into a JSON object to set these options:

{
  [...]
  "DicomWeb" : {
    "Servers" : {
      "sample" : {
        "Url" : "http://192.168.1.1/dicom-web/",
        "Username" : "username",
        "Password" : "password",
        "HasDelete" : true,
        "ChunkedTransfers" : true   // Set to "false" if "sample" is Orthanc <= 1.5.6
      }
    }
  }
}

Furthermore, if the DICOMweb server is protected with HTTPS client authentication, you must provide your client certificate (in the PEM format), your client private key (also in the PEM format), together with the password protecting the private key:

{
  [...]
  "DicomWeb" : {
    "Servers" : {
      "sample" : {
        "Url" : "http://192.168.1.1/dicom-web/",
        "CertificateFile" : "client.crt",
        "CertificateKeyFile" : "client.key",
        "CertificateKeyPassword" : "password"
      }
    }
  }
}

Finally, it is also possible to use client authentication with hardware security modules and smart cards through PKCS#11 (this feature is only available is the core of Orthanc was compiled with the -DENABLE_PKCS11=ON option in CMake, and if the Orthanc configuration file has a proper Pkcs11 section):

{
  [...]
  "DicomWeb" : {
    "Servers" : {
      "sample" : {
        "Url" : "http://192.168.1.1/dicom-web/",
        "Pkcs11" : true
      }
    }
  }
}

Remark: A plugin by Osimis is available to dynamically create authenticated connections to Google Cloud Platform.

Important remark: When querying a DICOMweb server, Orthanc will automatically use the global configuration options HttpProxy, HttpTimeout, HttpsVerifyPeers, HttpsCACertificates, and Pkcs11. Make sure to adapt them if need be.

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:

$ 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.

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.