Mercurial > hg > orthanc-book
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
31:93bbfaf0e62c | 32:03b32d0e49f2 |
---|---|
15 For general information, check out the `official homepage of the | 15 For general information, check out the `official homepage of the |
16 plugins <http://www.orthanc-server.com/static.php?page=dicomweb>`__. | 16 plugins <http://www.orthanc-server.com/static.php?page=dicomweb>`__. |
17 | 17 |
18 The full standard is not implemented yet, the supported features are | 18 The full standard is not implemented yet, the supported features are |
19 `tracked in the repository | 19 `tracked in the repository |
20 <https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Status.txt>`__. Some | 20 <https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Status.txt>`__. |
21 integration tests are `available separately | |
22 <https://bitbucket.org/sjodogne/orthanc-tests/src/default/Plugins/DicomWeb/Run.py>`__. | |
23 | 21 |
24 | 22 |
25 Compilation | 23 Compilation |
26 ----------- | 24 ----------- |
27 | 25 |
35 $ cd Build | 33 $ cd Build |
36 $ cmake .. -DSTATIC_BUILD=ON | 34 $ cmake .. -DSTATIC_BUILD=ON |
37 $ make | 35 $ make |
38 | 36 |
39 The compilation will produce a shared library ``OrthancDicomWeb`` that | 37 The compilation will produce a shared library ``OrthancDicomWeb`` that |
40 contains the DICOMweb plugin. Pre-compiled binaries for Microsoft | 38 contains the DICOMweb plugin. Pre-compiled binaries for Microsoft |
41 Windows `are also available | 39 Windows `are also available |
42 <http://www.orthanc-server.com/browse.php?path=/plugin-dicom-web>`__. | 40 <http://www.orthanc-server.com/browse.php?path=/plugin-dicom-web>`__. |
43 A package for `Apple's Mac OS X | 41 A package for `Apple's Mac OS X |
44 <http://localhost/~jodogne/orthanc/static.php?page=download-mac>`__ is | 42 <http://localhost/~jodogne/orthanc/static.php?page=download-mac>`__ is |
45 available courtesy of `Osimis <http://osimis.io/>`__. | 43 available courtesy of `Osimis <http://osimis.io/>`__. |
46 | 44 |
45 *Remark:* Some older build instructions are also available in the | |
46 `source distribution | |
47 <https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Resources/BuildInstructions.txt>`__. | |
48 | |
47 | 49 |
48 Usage | 50 Usage |
49 ----- | 51 ----- |
50 | 52 |
51 .. highlight:: json | 53 .. highlight:: json |
52 | 54 |
53 You of course first have to :ref:`install Orthanc <binaries>`. Once | 55 You of course first have to :ref:`install Orthanc <binaries>`. Once |
54 Orthanc is installed, you must change the :ref:`configuration file | 56 Orthanc is installed, you must change the :ref:`configuration file |
55 <configuration>` to tell Orthanc where it can find the plugin: This is | 57 <configuration>` to tell Orthanc where it can find the plugin: This is |
56 done by properly modifying the ``Plugins`` option. You could for | 58 done by properly modifying the ``Plugins`` option. For GNU/Linux, you |
57 instance use the following configuration file:: | 59 could for instance use the following configuration file:: |
58 | 60 |
59 { | 61 { |
60 "Name" : "MyOrthanc", | 62 "Name" : "MyOrthanc", |
61 [...] | 63 [...] |
62 "Plugins" : [ | 64 "Plugins" : [ |
63 "/home/user/OrthancDicomWeb/Build/libOrthancDicomWeb.so" | 65 "/home/user/OrthancDicomWeb/Build/libOrthancDicomWeb.so" |
64 ] | 66 ] |
65 } | 67 } |
66 | 68 |
67 The root of the DICOMweb REST API is then accessible at ``http://localhost:8042/dicom-web/``. | 69 Or, for Windows:: |
70 | |
71 { | |
72 "Name" : "MyOrthanc", | |
73 [...] | |
74 "Plugins" : [ | |
75 "c:/Temp/OrthancDicomWeb.dll" | |
76 ] | |
77 } | |
78 | |
79 Note that the DICOMweb server will share all the parameters of the | |
80 Orthanc HTTP server, notably wrt. authentication and HTTPS | |
81 encryption. For this reason, you will most probably have to enable the | |
82 remote access to the Orthanc HTTP server:: | |
83 | |
84 { | |
85 [...] | |
86 "RemoteAccessEnabled" : true, | |
87 [...] | |
88 } | |
89 | |
90 Once Orthanc has restarted, the root of the DICOMweb REST API is | |
91 accessible at ``http://localhost:8042/dicom-web/``. | |
68 | 92 |
69 | 93 |
70 Options | 94 Options |
71 ------- | 95 ------- |
72 | 96 |
97 Server-related options | |
98 ^^^^^^^^^^^^^^^^^^^^^^ | |
99 | |
73 .. highlight:: json | 100 .. highlight:: json |
74 | 101 |
75 Several configuration options are also available, and are listed in | 102 There are several configuration options that can be set to fine-tune |
76 the example below:: | 103 the Orthanc DICOMweb server. Here is the full list of the available |
77 | 104 options, all of them must be grouped inside the ``DicomWeb`` section of |
78 { | 105 the Orthanc configuration file:: |
106 | |
107 { | |
108 [...] | |
79 "DicomWeb" : { | 109 "DicomWeb" : { |
80 "Enable" : true, // Whether DICOMweb support is enabled | 110 "Enable" : true, // Whether DICOMweb support is enabled |
81 "Root" : "/dicom-web/", // Root URI of the DICOMweb API (for QIDO-RS, STOW-RS and WADO-RS) | 111 "Root" : "/dicom-web/", // Root URI of the DICOMweb API (for QIDO-RS, STOW-RS and WADO-RS) |
82 "EnableWado" : true, // Whether WADO-URI (aka. WADO) support is enabled | 112 "EnableWado" : true, // Whether WADO-URI (previously known as WADO) support is enabled |
83 "WadoRoot" : "/wado", // Root URI of the WADO-URI (aka. WADO) API | 113 "WadoRoot" : "/wado", // Root URI of the WADO-URI (aka. WADO) API |
84 "Host" : "localhost", // Hard-codes the name of the host for subsequent WADO-RS requests | 114 "Host" : "localhost", // Hard-codes the name of the host for subsequent WADO-RS requests |
85 "Ssl" : false // Whether HTTPS should be used for subsequent WADO-RS requests | 115 "Ssl" : false, // Whether HTTPS should be used for subsequent WADO-RS requests |
86 } | 116 "StowMaxInstances" : 10, // For STOW-RS client, the maximum number of instances in one single HTTP query (0 = no limit) |
87 } | 117 "StowMaxSize" : 10 // For STOW-RS client, the maximum size of the body in one single HTTP query (in MB, 0 = no limit) |
88 | 118 } |
119 } | |
120 | |
121 | |
122 Client-related options | |
123 ^^^^^^^^^^^^^^^^^^^^^^ | |
124 | |
125 .. highlight:: json | |
126 | |
127 If you want to connect Orthanc as a client to remote DICOMweb servers | |
128 (cf. below), you need to modify the configuration file so as to define | |
129 each of them in the option ``DicomWeb.Servers``. The syntax is | |
130 identical to the ``OrthancPeers`` option of the :ref:`configuration of | |
131 the Orthanc core <configuration>`. | |
132 | |
133 In the most simple case, here is how to instruct Orthanc about the | |
134 existence of a password-less DICOMweb server that will be referred to | |
135 as "sample" in Orthanc:: | |
136 | |
137 { | |
138 [...] | |
139 "DicomWeb" : { | |
140 "Servers" : { | |
141 "sample" : [ "http://192.168.1.1/dicom-web/" ] | |
142 } | |
143 } | |
144 } | |
145 | |
146 You are of course free to add as many DICOMweb servers as you need. If | |
147 the DICOMweb server is protected by a password (with `HTTP Basic | |
148 access authentication | |
149 <https://en.wikipedia.org/wiki/Basic_access_authentication>`__):: | |
150 | |
151 { | |
152 [...] | |
153 "DicomWeb" : { | |
154 "Servers" : { | |
155 "sample" : [ "http://192.168.1.1/dicom-web/", "username", "password" ] | |
156 } | |
157 } | |
158 } | |
159 | |
160 If the DICOMweb server is protected with HTTPS client authentication, | |
161 you must provide your client certificate (in the `PEM format | |
162 <https://en.wikipedia.org/wiki/Privacy-enhanced_Electronic_Mail>`__), | |
163 your client private key (also in the PEM format), together with the | |
164 password protecting the private key:: | |
165 | |
166 { | |
167 [...] | |
168 "DicomWeb" : { | |
169 "Servers" : { | |
170 "sample" : { | |
171 "Url" : "http://192.168.1.1/dicom-web/", | |
172 "CertificateFile" : "client.crt", | |
173 "CertificateKeyFile" : "client.key", | |
174 "CertificateKeyPassword" : "password" | |
175 } | |
176 } | |
177 } | |
178 } | |
179 | |
180 Finally, it is also possible to use client authentication with | |
181 hardware security modules and smart cards through `PKCS#11 | |
182 <https://en.wikipedia.org/wiki/PKCS_11>`__ (this feature is only | |
183 available is the core of Orthanc was compiled with the | |
184 ``-DENABLE_PKCS11=ON`` option in CMake, and if the Orthanc | |
185 configuration file has a proper ``Pkcs11`` section):: | |
186 | |
187 { | |
188 [...] | |
189 "DicomWeb" : { | |
190 "Servers" : { | |
191 "sample" : { | |
192 "Url" : "http://192.168.1.1/dicom-web/", | |
193 "Pkcs11" : true | |
194 } | |
195 } | |
196 } | |
197 } | |
198 | |
199 **Important remark:** When querying a DICOMweb server, Orthanc will | |
200 automatically use the global configuration options ``HttpProxy``, | |
201 ``HttpTimeout``, ``HttpsVerifyPeers``, ``HttpsCACertificates``, and | |
202 ``Pkcs11``. Make sure to adapt them if need be. | |
203 | |
204 | |
205 Quickstart | |
206 ---------- | |
207 | |
208 Once your Orthanc is properly configured (see above), you can make | |
209 REST calls to the DICOMweb API. For demonstration purpose, this | |
210 section makes the assumption that the ``VIX`` dataset provided by | |
211 `OsiriX <http://www.osirix-viewer.com/datasets/>`__ has been uploaded | |
212 to Orthanc. | |
213 | |
214 WADO-URI | |
215 ^^^^^^^^ | |
216 | |
217 .. highlight:: text | |
218 | |
219 Here is a proper WADO-URI (previously known simply as WADO) request to | |
220 render one slice of the VIX dataset as a JPEG image:: | |
221 | |
222 http://localhost:8042/wado?objectUID=1.3.12.2.1107.5.1.4.54693.30000006100507010800000005466&requestType=WADO | |
223 | |
224 The ``objectUID`` corresponds to the ``SOPInstanceUID`` DICOM tag of | |
225 some instance in the ``VIX`` dataset. Given the Orthanc identifier of | |
226 an instance from VIX | |
227 (e.g. ``14b4db2c-065edecb-6a767936-7068293a-92fcb080``), the latter | |
228 tag can be obtained from the ``MainDicomTags`` field:: | |
229 | |
230 # curl http://localhost:8042/instances/14b4db2c-065edecb-6a767936-7068293a-92fcb080 | |
231 | |
232 | |
233 WADO-RS | |
234 ^^^^^^^ | |
235 | |
236 .. highlight:: text | |
237 | |
238 Regarding WADO-RS (i.e. DICOMweb RESTful services), here is how to | |
239 obtain the tags of all the instances stored by Orthanc:: | |
240 | |
241 # curl http://localhost:8042/dicom-web/instances | |
242 | |
243 Note that, as the MIME type of this answer is a multipart | |
244 ``application/dicom+xml``, a Web browser will not be able to display | |
245 it. You will have to use either AJAX (JavaScript) or a command-line | |
246 tool (such as curl). | |
247 | |
248 Here is how to generate a JPEG preview of one instance with WADO-RS | |
249 (through the RetrieveFrames primitive):: | |
250 | |
251 # 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' | |
252 | |
253 | |
254 | |
255 Querying a remote DICOMweb server with Orthanc | |
256 ---------------------------------------------- | |
257 | |
258 Listing the available servers | |
259 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
260 | |
261 .. highlight:: text | |
262 | |
263 The list of the remote DICOMweb servers that are known to the DICOMweb | |
264 plugin can be obtained as follows:: | |
265 | |
266 # curl http://localhost:8042/dicom-web/servers/ | |
267 [ "sample" ] | |
268 | |
269 Here, a single server called ``sample`` is configured. | |
270 | |
271 | |
272 Making a call to QIDO-RS or WADO-RS | |
273 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
274 | |
275 .. highlight:: text | |
276 | |
277 In Orthanc, the URI ``/{dicom-web-root}/servers/{name}/get`` allows to | |
278 make a HTTP GET call against a DICOMweb server. This can be used to | |
279 issue a QIDO-RS or WADO-RS command. Orthanc will take care of properly | |
280 encoding the URL and authenticating the client. | |
281 | |
282 For instance, here is a sample QIDO-RS search to query all the studies | |
283 (using a bash command-line):: | |
284 | |
285 # curl http://localhost:8042/dicom-web/servers/sample/get -d @- << EOF | |
286 { | |
287 "Uri" : "/studies" | |
288 } | |
289 EOF | |
290 | |
291 You do not have to specify the base URL of the remote DICOMweb server, | |
292 as it is encoded in the configuration file. | |
293 | |
294 The result of the command above is a multipart | |
295 ``application/dicom+xml`` document. It is possible to request a more | |
296 human-friendly JSON answer by adding the ``Accept`` HTTP header. Here | |
297 is how to search for a given patient name, while requesting a JSON | |
298 answer and pretty-printing through the ``json_pp`` command-line tool:: | |
299 | |
300 # curl http://localhost:8042/dicom-web/servers/sample/get -d @- << EOF | json_pp | |
301 { | |
302 "Uri" : "/studies", | |
303 "HttpHeaders" : { | |
304 "Accept" : "application/json" | |
305 }, | |
306 "Arguments" : { | |
307 "00100010" : "*JODOGNE*" | |
308 } | |
309 } | |
310 EOF | |
311 | |
312 Note how all the GET arguments must be specified in the ``Arguments`` | |
313 field. Orthanc will take care of properly encoding it to a URL. | |
314 | |
315 An user-friendly reference of the features available in QIDO-RS and | |
316 WADO-RS `can be found on this site | |
317 <http://dicomweb.hcintegrations.ca/#/home>`__. | |
318 | |
319 | |
320 Sending DICOM resources to a STOW-RS server | |
321 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
322 | |
323 .. highlight:: text | |
324 | |
325 STOW-RS allows to send local DICOM resources to a remote DICOMweb | |
326 server. In Orthanc, the STOW-RS client primitive is available at URI | |
327 ``/{dicom-web-root}/servers/{name}/stow``. Here is a sample call:: | |
328 | |
329 # curl http://localhost:8042/dicom-web/servers/sample/stow -X POST -d @- << EOF | |
330 { | |
331 "Resources" : [ | |
332 "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228" | |
333 ] | |
334 } | |
335 EOF | |
336 | |
337 Note that this primitive takes as its input a list of :ref:`Orthanc | |
338 identifiers <orthanc-ids>` corresponding to the resources (patients, | |
339 studies, series and/or instances) to be exported. | |
340 | |
341 Remark 1: Additional HTTP headers can be added with an optional | |
342 ``HttpHeaders" argument`` as for QIDO-RS and WADO-RS. This might be | |
343 useful e.g. for cookie-based session management. | |
344 | |
345 Remark 2: One call to this ``.../stow`` primitive will possibly result | |
346 in several HTTP requests to the DICOMweb server, in order to limit the | |
347 size of the HTTP messages. The configuration options | |
348 ``DicomWeb.StowMaxInstances`` and ``DicomWeb.StowMaxSize`` can be used | |
349 to tune this behavior (set both options to 0 to send one single | |
350 request). | |
351 | |
352 | |
353 Retrieving DICOM resources from a WADO-RS server | |
354 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
355 | |
356 .. highlight:: text | |
357 | |
358 Once DICOM resources of interest have been identified through a | |
359 QIDO-RS call to a remote DICOMweb server (cf. above), it is | |
360 interesting to download them locally with a WADO-RS call. You could do | |
361 it manually with a second call to the | |
362 ``/{dicom-web-root}/servers/{name}/get`` URI, but Orthanc provides | |
363 another primitive ``.../retrieve`` to automate this process. | |
364 | |
365 Here is how you would download one study, one series and one instance | |
366 whose StudyInstanceUID (0020,000d), SeriesInstanceUID (0020,000e) are | |
367 SOPInstanceUID (0008,0018) have been identified through a former | |
368 QIDO-RS call:: | |
369 | |
370 # curl http://localhost:8042/dicom-web/servers/sample/retrieve -X POST -d @- << EOF | |
371 { | |
372 "Resources" : [ | |
373 { | |
374 "Study" : "1.3.51.0.1.1.192.168.29.133.1688840.1688819" | |
375 }, | |
376 { | |
377 "Study" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732", | |
378 "Series" : "1.3.12.2.1107.5.2.33.37097.2012041613040617636372171.0.0.0" | |
379 }, | |
380 { | |
381 "Study" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732", | |
382 "Series" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0", | |
383 "Instance" : "1.3.12.2.1107.5.2.33.37097.2012041612485540185869716" | |
384 } | |
385 ] | |
386 } | |
387 EOF | |
388 | |
389 Orthanc will reply with the list of the Orthanc identifiers of all the | |
390 DICOM instances that were downloaded from the remote server. | |
391 | |
392 Remark 1: Contrarily to the ``.../stow`` URI that uses :ref:`Orthanc | |
393 identifiers <orthanc-ids>`, the ``.../retrieve`` URI uses DICOM | |
394 identifiers. | |
395 | |
396 Remark 2: The ``HttpArguments`` is also available. | |
397 | |
398 | |
399 | |
400 Additional samples | |
401 ------------------ | |
402 | |
403 Samples of how to call DICOMweb services from standalone applications | |
404 are available for `Python | |
405 <https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Resources/Samples/Python/>`__ | |
406 and for `JavaScript | |
407 <https://bitbucket.org/sjodogne/orthanc-dicomweb/src/default/Resources/Samples/JavaScript>`__. | |
408 | |
409 Some integration tests are also `available separately | |
410 <https://bitbucket.org/sjodogne/orthanc-tests/src/default/Plugins/DicomWeb/Run.py>`__ | |
411 (work in progress). |