orthanc-book: Sphinx/source/plugins/dicomweb.rst comparison

comparison Sphinx/source/plugins/dicomweb.rst @ 32:03b32d0e49f2

documentation of the dicomweb plugin

author	Sebastien Jodogne <s.jodogne@gmail.com>
date	Wed, 20 Jul 2016 13:34:54 +0200
parents	93bbfaf0e62c
children	11e204c432a7

comparison

equal deleted inserted replaced

-:93bbfaf0e62c
+:03b32d0e49f2
 For general information, check out the `official homepage of the
 plugins <http://www.orthanc-server.com/static.php?page=dicomweb>`__.
 The full standard is not implemented yet, the supported features are
 `tracked in the repository
-<https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Status.txt>`__. Some
+<https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Status.txt>`__.
-integration tests are `available separately
-<https://bitbucket.org/sjodogne/orthanc-tests/src/default/Plugins/DicomWeb/Run.py>`__.
 Compilation
 -----------
 $ cd Build
 $ cmake .. -DSTATIC_BUILD=ON
 $ make
 The compilation will produce a shared library ``OrthancDicomWeb`` that
-contains the DICOMweb plugin.  Pre-compiled binaries for Microsoft
+contains the DICOMweb plugin. Pre-compiled binaries for Microsoft
 Windows `are also available
 <http://www.orthanc-server.com/browse.php?path=/plugin-dicom-web>`__.
 A package for `Apple's Mac OS X
 <http://localhost/~jodogne/orthanc/static.php?page=download-mac>`__ is
 available courtesy of `Osimis <http://osimis.io/>`__.
+*Remark:* Some older build instructions are also available in the
+`source distribution
+<https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Resources/BuildInstructions.txt>`__.
 Usage
 -----
 .. highlight:: json
 You of course first have to :ref:`install Orthanc <binaries>`. Once
 Orthanc is installed, you must change the :ref:`configuration file
 <configuration>` to tell Orthanc where it can find the plugin: This is
-done by properly modifying the ``Plugins`` option. You could for
+done by properly modifying the ``Plugins`` option. For GNU/Linux, you
-instance use the following configuration file::
+could for instance use the following configuration file::
 {
 "Name" : "MyOrthanc",
 [...]
 "Plugins" : [
 "/home/user/OrthancDicomWeb/Build/libOrthancDicomWeb.so"
 ]
 }
-The root of the DICOMweb REST API is then accessible at ``http://localhost:8042/dicom-web/``.
+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
 -------
+Server-related options
+^^^^^^^^^^^^^^^^^^^^^^
 .. highlight:: json
-Several configuration options are also available, and are listed in
+There are several configuration options that can be set to fine-tune
-the example below::
+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
+"Enable" : true,          // Whether DICOMweb support is enabled
-"Root" : "/dicom-web/",  // Root URI of the DICOMweb API (for QIDO-RS, STOW-RS and WADO-RS)
+"Root" : "/dicom-web/",   // Root URI of the DICOMweb API (for QIDO-RS, STOW-RS and WADO-RS)
-"EnableWado" : true,     // Whether WADO-URI (aka. WADO) support is enabled
+"EnableWado" : true,      // Whether WADO-URI (previously known as WADO) support is enabled
-"WadoRoot" : "/wado",    // Root URI of the WADO-URI (aka. WADO) API
+"WadoRoot" : "/wado",     // Root URI of the WADO-URI (aka. WADO) API
-"Host" : "localhost",    // Hard-codes the name of the host for subsequent WADO-RS requests
+"Host" : "localhost",     // Hard-codes the name of the host for subsequent WADO-RS requests
-"Ssl" : false            // Whether HTTPS should be used for subsequent WADO-RS requests
+"Ssl" : false,            // Whether HTTPS should be used for subsequent WADO-RS requests
-}
+"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)
+}
+}
+Client-related options
+^^^^^^^^^^^^^^^^^^^^^^
+.. highlight:: json
+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 :ref:`configuration of
+the Orthanc core <configuration>`.
+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
+<https://en.wikipedia.org/wiki/Basic_access_authentication>`__)::
+{
+[...]
+"DicomWeb" : {
+"Servers" : {
+"sample" : [ "http://192.168.1.1/dicom-web/", "username", "password" ]
+}
+}
+}
+If the DICOMweb server is protected with HTTPS client authentication,
+you must provide your client certificate (in the `PEM format
+<https://en.wikipedia.org/wiki/Privacy-enhanced_Electronic_Mail>`__),
+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
+<https://en.wikipedia.org/wiki/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
+}
+}
+}
+}
+**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.
+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 <http://www.osirix-viewer.com/datasets/>`__ has been uploaded
+to Orthanc.
+WADO-URI
+^^^^^^^^
+.. highlight:: text
+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
+^^^^^^^
+.. highlight:: text
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. highlight:: text
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. highlight:: text
+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 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
+<http://dicomweb.hcintegrations.ca/#/home>`__.
+Sending DICOM resources to a STOW-RS server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. highlight:: text
+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 :ref:`Orthanc
+identifiers <orthanc-ids>` 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. highlight:: text
+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 :ref:`Orthanc
+identifiers <orthanc-ids>`, the ``.../retrieve`` URI uses DICOM
+identifiers.
+Remark 2: The ``HttpArguments`` is also available.
+Additional samples
+------------------
+Samples of how to call DICOMweb services from standalone applications
+are available for `Python
+<https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Resources/Samples/Python/>`__
+and for `JavaScript
+<https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Resources/Samples/JavaScript>`__.
+Some integration tests are also `available separately
+<https://bitbucket.org/sjodogne/orthanc-tests/src/default/Plugins/DicomWeb/Run.py>`__
+(work in progress).

Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/dicomweb.rst @ 32:03b32d0e49f2