Mercurial > hg > orthanc-book
annotate Sphinx/source/dicom-guide.rst @ 21:cd6c91d3cef5
Orthanc 1.1.0
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Mon, 27 Jun 2016 14:45:33 +0200 |
parents | 6e99967d3503 |
children | 669ea65ba7fb |
rev | line source |
---|---|
0 | 1 .. _dicom-guide: |
2 | |
3 Understanding DICOM with Orthanc | |
4 ================================ | |
5 | |
6 .. contents:: | |
7 | |
8 | |
9 This section of the Orthanc Book provides a **gentle, informal, | |
10 high-level introduction to DICOM**. We will try and map | |
11 DICOM's own concepts to a modern terminology that should hopefully be | |
12 more easy to understand for software engineers diving for the first | |
13 time into DICOM. Once the concepts of this page are understood, | |
14 interested readers are invited to read a more formal textbook about | |
15 DICOM, such as the so-called "`Practical introduction and survival | |
16 guide <http://www.springer.com/us/book/9783642108495>`__", or to read | |
17 the full `DICOM specification | |
18 <http://medical.nema.org/medical/dicom/current/output/html/>`__. | |
19 | |
20 All the DICOM concepts that are defined in this introduction are | |
21 illustrated with `Orthanc <http://www.orthanc-server.com/>`__, a | |
22 lightweight, yet powerful standalone DICOM server for healthcare and | |
23 medical research. As Orthanc is free and open-source software, it is a | |
24 good companion to learn DICOM. | |
25 | |
26 | |
27 .. _dicom-format: | |
28 | |
29 DICOM file format | |
30 ----------------- | |
31 | |
32 The DICOM standard can be very roughly divided in 2 parts: | |
33 | |
34 1. The part specifying the DICOM **file format**. | |
35 2. The part specifying the DICOM **network protocol**. | |
36 | |
37 The DICOM file format is the topic of the present section. It is | |
38 inherently similar to well-known formats such as JPEG, PNG or | |
39 TIFF. However, besides the so-called "**pixel data**" that encodes the | |
40 medical image itself, a DICOM file also embeds medical information. | |
41 | |
42 | |
43 .. _dicom-tags: | |
44 | |
45 DICOM tags | |
46 ^^^^^^^^^^ | |
47 | |
48 The medical information encoded by a DICOM file is called a **data | |
49 set** and takes the form of a `key-value associative array | |
50 <https://en.wikipedia.org/wiki/Associative_array>`__. Each value can | |
51 itself be a list of data sets (called a **sequence**), leading to a | |
52 hierarchical data structure that is much like a XML or JSON file. | |
53 | |
54 In the DICOM terminology, each key is called a **DICOM tag**. The list | |
55 of the standard DICOM tags are normalized by an official dictionary, | |
56 each tag being identified by two 16-bit hexadecimal numbers. For | |
57 instance, the birth date of a patient is associated with the DICOM tag | |
58 ``(0x0010, 0x0030)``. Note that it is common to drop the "``0x``" | |
59 prefix and to simply write ``0010,0030``. For better readability, it | |
60 is also common to nickname these DICOM tags with a `camel case | |
61 <https://en.wikipedia.org/wiki/CamelCase>`__ English name (such as | |
62 "*PatientName*" or "*StudyDescription*"). The standard associates each | |
63 DICOM tag with a data type (a string, a date, a floating-point | |
64 number...), that is known as its **value representation**. | |
65 | |
66 Here is how :ref:`Orthanc Explorer <orthanc-explorer>` displays the | |
67 DICOM tags stored in a DICOM file (note that the file contains a | |
68 sequence identified by the tag ``ProcedureCodeSequence (0x0008, | |
69 0x1032)``): | |
70 | |
71 .. image:: images/DicomTags.png | |
72 :align: center | |
73 :width: 450px | |
74 | |
75 | | |
76 | |
77 The DICOM file format also specifies the set of DICOM tags that are | |
78 mandatory or optional for each kind of imaging modality (CT, MR, NM, | |
79 CBCT, PET...). Such a specification is called a **storage | |
80 service-object pair** (storage SOP). Mandatory tags are called "*type | |
81 1*", mandatory tags that can have a null value are called "*type 2*", | |
82 and optional tags are called "*type 3*". | |
83 | |
84 The DICOM standard also allows vendors to introduce non-standard, | |
85 **proprietary tags** for their own use. Proprietary tags can be | |
86 identified by the fact that their first hexadecimal number is odd | |
87 (e.g. ``(0x0009, 0x0010)``). Obviously, such proprietary tags should | |
88 be avoided for maximal interoperability. | |
89 | |
90 | |
91 .. _dicom-pixel-data: | |
92 | |
93 Pixel data | |
94 ^^^^^^^^^^ | |
95 | |
96 The image itself is associated with the DICOM tag ``PixelData (0x7fe0, | |
97 0x0010)``. The content of image can be compressed using many image | |
98 formats, such as JPEG, `Lossless JPEG | |
99 <https://en.wikipedia.org/wiki/Lossless_JPEG>`__ or `JPEG 2000 | |
100 <https://en.wikipedia.org/wiki/JPEG_2000>`__. Obviously, | |
101 non-destructive (lossless) compression should always be favored to | |
102 avoid any loss of medical information. Note that a DICOM file can also | |
103 act as a wrapper around a video encoded using `MPEG-2 | |
104 <https://en.wikipedia.org/wiki/MPEG-2>`__ or `H.264 | |
105 <https://en.wikipedia.org/wiki/H.264/MPEG-4_AVC>`__. | |
106 | |
107 The image compression algorithm can be identified by inspecting the | |
108 **transfer syntax** that is associated with the DICOM file in its | |
109 header. | |
110 | |
111 In practice, few imaging devices in hospitals (besides the `PACS | |
112 <https://en.wikipedia.org/wiki/Picture_archiving_and_communication_system>`__ | |
113 itself) support image compression. As a consequence, to ensure best | |
114 portability, the pixel data of most DICOM files circulating in | |
115 hospitals is **uncompressed**. In other words, the image is encoded as | |
116 a raw buffer, with a given width, height, pixel type (integer or | |
117 float), `color depth <https://en.wikipedia.org/wiki/Color_depth>`__ | |
118 (most often 8, 10, 12 bpp - *bits per pixel*) and photometric | |
119 interpretation (most often grayscale or RGB). The transfer syntax that | |
120 is associated with such uncompressed images can either be `little | |
121 endian <https://fr.wikipedia.org/wiki/Endianness>`__ (the most common | |
122 case) or big endian. | |
123 | |
124 A DICOM image can be **multi-frame**, meaning that it encodes an array | |
125 of different image frames. This is for instance used to encode | |
126 uncompressed video sequences, that are often referred to as **cine** | |
127 or **2D+t** images (e.g. for `ultrasound imaging | |
128 <https://en.wikipedia.org/wiki/Medical_ultrasound>`__). | |
129 | |
130 `As written in its DICOM conformance statement | |
131 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/DicomConformanceStatement.txt>`__, | |
132 the Orthanc software can receive, store and send any kind of DICOM | |
133 images (i.e. all the standard transfer syntaxes are | |
134 supported). Furthermore, Orthanc can :ref:`convert most uncompressed | |
135 images <supported-images>` to PNG images. The `PNG format | |
136 <https://en.wikipedia.org/wiki/Portable_Network_Graphics>`__ was | |
137 chosen by Orthanc as it is lossless, is natively supported by many | |
138 browsers, software or programming frameworks, and is able to encode up | |
139 to 16bpp integer pixels. This on-the-fly conversion to PNG images is | |
140 what happens when previewing a DICOM image within :ref:`Orthanc | |
141 Explorer <orthanc-explorer>`: | |
142 | |
143 .. image:: images/PreviewInstance.png | |
144 :align: center | |
145 :width: 400px | |
146 | |
147 | |
148 Model of the real world | |
149 ^^^^^^^^^^^^^^^^^^^^^^^ | |
150 | |
151 This concludes our overview of the DICOM file format itself. It is now | |
152 important to give an overview of the so-called "**DICOM model of the | |
153 real world**" (`source | |
154 <http://medical.nema.org/medical/dicom/current/output/html/part04.html#sect_C.6.1.1>`__): | |
155 | |
156 .. image:: images/PS3.4_C.6-1.svg | |
157 :align: center | |
158 :height: 400px | |
159 | |
160 This UML diagram shows that a given **patient** benefits during her | |
161 life from a set of medical imaging **studies**. Each study is made of | |
162 a set of **series**. Each series is in turn a set of **instances**, | |
163 the latter being a synonym for a single DICOM file. In Orthanc's | |
164 vocabulary, a **DICOM resource** is an umbrella term to talk either | |
165 about a patient, a study, a series or an instance. | |
166 | |
167 Any imaging study can be associated with multiple series of | |
168 images. This is especially visible with nuclear medicine, as any | |
169 `PET-CT-scan <https://en.wikipedia.org/wiki/PET-CT>`__ study will | |
170 contain at least two separate series: the CT series and the PET | |
171 series. But any kind of imaging study will usually generate a set of | |
172 separate series. In general, a series can be thought of as either a | |
173 single 2D image (as in standard `digital radiography | |
174 <https://en.wikipedia.org/wiki/Digital_radiography>`__), a single 3D | |
175 volume (as in a `CT-scan <https://en.wikipedia.org/wiki/CT_scan>`__), | |
176 or a 2D+t cine sequence. But a series might also encode a single PDF | |
177 report, a `structured report | |
178 <http://www.dclunie.com/pixelmed/DICOMSR.book.pdf>`__, a 3D+t image | |
179 (i.e. a temporal sequence of 3D images)... | |
180 | |
181 In any case, the actual pixel data of a given series is spread across | |
182 multiple DICOM instances. This allows to split a single huge image | |
183 (medical imaging commonly deals with 4GB images) into hundreds of | |
184 small files of several megabytes, each of which can entirely fit in | |
185 the computer memory, at the price of a severe redundancy of the | |
186 medical information that is embedded within these files. | |
187 | |
188 For each of these 4 kinds of DICOM resources, the DICOM standard | |
189 specifies a **module** as a set of DICOM tags that describe these | |
190 resources. For instance, the DICOM tag *PatientName* is part of the | |
191 patient module, whereas *SeriesDescription* is part of the series | |
192 module. Any storage service-object pair (as :ref:`defined above | |
193 <dicom-tags>`) can be decomposed into a set of modules that make sense | |
194 for its associated type of modality, and whose conjunction forms | |
195 encodes all the medical information. | |
196 | |
197 According to this model of the real world, the default Web interface | |
198 of Orthanc allows to browse from the patient level to the instance | |
199 level. Here is how :ref:`Orthanc Explorer <orthanc-explorer>` displays | |
200 a series: | |
201 | |
202 .. image:: images/RealWorld.png | |
203 :align: center | |
204 :width: 450px | |
205 | |
206 | | |
207 | |
208 On the left side of the interface, an overview of the patient module, | |
209 the study module and the series module is displayed. On the right side, | |
210 the multiple instances of the series are accessible. | |
211 | |
212 | |
213 .. _dicom-identifiers: | |
214 | |
215 DICOM identifiers | |
216 ^^^^^^^^^^^^^^^^^ | |
217 | |
218 Very importantly, the DICOM standard specifies DICOM tags that allow | |
219 to index each single DICOM resource: | |
220 | |
221 * Patients are indexed with ``PatientID (0x0010, 0x0020)`` (part of the patient module). | |
222 * Studies are indexed with ``StudyInstanceUID (0x0020, 0x000d)`` (part of the study module). | |
223 * Series are indexed with ``SeriesInstanceUID (0x0020, 0x000e)`` (part of the series module). | |
224 * Instances are indexed with ``SOPInstanceUID (0x0008, 0x0018)`` (part of the SOP module). | |
225 | |
226 The DICOM standard orders *StudyInstanceUID*, *SeriesInstanceUID* and | |
227 *SOPInstanceUID* to be `globally unique | |
228 <https://en.wikipedia.org/wiki/Globally_unique_identifier>`__. In | |
229 other words, it is mandatory for two different imaging devices to | |
230 never generate the same identifiers, even if they are manufactured by | |
231 different vendors. Orthanc exploits this rule to derive its :ref:`own | |
232 unique identifiers <orthanc-ids>`. | |
233 | |
234 Importantly, even if the *PatientID* must be unique inside a given | |
235 hospital, it is not guaranteed to be globally unique. This means that | |
236 different patients imaged in different hospitals might share the same | |
237 *PatientID*. For this reason, you should always browse from the study | |
238 level (and not from the patient level) as soon as you deal with an | |
239 application that handles patients from different hospitals. | |
240 | |
241 *Note:* The current version of the :ref:`Orthanc Explorer | |
21 | 242 <orthanc-explorer>` interface (1.1.0 at the time of writing) is |
0 | 243 designed for single-hospital scenarios, and thus does not provide |
244 study-level access. But the core engine of Orthanc does support | |
245 study-level access through its :ref:`REST API <rest>`. | |
246 | |
247 Finally, the patient module is not always fully meaningful. This is | |
248 for instance the case in emergency imaging, where the `radiology | |
249 information system | |
250 <https://en.wikipedia.org/wiki/Radiology_information_system>`__ might | |
251 not have previously encountered the imaged patient. In such a case, an | |
252 unique ``AccessionNumber (0x0008, 0x0050)`` is associated with the | |
253 imaging study by the imaging device of the emergency room: The patient | |
254 module will be injected later on in the PACS once the administrative | |
255 information is available, as part of a reconciliation process. | |
256 | |
257 In any case, the core engine Orthanc keeps an index of all these DICOM | |
258 identifiers (*PatientID*, *AccessionNumber*, *StudyInstanceUID*, | |
259 *SeriesInstanceUID* and *SOPInstanceUID*) and is able to quickly maps | |
260 them to its own :ref:`internal identifiers <orthanc-ids>`. This lookup | |
261 is implemented by the ``/tools/lookup`` URI of the :ref:`REST API of | |
262 Orthanc <rest>`. | |
263 | |
264 | |
265 DICOM network protocol | |
266 ---------------------- | |
267 | |
268 This concludes our overview of the DICOM file format. :ref:`As written | |
269 above <dicom-format>`, we now describe the second main part of the | |
270 DICOM standard, i.e. the **DICOM network protocol**. | |
271 | |
272 | |
273 .. _dicom-protocol-overview: | |
274 | |
275 Overview | |
276 ^^^^^^^^ | |
277 | |
278 The DICOM protocol is actually one of the earliest example of `Web | |
279 services <https://en.wikipedia.org/wiki/Web_service>`__, long before | |
280 the introduction of `SOAP <https://en.wikipedia.org/wiki/SOAP>`__ or | |
281 `REST | |
282 <https://en.wikipedia.org/wiki/Representational_state_transfer>`__. It | |
283 allows to: | |
284 | |
285 1. **Test the connection** between two devices (:ref:`C-Echo | |
286 <dicom-echo>`). | |
287 2. **Send images** from the local imaging device to a remote device | |
288 (:ref:`C-Store <dicom-store>`). | |
289 3. **Search the content** of a remote device (:ref:`C-Find <dicom-find>`). | |
290 4. **Retrieve images** from a remote device (:ref:`C-Move <dicom-move>`). | |
291 | |
292 Here is a picture that summarizes some key concepts: | |
293 | |
294 .. image:: images/Protocol.svg | |
295 :height: 200px | |
296 :align: center | |
297 | |
298 In the DICOM terminology, the client of a DICOM service is called a | |
299 **service class user** (SCU), and the server that handles the requests | |
300 is called a **service class provider** (SCP). The client sends a | |
301 request that is encoded as a DICOM file (the **command**), and the | |
302 server answers with a DICOM file. | |
303 | |
304 The connection of a DICOM client to a DICOM server is called an | |
305 **association**. Such an association starts with a handshake where the | |
306 client and the server agree on which commands can be exchanged between | |
307 them, and on which :ref:`transfer syntaxes <dicom-pixel-data>` are | |
308 supported. The result of this negotiation is called the **presentation | |
309 context**. Once the association is negotiated, this communication | |
310 channel can be used to successively send multiple, independent | |
311 commands. | |
312 | |
313 | |
314 Parameters of a DICOM server | |
315 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
316 | |
317 Historically, the DICOM protocol was designed to work over | |
318 `point-to-point links | |
319 <https://en.wikipedia.org/wiki/Point-to-point_(telecommunications)>`__. | |
320 Nowadays, the DICOM protocol is used over the `TCP/IP stack | |
321 <https://en.wikipedia.org/wiki/Internet_protocol_suite>`__. This | |
322 implies that a DICOM server can be identified by specifying the | |
323 parameters of its `network socket | |
324 <https://en.wikipedia.org/wiki/Network_socket>`__: | |
325 | |
326 1. Its **IP address** (or, equivalently, its symbolic DNS hostname). | |
327 2. Its **TCP port** (the standard DICOM port is 104, but Orthanc uses | |
328 the non-priviliged port 4242 by default). | |
329 | |
330 Furthermore, each imaging device (may it be a client or a server) must | |
331 be associated with a symbolic name that is called the **application | |
332 entity title (AET)**. The AET is assumed to be unique inside the | |
333 Intranet of the hospital. For best compatibility between vendors, the | |
334 AET should be only made of alphanumeric characters in upper case (plus | |
335 the "``-``" and "``_``" characters), and its length must be below 16 | |
336 characters. | |
337 | |
338 Taken together, the IP address, the TCP port and the AET describe all | |
339 the parameters of a DICOM server. The administrators of a medical | |
340 imaging network should carefully keep track of these parameters for | |
341 each imaging device, and should define an hospital-wide policy to | |
342 assign AETs to new devices. | |
343 | |
344 | |
345 Configuring Orthanc | |
346 ^^^^^^^^^^^^^^^^^^^ | |
347 | |
348 Orthanc can act both as a DICOM client and as a DICOM server, | |
349 depending on the parameters in its :ref:`configuration file | |
350 <configuration>`. To configure the **DICOM server** of Orthanc, the | |
351 following options are especially important: | |
352 | |
353 1. ``DicomServerEnabled`` must be set to ``true``. | |
354 2. ``DicomAet`` must be set to the AET that is reserved to Orthanc. | |
355 3. ``DicomPort`` specifies the TCP port of the DICOM server. | |
356 | |
357 To configure Orthanc as a **DICOM client**, you must list the remote DICOM | |
358 servers that are known to Orthanc into the ``DicomModalities`` option. | |
359 For each remote server, you must specify in the following order: | |
360 | |
361 1. An user-friendly, symbolic name for the server that will be | |
362 displayed by :ref:`Orthanc Explorer <orthanc-explorer>` (possibly | |
363 its AET). | |
364 2. The AET of the remote server. | |
365 3. Its IP address or its hostname. | |
366 4. Its DICOM port (most probably 104, or 4242 if the remote server is | |
367 another instance of Orthanc). | |
368 | |
369 Of course, after any change to the configuration of Orthanc, the | |
370 software must be restarted to take the new parameters into account. | |
371 | |
372 | |
373 .. _dicom-echo: | |
374 | |
375 C-Echo: Testing connectivity | |
376 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
377 | |
378 Routers might block the DICOM protocol between separate `subnets | |
379 <https://en.wikipedia.org/wiki/Subnetwork>`__ (often, only the HTTP, | |
380 HTTPS and SSH protocols are enabled by default). Furthermore, the | |
381 firewalls that are installed on the clients or on the servers might | |
382 also block the DICOM protocol. This is especially true for the | |
383 `Microsoft Windows firewall | |
384 <https://en.wikipedia.org/wiki/Windows_Firewall>`__ and for | |
385 :ref:`RedHat-based Linux boxes <redhat>`. As a consequence, after any | |
386 change in the DICOM topology of an hospital (notably when connecting | |
387 two imaging devices), one should always check whether the DICOM | |
388 protocol can travel from end to end, i.e. between the DICOM client | |
389 and the DICOM server. | |
390 | |
391 This is where the **DICOM Echo service** comes into play. This service | |
392 is triggered when the client sends a so-called ``C-Echo`` command to | |
393 the server as its DICOM query. The server answers with an empty DICOM | |
394 answer. In practice, to test the connectivity between two devices, you | |
395 should: | |
396 | |
397 1. Use the standard command-line tool ``ping`` to test the **TCP-level | |
398 connectivity** between the client and the server, then | |
399 2. Issue the **C-Echo** from the client to the server to test the | |
400 DICOM-level connectivity. | |
401 | |
402 The second step can be done directly from :ref:`Orthanc Explorer | |
403 <orthanc-explorer>`, the embedded administrative interface of Orthanc, | |
404 in the "*Query/Retrieve*" panel, as depicted below: | |
405 | |
406 .. image:: images/Echo.png | |
407 :align: center | |
408 :width: 450px | |
409 | |
410 | | |
411 | |
412 In this screenshot, ``sample`` corresponds to the symbolic name of a | |
413 DICOM server that is declared in the ``DicomModalities`` | |
414 :ref:`configuration option <configuration>`. Once DICOM Echo succeeds, | |
415 the client should be able to send images to the server, and to | |
416 initiate a query/retrieve. This is the topic of the following | |
417 sections. | |
418 | |
419 | |
420 .. _dicom-store: | |
421 | |
422 C-Store: Sending images to a server | |
423 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
424 | |
425 The **DICOM Store Service** is used to send DICOM instances to a | |
426 remote imaging device. This service is triggered when the client sends | |
427 to the server a so-called ``C-Store`` command together with the | |
428 content of a DICOM instance. Schematically, C-Store works as follows: | |
429 | |
430 .. image:: images/CStore.svg | |
431 :align: center | |
432 :width: 500px | |
433 | |
434 Orthanc can act both as a C-Store client (SCU) or as a C-Store server | |
435 (SCP). In other words, it can either send or receive DICOM files. | |
436 | |
437 In the :ref:`Orthanc Explorer <orthanc-explorer>` interface, each | |
438 DICOM resource (patient, study, series or instance) comes with a | |
439 button entitled "*Send to remote modality*". Clicking on this button | |
440 allows to send the image to any DICOM server that is declared in the | |
441 ``DicomModalities`` :ref:`configuration option <configuration>`. In | |
442 the following screenshot, all the instances of one patient will be | |
443 sent to the device whose symbolic name is ``sample``: | |
444 | |
445 .. image:: images/CStoreGui.png | |
446 :align: center | |
447 :width: 450px | |
448 | |
449 | |
450 .. _dicom-find: | |
451 | |
452 C-Find: Browsing the content of a server | |
453 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
454 | |
455 The **DICOM Find Service** is used to **search** a list of DICOM | |
456 resources that are hosted by some remote DICOM server. The kind of | |
457 resource that is looked for (patients, studies or series) must be | |
458 specified, leading to the **query level** of the query. Besides the | |
459 query level, the query contains a set of filters on DICOM tags of | |
460 interest: These filters are essentially `wildcards | |
461 <https://en.wikipedia.org/wiki/Glob_(programming)>`__ describing the | |
462 resources that are looked for. This service is triggered when the | |
463 client sends to the server a so-called ``C-Find`` command that encodes | |
464 the query level and the filters. Schematically, C-Find works as | |
465 follows: | |
466 | |
467 .. image:: images/CFind.svg | |
468 :align: center | |
469 :width: 500px | |
470 | |
471 Orthanc can act both as a C-Find client (SCU) or as a C-Find server | |
472 (SCP). In other words, it can be used to search the content of a | |
473 remote server, and conversely it can inform a remote client about its | |
474 own content. | |
475 | |
476 In the :ref:`Orthanc Explorer <orthanc-explorer>` interface, it | |
477 is possible to initiate a search at the study level. This feature | |
478 is available in the "*Query/Retrieve*" panel, as depicted below: | |
479 | |
480 .. image:: images/CFindGui1.png | |
481 :align: center | |
482 :width: 500px | |
483 | |
484 | | |
485 | |
486 This screenshot shows that we are looking for a study whose associated | |
487 patient has a name that starts with "*Brain*", and that is of MR | |
488 modality. Orthanc Explorer then lists the matching studies: | |
489 | |
490 .. image:: images/CFindGui2.png | |
491 :align: center | |
492 :width: 500px | |
493 | |
494 | | |
495 | |
496 It is then possible to click on some matching study, to list the | |
497 individual series it is made of: | |
498 | |
499 .. image:: images/CFindGui3.png | |
500 :align: center | |
501 :width: 500px | |
502 | |
503 | |
504 .. _dicom-move: | |
505 | |
506 C-Move: Query/retrieve | |
507 ^^^^^^^^^^^^^^^^^^^^^^ | |
508 | |
509 This brings us to the last important component of the DICOM network | |
510 protocol, the **DICOM Move Service**. This service is notably used to | |
511 locally retrieve DICOM files from a remote server, given the results | |
512 of a :ref:`C-Find query <dicom-find>`. Taken together, ``C-Find`` and | |
513 ``C-Move`` give rise to the **query/retrieve** mechanism at is at the | |
514 core of the exchange of DICOM files within the hospital. | |
515 | |
516 C-Move is probably the part of the DICOM standard that is the less | |
517 intuitive, which leads to many configuration problems in medical | |
518 imaging networks. This stems from the fact that C-Move is actually not | |
519 limited to query/retrieve. It is a more generic protocol that can | |
520 involve up to **3 distinct imaging devices**, as depicted below: | |
521 | |
522 .. image:: images/CMove.svg | |
523 :align: center | |
524 :width: 500px | |
525 | |
526 Whenever an imaging device (called the *issuer* above) initiates a | |
527 C-Move command, it asks a DICOM server (called the *source* above) to | |
528 send some of its images to another DICOM server (called the *target* | |
529 above). Accordingly, a C-Move command encodes the :ref:`identifiers | |
530 <dicom-identifiers>` of the DICOM resources to be sent, together with | |
531 the AET of the target server. To put it in other words, a C-Move | |
532 command drives a **C-Store between two remote DICOM servers** (the | |
533 *source* and the *target*). | |
534 | |
535 The query/retrieve mechanism corresponds to the special case of a | |
536 C-Move command where the target and the issuer are the same imaging | |
537 device. The most common configuration problem for query/retrieve is | |
538 therefore to forget to declare the AET of the "*issuer/target*" device | |
539 into the configuration of the "*source*" device. | |
540 | |
541 Orthanc can act both as a C-Move client (SCU) or as a C-Move server | |
542 (SCP). This implies that Orthanc can either initiate a query/retrieve, | |
543 or be driven as part of a query/retrieve request. You might want to | |
544 give a look at the ":ref:`query-retrieve`" section of this book to | |
545 learn how to concretely configure Orthanc for query/retrieve. | |
546 | |
547 A C-Move session can be initiated from the :ref:`Orthanc Explorer | |
548 <orthanc-explorer>` interface, after a :ref:`C-Find query | |
549 <dicom-find>` is complete. It is sufficient to click on the download | |
550 button that is to the right of the study or series of interest: | |
551 | |
552 .. image:: images/CMoveGui1.png | |
553 :align: center | |
554 :width: 500px | |
555 | |
556 | | |
557 | |
558 A dialog box then pops up, asking the AET of the *target* modality. | |
559 By default, this field is pre-filled with the AET of Orthanc, which | |
560 corresponds to the initiation of a query/retrieve: | |
561 | |
562 .. image:: images/CMoveGui2.png | |
563 :align: center | |
564 :width: 500px | |
565 | |
566 | | |
567 | |
9
6e99967d3503
C-GET is not deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
568 *Note 1:* Even if C-Move may seem counter-intuitive, this is the most |
6e99967d3503
C-GET is not deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
569 popular and widespread way to initiate a query/retrieve against a PACS |
6e99967d3503
C-GET is not deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
570 server. The DICOM standard features an `alternative mechanism called |
6e99967d3503
C-GET is not deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
571 C-Get |
6e99967d3503
C-GET is not deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
572 <http://dclunie.blogspot.be/2016/05/to-c-move-is-human-to-c-get-divine.html>`_. |
21 | 573 As of Orthanc 1.1.0, C-Get is not supported yet (but work is in |
9
6e99967d3503
C-GET is not deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
574 progress). |
0 | 575 |
576 *Note 2:* As :ref:`written above <dicom-pixel-data>`, the Orthanc | |
577 engine is quite generic and is compatible with virtually any image | |
578 compression algorithm (aka. transfer syntax). In particular, during | |
579 the :ref:`negotiation of a presentation context | |
580 <dicom-protocol-overview>`, Orthanc reports by default that it is | |
581 compatible with the JPEG 2000 encoding. This leads some PACS engines | |
582 to compress their images before sending them to Orthanc, so as to | |
583 reduce the network bandwidth. Unfortunately, because many medical | |
584 image analysis software are not compatible with such an image | |
585 compression, the JPEG 2000 image that is received by Orthanc might be | |
586 unusable by such software. You might therefore have to **disable | |
587 transfer syntaxes** by setting the ``*TransferSyntaxAccepted`` options | |
588 to ``false`` in the :ref:`configuration file of Orthanc | |
589 <configuration>` (by default, all the transfer syntaxes are enabled). | |
590 | |
591 | |
592 | |
593 Using HTTP instead of the DICOM protocol | |
594 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
595 | |
596 We conclude this brief overview of DICOM by insisting on the fact that | |
597 the **DICOM protocol inherently targets the Intranet** of a single | |
598 hospital, not the Internet or the cloud. This protocol might be | |
599 blocked by outbound firewalls, and there is no convention ensuring | |
600 that the AETs are globally unique across all the | |
601 hospitals. Furthermore, even though the DICOM protocol supports TLS | |
602 encryption, this feature is rarely enabled. | |
603 | |
604 Depending on your application, you might therefore want to leverage | |
605 the **HTTP protocol** in the context of DICOM. Such Web-based | |
606 protocols are probably more familiar to physicians/physicists/software | |
607 engineers, are easier to work with, can be transparently encrypted | |
608 (**HTTPS**), and are compatible with multiple-hospital scenarios. To | |
609 this end, you have two possibilities: | |
610 | |
611 1. Resort to the :ref:`Orthanc peer <peers>` mechanism. Because each | |
612 Orthanc server comes with its built-in :ref:`REST API <rest>`, | |
613 remote systems can obtain a full programmatic control over the | |
614 content of Orthanc. This access can be secured by HTTP | |
615 authentication and :ref:`SSL encryption <https>`. The :ref:`Orthanc | |
616 Explorer <orthanc-explorer>` interface can transparently use this | |
617 peer mechanism to send DICOM files over HTTP(S). | |
618 2. Resort to the `DICOMweb standard <http://www.dicomweb.org/>`__, | |
619 that is an extension to the DICOM standard specifying how to access | |
620 the content of a remote DICOM server through HTTP(S). Because the | |
621 peer mechanism is bound to Orthanc, DICOMweb offers a less | |
622 expressive, but more generic access to remote servers. | |
623 Importantly, a `DICOMweb plugin to Orthanc | |
624 <http://www.orthanc-server.com/static.php?page=dicomweb>`__ is | |
625 freely available. |