Mercurial > hg > orthanc-book
annotate Sphinx/source/users/rest.rst @ 139:fded2e8d1d49
fix
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Tue, 24 Apr 2018 20:40:26 +0200 |
| parents | f3127d33cf5e |
| children | 498c9e42c99d |
| 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 | |
| 124 Browsing from the patient down to the instance | |
| 125 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 126 | |
| 127 .. highlight:: bash | |
| 128 | |
| 129 The field ``Studies`` list all the DICOM studies that are associated | |
| 130 with the patient. So, considering the patient above, we would go down | |
| 131 in her DICOM hierarchy as follows:: | |
| 132 | |
| 133 $ curl http://localhost:8042/studies/9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15 | |
| 134 | |
| 135 .. highlight:: json | |
| 136 | |
| 137 And Orthanc could answer:: | |
| 138 | |
| 139 { | |
| 140 "ID" : "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15", | |
| 141 "MainDicomTags" : { | |
| 142 "AccessionNumber" : "(null)", | |
| 143 "StudyDate" : "20120716", | |
| 144 "StudyDescription" : "TestSUVce-TF", | |
| 145 "StudyID" : "23848", | |
| 146 "StudyInstanceUID" : "1.2.840.113704.1.111.7016.1342451220.40", | |
| 147 "StudyTime" : "170728" | |
| 148 }, | |
| 149 "ParentPatient" : "07a6ec1c-1be5920b-18ef5358-d24441f3-10e926ea", | |
| 150 "Series" : [ | |
| 151 "6821d761-31fb55a9-031ebecb-ba7f9aae-ffe4ddc0", | |
| 152 "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35", | |
| 153 "7384c47e-6398f2a8-901846ef-da1e2e0b-6c50d598" | |
| 154 ], | |
| 155 "Type" : "Study" | |
| 156 } | |
| 157 | |
| 158 .. highlight:: bash | |
| 159 | |
| 160 The main DICOM tags are now those that are related to the study | |
| 161 level. It is possible to retrieve the identifier of the patient in the | |
| 162 ``ParentPatient`` field, which can be used to go upward the DICOM | |
| 163 hierarchy. But let us rather go down to the series level by using the | |
| 164 ``Series`` array. The next command would return information about one | |
| 165 of the three series that have just been reported:: | |
| 166 | |
| 167 $ curl http://localhost:8042/series/2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35 | |
| 168 | |
| 169 .. highlight:: json | |
| 170 | |
| 171 Here is a possible answer:: | |
| 172 | |
| 173 { | |
| 174 "ExpectedNumberOfInstances" : 45, | |
| 175 "ID" : "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35", | |
| 176 "Instances" : [ | |
| 177 "41bc3f74-360f9d10-6ae9ffa4-01ea2045-cbd457dd", | |
| 178 "1d3de868-6c4f0494-709fd140-7ccc4c94-a6daa3a8", | |
| 179 <...> | |
| 180 "1010f80b-161b71c0-897ec01b-c85cd206-e669a3ea", | |
| 181 "e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4" | |
| 182 ], | |
| 183 "MainDicomTags" : { | |
| 184 "Manufacturer" : "Philips Medical Systems", | |
| 185 "Modality" : "PT", | |
| 186 "NumberOfSlices" : "45", | |
| 187 "ProtocolName" : "CHU/Body_PET/CT___50", | |
| 188 "SeriesDate" : "20120716", | |
| 189 "SeriesDescription" : "[WB_CTAC] Body", | |
| 190 "SeriesInstanceUID" : "1.3.46.670589.28.2.12.30.26407.37145.2.2516.0.1342458737", | |
| 191 "SeriesNumber" : "587370", | |
| 192 "SeriesTime" : "171121", | |
| 193 "StationName" : "r054-svr" | |
| 194 }, | |
| 195 "ParentStudy" : "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15", | |
| 196 "Status" : "Complete", | |
| 197 "Type" : "Series" | |
| 198 } | |
| 199 | |
| 200 It can be seen that this series comes from a PET modality. Orthanc has | |
| 201 computed that this series should contain 45 instances. | |
| 202 | |
| 203 .. highlight:: bash | |
| 204 | |
| 205 So far, we have navigated from the patient level, to the study level, | |
| 206 and finally to the series level. There only remains the instance | |
| 207 level. Let us dump the content of one of the instances:: | |
| 208 | |
| 209 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4 | |
| 210 | |
| 211 .. highlight:: json | |
| 212 | |
| 213 The instance contains the following information:: | |
| 214 | |
| 215 { | |
| 216 "FileSize" : 70356, | |
| 217 "FileUuid" : "3fd265f0-c2b6-41a2-ace8-ae332db63e06", | |
| 218 "ID" : "e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4", | |
| 219 "IndexInSeries" : 6, | |
| 220 "MainDicomTags" : { | |
| 221 "ImageIndex" : "6", | |
| 222 "InstanceCreationDate" : "20120716", | |
| 223 "InstanceCreationTime" : "171344", | |
| 224 "InstanceNumber" : "6", | |
| 225 "SOPInstanceUID" : "1.3.46.670589.28.2.15.30.26407.37145.3.2116.39.1342458737" | |
| 226 }, | |
| 227 "ParentSeries" : "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35", | |
| 228 "Type" : "Instance" | |
| 229 } | |
| 230 | |
| 231 .. highlight:: bash | |
| 232 | |
| 233 The instance has the index 6 in the parent series. The instance is | |
| 234 stored as a raw DICOM file of 70356 bytes. You would download this | |
| 235 DICOM file using the following command:: | |
| 236 | |
| 237 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/file > Instance.dcm | |
| 238 | |
| 239 | |
| 240 Accessing the DICOM fields of an instance as a JSON file | |
| 241 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 242 | |
| 243 .. highlight:: bash | |
| 244 | |
| 245 When one gets to the instance level, you can retrieve the hierarchy of | |
| 246 all the DICOM tags of this instance as a JSON file:: | |
| 247 | |
| 248 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/simplified-tags | |
| 249 | |
| 250 .. highlight:: json | |
| 251 | |
| 252 Here is a excerpt of the Orthanc answer:: | |
| 253 | |
| 254 { | |
| 255 "ACR_NEMA_2C_VariablePixelDataGroupLength" : "57130", | |
| 256 "AccessionNumber" : null, | |
| 257 "AcquisitionDate" : "20120716", | |
| 258 "AcquisitionDateTime" : "20120716171219", | |
| 259 "AcquisitionTime" : "171219", | |
| 260 "ActualFrameDuration" : "3597793", | |
| 261 "AttenuationCorrectionMethod" : "CTAC-SG", | |
| 262 <...> | |
| 263 "PatientID" : "000000185", | |
| 264 "PatientName" : "Anonymous^Unknown", | |
| 265 "PatientOrientationCodeSequence" : [ | |
| 266 { | |
| 267 "CodeMeaning" : "recumbent", | |
| 268 "CodeValue" : "F-10450", | |
| 269 "CodingSchemeDesignator" : "99SDM", | |
| 270 "PatientOrientationModifierCodeSequence" : [ | |
| 271 { | |
| 272 "CodeMeaning" : "supine", | |
| 273 "CodeValue" : "F-10340", | |
| 274 "CodingSchemeDesignator" : "99SDM" | |
| 275 } | |
| 276 ] | |
| 277 } | |
| 278 ], | |
| 279 <...> | |
| 280 "StudyDescription" : "TestSUVce-TF", | |
| 281 "StudyID" : "23848", | |
| 282 "StudyInstanceUID" : "1.2.840.113704.1.111.7016.1342451220.40", | |
| 283 "StudyTime" : "171117", | |
| 284 "TypeOfDetectorMotion" : "NONE", | |
| 285 "Units" : "BQML", | |
| 286 "Unknown" : null, | |
| 287 "WindowCenter" : "1.496995e+04", | |
| 288 "WindowWidth" : "2.993990e+04" | |
| 289 } | |
| 290 | |
| 291 .. highlight:: bash | |
| 292 | |
| 293 If you need more detailed information about the type of the variables | |
| 294 or if you wish to use the hexadecimal indexes of DICOM tags, you are | |
| 295 free to use the following URL:: | |
| 296 | |
| 297 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/tags | |
| 298 | |
| 299 Accessing the raw DICOM fields of an instance | |
| 300 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 301 | |
| 302 .. highlight:: bash | |
| 303 | |
| 304 You also have the opportunity to access the raw value of the DICOM | |
| 305 tags of an instance, without going through a JSON file. Here is how | |
| 306 you would find the Patient Name of the instance:: | |
| 307 | |
| 308 $ 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
|
309 Anonymous^Unknown |
| 0 | 310 |
| 311 The list of all the available tags for this instance can also be retrieved easily:: | |
| 312 | |
| 313 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content | |
| 314 | |
| 315 It is also possible to recursively explore the sequences of tags:: | |
| 316 | |
| 317 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content/0008-1250/0/0040-a170/0/0008-0104 | |
| 318 For Attenuation Correction | |
| 319 | |
| 320 The command above has opened the "0008-1250" tag that is a DICOM | |
| 321 sequence, taken its first child, opened its "0040-a170" tag that is | |
| 322 also a sequence, taken the first child of this child, and returned the | |
| 323 "0008-0104" DICOM tag. | |
| 324 | |
| 325 Downloading images | |
| 326 ^^^^^^^^^^^^^^^^^^ | |
| 327 | |
| 328 .. highlight:: bash | |
| 329 | |
| 330 It is also possible to download a preview PNG image that corresponds to some DICOM instance:: | |
| 331 | |
| 332 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/preview > Preview.png | |
| 333 | |
| 334 The resulting image will be a standard graylevel PNG image that can be opened by any painting software. | |
| 335 | |
| 336 | |
| 337 .. _changes: | |
| 338 | |
| 339 | |
| 340 | |
| 341 Sending resources to remote modalities | |
| 342 -------------------------------------- | |
| 343 | |
| 344 Orthanc can send its DICOM instances to remote DICOM modalities (C-Store SCU). This process | |
| 345 can be triggered by the REST API. | |
| 346 | |
| 347 Configuration | |
| 348 ^^^^^^^^^^^^^ | |
| 349 | |
| 350 .. highlight:: json | |
| 351 | |
| 352 You first have to declare the AET, the IP address and the port number | |
| 353 of the remote modality inside the :ref:`configuration file | |
| 354 <configuration>`. For instance, here is how to declare a remote | |
| 355 modality:: | |
| 356 | |
| 357 ... | |
| 358 "DicomModalities" : { | |
| 359 "sample" : [ "STORESCP", "127.0.0.1", 2000 ] | |
| 360 }, | |
| 361 ... | |
| 362 | |
| 363 .. highlight:: bash | |
| 364 | |
| 365 Such a configuration would enable Orthanc to connect to another DICOM | |
| 366 store (for instance, another Orthanc instance) that listens on the | |
| 367 localhost on the port 2000. The modalities that are known to Orthanc | |
| 368 can be queried:: | |
| 369 | |
| 370 $ curl http://localhost:8042/modalities | |
| 371 | |
| 372 | |
| 373 Sending One Resource | |
| 374 ^^^^^^^^^^^^^^^^^^^^ | |
| 375 | |
| 376 .. highlight:: bash | |
| 377 | |
| 378 Once you have identified the Orthanc identifier of the DICOM resource | |
| 379 that would like to send :ref:`as explained above <rest-access>`, you | |
| 380 would use the following command to send it:: | |
| 381 | |
| 382 $ curl -X POST http://localhost:8042/modalities/sample/store -d c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f | |
| 383 | |
| 384 The ``/sample/`` component of the URI corresponds to the identifier of | |
| 385 the remote modality, as specified above in the configuration file. | |
| 386 | |
| 387 Note that you can send isolated DICOM instances with this command, but also entire patients, studies or series. | |
| 388 | |
| 389 Bulk Store SCU | |
| 390 ^^^^^^^^^^^^^^ | |
| 391 | |
| 392 .. highlight:: bash | |
| 393 | |
| 394 Each time a POST request is made to ``/modalities/.../store``, a new | |
| 395 DICOM connection is possibly established. This may lead to a large | |
| 396 communication overhead if sending multiple isolated instances. | |
| 397 | |
| 398 To circumvent this problem, you have 2 possibilities: | |
| 399 | |
| 400 1. Set the ``DicomAssociationCloseDelay`` option in the | |
| 401 :ref:`configuration file <configuration>` to a non-zero value. This | |
| 402 will keep the DICOM connection open for a certain amount of time, | |
| 403 waiting for new instances to be routed. | |
| 404 | |
| 405 2. If you do not want to keep the connection open but inactive, it is | |
| 406 possible to send multiple instances with a single POST request | |
| 407 (so-called "Bulk Store SCU", available from Orthanc 0.5.2):: | |
| 408 | |
| 409 $ 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"]' | |
| 410 | |
| 411 The list of the resources to be sent are given as a JSON array. In | |
| 412 this case, a single DICOM connection is used. `Sample code is | |
| 413 available | |
| 414 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Python/HighPerformanceAutoRouting.py>`__. | |
| 415 | |
| 416 | |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
417 Performing Query/Retrieve and Find with REST |
| 138 | 418 -------------------------------------------- |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
419 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
420 *Section contributed by Bryan Dearlove* |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
421 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
422 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
|
423 or on remote modalities through the REST API. |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
424 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
425 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
|
426 within the :ref:`configuration file <configuration>` (See |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
427 Configuration section under Sending resources to remote modalities). |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
428 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
429 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
430 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
|
431 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
432 |
| 138 | 433 .. highlight:: bash |
| 434 | |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
435 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
|
436 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
|
437 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
|
438 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
|
439 insensitive unless configured otherwise within the Orthanc |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
440 configuration file:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
441 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
442 $ curl --request POST \ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
443 --url http://localhost:8042/modalities/sample/query \ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
444 --data '{"Level":"Study","Query": {"PatientID":"","StudyDescription":"*Chest*","PatientName":""}}' |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
445 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
446 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
447 .. highlight:: json |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
448 |
| 138 | 449 You will receive back an ID which can be used to retrieve more |
| 450 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
|
451 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
452 { |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
453 "ID": "5af318ac-78fb-47ff-b0b0-0df18b0588e0", |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
454 "Path": "/queries/5af318ac-78fb-47ff-b0b0-0df18b0588e0" |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
455 } |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
456 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
457 |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
458 Additional Options |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
459 ^^^^^^^^^^^^^^^^^^ |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
460 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
461 .. highlight:: json |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
462 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
463 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
|
464 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
|
465 `Jones` you can do:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
466 |
| 139 | 467 "PatientName":"Jones*" |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
468 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
469 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
|
470 it you can do:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
471 |
| 139 | 472 "PatientName":"*Jo*" |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
473 |
| 138 | 474 To perform date searches you can specify within StudyDate a starting |
| 475 date and/or a before date. For example ``"StudyDate":"20180323-"`` | |
| 476 would search for all study dates after the specified date to | |
| 477 now. Doing ``"StudyDate":"20180323-20180325"`` would search for all | |
| 478 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
|
479 |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
480 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
481 Reviewing Level |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
482 ^^^^^^^^^^^^^^^ |
|
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 .. highlight:: bash |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
485 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
486 :: |
|
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 $ 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
|
489 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
490 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
|
491 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
|
492 |
|
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 Reviewing Modality |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
495 ^^^^^^^^^^^^^^^^^^ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
496 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
497 .. highlight:: bash |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
498 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
499 :: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
500 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
501 $ 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
|
502 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
503 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
|
504 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
505 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
506 Reviewing Query |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
507 ^^^^^^^^^^^^^^^ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
508 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
509 .. highlight:: bash |
|
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 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
|
512 performed using you can use the query filter:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
513 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
514 $ 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
|
515 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
516 |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
517 Reviewing Query Answers |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
518 ^^^^^^^^^^^^^^^^^^^^^^^ |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
519 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
520 .. highlight:: bash |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
521 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
522 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
|
523 a GET with the answers parameter:: |
|
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 $ 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
|
526 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
527 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
|
528 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
|
529 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
|
530 for content details:: |
|
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 $ 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
|
533 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
534 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
|
535 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
|
536 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
|
537 POST body: `"ModalitiesInStudy":""` |
|
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 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
540 Performing Retrieve (C-Move) |
|
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 .. highlight:: bash |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
544 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
545 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
|
546 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
|
547 in the POST contents:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
548 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
549 $ 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
|
550 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
551 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
|
552 specifying that individual content item:: |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
553 |
|
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
554 $ 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
|
555 |
| 138 | 556 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
557 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
|
558 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
559 .. highlight:: bash |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
560 |
| 138 | 561 Performing a find within Orthanc is very similar to using Queries |
| 562 against DICOM modalities and the additional options listed above work | |
| 563 with find also. When performing a find, you will receive the Orthanc | |
| 564 ID's of all the matched items within your find. For example if you | |
| 565 perform a study level find and 5 Studies match you will receive 5 | |
| 566 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
|
567 |
| 138 | 568 $ 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
|
569 |
| 138 | 570 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
571 Additional Options |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
572 ^^^^^^^^^^^^^^^^^^ |
| 138 | 573 .. highlight:: json |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
574 |
|
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
575 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
|
576 |
| 138 | 577 "Limit":4 |
|
136
8e08909ab69b
Added find information to: Performing Query/Retrieve and Find with REST
Bryan Dearlove <bdearlove@gmail.com>
parents:
132
diff
changeset
|
578 |
|
132
55a2ee3c462d
Performing Query/Retrieve with REST
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
114
diff
changeset
|
579 |
| 0 | 580 Tracking changes |
| 581 ---------------- | |
| 582 | |
| 583 .. highlight:: bash | |
| 584 | |
| 585 Whenever Orthanc receives a new DICOM instance, this event is recorded | |
| 586 in the so-called "Changes Log". This enables remote scripts to react | |
| 587 to the arrival of new DICOM resources. A typical application is | |
| 588 **auto-routing**, where an external script waits for a new DICOM | |
| 589 instance to arrive into Orthanc, then forward this instance to another | |
| 590 modality. | |
| 591 | |
| 592 The Changes Log can be accessed by the following command:: | |
| 593 | |
| 594 $ curl http://localhost:8042/changes | |
| 595 | |
| 596 .. highlight:: json | |
| 597 | |
| 598 Here is a typical output:: | |
| 599 | |
| 600 { | |
| 601 "Changes" : [ | |
| 602 { | |
| 603 "ChangeType" : "NewInstance", | |
| 604 "Date" : "20130507T143902", | |
| 605 "ID" : "8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe", | |
| 606 "Path" : "/instances/8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe", | |
| 607 "ResourceType" : "Instance", | |
| 608 "Seq" : 921 | |
| 609 }, | |
| 610 { | |
| 611 "ChangeType" : "NewSeries", | |
| 612 "Date" : "20130507T143902", | |
| 613 "ID" : "cceb768f-e0f8df71-511b0277-07e55743-9ef8890d", | |
| 614 "Path" : "/series/cceb768f-e0f8df71-511b0277-07e55743-9ef8890d", | |
| 615 "ResourceType" : "Series", | |
| 616 "Seq" : 922 | |
| 617 }, | |
| 618 { | |
| 619 "ChangeType" : "NewStudy", | |
| 620 "Date" : "20130507T143902", | |
| 621 "ID" : "c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f", | |
| 622 "Path" : "/studies/c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f", | |
| 623 "ResourceType" : "Study", | |
| 624 "Seq" : 923 | |
| 625 }, | |
| 626 { | |
| 627 "ChangeType" : "NewPatient", | |
| 628 "Date" : "20130507T143902", | |
| 629 "ID" : "dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94", | |
| 630 "Path" : "/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94", | |
| 631 "ResourceType" : "Patient", | |
| 632 "Seq" : 924 | |
| 633 } | |
| 634 ], | |
| 635 "Done" : true, | |
| 636 "Last" : 924 | |
| 637 } | |
| 638 | |
| 639 This output corresponds to the receiving of one single DICOM instance | |
| 640 by Orthanc. It records that a new instance, a new series, a new study | |
| 641 and a new patient has been created inside Orthanc. Note that each | |
| 642 changes is labeled by a ``ChangeType``, a ``Date`` (in the `ISO format | |
| 25 | 643 <https://en.wikipedia.org/wiki/ISO_8601>`__), the location of the |
| 0 | 644 resource inside Orthanc, and a sequence number (``Seq``). |
| 645 | |
| 646 Note that this call is non-blocking. It is up to the calling program | |
| 647 to wait for the occurrence of a new event (by implementing a polling | |
| 648 loop). | |
| 649 | |
| 650 .. highlight:: bash | |
| 651 | |
| 652 This call only returns a fixed number of events, that can be changed | |
| 653 by using the ``limit`` option:: | |
| 654 | |
| 655 $ curl http://localhost:8042/changes?limit=100 | |
| 656 | |
| 657 The flag ``Last`` records the sequence number of the lastly returned | |
| 658 event. The flag ``Done`` is set to ``true`` if no further event has | |
| 659 occurred after this lastly returned event. If ``Done`` is set to | |
| 660 ``false``, further events are available and can be retrieved. This is | |
| 661 done by setting the ``since`` option that specifies from which | |
| 662 sequence number the changes must be returned:: | |
| 663 | |
| 664 $ curl 'http://localhost:8042/changes?limit=100&since=922' | |
| 665 | |
| 666 A `sample code in the source distribution | |
| 667 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Python/ChangesLoop.py>`__ | |
| 668 shows how to use this Changes API to implement a polling loop. | |
| 669 | |
| 670 | |
| 671 Deleting resources from Orthanc | |
| 672 ------------------------------- | |
| 673 | |
| 674 .. highlight:: bash | |
| 675 | |
| 676 Deleting patients, studies, series or instances | |
| 677 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 678 | |
| 679 Deleting DICOM resources (i.e. patients, studies, series or instances) | |
| 680 from Orthanc is as simple as using a HTTP DELETE on the URI of this | |
| 681 resource. | |
| 682 | |
| 683 Concretely, you would first explore the resources that are stored in | |
| 684 Orthanc :ref:`as explained above <rest-access>`:: | |
| 685 | |
| 686 $ curl http://localhost:8042/patients | |
| 687 $ curl http://localhost:8042/studies | |
| 688 $ curl http://localhost:8042/series | |
| 689 $ curl http://localhost:8042/instances | |
| 690 | |
| 691 Secondly, once you have spotted the resources to be removed, you would | |
| 692 use the following command-line syntax to delete them:: | |
| 693 | |
| 694 $ curl -X DELETE http://localhost:8042/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94 | |
| 695 $ curl -X DELETE http://localhost:8042/studies/c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f | |
| 696 $ curl -X DELETE http://localhost:8042/series/cceb768f-e0f8df71-511b0277-07e55743-9ef8890d | |
| 697 $ curl -X DELETE http://localhost:8042/instances/8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe | |
| 698 | |
| 699 | |
| 700 Clearing log of changes | |
| 701 ^^^^^^^^^^^^^^^^^^^^^^^ | |
| 702 | |
| 703 :ref:`As described above <changes>`, Orthanc keeps track of all the | |
| 704 changes that occur in the DICOM store. This so-called "Changes Log" | |
| 705 is accessible at the following URI:: | |
| 706 | |
| 707 $ curl http://localhost:8042/changes | |
| 708 | |
| 709 To clear the content of the Changes Log, simply DELETE this URI:: | |
| 710 | |
| 711 $ curl -X DELETE http://localhost:8042/changes | |
| 712 | |
| 713 Clearing log of exported resources | |
| 714 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 715 | |
| 716 For medical traceability, Orthanc stores a log of all the resources | |
| 717 that have been exported to remote modalities:: | |
| 718 | |
| 719 $ curl http://localhost:8042/exports | |
| 720 | |
| 721 In auto-routing scenarios, it is important to prevent this log to grow | |
| 722 indefinitely as incoming instances are routed. You can either disable | |
| 723 this logging by setting the option ``LogExportedResources`` to ``false`` | |
| 724 in the :ref:`configuration file <configuration>`, or periodically | |
| 725 clear this log by DELETE-ing this URI:: | |
| 726 | |
| 727 $ curl -X DELETE http://localhost:8042/exports | |
| 728 | |
| 729 | |
| 730 Anonymization and modification | |
| 731 ------------------------------ | |
| 732 | |
| 733 The process of anonymizing and modifying DICOM resources is | |
| 734 :ref:`documented in a separate page <anonymization>`. | |
| 735 | |
| 736 | |
| 737 Further reading | |
| 738 --------------- | |
| 739 | |
| 740 The examples above have shown you the basic principles for driving an | |
| 741 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
|
742 API have not been described: |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
743 |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
744 * 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
|
745 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
|
746 * 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
|
747 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
|
748 Web site |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
749 <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
|
750 (click on the *Reference of the REST API* button). |