Mercurial > hg > orthanc-book

comparison Sphinx/source/users/rest.rst @ 0:901e8961f46e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial commit
author Sebastien Jodogne <s.jodogne@gmail.com>
date Fri, 22 Apr 2016 12:57:38 +0200
parents
children 669ea65ba7fb
comparison
equal deleted inserted replaced
-1:000000000000 0:901e8961f46e
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
23 tool <http://curl.haxx.se/>`__, but equivalent calls can be readily
24 transposed to any programming language that supports both HTTP and
25 JSON.
26
27
28 Sending DICOM images
29 --------------------
30
31 .. highlight:: bash
32
33 The upload of DICOM files is possible by querying the REST API using
34 the following syntax::
35
36 $ curl -X POST http://localhost:8042/instances --data-binary @CT.X.1.2.276.0.7230010.dcm
37
38 .. highlight:: json
39
40 Orthanc will respond with a JSON file that contain information about
41 the location of the stored instance, such as::
42
43 {
44 "ID" : "e87da270-c52b-4f2a-b8c6-bae25928d0b0",
45 "Path" : "/instances/e87da270-c52b-4f2a-b8c6-bae25928d0b0",
46 "Status" : "Success"
47 }
48
49 .. highlight:: bash
50
51 Note that in the case of curl, setting the ``Expect`` HTTP Header will
52 significantly `reduce the execution time of POST requests
53 <http://stackoverflow.com/a/463277/881731>`__::
54
55 $ curl -X POST -H "Expect:" http://localhost:8042/instances --data-binary @CT.X.1.2.276.0.7230010.dcm
56
57 The code distribution of Orthanc contains a `sample Python script
58 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/ImportDicomFiles/ImportDicomFiles.py>`__
59 that recursively upload the content of some folder into Orthanc using
60 the REST API::
61
62 $ python ImportDicomFiles.py localhost 8042 ~/DICOM/
63
64
65 .. _rest-access:
66
67 Accessing the content of Orthanc
68 --------------------------------
69
70 Orthanc structures the stored DICOM resources using the "Patient,
71 Study, Series, Instance" model of the DICOM standard. Each DICOM
72 resource is associated with an :ref:`unique identifier <orthanc-ids>`.
73
74 List all the DICOM resources
75 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
76
77 Here is how you would list all the DICOM resources that are stored in
78 your local Orthanc instance::
79
80 $ curl http://localhost:8042/patients
81 $ curl http://localhost:8042/studies
82 $ curl http://localhost:8042/series
83 $ curl http://localhost:8042/instances
84
85 Note that the result of this command is a `JSON file
86 <http://en.wikipedia.org/wiki/Json>`__ that contains an array of
87 resource identifiers. The JSON file format is lightweight and can be
88 parsed from almost any computer language.
89
90 Accessing a patient
91 ^^^^^^^^^^^^^^^^^^^
92
93 .. highlight:: bash
94
95 To access a single resource, add its identifier to the `URI
96 <http://en.wikipedia.org/wiki/Uniform_resource_identifier>`__. You
97 would for instance retrieve the main information about one patient as
98 follows::
99
100 $ curl http://localhost:8042/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94
101
102 .. highlight:: json
103
104 Here is a possible answer from Orthanc::
105
106 {
107 "ID" : "07a6ec1c-1be5920b-18ef5358-d24441f3-10e926ea",
108 "MainDicomTags" : {
109 "OtherPatientIDs" : "(null)",
110 "PatientBirthDate" : "0",
111 "PatientID" : "000000185",
112 "PatientName" : "Anonymous^Unknown",
113 "PatientSex" : "O"
114 },
115 "Studies" : [ "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15" ],
116 "Type" : "Patient"
117 }
118
119 This is once again a JSON file. Note how Orthanc gives you a summary
120 of the main DICOM tags that correspond to the patient level.
121
122 Browsing from the patient down to the instance
123 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
124
125 .. highlight:: bash
126
127 The field ``Studies`` list all the DICOM studies that are associated
128 with the patient. So, considering the patient above, we would go down
129 in her DICOM hierarchy as follows::
130
131 $ curl http://localhost:8042/studies/9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15
132
133 .. highlight:: json
134
135 And Orthanc could answer::
136
137 {
138 "ID" : "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15",
139 "MainDicomTags" : {
140 "AccessionNumber" : "(null)",
141 "StudyDate" : "20120716",
142 "StudyDescription" : "TestSUVce-TF",
143 "StudyID" : "23848",
144 "StudyInstanceUID" : "1.2.840.113704.1.111.7016.1342451220.40",
145 "StudyTime" : "170728"
146 },
147 "ParentPatient" : "07a6ec1c-1be5920b-18ef5358-d24441f3-10e926ea",
148 "Series" : [
149 "6821d761-31fb55a9-031ebecb-ba7f9aae-ffe4ddc0",
150 "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35",
151 "7384c47e-6398f2a8-901846ef-da1e2e0b-6c50d598"
152 ],
153 "Type" : "Study"
154 }
155
156 .. highlight:: bash
157
158 The main DICOM tags are now those that are related to the study
159 level. It is possible to retrieve the identifier of the patient in the
160 ``ParentPatient`` field, which can be used to go upward the DICOM
161 hierarchy. But let us rather go down to the series level by using the
162 ``Series`` array. The next command would return information about one
163 of the three series that have just been reported::
164
165 $ curl http://localhost:8042/series/2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35
166
167 .. highlight:: json
168
169 Here is a possible answer::
170
171 {
172 "ExpectedNumberOfInstances" : 45,
173 "ID" : "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35",
174 "Instances" : [
175 "41bc3f74-360f9d10-6ae9ffa4-01ea2045-cbd457dd",
176 "1d3de868-6c4f0494-709fd140-7ccc4c94-a6daa3a8",
177 <...>
178 "1010f80b-161b71c0-897ec01b-c85cd206-e669a3ea",
179 "e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4"
180 ],
181 "MainDicomTags" : {
182 "Manufacturer" : "Philips Medical Systems",
183 "Modality" : "PT",
184 "NumberOfSlices" : "45",
185 "ProtocolName" : "CHU/Body_PET/CT___50",
186 "SeriesDate" : "20120716",
187 "SeriesDescription" : "[WB_CTAC] Body",
188 "SeriesInstanceUID" : "1.3.46.670589.28.2.12.30.26407.37145.2.2516.0.1342458737",
189 "SeriesNumber" : "587370",
190 "SeriesTime" : "171121",
191 "StationName" : "r054-svr"
192 },
193 "ParentStudy" : "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15",
194 "Status" : "Complete",
195 "Type" : "Series"
196 }
197
198 It can be seen that this series comes from a PET modality. Orthanc has
199 computed that this series should contain 45 instances.
200
201 .. highlight:: bash
202
203 So far, we have navigated from the patient level, to the study level,
204 and finally to the series level. There only remains the instance
205 level. Let us dump the content of one of the instances::
206
207 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4
208
209 .. highlight:: json
210
211 The instance contains the following information::
212
213 {
214 "FileSize" : 70356,
215 "FileUuid" : "3fd265f0-c2b6-41a2-ace8-ae332db63e06",
216 "ID" : "e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4",
217 "IndexInSeries" : 6,
218 "MainDicomTags" : {
219 "ImageIndex" : "6",
220 "InstanceCreationDate" : "20120716",
221 "InstanceCreationTime" : "171344",
222 "InstanceNumber" : "6",
223 "SOPInstanceUID" : "1.3.46.670589.28.2.15.30.26407.37145.3.2116.39.1342458737"
224 },
225 "ParentSeries" : "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35",
226 "Type" : "Instance"
227 }
228
229 .. highlight:: bash
230
231 The instance has the index 6 in the parent series. The instance is
232 stored as a raw DICOM file of 70356 bytes. You would download this
233 DICOM file using the following command::
234
235 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/file > Instance.dcm
236
237
238 Accessing the DICOM fields of an instance as a JSON file
239 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
240
241 .. highlight:: bash
242
243 When one gets to the instance level, you can retrieve the hierarchy of
244 all the DICOM tags of this instance as a JSON file::
245
246 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/simplified-tags
247
248 .. highlight:: json
249
250 Here is a excerpt of the Orthanc answer::
251
252 {
253 "ACR_NEMA_2C_VariablePixelDataGroupLength" : "57130",
254 "AccessionNumber" : null,
255 "AcquisitionDate" : "20120716",
256 "AcquisitionDateTime" : "20120716171219",
257 "AcquisitionTime" : "171219",
258 "ActualFrameDuration" : "3597793",
259 "AttenuationCorrectionMethod" : "CTAC-SG",
260 <...>
261 "PatientID" : "000000185",
262 "PatientName" : "Anonymous^Unknown",
263 "PatientOrientationCodeSequence" : [
264 {
265 "CodeMeaning" : "recumbent",
266 "CodeValue" : "F-10450",
267 "CodingSchemeDesignator" : "99SDM",
268 "PatientOrientationModifierCodeSequence" : [
269 {
270 "CodeMeaning" : "supine",
271 "CodeValue" : "F-10340",
272 "CodingSchemeDesignator" : "99SDM"
273 }
274 ]
275 }
276 ],
277 <...>
278 "StudyDescription" : "TestSUVce-TF",
279 "StudyID" : "23848",
280 "StudyInstanceUID" : "1.2.840.113704.1.111.7016.1342451220.40",
281 "StudyTime" : "171117",
282 "TypeOfDetectorMotion" : "NONE",
283 "Units" : "BQML",
284 "Unknown" : null,
285 "WindowCenter" : "1.496995e+04",
286 "WindowWidth" : "2.993990e+04"
287 }
288
289 .. highlight:: bash
290
291 If you need more detailed information about the type of the variables
292 or if you wish to use the hexadecimal indexes of DICOM tags, you are
293 free to use the following URL::
294
295 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/tags
296
297 Accessing the raw DICOM fields of an instance
298 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
299
300 .. highlight:: bash
301
302 You also have the opportunity to access the raw value of the DICOM
303 tags of an instance, without going through a JSON file. Here is how
304 you would find the Patient Name of the instance::
305
306 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content/0010-0010
307 Anonymous^Unknown
308
309 The list of all the available tags for this instance can also be retrieved easily::
310
311 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content
312
313 It is also possible to recursively explore the sequences of tags::
314
315 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content/0008-1250/0/0040-a170/0/0008-0104
316 For Attenuation Correction
317
318 The command above has opened the "0008-1250" tag that is a DICOM
319 sequence, taken its first child, opened its "0040-a170" tag that is
320 also a sequence, taken the first child of this child, and returned the
321 "0008-0104" DICOM tag.
322
323 Downloading images
324 ^^^^^^^^^^^^^^^^^^
325
326 .. highlight:: bash
327
328 It is also possible to download a preview PNG image that corresponds to some DICOM instance::
329
330 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/preview > Preview.png
331
332 The resulting image will be a standard graylevel PNG image that can be opened by any painting software.
333
334
335 .. _changes:
336
337
338
339 Sending resources to remote modalities
340 --------------------------------------
341
342 Orthanc can send its DICOM instances to remote DICOM modalities (C-Store SCU). This process
343 can be triggered by the REST API.
344
345 Configuration
346 ^^^^^^^^^^^^^
347
348 .. highlight:: json
349
350 You first have to declare the AET, the IP address and the port number
351 of the remote modality inside the :ref:`configuration file
352 <configuration>`. For instance, here is how to declare a remote
353 modality::
354
355 ...
356 "DicomModalities" : {
357 "sample" : [ "STORESCP", "127.0.0.1", 2000 ]
358 },
359 ...
360
361 .. highlight:: bash
362
363 Such a configuration would enable Orthanc to connect to another DICOM
364 store (for instance, another Orthanc instance) that listens on the
365 localhost on the port 2000. The modalities that are known to Orthanc
366 can be queried::
367
368 $ curl http://localhost:8042/modalities
369
370
371 Sending One Resource
372 ^^^^^^^^^^^^^^^^^^^^
373
374 .. highlight:: bash
375
376 Once you have identified the Orthanc identifier of the DICOM resource
377 that would like to send :ref:`as explained above <rest-access>`, you
378 would use the following command to send it::
379
380 $ curl -X POST http://localhost:8042/modalities/sample/store -d c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f
381
382 The ``/sample/`` component of the URI corresponds to the identifier of
383 the remote modality, as specified above in the configuration file.
384
385 Note that you can send isolated DICOM instances with this command, but also entire patients, studies or series.
386
387 Bulk Store SCU
388 ^^^^^^^^^^^^^^
389
390 .. highlight:: bash
391
392 Each time a POST request is made to ``/modalities/.../store``, a new
393 DICOM connection is possibly established. This may lead to a large
394 communication overhead if sending multiple isolated instances.
395
396 To circumvent this problem, you have 2 possibilities:
397
398 1. Set the ``DicomAssociationCloseDelay`` option in the
399 :ref:`configuration file <configuration>` to a non-zero value. This
400 will keep the DICOM connection open for a certain amount of time,
401 waiting for new instances to be routed.
402
403 2. If you do not want to keep the connection open but inactive, it is
404 possible to send multiple instances with a single POST request
405 (so-called "Bulk Store SCU", available from Orthanc 0.5.2)::
406
407 $ 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"]'
408
409 The list of the resources to be sent are given as a JSON array. In
410 this case, a single DICOM connection is used. `Sample code is
411 available
412 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Python/HighPerformanceAutoRouting.py>`__.
413
414
415 Tracking changes
416 ----------------
417
418 .. highlight:: bash
419
420 Whenever Orthanc receives a new DICOM instance, this event is recorded
421 in the so-called "Changes Log". This enables remote scripts to react
422 to the arrival of new DICOM resources. A typical application is
423 **auto-routing**, where an external script waits for a new DICOM
424 instance to arrive into Orthanc, then forward this instance to another
425 modality.
426
427 The Changes Log can be accessed by the following command::
428
429 $ curl http://localhost:8042/changes
430
431 .. highlight:: json
432
433 Here is a typical output::
434
435 {
436 "Changes" : [
437 {
438 "ChangeType" : "NewInstance",
439 "Date" : "20130507T143902",
440 "ID" : "8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe",
441 "Path" : "/instances/8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe",
442 "ResourceType" : "Instance",
443 "Seq" : 921
444 },
445 {
446 "ChangeType" : "NewSeries",
447 "Date" : "20130507T143902",
448 "ID" : "cceb768f-e0f8df71-511b0277-07e55743-9ef8890d",
449 "Path" : "/series/cceb768f-e0f8df71-511b0277-07e55743-9ef8890d",
450 "ResourceType" : "Series",
451 "Seq" : 922
452 },
453 {
454 "ChangeType" : "NewStudy",
455 "Date" : "20130507T143902",
456 "ID" : "c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f",
457 "Path" : "/studies/c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f",
458 "ResourceType" : "Study",
459 "Seq" : 923
460 },
461 {
462 "ChangeType" : "NewPatient",
463 "Date" : "20130507T143902",
464 "ID" : "dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94",
465 "Path" : "/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94",
466 "ResourceType" : "Patient",
467 "Seq" : 924
468 }
469 ],
470 "Done" : true,
471 "Last" : 924
472 }
473
474 This output corresponds to the receiving of one single DICOM instance
475 by Orthanc. It records that a new instance, a new series, a new study
476 and a new patient has been created inside Orthanc. Note that each
477 changes is labeled by a ``ChangeType``, a ``Date`` (in the `ISO format
478 <http://en.wikipedia.org/wiki/ISO_8601>`__), the location of the
479 resource inside Orthanc, and a sequence number (``Seq``).
480
481 Note that this call is non-blocking. It is up to the calling program
482 to wait for the occurrence of a new event (by implementing a polling
483 loop).
484
485 .. highlight:: bash
486
487 This call only returns a fixed number of events, that can be changed
488 by using the ``limit`` option::
489
490 $ curl http://localhost:8042/changes?limit=100
491
492 The flag ``Last`` records the sequence number of the lastly returned
493 event. The flag ``Done`` is set to ``true`` if no further event has
494 occurred after this lastly returned event. If ``Done`` is set to
495 ``false``, further events are available and can be retrieved. This is
496 done by setting the ``since`` option that specifies from which
497 sequence number the changes must be returned::
498
499 $ curl 'http://localhost:8042/changes?limit=100&since=922'
500
501 A `sample code in the source distribution
502 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Python/ChangesLoop.py>`__
503 shows how to use this Changes API to implement a polling loop.
504
505
506 Deleting resources from Orthanc
507 -------------------------------
508
509 .. highlight:: bash
510
511 Deleting patients, studies, series or instances
512 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
513
514 Deleting DICOM resources (i.e. patients, studies, series or instances)
515 from Orthanc is as simple as using a HTTP DELETE on the URI of this
516 resource.
517
518 Concretely, you would first explore the resources that are stored in
519 Orthanc :ref:`as explained above <rest-access>`::
520
521 $ curl http://localhost:8042/patients
522 $ curl http://localhost:8042/studies
523 $ curl http://localhost:8042/series
524 $ curl http://localhost:8042/instances
525
526 Secondly, once you have spotted the resources to be removed, you would
527 use the following command-line syntax to delete them::
528
529 $ curl -X DELETE http://localhost:8042/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94
530 $ curl -X DELETE http://localhost:8042/studies/c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f
531 $ curl -X DELETE http://localhost:8042/series/cceb768f-e0f8df71-511b0277-07e55743-9ef8890d
532 $ curl -X DELETE http://localhost:8042/instances/8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe
533
534
535 Clearing log of changes
536 ^^^^^^^^^^^^^^^^^^^^^^^
537
538 :ref:`As described above <changes>`, Orthanc keeps track of all the
539 changes that occur in the DICOM store. This so-called "Changes Log"
540 is accessible at the following URI::
541
542 $ curl http://localhost:8042/changes
543
544 To clear the content of the Changes Log, simply DELETE this URI::
545
546 $ curl -X DELETE http://localhost:8042/changes
547
548 Clearing log of exported resources
549 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
550
551 For medical traceability, Orthanc stores a log of all the resources
552 that have been exported to remote modalities::
553
554 $ curl http://localhost:8042/exports
555
556 In auto-routing scenarios, it is important to prevent this log to grow
557 indefinitely as incoming instances are routed. You can either disable
558 this logging by setting the option ``LogExportedResources`` to ``false``
559 in the :ref:`configuration file <configuration>`, or periodically
560 clear this log by DELETE-ing this URI::
561
562 $ curl -X DELETE http://localhost:8042/exports
563
564
565 Anonymization and modification
566 ------------------------------
567
568 The process of anonymizing and modifying DICOM resources is
569 :ref:`documented in a separate page <anonymization>`.
570
571
572 Further reading
573 ---------------
574
575 The examples above have shown you the basic principles for driving an
576 instance of Orthanc through its REST API. All the possibilities of the
577 API have not been described. A :ref:`FAQ entry <rest-samples>` lists
578 where you can find more advanced samples of the REST API of Orthanc.