Mercurial > hg > orthanc-book

changeset 32:03b32d0e49f2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
files Sphinx/source/plugins/dicomweb.rst Sphinx/source/plugins/webviewer.rst
diffstat 2 files changed, 342 insertions(+), 15 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/plugins/dicomweb.rst	Wed Jul 20 11:35:54 2016 +0200
+++ b/Sphinx/source/plugins/dicomweb.rst	Wed Jul 20 13:34:54 2016 +0200
@@ -17,9 +17,7 @@
 
 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
-integration tests are `available separately
-<https://bitbucket.org/sjodogne/orthanc-tests/src/default/Plugins/DicomWeb/Run.py>`__.
+<https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Status.txt>`__.
 
 
 Compilation
@@ -37,13 +35,17 @@
   $ 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
 -----
@@ -53,8 +55,8 @@
 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
-instance use the following configuration file::
+done by properly modifying the ``Plugins`` option. For GNU/Linux, you
+could for instance use the following configuration file::
 
   {
     "Name" : "MyOrthanc",
@@ -64,25 +66,346 @@
     ]
   }
 
-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
-the example below::
+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
+      "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
+      "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" : {
-      "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 (aka. WADO) support is enabled
-      "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
-      "Ssl" : false            // Whether HTTPS should be used for subsequent WADO-RS requests
+      "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).
--- a/Sphinx/source/plugins/webviewer.rst	Wed Jul 20 11:35:54 2016 +0200
+++ b/Sphinx/source/plugins/webviewer.rst	Wed Jul 20 13:34:54 2016 +0200
@@ -31,6 +31,10 @@
 Microsoft Windows `are also available
 <http://www.orthanc-server.com/browse.php?path=/plugin-webviewer>`__.
 
+*Remark:* Some older build instructions are also available in the
+`source distribution
+<https://bitbucket.org/sjodogne/orthanc-webviewer/src/default/Resources/BuildInstructions.txt>`__.
+
 
 Usage
 -----