Mercurial > hg > orthanc-book
annotate Sphinx/source/users/rest.rst @ 203:b79ef7808f16
note about plugins
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Tue, 12 Feb 2019 16:20:52 +0100 |
| parents | 901bc7b2dbab |
| children | 7213bef30604 |
| rev | line source |
|---|---|
| 0 | 1 .. _rest: |
| 2 | |
| 3 REST API of Orthanc | |
| 4 =================== | |
| 5 | |
| 6 .. contents:: | |
| 7 :depth: 3 | |
| 8 | |
| 9 One of the major strengths of Orthanc lies in its built-in `RESTful | |
| 10 API | |
| 11 <https://en.wikipedia.org/wiki/Representational_state_transfer>`__, | |
| 12 that can be used to drive Orthanc from external applications, | |
| 13 independently of the programming language that is used to develop | |
| 14 these applications. The REST API of Orthanc gives a full programmatic | |
| 15 access to all the core features of Orthanc. | |
| 16 | |
| 17 Importantly, Orthanc Explorer (the embedded administrative interface | |
| 18 of Orthanc) entirely resorts to this REST API for all its features. | |
| 19 This implies that anything that can be done through Orthanc Explorer, | |
| 20 can also be done through REST queries. | |
| 21 | |
| 22 *Note:* All the examples are illustrated with the `cURL command-line | |
| 25 | 23 tool <https://curl.haxx.se/>`__, but equivalent calls can be readily |
| 0 | 24 transposed to any programming language that supports both HTTP and |
| 25 JSON. | |
| 26 | |
| 27 | |
| 114 | 28 .. _sending-dicom-images: |
| 29 | |
| 0 | 30 Sending DICOM images |
| 31 -------------------- | |
| 32 | |
| 33 .. highlight:: bash | |
| 34 | |
| 35 The upload of DICOM files is possible by querying the REST API using | |
| 36 the following syntax:: | |
| 37 | |
| 38 $ curl -X POST http://localhost:8042/instances --data-binary @CT.X.1.2.276.0.7230010.dcm | |
| 39 | |
| 40 .. highlight:: json | |
| 41 | |
| 42 Orthanc will respond with a JSON file that contain information about | |
| 43 the location of the stored instance, such as:: | |
| 44 | |
| 45 { | |
| 46 "ID" : "e87da270-c52b-4f2a-b8c6-bae25928d0b0", | |
| 47 "Path" : "/instances/e87da270-c52b-4f2a-b8c6-bae25928d0b0", | |
| 48 "Status" : "Success" | |
| 49 } | |
| 50 | |
| 51 .. highlight:: bash | |
| 52 | |
| 53 Note that in the case of curl, setting the ``Expect`` HTTP Header will | |
| 54 significantly `reduce the execution time of POST requests | |
| 25 | 55 <http://stackoverflow.com/questions/463144/php-http-post-fails-when-curl-data-1024/463277#463277>`__:: |
| 0 | 56 |
| 57 $ curl -X POST -H "Expect:" http://localhost:8042/instances --data-binary @CT.X.1.2.276.0.7230010.dcm | |
| 58 | |
| 59 The code distribution of Orthanc contains a `sample Python script | |
| 60 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/ImportDicomFiles/ImportDicomFiles.py>`__ | |
| 61 that recursively upload the content of some folder into Orthanc using | |
| 62 the REST API:: | |
| 63 | |
| 64 $ python ImportDicomFiles.py localhost 8042 ~/DICOM/ | |
| 65 | |
| 66 | |
| 67 .. _rest-access: | |
| 68 | |
| 69 Accessing the content of Orthanc | |
| 70 -------------------------------- | |
| 71 | |
| 72 Orthanc structures the stored DICOM resources using the "Patient, | |
| 73 Study, Series, Instance" model of the DICOM standard. Each DICOM | |
| 74 resource is associated with an :ref:`unique identifier <orthanc-ids>`. | |
| 75 | |
| 76 List all the DICOM resources | |
| 77 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 78 | |
| 79 Here is how you would list all the DICOM resources that are stored in | |
| 80 your local Orthanc instance:: | |
| 81 | |
| 82 $ curl http://localhost:8042/patients | |
| 83 $ curl http://localhost:8042/studies | |
| 84 $ curl http://localhost:8042/series | |
| 85 $ curl http://localhost:8042/instances | |
| 86 | |
| 87 Note that the result of this command is a `JSON file | |
| 25 | 88 <https://en.wikipedia.org/wiki/Json>`__ that contains an array of |
| 0 | 89 resource identifiers. The JSON file format is lightweight and can be |
| 90 parsed from almost any computer language. | |
| 91 | |
| 92 Accessing a patient | |
| 93 ^^^^^^^^^^^^^^^^^^^ | |
| 94 | |
| 95 .. highlight:: bash | |
| 96 | |
| 97 To access a single resource, add its identifier to the `URI | |
| 25 | 98 <https://en.wikipedia.org/wiki/Uniform_resource_identifier>`__. You |
| 0 | 99 would for instance retrieve the main information about one patient as |
| 100 follows:: | |
| 101 | |
| 102 $ curl http://localhost:8042/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94 | |
| 103 | |
| 104 .. highlight:: json | |
| 105 | |
| 106 Here is a possible answer from Orthanc:: | |
| 107 | |
| 108 { | |
| 109 "ID" : "07a6ec1c-1be5920b-18ef5358-d24441f3-10e926ea", | |
| 110 "MainDicomTags" : { | |
| 111 "OtherPatientIDs" : "(null)", | |
| 112 "PatientBirthDate" : "0", | |
| 113 "PatientID" : "000000185", | |
| 114 "PatientName" : "Anonymous^Unknown", | |
| 115 "PatientSex" : "O" | |
| 116 }, | |
| 117 "Studies" : [ "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15" ], | |
| 118 "Type" : "Patient" | |
| 119 } | |
| 120 | |
| 121 This is once again a JSON file. Note how Orthanc gives you a summary | |
| 122 of the main DICOM tags that correspond to the patient level. | |
| 123 | |
|
168
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
124 |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
125 .. _browsing-hierarchy: |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
126 |
| 0 | 127 Browsing from the patient down to the instance |
| 128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 129 | |
| 130 .. highlight:: bash | |
| 131 | |
| 132 The field ``Studies`` list all the DICOM studies that are associated | |
| 133 with the patient. So, considering the patient above, we would go down | |
| 134 in her DICOM hierarchy as follows:: | |
| 135 | |
| 136 $ curl http://localhost:8042/studies/9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15 | |
| 137 | |
| 138 .. highlight:: json | |
| 139 | |
| 140 And Orthanc could answer:: | |
| 141 | |
| 142 { | |
| 143 "ID" : "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15", | |
| 144 "MainDicomTags" : { | |
| 145 "AccessionNumber" : "(null)", | |
| 146 "StudyDate" : "20120716", | |
| 147 "StudyDescription" : "TestSUVce-TF", | |
| 148 "StudyID" : "23848", | |
| 149 "StudyInstanceUID" : "1.2.840.113704.1.111.7016.1342451220.40", | |
| 150 "StudyTime" : "170728" | |
| 151 }, | |
| 152 "ParentPatient" : "07a6ec1c-1be5920b-18ef5358-d24441f3-10e926ea", | |
| 153 "Series" : [ | |
| 154 "6821d761-31fb55a9-031ebecb-ba7f9aae-ffe4ddc0", | |
| 155 "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35", | |
| 156 "7384c47e-6398f2a8-901846ef-da1e2e0b-6c50d598" | |
| 157 ], | |
| 158 "Type" : "Study" | |
| 159 } | |
| 160 | |
| 161 .. highlight:: bash | |
| 162 | |
| 163 The main DICOM tags are now those that are related to the study | |
| 164 level. It is possible to retrieve the identifier of the patient in the | |
| 165 ``ParentPatient`` field, which can be used to go upward the DICOM | |
| 166 hierarchy. But let us rather go down to the series level by using the | |
| 167 ``Series`` array. The next command would return information about one | |
| 168 of the three series that have just been reported:: | |
| 169 | |
| 170 $ curl http://localhost:8042/series/2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35 | |
| 171 | |
| 172 .. highlight:: json | |
| 173 | |
| 174 Here is a possible answer:: | |
| 175 | |
| 176 { | |
| 177 "ExpectedNumberOfInstances" : 45, | |
| 178 "ID" : "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35", | |
| 179 "Instances" : [ | |
| 180 "41bc3f74-360f9d10-6ae9ffa4-01ea2045-cbd457dd", | |
| 181 "1d3de868-6c4f0494-709fd140-7ccc4c94-a6daa3a8", | |
| 182 <...> | |
| 183 "1010f80b-161b71c0-897ec01b-c85cd206-e669a3ea", | |
| 184 "e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4" | |
| 185 ], | |
| 186 "MainDicomTags" : { | |
| 187 "Manufacturer" : "Philips Medical Systems", | |
| 188 "Modality" : "PT", | |
| 189 "NumberOfSlices" : "45", | |
| 190 "ProtocolName" : "CHU/Body_PET/CT___50", | |
| 191 "SeriesDate" : "20120716", | |
| 192 "SeriesDescription" : "[WB_CTAC] Body", | |
| 193 "SeriesInstanceUID" : "1.3.46.670589.28.2.12.30.26407.37145.2.2516.0.1342458737", | |
| 194 "SeriesNumber" : "587370", | |
| 195 "SeriesTime" : "171121", | |
| 196 "StationName" : "r054-svr" | |
| 197 }, | |
| 198 "ParentStudy" : "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15", | |
| 199 "Status" : "Complete", | |
| 200 "Type" : "Series" | |
| 201 } | |
| 202 | |
| 203 It can be seen that this series comes from a PET modality. Orthanc has | |
| 204 computed that this series should contain 45 instances. | |
| 205 | |
| 206 .. highlight:: bash | |
| 207 | |
| 208 So far, we have navigated from the patient level, to the study level, | |
| 209 and finally to the series level. There only remains the instance | |
| 210 level. Let us dump the content of one of the instances:: | |
| 211 | |
| 212 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4 | |
| 213 | |
| 214 .. highlight:: json | |
| 215 | |
| 216 The instance contains the following information:: | |
| 217 | |
| 218 { | |
| 219 "FileSize" : 70356, | |
| 220 "FileUuid" : "3fd265f0-c2b6-41a2-ace8-ae332db63e06", | |
| 221 "ID" : "e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4", | |
| 222 "IndexInSeries" : 6, | |
| 223 "MainDicomTags" : { | |
| 224 "ImageIndex" : "6", | |
| 225 "InstanceCreationDate" : "20120716", | |
| 226 "InstanceCreationTime" : "171344", | |
| 227 "InstanceNumber" : "6", | |
| 228 "SOPInstanceUID" : "1.3.46.670589.28.2.15.30.26407.37145.3.2116.39.1342458737" | |
| 229 }, | |
| 230 "ParentSeries" : "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35", | |
| 231 "Type" : "Instance" | |
| 232 } | |
| 233 | |
| 234 .. highlight:: bash | |
| 235 | |
| 236 The instance has the index 6 in the parent series. The instance is | |
| 237 stored as a raw DICOM file of 70356 bytes. You would download this | |
| 238 DICOM file using the following command:: | |
| 239 | |
| 240 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/file > Instance.dcm | |
| 241 | |
| 242 | |
| 243 Accessing the DICOM fields of an instance as a JSON file | |
| 244 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 245 | |
| 246 .. highlight:: bash | |
| 247 | |
| 248 When one gets to the instance level, you can retrieve the hierarchy of | |
| 249 all the DICOM tags of this instance as a JSON file:: | |
| 250 | |
| 251 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/simplified-tags | |
| 252 | |
| 253 .. highlight:: json | |
| 254 | |
| 255 Here is a excerpt of the Orthanc answer:: | |
| 256 | |
| 257 { | |
| 258 "ACR_NEMA_2C_VariablePixelDataGroupLength" : "57130", | |
| 259 "AccessionNumber" : null, | |
| 260 "AcquisitionDate" : "20120716", | |
| 261 "AcquisitionDateTime" : "20120716171219", | |
| 262 "AcquisitionTime" : "171219", | |
| 263 "ActualFrameDuration" : "3597793", | |
| 264 "AttenuationCorrectionMethod" : "CTAC-SG", | |
| 265 <...> | |
| 266 "PatientID" : "000000185", | |
| 267 "PatientName" : "Anonymous^Unknown", | |
| 268 "PatientOrientationCodeSequence" : [ | |
| 269 { | |
| 270 "CodeMeaning" : "recumbent", | |
| 271 "CodeValue" : "F-10450", | |
| 272 "CodingSchemeDesignator" : "99SDM", | |
| 273 "PatientOrientationModifierCodeSequence" : [ | |
| 274 { | |
| 275 "CodeMeaning" : "supine", | |
| 276 "CodeValue" : "F-10340", | |
| 277 "CodingSchemeDesignator" : "99SDM" | |
| 278 } | |
| 279 ] | |
| 280 } | |
| 281 ], | |
| 282 <...> | |
| 283 "StudyDescription" : "TestSUVce-TF", | |
| 284 "StudyID" : "23848", | |
| 285 "StudyInstanceUID" : "1.2.840.113704.1.111.7016.1342451220.40", | |
| 286 "StudyTime" : "171117", | |
| 287 "TypeOfDetectorMotion" : "NONE", | |
| 288 "Units" : "BQML", | |
| 289 "Unknown" : null, | |
| 290 "WindowCenter" : "1.496995e+04", | |
| 291 "WindowWidth" : "2.993990e+04" | |
| 292 } | |
| 293 | |
| 294 .. highlight:: bash | |
| 295 | |
| 296 If you need more detailed information about the type of the variables | |
| 297 or if you wish to use the hexadecimal indexes of DICOM tags, you are | |
| 298 free to use the following URL:: | |
| 299 | |
| 300 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/tags | |
| 301 | |
| 302 Accessing the raw DICOM fields of an instance | |
| 303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 304 | |
| 305 .. highlight:: bash | |
| 306 | |
| 307 You also have the opportunity to access the raw value of the DICOM | |
| 308 tags of an instance, without going through a JSON file. Here is how | |
| 309 you would find the Patient Name of the instance:: | |
| 310 | |
| 311 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content/0010-0010 | |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
312 Anonymous^Unknown |
| 0 | 313 |
| 314 The list of all the available tags for this instance can also be retrieved easily:: | |
| 315 | |
| 316 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content | |
| 317 | |
| 318 It is also possible to recursively explore the sequences of tags:: | |
| 319 | |
| 320 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content/0008-1250/0/0040-a170/0/0008-0104 | |
| 321 For Attenuation Correction | |
| 322 | |
| 323 The command above has opened the "0008-1250" tag that is a DICOM | |
| 324 sequence, taken its first child, opened its "0040-a170" tag that is | |
| 325 also a sequence, taken the first child of this child, and returned the | |
| 326 "0008-0104" DICOM tag. | |
| 327 | |
| 328 Downloading images | |
| 329 ^^^^^^^^^^^^^^^^^^ | |
| 330 | |
| 331 .. highlight:: bash | |
| 332 | |
|
168
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
333 As :ref:`explained above <browsing-hierarchy>`, the raw DICOM file |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
334 corresponding to a single instance can be retrieved as follows:: |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
335 |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
336 $ curl http://localhost:8042/instances/609665c0-c5198aa2-8632476b-a00e0de0-e9075d94/file > Instance.dcm |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
337 |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
338 It is also possible to download a preview PNG image that corresponds |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
339 to some DICOM instance:: |
| 0 | 340 |
|
168
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
341 $ curl http://localhost:8042/instances/609665c0-c5198aa2-8632476b-a00e0de0-e9075d94/preview > Preview.png |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
342 |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
343 The resulting image will be a standard graylevel PNG image (with 8 |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
344 bits per pixel) that can be opened by any painting software. The |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
345 dynamic range of the pixel data is stretched to the [0..255] range. |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
346 An equivalent JPEG image can be downloaded by setting the `HTTP header |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
347 <https://en.wikipedia.org/wiki/List_of_HTTP_header_fields>`__ |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
348 ``Accept`` to ``image/jpeg``:: |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
349 |
| 169 | 350 $ curl -H 'Accept: image/jpeg' http://localhost:8042/instances/609665c0-c5198aa2-8632476b-a00e0de0-e9075d94/preview > Preview.jpg |
| 0 | 351 |
|
168
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
352 If you don't want to stretch the dynamic range, and create a 8bpp or |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
353 16bpp PNG image, you can use the following URIs:: |
| 0 | 354 |
|
168
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
355 $ curl http://localhost:8042/instances/609665c0-c5198aa2-8632476b-a00e0de0-e9075d94/image-uint8 > full-8.png |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
356 $ curl http://localhost:8042/instances/609665c0-c5198aa2-8632476b-a00e0de0-e9075d94/image-uint16 > full-16.png |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
357 |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
358 In these images, the values are cropped to the maximal value that can |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
359 be encoded by the target image format. The |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
360 ``/instances/{...}/image-int16`` is available as well to download |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
361 signed DICOM pixel data. |
| 0 | 362 |
|
168
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
363 Since Orthanc 1.4.2, it is also possible to download such images in |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
364 the generic `PAM format |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
365 <https://en.wikipedia.org/wiki/Netpbm#PAM_graphics_format>`__:: |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
366 |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
367 $ curl -H 'Accept: image/x-portable-arbitrarymap' http://localhost:8042/instances/609665c0-c5198aa2-8632476b-a00e0de0-e9075d94/image-uint16 > full-16.pam |
| 0 | 368 |
|
168
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
369 Users of Matlab or Octave can find related information :ref:`in the |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
370 dedicated section <matlab>`. |
| 0 | 371 |
|
168
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
372 |
|
86e92d0cc53e
information about images
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
155
diff
changeset
|
373 .. _changes: |
| 0 | 374 |
| 375 Sending resources to remote modalities | |
| 376 -------------------------------------- | |
| 377 | |
| 378 Orthanc can send its DICOM instances to remote DICOM modalities (C-Store SCU). This process | |
| 379 can be triggered by the REST API. | |
| 380 | |
| 381 Configuration | |
| 382 ^^^^^^^^^^^^^ | |
| 383 | |
| 384 .. highlight:: json | |
| 385 | |
| 386 You first have to declare the AET, the IP address and the port number | |
| 387 of the remote modality inside the :ref:`configuration file | |
| 388 <configuration>`. For instance, here is how to declare a remote | |
| 389 modality:: | |
| 390 | |
| 391 ... | |
| 392 "DicomModalities" : { | |
| 393 "sample" : [ "STORESCP", "127.0.0.1", 2000 ] | |
| 394 }, | |
| 395 ... | |
| 396 | |
| 397 .. highlight:: bash | |
| 398 | |
| 399 Such a configuration would enable Orthanc to connect to another DICOM | |
| 400 store (for instance, another Orthanc instance) that listens on the | |
| 401 localhost on the port 2000. The modalities that are known to Orthanc | |
| 402 can be queried:: | |
| 403 | |
| 404 $ curl http://localhost:8042/modalities | |
| 405 | |
| 406 | |
| 407 Sending One Resource | |
| 408 ^^^^^^^^^^^^^^^^^^^^ | |
| 409 | |
| 410 .. highlight:: bash | |
| 411 | |
| 412 Once you have identified the Orthanc identifier of the DICOM resource | |
| 413 that would like to send :ref:`as explained above <rest-access>`, you | |
| 414 would use the following command to send it:: | |
| 415 | |
| 416 $ curl -X POST http://localhost:8042/modalities/sample/store -d c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f | |
| 417 | |
| 418 The ``/sample/`` component of the URI corresponds to the identifier of | |
| 419 the remote modality, as specified above in the configuration file. | |
| 420 | |
|
173
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
421 Note that you can send isolated DICOM instances with this command, but |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
422 also entire patients, studies or series. |
| 0 | 423 |
| 424 Bulk Store SCU | |
| 425 ^^^^^^^^^^^^^^ | |
| 426 | |
| 427 .. highlight:: bash | |
| 428 | |
| 429 Each time a POST request is made to ``/modalities/.../store``, a new | |
|
173
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
430 DICOM association is possibly established. This may lead to a large |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
431 communication overhead if sending multiple isolated instances by |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
432 making one REST call for each of these instances. |
| 0 | 433 |
| 434 To circumvent this problem, you have 2 possibilities: | |
| 435 | |
| 436 1. Set the ``DicomAssociationCloseDelay`` option in the | |
| 437 :ref:`configuration file <configuration>` to a non-zero value. This | |
| 438 will keep the DICOM connection open for a certain amount of time, | |
|
173
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
439 waiting for new instances to be routed. This is useful if |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
440 autorouting images :ref:`using Lua <lua-auto-routing>`. |
| 0 | 441 |
|
173
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
442 2. It is possible to send multiple instances with a single POST |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
443 request (so-called "Bulk Store SCU", available from Orthanc |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
444 0.5.2):: |
| 0 | 445 |
| 446 $ curl -X POST http://localhost:8042/modalities/sample/store -d '["d4b46c8e-74b16992-b0f5ca11-f04a60fa-8eb13a88","d5604121-7d613ce6-c315a5-a77b3cf3-9c253b23","cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e"]' | |
| 447 | |
| 448 The list of the resources to be sent are given as a JSON array. In | |
| 449 this case, a single DICOM connection is used. `Sample code is | |
| 450 available | |
| 451 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Python/HighPerformanceAutoRouting.py>`__. | |
| 452 | |
|
173
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
453 Note that the list of resources to be sent can include the |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
454 :ref:`Orthanc identifiers <orthanc-ids>` of entire patients, |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
455 studies or series as well. |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
456 |
|
901bc7b2dbab
improved bulk store scu section
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
169
diff
changeset
|
457 |
| 0 | 458 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
459 Performing Query/Retrieve and Find with REST |
| 138 | 460 -------------------------------------------- |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
461 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
462 *Section contributed by Bryan Dearlove* |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
463 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
464 Orthanc can be used to perform queries on the local Orthanc instance, |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
465 or on remote modalities through the REST API. |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
466 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
467 To perform a query of a remote modality you must define the modality |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
468 within the :ref:`configuration file <configuration>` (See |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
469 Configuration section under Sending resources to remote modalities). |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
470 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
471 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
472 Performing Queries on Modalities |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
473 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
474 |
| 138 | 475 .. highlight:: bash |
| 476 | |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
477 To initiate a query you perform a POST command against the Modality |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
478 with the identifiers you are looking for. The the example below we are |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
479 performing a study level query against the modality sample for any |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
480 study descriptions with the word chest within it. This search is case |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
481 insensitive unless configured otherwise within the Orthanc |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
482 configuration file:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
483 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
484 $ curl --request POST \ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
485 --url http://localhost:8042/modalities/sample/query \ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
486 --data '{"Level":"Study","Query": {"PatientID":"","StudyDescription":"*Chest*","PatientName":""}}' |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
487 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
488 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
489 .. highlight:: json |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
490 |
| 138 | 491 You will receive back an ID which can be used to retrieve more |
| 492 information with GET commands or C-Move requests with a POST Command:: | |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
493 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
494 { |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
495 "ID": "5af318ac-78fb-47ff-b0b0-0df18b0588e0", |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
496 "Path": "/queries/5af318ac-78fb-47ff-b0b0-0df18b0588e0" |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
497 } |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
498 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
499 |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
500 Additional Options |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
501 ^^^^^^^^^^^^^^^^^^ |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
502 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
503 .. highlight:: json |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
504 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
505 You can use patient identifiers by including the `*` within your |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
506 search. For example if you were searching for a name beginning with |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
507 `Jones` you can do:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
508 |
| 139 | 509 "PatientName":"Jones*" |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
510 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
511 If you wanted to search for a name with the words `Jo` anywhere within |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
512 it you can do:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
513 |
| 139 | 514 "PatientName":"*Jo*" |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
515 |
| 138 | 516 To perform date searches you can specify within StudyDate a starting |
| 517 date and/or a before date. For example ``"StudyDate":"20180323-"`` | |
| 518 would search for all study dates after the specified date to | |
| 519 now. Doing ``"StudyDate":"20180323-20180325"`` would search for all | |
| 520 study dates between the specified date. | |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
521 |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
522 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
523 Reviewing Level |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
524 ^^^^^^^^^^^^^^^ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
525 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
526 .. highlight:: bash |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
527 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
528 :: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
529 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
530 $ curl --request GET --url http://localhost:8042/queries/5af318ac-78fb-47ff-b0b0-0df18b0588e0/level |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
531 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
532 Will retrieve the level with which the query was performed, Study, |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
533 Series or Instance. |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
534 |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
535 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
536 Reviewing Modality |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
537 ^^^^^^^^^^^^^^^^^^ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
538 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
539 .. highlight:: bash |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
540 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
541 :: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
542 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
543 $ curl --request GET --url http://localhost:8042/queries/5af318ac-78fb-47ff-b0b0-0df18b0588e0/modality |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
544 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
545 Will provide the modality name which the original query was performed against. |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
546 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
547 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
548 Reviewing Query |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
549 ^^^^^^^^^^^^^^^ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
550 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
551 .. highlight:: bash |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
552 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
553 To retrieve information on what identifiers the query was originally |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
554 performed using you can use the query filter:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
555 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
556 $ curl --request GET --url http://localhost:8042/queries/5af318ac-78fb-47ff-b0b0-0df18b0588e0/query |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
557 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
558 |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
559 Reviewing Query Answers |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
560 ^^^^^^^^^^^^^^^^^^^^^^^ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
561 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
562 .. highlight:: bash |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
563 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
564 You are able to individually review each answer returned by performing |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
565 a GET with the answers parameter:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
566 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
567 $ curl --request GET --url http://localhost:8042/queries/5af318ac-78fb-47ff-b0b0-0df18b0588e0/answers |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
568 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
569 You will get a JSON back with numbered identifiers for each answer you |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
570 received back. For example because we performed a Study level query we |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
571 received back 5 studies answers back. We are able to query each answer |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
572 for content details:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
573 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
574 $ curl --request GET --url http://localhost:8042/queries/5af318ac-78fb-47ff-b0b0-0df18b0588e0/answers/0/content |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
575 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
576 If there are content items missing, you may add them by adding that |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
577 identifier to the original query. For example if we wanted Modalities |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
578 listed in this JSON answer in the initial query we would add to the |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
579 POST body: `"ModalitiesInStudy":""` |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
580 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
581 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
582 Performing Retrieve (C-Move) |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
583 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
584 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
585 .. highlight:: bash |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
586 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
587 You can perform a C-Move to retrieve all studies within the original |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
588 query using a post command and identifying the Modality to be one to |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
589 in the POST contents:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
590 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
591 $ curl --request POST --url http://localhost:8042/queries/5af318ac-78fb-47ff-b0b0-0df18b0588e0/retrieve --data Orthanc |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
592 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
593 You are also able to perform individual C-Moves for a content item by |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
594 specifying that individual content item:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
595 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
596 $ curl --request POST --url http://localhost:8042/queries/5af318ac-78fb-47ff-b0b0-0df18b0588e0/answers/0/retrieve --data Orthanc |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
597 |
| 138 | 598 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
599 Performing Finds within Orthanc |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
600 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
601 .. highlight:: bash |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
602 |
| 138 | 603 Performing a find within Orthanc is very similar to using Queries |
| 604 against DICOM modalities and the additional options listed above work | |
| 605 with find also. When performing a find, you will receive the Orthanc | |
| 606 ID's of all the matched items within your find. For example if you | |
| 607 perform a study level find and 5 Studies match you will receive 5 | |
| 608 study level Orthanc ID's in JSON format as a response:: | |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
609 |
| 138 | 610 $ curl --request POST --url http://localhost:8042/tools/find --data '{"Level":"Instance","Query":{"Modality":"CR","StudyDate":"20180323-","PatientID":"*"}}' |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
611 |
| 138 | 612 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
613 Additional Options |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
614 ^^^^^^^^^^^^^^^^^^ |
| 138 | 615 .. highlight:: json |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
616 |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
617 You also have the ability to limit the responses by specifying a limit within the body of the POST message. For example:: |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
618 |
| 138 | 619 "Limit":4 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
620 |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
621 |
| 0 | 622 Tracking changes |
| 623 ---------------- | |
| 624 | |
| 625 .. highlight:: bash | |
| 626 | |
| 627 Whenever Orthanc receives a new DICOM instance, this event is recorded | |
| 628 in the so-called "Changes Log". This enables remote scripts to react | |
| 629 to the arrival of new DICOM resources. A typical application is | |
| 630 **auto-routing**, where an external script waits for a new DICOM | |
| 631 instance to arrive into Orthanc, then forward this instance to another | |
| 632 modality. | |
| 633 | |
| 634 The Changes Log can be accessed by the following command:: | |
| 635 | |
| 636 $ curl http://localhost:8042/changes | |
| 637 | |
| 638 .. highlight:: json | |
| 639 | |
| 640 Here is a typical output:: | |
| 641 | |
| 642 { | |
| 643 "Changes" : [ | |
| 644 { | |
| 645 "ChangeType" : "NewInstance", | |
| 646 "Date" : "20130507T143902", | |
| 647 "ID" : "8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe", | |
| 648 "Path" : "/instances/8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe", | |
| 649 "ResourceType" : "Instance", | |
| 650 "Seq" : 921 | |
| 651 }, | |
| 652 { | |
| 653 "ChangeType" : "NewSeries", | |
| 654 "Date" : "20130507T143902", | |
| 655 "ID" : "cceb768f-e0f8df71-511b0277-07e55743-9ef8890d", | |
| 656 "Path" : "/series/cceb768f-e0f8df71-511b0277-07e55743-9ef8890d", | |
| 657 "ResourceType" : "Series", | |
| 658 "Seq" : 922 | |
| 659 }, | |
| 660 { | |
| 661 "ChangeType" : "NewStudy", | |
| 662 "Date" : "20130507T143902", | |
| 663 "ID" : "c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f", | |
| 664 "Path" : "/studies/c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f", | |
| 665 "ResourceType" : "Study", | |
| 666 "Seq" : 923 | |
| 667 }, | |
| 668 { | |
| 669 "ChangeType" : "NewPatient", | |
| 670 "Date" : "20130507T143902", | |
| 671 "ID" : "dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94", | |
| 672 "Path" : "/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94", | |
| 673 "ResourceType" : "Patient", | |
| 674 "Seq" : 924 | |
| 675 } | |
| 676 ], | |
| 677 "Done" : true, | |
| 678 "Last" : 924 | |
| 679 } | |
| 680 | |
| 681 This output corresponds to the receiving of one single DICOM instance | |
| 682 by Orthanc. It records that a new instance, a new series, a new study | |
| 683 and a new patient has been created inside Orthanc. Note that each | |
| 684 changes is labeled by a ``ChangeType``, a ``Date`` (in the `ISO format | |
| 25 | 685 <https://en.wikipedia.org/wiki/ISO_8601>`__), the location of the |
| 0 | 686 resource inside Orthanc, and a sequence number (``Seq``). |
| 687 | |
| 688 Note that this call is non-blocking. It is up to the calling program | |
| 689 to wait for the occurrence of a new event (by implementing a polling | |
| 690 loop). | |
| 691 | |
| 692 .. highlight:: bash | |
| 693 | |
| 694 This call only returns a fixed number of events, that can be changed | |
| 695 by using the ``limit`` option:: | |
| 696 | |
| 697 $ curl http://localhost:8042/changes?limit=100 | |
| 698 | |
| 699 The flag ``Last`` records the sequence number of the lastly returned | |
| 700 event. The flag ``Done`` is set to ``true`` if no further event has | |
| 701 occurred after this lastly returned event. If ``Done`` is set to | |
| 702 ``false``, further events are available and can be retrieved. This is | |
| 703 done by setting the ``since`` option that specifies from which | |
| 704 sequence number the changes must be returned:: | |
| 705 | |
| 706 $ curl 'http://localhost:8042/changes?limit=100&since=922' | |
| 707 | |
| 708 A `sample code in the source distribution | |
| 709 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Python/ChangesLoop.py>`__ | |
| 710 shows how to use this Changes API to implement a polling loop. | |
| 711 | |
| 712 | |
| 713 Deleting resources from Orthanc | |
| 714 ------------------------------- | |
| 715 | |
| 716 .. highlight:: bash | |
| 717 | |
| 718 Deleting patients, studies, series or instances | |
| 719 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 720 | |
| 721 Deleting DICOM resources (i.e. patients, studies, series or instances) | |
| 722 from Orthanc is as simple as using a HTTP DELETE on the URI of this | |
| 723 resource. | |
| 724 | |
| 725 Concretely, you would first explore the resources that are stored in | |
| 726 Orthanc :ref:`as explained above <rest-access>`:: | |
| 727 | |
| 728 $ curl http://localhost:8042/patients | |
| 729 $ curl http://localhost:8042/studies | |
| 730 $ curl http://localhost:8042/series | |
| 731 $ curl http://localhost:8042/instances | |
| 732 | |
| 733 Secondly, once you have spotted the resources to be removed, you would | |
| 734 use the following command-line syntax to delete them:: | |
| 735 | |
| 736 $ curl -X DELETE http://localhost:8042/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94 | |
| 737 $ curl -X DELETE http://localhost:8042/studies/c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f | |
| 738 $ curl -X DELETE http://localhost:8042/series/cceb768f-e0f8df71-511b0277-07e55743-9ef8890d | |
| 739 $ curl -X DELETE http://localhost:8042/instances/8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe | |
| 740 | |
| 741 | |
| 742 Clearing log of changes | |
| 743 ^^^^^^^^^^^^^^^^^^^^^^^ | |
| 744 | |
| 745 :ref:`As described above <changes>`, Orthanc keeps track of all the | |
| 746 changes that occur in the DICOM store. This so-called "Changes Log" | |
| 747 is accessible at the following URI:: | |
| 748 | |
| 749 $ curl http://localhost:8042/changes | |
| 750 | |
| 751 To clear the content of the Changes Log, simply DELETE this URI:: | |
| 752 | |
| 753 $ curl -X DELETE http://localhost:8042/changes | |
| 754 | |
| 755 | |
| 155 | 756 Log of exported resources |
| 757 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 758 | |
| 759 For medical traceability, Orthanc can be configured to store a log of | |
| 760 all the resources that have been exported to remote modalities:: | |
| 0 | 761 |
| 762 $ curl http://localhost:8042/exports | |
| 763 | |
| 764 In auto-routing scenarios, it is important to prevent this log to grow | |
| 765 indefinitely as incoming instances are routed. You can either disable | |
| 766 this logging by setting the option ``LogExportedResources`` to ``false`` | |
| 767 in the :ref:`configuration file <configuration>`, or periodically | |
| 768 clear this log by DELETE-ing this URI:: | |
| 769 | |
| 770 $ curl -X DELETE http://localhost:8042/exports | |
| 771 | |
| 155 | 772 NB: Starting with Orthanc 1.4.0, the ``LogExportedResources`` is set |
| 773 to ``false`` by default. If the logging is desired, set this option to | |
| 774 ``true``. | |
| 775 | |
| 0 | 776 |
| 777 Anonymization and modification | |
| 778 ------------------------------ | |
| 779 | |
| 780 The process of anonymizing and modifying DICOM resources is | |
| 781 :ref:`documented in a separate page <anonymization>`. | |
| 782 | |
| 783 | |
| 784 Further reading | |
| 785 --------------- | |
| 786 | |
| 787 The examples above have shown you the basic principles for driving an | |
| 788 instance of Orthanc through its REST API. All the possibilities of the | |
|
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
789 API have not been described: |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
790 |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
791 * A :ref:`FAQ entry <rest-samples>` lists where you can find more |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
792 advanced samples of the REST API of Orthanc. |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
793 * The full documentation of the REST API is maintained as an online |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
794 spreadsheet accessible from the `documentation part of the official |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
795 Web site |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
796 <http://www.orthanc-server.com/static.php?page=documentation>`__ |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
797 (click on the *Reference of the REST API* button). |