Mercurial > hg > orthanc-book
annotate Sphinx/source/dicom-guide.rst @ 331:48673b8abae3
documentation of storage commitment scu
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Wed, 11 Mar 2020 15:32:21 +0100 |
| parents | a363714813b2 |
| children | 011b01ccf52d |
| 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 | |
| 25 | 18 <http://dicom.nema.org/medical/dicom/current/output/html/>`__. |
| 0 | 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 | |
| 28 | 148 .. _model-world: |
| 149 | |
| 0 | 150 Model of the real world |
| 151 ^^^^^^^^^^^^^^^^^^^^^^^ | |
| 152 | |
| 153 This concludes our overview of the DICOM file format itself. It is now | |
| 154 important to give an overview of the so-called "**DICOM model of the | |
| 155 real world**" (`source | |
| 25 | 156 <http://dicom.nema.org/medical/dicom/current/output/html/part04.html#sect_C.6.1.1>`__): |
| 0 | 157 |
| 158 .. image:: images/PS3.4_C.6-1.svg | |
| 159 :align: center | |
| 160 :height: 400px | |
| 161 | |
| 162 This UML diagram shows that a given **patient** benefits during her | |
| 163 life from a set of medical imaging **studies**. Each study is made of | |
| 164 a set of **series**. Each series is in turn a set of **instances**, | |
| 165 the latter being a synonym for a single DICOM file. In Orthanc's | |
| 166 vocabulary, a **DICOM resource** is an umbrella term to talk either | |
| 167 about a patient, a study, a series or an instance. | |
| 168 | |
| 169 Any imaging study can be associated with multiple series of | |
| 170 images. This is especially visible with nuclear medicine, as any | |
| 171 `PET-CT-scan <https://en.wikipedia.org/wiki/PET-CT>`__ study will | |
| 172 contain at least two separate series: the CT series and the PET | |
| 173 series. But any kind of imaging study will usually generate a set of | |
| 174 separate series. In general, a series can be thought of as either a | |
| 175 single 2D image (as in standard `digital radiography | |
| 176 <https://en.wikipedia.org/wiki/Digital_radiography>`__), a single 3D | |
| 177 volume (as in a `CT-scan <https://en.wikipedia.org/wiki/CT_scan>`__), | |
| 178 or a 2D+t cine sequence. But a series might also encode a single PDF | |
| 179 report, a `structured report | |
| 180 <http://www.dclunie.com/pixelmed/DICOMSR.book.pdf>`__, a 3D+t image | |
| 181 (i.e. a temporal sequence of 3D images)... | |
| 182 | |
| 183 In any case, the actual pixel data of a given series is spread across | |
| 184 multiple DICOM instances. This allows to split a single huge image | |
| 185 (medical imaging commonly deals with 4GB images) into hundreds of | |
| 186 small files of several megabytes, each of which can entirely fit in | |
| 187 the computer memory, at the price of a severe redundancy of the | |
| 188 medical information that is embedded within these files. | |
| 189 | |
| 190 For each of these 4 kinds of DICOM resources, the DICOM standard | |
| 191 specifies a **module** as a set of DICOM tags that describe these | |
| 192 resources. For instance, the DICOM tag *PatientName* is part of the | |
| 193 patient module, whereas *SeriesDescription* is part of the series | |
| 194 module. Any storage service-object pair (as :ref:`defined above | |
| 195 <dicom-tags>`) can be decomposed into a set of modules that make sense | |
| 196 for its associated type of modality, and whose conjunction forms | |
| 197 encodes all the medical information. | |
| 198 | |
| 199 According to this model of the real world, the default Web interface | |
| 200 of Orthanc allows to browse from the patient level to the instance | |
| 201 level. Here is how :ref:`Orthanc Explorer <orthanc-explorer>` displays | |
| 202 a series: | |
| 203 | |
| 204 .. image:: images/RealWorld.png | |
| 205 :align: center | |
| 206 :width: 450px | |
| 207 | |
| 208 | | |
| 209 | |
| 210 On the left side of the interface, an overview of the patient module, | |
| 211 the study module and the series module is displayed. On the right side, | |
| 212 the multiple instances of the series are accessible. | |
| 213 | |
| 214 | |
| 215 .. _dicom-identifiers: | |
| 216 | |
| 217 DICOM identifiers | |
| 218 ^^^^^^^^^^^^^^^^^ | |
| 219 | |
| 220 Very importantly, the DICOM standard specifies DICOM tags that allow | |
| 221 to index each single DICOM resource: | |
| 222 | |
| 223 * Patients are indexed with ``PatientID (0x0010, 0x0020)`` (part of the patient module). | |
| 224 * Studies are indexed with ``StudyInstanceUID (0x0020, 0x000d)`` (part of the study module). | |
| 225 * Series are indexed with ``SeriesInstanceUID (0x0020, 0x000e)`` (part of the series module). | |
| 226 * Instances are indexed with ``SOPInstanceUID (0x0008, 0x0018)`` (part of the SOP module). | |
| 227 | |
| 228 The DICOM standard orders *StudyInstanceUID*, *SeriesInstanceUID* and | |
| 229 *SOPInstanceUID* to be `globally unique | |
| 230 <https://en.wikipedia.org/wiki/Globally_unique_identifier>`__. In | |
| 231 other words, it is mandatory for two different imaging devices to | |
| 232 never generate the same identifiers, even if they are manufactured by | |
| 233 different vendors. Orthanc exploits this rule to derive its :ref:`own | |
| 234 unique identifiers <orthanc-ids>`. | |
| 235 | |
| 236 Importantly, even if the *PatientID* must be unique inside a given | |
| 237 hospital, it is not guaranteed to be globally unique. This means that | |
| 238 different patients imaged in different hospitals might share the same | |
| 239 *PatientID*. For this reason, you should always browse from the study | |
| 240 level (and not from the patient level) as soon as you deal with an | |
| 241 application that handles patients from different hospitals. | |
| 242 | |
| 166 | 243 *Note:* Note that since Orthanc 1.4.0, the :ref:`Orthanc Explorer |
| 244 <orthanc-explorer>` interface provides a new tab entitled "Studies" | |
| 245 for study-level access. | |
| 0 | 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 | |
| 238 | 265 .. _dicom-protocol: |
| 266 | |
| 0 | 267 DICOM network protocol |
| 268 ---------------------- | |
| 269 | |
| 270 This concludes our overview of the DICOM file format. :ref:`As written | |
| 271 above <dicom-format>`, we now describe the second main part of the | |
| 272 DICOM standard, i.e. the **DICOM network protocol**. | |
| 273 | |
| 274 | |
| 275 .. _dicom-protocol-overview: | |
| 276 | |
| 277 Overview | |
| 278 ^^^^^^^^ | |
| 279 | |
| 280 The DICOM protocol is actually one of the earliest example of `Web | |
| 281 services <https://en.wikipedia.org/wiki/Web_service>`__, long before | |
| 282 the introduction of `SOAP <https://en.wikipedia.org/wiki/SOAP>`__ or | |
| 283 `REST | |
| 284 <https://en.wikipedia.org/wiki/Representational_state_transfer>`__. It | |
| 285 allows to: | |
| 286 | |
| 287 1. **Test the connection** between two devices (:ref:`C-Echo | |
| 288 <dicom-echo>`). | |
| 289 2. **Send images** from the local imaging device to a remote device | |
| 290 (:ref:`C-Store <dicom-store>`). | |
| 291 3. **Search the content** of a remote device (:ref:`C-Find <dicom-find>`). | |
| 292 4. **Retrieve images** from a remote device (:ref:`C-Move <dicom-move>`). | |
| 293 | |
| 294 Here is a picture that summarizes some key concepts: | |
| 295 | |
| 296 .. image:: images/Protocol.svg | |
| 297 :height: 200px | |
| 298 :align: center | |
| 299 | |
| 300 In the DICOM terminology, the client of a DICOM service is called a | |
| 301 **service class user** (SCU), and the server that handles the requests | |
| 302 is called a **service class provider** (SCP). The client sends a | |
| 303 request that is encoded as a DICOM file (the **command**), and the | |
| 304 server answers with a DICOM file. | |
| 305 | |
| 306 The connection of a DICOM client to a DICOM server is called an | |
| 307 **association**. Such an association starts with a handshake where the | |
| 308 client and the server agree on which commands can be exchanged between | |
| 309 them, and on which :ref:`transfer syntaxes <dicom-pixel-data>` are | |
| 310 supported. The result of this negotiation is called the **presentation | |
| 311 context**. Once the association is negotiated, this communication | |
| 312 channel can be used to successively send multiple, independent | |
| 313 commands. | |
| 314 | |
| 315 | |
| 316 Parameters of a DICOM server | |
| 317 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 318 | |
| 319 Historically, the DICOM protocol was designed to work over | |
| 320 `point-to-point links | |
| 321 <https://en.wikipedia.org/wiki/Point-to-point_(telecommunications)>`__. | |
| 322 Nowadays, the DICOM protocol is used over the `TCP/IP stack | |
| 323 <https://en.wikipedia.org/wiki/Internet_protocol_suite>`__. This | |
| 324 implies that a DICOM server can be identified by specifying the | |
| 325 parameters of its `network socket | |
| 326 <https://en.wikipedia.org/wiki/Network_socket>`__: | |
| 327 | |
| 328 1. Its **IP address** (or, equivalently, its symbolic DNS hostname). | |
| 329 2. Its **TCP port** (the standard DICOM port is 104, but Orthanc uses | |
| 330 the non-priviliged port 4242 by default). | |
| 331 | |
| 332 Furthermore, each imaging device (may it be a client or a server) must | |
| 333 be associated with a symbolic name that is called the **application | |
| 334 entity title (AET)**. The AET is assumed to be unique inside the | |
| 335 Intranet of the hospital. For best compatibility between vendors, the | |
| 336 AET should be only made of alphanumeric characters in upper case (plus | |
| 337 the "``-``" and "``_``" characters), and its length must be below 16 | |
| 338 characters. | |
| 339 | |
| 340 Taken together, the IP address, the TCP port and the AET describe all | |
| 341 the parameters of a DICOM server. The administrators of a medical | |
| 342 imaging network should carefully keep track of these parameters for | |
| 343 each imaging device, and should define an hospital-wide policy to | |
| 344 assign AETs to new devices. | |
| 345 | |
| 346 | |
| 347 Configuring Orthanc | |
| 348 ^^^^^^^^^^^^^^^^^^^ | |
| 349 | |
| 350 Orthanc can act both as a DICOM client and as a DICOM server, | |
| 351 depending on the parameters in its :ref:`configuration file | |
| 352 <configuration>`. To configure the **DICOM server** of Orthanc, the | |
| 353 following options are especially important: | |
| 354 | |
| 355 1. ``DicomServerEnabled`` must be set to ``true``. | |
| 356 2. ``DicomAet`` must be set to the AET that is reserved to Orthanc. | |
| 357 3. ``DicomPort`` specifies the TCP port of the DICOM server. | |
| 358 | |
| 359 To configure Orthanc as a **DICOM client**, you must list the remote DICOM | |
| 360 servers that are known to Orthanc into the ``DicomModalities`` option. | |
| 361 For each remote server, you must specify in the following order: | |
| 362 | |
| 363 1. An user-friendly, symbolic name for the server that will be | |
| 364 displayed by :ref:`Orthanc Explorer <orthanc-explorer>` (possibly | |
| 365 its AET). | |
| 366 2. The AET of the remote server. | |
| 367 3. Its IP address or its hostname. | |
| 368 4. Its DICOM port (most probably 104, or 4242 if the remote server is | |
| 369 another instance of Orthanc). | |
| 370 | |
| 371 Of course, after any change to the configuration of Orthanc, the | |
| 372 software must be restarted to take the new parameters into account. | |
| 373 | |
| 374 | |
| 375 .. _dicom-echo: | |
| 376 | |
| 377 C-Echo: Testing connectivity | |
| 378 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 379 | |
| 380 Routers might block the DICOM protocol between separate `subnets | |
| 381 <https://en.wikipedia.org/wiki/Subnetwork>`__ (often, only the HTTP, | |
| 382 HTTPS and SSH protocols are enabled by default). Furthermore, the | |
| 383 firewalls that are installed on the clients or on the servers might | |
| 384 also block the DICOM protocol. This is especially true for the | |
| 385 `Microsoft Windows firewall | |
| 386 <https://en.wikipedia.org/wiki/Windows_Firewall>`__ and for | |
| 42 | 387 :ref:`RedHat-based GNU/Linux boxes <redhat>`. As a consequence, after |
| 388 any change in the DICOM topology of an hospital (notably when | |
| 389 connecting two imaging devices), one should always check whether the | |
| 390 DICOM protocol can travel from end to end, i.e. between the DICOM | |
| 391 client and the DICOM server. | |
| 0 | 392 |
| 393 This is where the **DICOM Echo service** comes into play. This service | |
| 394 is triggered when the client sends a so-called ``C-Echo`` command to | |
| 395 the server as its DICOM query. The server answers with an empty DICOM | |
| 396 answer. In practice, to test the connectivity between two devices, you | |
| 397 should: | |
| 398 | |
| 399 1. Use the standard command-line tool ``ping`` to test the **TCP-level | |
| 400 connectivity** between the client and the server, then | |
| 401 2. Issue the **C-Echo** from the client to the server to test the | |
| 402 DICOM-level connectivity. | |
| 403 | |
| 404 The second step can be done directly from :ref:`Orthanc Explorer | |
| 405 <orthanc-explorer>`, the embedded administrative interface of Orthanc, | |
| 406 in the "*Query/Retrieve*" panel, as depicted below: | |
| 407 | |
| 408 .. image:: images/Echo.png | |
| 409 :align: center | |
| 410 :width: 450px | |
| 411 | |
| 412 | | |
| 413 | |
| 414 In this screenshot, ``sample`` corresponds to the symbolic name of a | |
| 415 DICOM server that is declared in the ``DicomModalities`` | |
| 416 :ref:`configuration option <configuration>`. Once DICOM Echo succeeds, | |
| 417 the client should be able to send images to the server, and to | |
| 418 initiate a query/retrieve. This is the topic of the following | |
| 419 sections. | |
| 420 | |
| 421 | |
| 422 .. _dicom-store: | |
| 423 | |
| 424 C-Store: Sending images to a server | |
| 425 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 426 | |
| 427 The **DICOM Store Service** is used to send DICOM instances to a | |
| 428 remote imaging device. This service is triggered when the client sends | |
| 429 to the server a so-called ``C-Store`` command together with the | |
| 430 content of a DICOM instance. Schematically, C-Store works as follows: | |
| 431 | |
| 432 .. image:: images/CStore.svg | |
| 433 :align: center | |
| 434 :width: 500px | |
| 435 | |
| 436 Orthanc can act both as a C-Store client (SCU) or as a C-Store server | |
| 437 (SCP). In other words, it can either send or receive DICOM files. | |
| 438 | |
| 439 In the :ref:`Orthanc Explorer <orthanc-explorer>` interface, each | |
| 440 DICOM resource (patient, study, series or instance) comes with a | |
| 441 button entitled "*Send to remote modality*". Clicking on this button | |
| 442 allows to send the image to any DICOM server that is declared in the | |
| 443 ``DicomModalities`` :ref:`configuration option <configuration>`. In | |
| 444 the following screenshot, all the instances of one patient will be | |
| 445 sent to the device whose symbolic name is ``sample``: | |
| 446 | |
| 447 .. image:: images/CStoreGui.png | |
| 448 :align: center | |
| 449 :width: 450px | |
| 450 | |
| 451 | |
| 452 .. _dicom-find: | |
| 453 | |
| 454 C-Find: Browsing the content of a server | |
| 455 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 456 | |
| 457 The **DICOM Find Service** is used to **search** a list of DICOM | |
| 458 resources that are hosted by some remote DICOM server. The kind of | |
| 459 resource that is looked for (patients, studies or series) must be | |
| 460 specified, leading to the **query level** of the query. Besides the | |
| 461 query level, the query contains a set of filters on DICOM tags of | |
| 462 interest: These filters are essentially `wildcards | |
| 463 <https://en.wikipedia.org/wiki/Glob_(programming)>`__ describing the | |
| 464 resources that are looked for. This service is triggered when the | |
| 465 client sends to the server a so-called ``C-Find`` command that encodes | |
| 466 the query level and the filters. Schematically, C-Find works as | |
| 467 follows: | |
| 468 | |
| 469 .. image:: images/CFind.svg | |
| 470 :align: center | |
| 471 :width: 500px | |
| 472 | |
| 473 Orthanc can act both as a C-Find client (SCU) or as a C-Find server | |
| 474 (SCP). In other words, it can be used to search the content of a | |
| 475 remote server, and conversely it can inform a remote client about its | |
| 476 own content. | |
| 477 | |
| 478 In the :ref:`Orthanc Explorer <orthanc-explorer>` interface, it | |
| 479 is possible to initiate a search at the study level. This feature | |
| 480 is available in the "*Query/Retrieve*" panel, as depicted below: | |
| 481 | |
| 482 .. image:: images/CFindGui1.png | |
| 483 :align: center | |
| 484 :width: 500px | |
| 485 | |
| 486 | | |
| 487 | |
| 488 This screenshot shows that we are looking for a study whose associated | |
| 489 patient has a name that starts with "*Brain*", and that is of MR | |
| 490 modality. Orthanc Explorer then lists the matching studies: | |
| 491 | |
| 492 .. image:: images/CFindGui2.png | |
| 493 :align: center | |
| 494 :width: 500px | |
| 495 | |
| 496 | | |
| 497 | |
| 498 It is then possible to click on some matching study, to list the | |
| 499 individual series it is made of: | |
| 500 | |
| 501 .. image:: images/CFindGui3.png | |
| 502 :align: center | |
| 503 :width: 500px | |
| 504 | |
| 505 | |
| 506 .. _dicom-move: | |
| 507 | |
| 508 C-Move: Query/retrieve | |
| 509 ^^^^^^^^^^^^^^^^^^^^^^ | |
| 510 | |
| 511 This brings us to the last important component of the DICOM network | |
| 512 protocol, the **DICOM Move Service**. This service is notably used to | |
| 513 locally retrieve DICOM files from a remote server, given the results | |
| 514 of a :ref:`C-Find query <dicom-find>`. Taken together, ``C-Find`` and | |
| 515 ``C-Move`` give rise to the **query/retrieve** mechanism at is at the | |
| 516 core of the exchange of DICOM files within the hospital. | |
| 517 | |
| 518 C-Move is probably the part of the DICOM standard that is the less | |
| 519 intuitive, which leads to many configuration problems in medical | |
| 520 imaging networks. This stems from the fact that C-Move is actually not | |
| 521 limited to query/retrieve. It is a more generic protocol that can | |
| 522 involve up to **3 distinct imaging devices**, as depicted below: | |
| 523 | |
| 524 .. image:: images/CMove.svg | |
| 525 :align: center | |
| 526 :width: 500px | |
| 527 | |
| 528 Whenever an imaging device (called the *issuer* above) initiates a | |
| 529 C-Move command, it asks a DICOM server (called the *source* above) to | |
| 530 send some of its images to another DICOM server (called the *target* | |
| 531 above). Accordingly, a C-Move command encodes the :ref:`identifiers | |
| 532 <dicom-identifiers>` of the DICOM resources to be sent, together with | |
| 533 the AET of the target server. To put it in other words, a C-Move | |
| 534 command drives a **C-Store between two remote DICOM servers** (the | |
| 535 *source* and the *target*). | |
| 536 | |
| 537 The query/retrieve mechanism corresponds to the special case of a | |
| 538 C-Move command where the target and the issuer are the same imaging | |
| 539 device. The most common configuration problem for query/retrieve is | |
| 540 therefore to forget to declare the AET of the "*issuer/target*" device | |
| 541 into the configuration of the "*source*" device. | |
| 542 | |
| 543 Orthanc can act both as a C-Move client (SCU) or as a C-Move server | |
| 544 (SCP). This implies that Orthanc can either initiate a query/retrieve, | |
| 545 or be driven as part of a query/retrieve request. You might want to | |
| 546 give a look at the ":ref:`query-retrieve`" section of this book to | |
| 547 learn how to concretely configure Orthanc for query/retrieve. | |
| 548 | |
| 549 A C-Move session can be initiated from the :ref:`Orthanc Explorer | |
| 550 <orthanc-explorer>` interface, after a :ref:`C-Find query | |
| 551 <dicom-find>` is complete. It is sufficient to click on the download | |
| 552 button that is to the right of the study or series of interest: | |
| 553 | |
| 554 .. image:: images/CMoveGui1.png | |
| 555 :align: center | |
| 556 :width: 500px | |
| 557 | |
| 558 | | |
| 559 | |
| 560 A dialog box then pops up, asking the AET of the *target* modality. | |
| 561 By default, this field is pre-filled with the AET of Orthanc, which | |
| 562 corresponds to the initiation of a query/retrieve: | |
| 563 | |
| 564 .. image:: images/CMoveGui2.png | |
| 565 :align: center | |
| 566 :width: 500px | |
| 567 | |
| 568 | | |
| 569 | |
|
9
6e99967d3503
C-GET is not deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
570 *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
|
571 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
|
572 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
|
573 C-Get |
|
6e99967d3503
C-GET is not deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
574 <http://dclunie.blogspot.be/2016/05/to-c-move-is-human-to-c-get-divine.html>`_. |
| 157 | 575 As of Orthanc 1.4.1, 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
|
576 progress). |
| 0 | 577 |
| 578 *Note 2:* As :ref:`written above <dicom-pixel-data>`, the Orthanc | |
| 579 engine is quite generic and is compatible with virtually any image | |
| 580 compression algorithm (aka. transfer syntax). In particular, during | |
| 581 the :ref:`negotiation of a presentation context | |
| 582 <dicom-protocol-overview>`, Orthanc reports by default that it is | |
| 583 compatible with the JPEG 2000 encoding. This leads some PACS engines | |
| 584 to compress their images before sending them to Orthanc, so as to | |
| 585 reduce the network bandwidth. Unfortunately, because many medical | |
| 586 image analysis software are not compatible with such an image | |
| 587 compression, the JPEG 2000 image that is received by Orthanc might be | |
| 588 unusable by such software. You might therefore have to **disable | |
| 589 transfer syntaxes** by setting the ``*TransferSyntaxAccepted`` options | |
| 590 to ``false`` in the :ref:`configuration file of Orthanc | |
| 591 <configuration>` (by default, all the transfer syntaxes are enabled). | |
| 592 | |
| 593 | |
| 594 | |
| 595 Using HTTP instead of the DICOM protocol | |
| 596 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 597 | |
| 598 We conclude this brief overview of DICOM by insisting on the fact that | |
| 599 the **DICOM protocol inherently targets the Intranet** of a single | |
| 600 hospital, not the Internet or the cloud. This protocol might be | |
| 601 blocked by outbound firewalls, and there is no convention ensuring | |
| 602 that the AETs are globally unique across all the | |
| 603 hospitals. Furthermore, even though the DICOM protocol supports TLS | |
| 604 encryption, this feature is rarely enabled. | |
| 605 | |
| 606 Depending on your application, you might therefore want to leverage | |
| 607 the **HTTP protocol** in the context of DICOM. Such Web-based | |
| 608 protocols are probably more familiar to physicians/physicists/software | |
| 609 engineers, are easier to work with, can be transparently encrypted | |
| 610 (**HTTPS**), and are compatible with multiple-hospital scenarios. To | |
| 611 this end, you have two possibilities: | |
| 612 | |
| 613 1. Resort to the :ref:`Orthanc peer <peers>` mechanism. Because each | |
| 614 Orthanc server comes with its built-in :ref:`REST API <rest>`, | |
| 615 remote systems can obtain a full programmatic control over the | |
| 616 content of Orthanc. This access can be secured by HTTP | |
| 617 authentication and :ref:`SSL encryption <https>`. The :ref:`Orthanc | |
| 618 Explorer <orthanc-explorer>` interface can transparently use this | |
| 619 peer mechanism to send DICOM files over HTTP(S). | |
| 620 2. Resort to the `DICOMweb standard <http://www.dicomweb.org/>`__, | |
| 621 that is an extension to the DICOM standard specifying how to access | |
| 622 the content of a remote DICOM server through HTTP(S). Because the | |
| 623 peer mechanism is bound to Orthanc, DICOMweb offers a less | |
| 624 expressive, but more generic access to remote servers. | |
| 625 Importantly, a `DICOMweb plugin to Orthanc | |
| 626 <http://www.orthanc-server.com/static.php?page=dicomweb>`__ is | |
| 627 freely available. |