Mercurial > hg > orthanc-book
annotate Sphinx/source/users/storage-commitment.rst @ 328:d39237f67df6
explicitly talk about DICOM storage commitment
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Thu, 05 Mar 2020 09:54:44 +0100 |
| parents | c5226c5509ca |
| children | 117be48706ba |
| rev | line source |
|---|---|
| 322 | 1 .. _storage-commitment: |
| 2 | |
|
328
d39237f67df6
explicitly talk about DICOM storage commitment
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
322
diff
changeset
|
3 DICOM storage commitment |
|
d39237f67df6
explicitly talk about DICOM storage commitment
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
322
diff
changeset
|
4 ======================== |
| 322 | 5 |
| 6 .. contents:: | |
| 7 :depth: 3 | |
| 8 | |
| 9 | |
| 10 Introduction | |
| 11 ------------ | |
| 12 | |
| 13 Starting with **release 1.6.0**, Orthanc implements DICOM storage | |
| 14 commitment, both as an SCP and as a SCU. | |
| 15 | |
| 16 Storage commitment is a feature of the DICOM standard by which an | |
| 17 imaging modality "A" asks a remote imaging modality "B", whether "B" | |
| 18 accepts responsibility for having stored the images "A" has sent to | |
| 19 it. | |
| 20 | |
| 21 Typically, a storage commitment request is issued by "A" after "A" has | |
| 22 sent images to "B" using the :ref:`DICOM C-STORE command | |
| 23 <dicom-store>`. If "B" answers that all the images have been properly | |
| 24 received, the modality "A" has the guarantee that the C-STORE commands | |
| 25 ran fine, and thus "A" might decide to remove the images from its | |
| 26 database. If "B" answers that there was an error, "A" might decide to | |
| 27 send the images again. | |
| 28 | |
| 29 For more technical information, one may refer to the storage | |
| 30 commitment `Information Object Definition | |
| 31 <http://dicom.nema.org/medical/dicom/2019e/output/html/part03.html#sect_B.15>`__ | |
| 32 and `Service Class | |
| 33 <http://dicom.nema.org/medical/dicom/2019e/output/html/part04.html#chapter_J>`__ | |
| 34 in the DICOM standard. Orthanc follows the objective of the IHE | |
| 35 Technical Framework regarding the `Storage Commitment transaction | |
| 36 (RAD-10) | |
| 37 <https://www.ihe.net/uploadedFiles/Documents/Radiology/IHE_RAD_TF_Vol2.pdf#page=160>`__. Following | |
| 38 this IHE specification, Orthanc only implements the **Storage | |
| 39 Commitment Push Model SOP Class**, both as an SCU ("Evidence Creator") | |
| 40 and as an SCP ("Image Manager"). | |
| 41 | |
| 42 Orthanc makes the assumption that the storage commitment responses are | |
| 43 sent **asynchronously**, which corresponds to most implementations of | |
| 44 storage commitment. | |
| 45 | |
| 46 | |
| 47 .. _storage-commitment-scp: | |
| 48 | |
| 49 Storage commitment SCP | |
| 50 ---------------------- | |
| 51 | |
| 52 Overview | |
| 53 ^^^^^^^^ | |
| 54 | |
| 55 Here is a diagram that outlines how storage commitment works in Orthanc: | |
| 56 | |
| 57 .. image:: ../images/StorageCommitmentSCP.svg | |
| 58 :align: center | |
| 59 :width: 650px | |
| 60 | |
| 61 | In this sequence, three DICOM associations are used: The first one | |
| 62 is the usual command to send the DICOM images from some SCU to the | |
| 63 Orthanc SCP (:ref:`C-STORE <dicom-store>`), the second association | |
| 64 is the one by which the SCU asks the Orthanc SCP to process a | |
| 65 storage commitment request (the SCU provides a list of DICOM | |
| 66 instances to be checked by specifying their SOP instance UID and | |
| 67 their SOP class UID), and the third one is the storage commitment | |
| 68 response coming from the Orthanc SCP. The response is sent | |
| 69 asynchronously from the Orthanc SCP to the SCU, once the storage | |
| 70 commitment request has been processed by Orthanc. | |
| 71 | |
| 72 The list of the DICOM modalities from which Orthanc accepts incoming | |
| 73 storage commitment requests is specified in the :ref:`configuration | |
| 74 file of Orthanc <configuration>`, by the ``DicomModalities`` | |
| 75 option. It is possible to disable storage commitment for selected | |
| 76 modalities by setting their dedicated Boolean permission flag | |
| 77 ``AllowStorageCommitment`` to ``false``. | |
| 78 | |
| 79 As can be seen, the storage commitment SCP of Orthanc also takes | |
| 80 advantage of the :ref:`jobs engine <jobs>` that is embedded within | |
| 81 Orthanc. Whenever Orthanc receives a storage commitment request, it | |
| 82 internally creates a job with a dedicated type (namely | |
| 83 ``StorageCommitmentScp``). :ref:`This job can be controlled | |
| 84 <jobs-monitoring>` using the REST API of Orthanc, just like any other | |
| 85 job. As a consequence, an external software is able to monitor, cancel | |
| 86 or pause incoming storage commitment requests, by inspecting the list | |
| 87 of jobs whose type is ``StorageCommitmentScp``. | |
| 88 | |
| 89 | |
| 90 | |
| 91 Sample usage | |
| 92 ^^^^^^^^^^^^ | |
| 93 | |
| 94 In this section, we show how to query the storage commitment SCP of | |
| 95 Orthanc from the command-line tool ``stgcmtscu``. This free and | |
| 96 open-source tool originates from the `dcm4che project | |
| 97 <https://www.dcm4che.org/>`__ and simulates a basic storage commitment | |
| 98 SCU. | |
| 99 | |
| 100 .. highlight:: json | |
| 101 | |
| 102 Firstly, we define one DICOM modality corresponding to ``stgcmtscu`` | |
| 103 by creating the following :ref:`configuration file <configuration>` | |
| 104 for Orthanc:: | |
| 105 | |
| 106 { | |
| 107 "DicomPort" : 4242, | |
| 108 "DicomModalities" : { | |
| 109 "storage-commitment" : [ "STGCMTSCU", "127.0.0.1", 11114 ] | |
| 110 } | |
| 111 } | |
| 112 | |
| 113 | |
| 114 .. highlight:: text | |
| 115 | |
| 116 Secondly, we start Orthanc using the just-created configuration file:: | |
| 117 | |
| 118 $ ./Orthanc --verbose storage-commitment.json | |
| 119 | |
| 120 We'll be using some sample file ``/tmp/DummyCT.dcm``, whose DICOM tags | |
| 121 "SOP instance UID" and "SOP class UID" can be retrieved as follows:: | |
| 122 | |
| 123 $ dcm2xml /tmp/DummyCT.dcm | grep -E '"SOPInstanceUID"|"SOPClassUID"' | |
| 124 <element tag="0008,0016" vr="UI" vm="1" len="26" name="SOPClassUID">1.2.840.10008.5.1.4.1.1.4</element> | |
| 125 <element tag="0008,0018" vr="UI" vm="1" len="54" name="SOPInstanceUID">1.2.840.113619.2.176.2025.1499492.7040.1171286242.109</element> | |
| 126 | |
| 127 Thirdly, we use ``stgcmtscu`` to get the status of one sample DICOM | |
| 128 file. Here is what can be read at the end of the logs of | |
| 129 ``stgcmtscu``:: | |
| 130 | |
| 131 $ /home/jodogne/Downloads/dcm4che-5.20.0/bin/stgcmtscu -b STGCMTSCU:11114 -c ORTHANC@localhost:4242 /tmp/DummyCT.dcm | |
| 132 [...] | |
| 133 18:14:22,949 DEBUG - STGCMTSCU<-ORTHANC(2) >> 1:N-EVENT-REPORT-RQ Dataset receiving... | |
| 134 18:14:22,949 DEBUG - Dataset: | |
| 135 (0008,1195) UI [2.25.250402771220435242864082979068071491247] TransactionUID | |
| 136 (0008,1198) SQ [1 Items] FailedSOPSequence | |
| 137 >Item #1 | |
| 138 >(0008,1150) UI [1.2.840.10008.5.1.4.1.1.4] ReferencedSOPClassUID | |
| 139 >(0008,1155) UI [1.2.840.113619.2.176.2025.1499492.7040.1171286242.109] ReferencedSOPInstanceUID | |
| 140 >(0008,1197) US [274] FailureReason | |
| 141 (0008,1199) SQ [] ReferencedSOPSequence | |
| 142 | |
| 143 As can be seen, the SOP class/instance UIDs of ``/tmp/DummyCT.dcm`` | |
| 144 are reported by the Orthanc SCP in the ``FailedSOPSequence`` field, | |
| 145 which indicates the fact that Orthanc has not stored this instance | |
| 146 yet. The ``FailureReason`` 274 corresponds to status 0x0112, namely | |
| 147 "No such object instance". | |
| 148 | |
| 149 Fourthly, let's upload the sample file, then execute ``stgcmtscu`` a | |
| 150 second time:: | |
| 151 | |
| 152 $ storescu localhost 4242 /tmp/DummyCT.dcm | |
| 153 $ /home/jodogne/Downloads/dcm4che-5.20.0/bin/stgcmtscu -b STGCMTSCU:11114 -c ORTHANC@localhost:4242 /tmp/DummyCT.dcm | |
| 154 [...] | |
| 155 18:19:48,090 DEBUG - STGCMTSCU<-ORTHANC(2) >> 1:N-EVENT-REPORT-RQ Dataset receiving... | |
| 156 18:19:48,090 DEBUG - Dataset: | |
| 157 (0008,1195) UI [2.25.141864351815234988385597655400095444069] TransactionUID | |
| 158 (0008,1199) SQ [1 Items] ReferencedSOPSequence | |
| 159 >Item #1 | |
| 160 >(0008,1150) UI [1.2.840.10008.5.1.4.1.1.4] ReferencedSOPClassUID | |
| 161 >(0008,1155) UI [1.2.840.113619.2.176.2025.1499492.7040.1171286242.109] ReferencedSOPInstanceUID | |
| 162 | |
| 163 The instance of interest is now reported in the | |
| 164 ``ReferencedSOPSequence`` tag, instead of ``FailedSOPSequence``. This | |
| 165 shows that Orthanc has properly received the sample instance. | |
| 166 | |
| 167 | |
| 168 | |
| 169 Plugins | |
| 170 ^^^^^^^ | |
| 171 | |
| 172 The Orthanc core implements a basic storage commitment SCP. This basic | |
| 173 handler simply checks for the presence of the requested DICOM | |
| 174 instances in the Orthanc database, and makes sure that their SOP class | |
| 175 UIDs do match those provided by the remote storage commitment SCU. | |
| 176 | |
| 177 For more advanced scenarios, it is possible to override this default | |
| 178 SCP to customize the way incoming storage commitment requests are | |
| 179 processed by Orthanc. This customization is done :ref:`by creating an | |
| 180 Orthanc plugin <creating-plugins>`. | |
| 181 | |
| 182 The custom storage commitment SCP is installed in the Orthanc core by | |
| 183 using the ``OrthancPluginRegisterStorageCommitmentScpCallback()`` | |
| 184 function of the `plugin SDK <http://sdk.orthanc-server.com/>`__. | |
| 185 | |
| 186 Importantly, this primitive frees the plugin developer from manually | |
| 187 creating the Orthanc jobs. One job is automatically created for each | |
| 188 incoming storage commitment request by the Orthanc core, allowing the | |
| 189 developer to focus only on the processing of the queried instances. | |
| 190 | |
| 191 Note that a `sample plugin | |
| 192 <https://bitbucket.org/sjodogne/orthanc/src/storage-commitment/Plugins/Samples/StorageCommitmentScp/>`__ | |
| 193 is also available in the source distribution of Orthanc. | |
| 194 | |
| 195 | |
| 196 | |
| 197 .. _storage-commitment-scu: | |
| 198 | |
| 199 Storage commitment SCU | |
| 200 ---------------------- | |
| 201 | |
| 202 *Work in progress* | |
| 203 | |
| 204 *Sample using dcmqrscp* |