annotate Sphinx/source/plugins/python.rst @ 513:f22b3743fd3f

Orthanc 1.7.4
author Sebastien Jodogne <s.jodogne@gmail.com>
date Fri, 18 Sep 2020 15:18:40 +0200
parents 98592b9e7ad5
children 50bdd7c7e9b9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
343
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _python-plugin:
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 Python plugin for Orthanc
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5 =========================
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 .. contents::
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8
371
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
9
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
10 Overview
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
11 --------
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
12
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
13 This plugin can be used to write :ref:`Orthanc plugins
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
14 <creating-plugins>` using the `Python programming language
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
15 <https://en.wikipedia.org/wiki/Python_(programming_language)>`__
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
16 instead of the more complex C/C++ programming languages.
343
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
18 Python plugins have access to more features and a more consistent SDK
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
19 than :ref:`Lua scripts <lua>`. The Python API is automatically
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
20 generated from the `Orthanc plugin SDK in C
513
f22b3743fd3f Orthanc 1.7.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 501
diff changeset
21 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.7.4/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__
345
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
22 using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
23 front-end.
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
24
462
fcc352fd4283 upgrade python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 442
diff changeset
25 As of release 2.0 of the plugin, the coverage of the C SDK is about
fcc352fd4283 upgrade python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 442
diff changeset
26 75% (119 functions are automatically wrapped in Python out of a total
fcc352fd4283 upgrade python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 442
diff changeset
27 of 157 functions in the Orthanc SDK 1.7.2).
343
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28
371
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
29
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
30 Source code
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
31 -----------
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
32
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
33 * Link to the `official releases of this plugin
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
34 <https://www.orthanc-server.com/browse.php?path=/plugin-python>`__.
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
35
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
36 * Link to the `code repository
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
37 <https://hg.orthanc-server.com/orthanc-python/>`__.
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
38
5cb37e6b014b explicit links to the source code of python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
39
353
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
40 Licensing
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
41 ---------
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
42
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
43 Pay attention to the fact that this plugin is licensed under the terms
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
44 of the `AGPL license
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
45 <https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License>`__.
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
46
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
47 This has an important consequence: If you distribute Orthanc to
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
48 clients together with one Python script, or if you put an Orthanc
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
49 server equipped with one Python script on a Web portal, you **must**
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
50 disclose the source code of your Python script to the Orthanc
354
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 353
diff changeset
51 community under the terms of the AGPL license.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 353
diff changeset
52
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 353
diff changeset
53 We suggest you to put the source code of your Python scripts on the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 353
diff changeset
54 dedicated `"OrthancContributed" repository on GitHub
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 353
diff changeset
55 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__,
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 353
diff changeset
56 and/or to send it to the `Orthanc Users
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 353
diff changeset
57 <https://groups.google.com/forum/#!forum/orthanc-users>`__ discussion
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 353
diff changeset
58 group.
353
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
59
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
60 Check out the :ref:`FAQ about licensing <licensing>` for more context.
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
61
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
62
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
63 Usage
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
64 -----
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
65
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
66 Docker
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
67 ......
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
68
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
69 .. highlight:: json
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
70
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
71 The most direct way of starting Orthanc together with the Python
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
72 plugin is through :ref:`Docker <docker>`. Let's create the file
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
73 ``/tmp/hello.py`` that contains the following basic Python script::
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
74
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
75 print('Hello world!')
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
76
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
77 .. highlight:: json
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
78
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
79 Let's also create the file ``/tmp/orthanc.json`` that contains the
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
80 following minimal :ref:`configuration for Orthanc <configuration>`::
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
81
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
82 {
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
83 "StorageDirectory" : "/var/lib/orthanc/db",
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
84 "RemoteAccessAllowed" : true,
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
85 "Plugins" : [
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
86 "/usr/local/share/orthanc/plugins"
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
87 ],
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
88 "PythonScript" : "/etc/orthanc/hello.py"
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
89 }
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
90
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
91 .. highlight:: bash
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
92
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
93 Given these two files, Orthanc can be started as follows::
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
94
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
95 $ docker run -p 4242:4242 -p 8042:8042 --rm \
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
96 -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro \
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
97 -v /tmp/hello.py:/etc/orthanc/hello.py:ro \
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
98 jodogne/orthanc-python
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
99
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
100 .. highlight:: text
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
101
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
102 You'll see the following excerpt in the log, which indicates that the Python plugin is properly loaded::
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
103
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
104 W0331 15:48:12.990661 PluginsManager.cpp:269] Registering plugin 'python' (version mainline)
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
105 W0331 15:48:12.990691 PluginsManager.cpp:168] Python plugin is initializing
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
106 W0331 15:48:12.990743 PluginsManager.cpp:168] Using Python script "hello.py" from directory: /etc/orthanc
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
107 W0331 15:48:12.990819 PluginsManager.cpp:168] Program name: /usr/local/sbin/Orthanc
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
108 Hello world!
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
109
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
110
405
ba486cac480a link to python sample
Alain Mazy <alain@mazy.be>
parents: 379
diff changeset
111 `Here <https://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/python/>`__ is a full example
ba486cac480a link to python sample
Alain Mazy <alain@mazy.be>
parents: 379
diff changeset
112 of a more complex setup using the :ref:`osimis/orthanc <docker-osimis>` images.
ba486cac480a link to python sample
Alain Mazy <alain@mazy.be>
parents: 379
diff changeset
113
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
114 Compiling from source
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
115 .....................
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
116
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
117 .. highlight:: bash
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
118
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
119 The procedure to compile this plugin from source is similar to that
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
120 for the :ref:`core of Orthanc <compiling>`. The following commands
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
121 should work for most UNIX-like distribution (including GNU/Linux)::
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
122
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
123 $ mkdir Build
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
124 $ cd Build
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
125 $ cmake .. -DPYTHON_VERSION=3.7 -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
126 $ make
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
127
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
128 Before running CMake, make sure that the Python interpreter and its
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
129 associated development library are installed. On Ubuntu 18.04 LTS, you
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
130 would for instance install packages ``libpython3.7-dev`` and
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
131 ``python3.7``.
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
132
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
133 The compilation will produce the shared library ``OrthancPython``,
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
134 that can be loaded by properly setting the ``Plugins``
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
135 :ref:`configuration option <configuration>` of Orthanc.
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
136
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
137 **Warning:** The shared library is only compatible with the Python
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
138 interpreter whose version corresponds to the value of the
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
139 ``PYTHON_VERSION`` argument that was given to CMake.
501
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
140
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
141 **Note for OS X:** As indicated by `Stephen Douglas Scotti
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
142 <https://groups.google.com/g/orthanc-users/c/RnmZKFv8FaY/m/HhvOD2A2CAAJ>`__,
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
143 here is a sample invocation of CMake to force the version of Python to
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
144 be used on OS X::
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
145
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
146 $ cmake .. -DPYTHON_VERSION=3.8 -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release \
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
147 -DPYTHON_LIBRARY=/usr/local/Cellar/python@3.8/3.8.5/Frameworks/Python.framework/Versions/3.8/lib/libpython3.8.dylib \
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
148 -DPYTHON_INCLUDE_DIR=/usr/local/Cellar/python@3.8/3.8.5/Frameworks/Python.framework/Versions/3.8/include/python3.8/
98592b9e7ad5 force version of python on os x
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 490
diff changeset
149
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
150
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
151 Microsoft Windows
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
152 .................
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
153
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
154 Pre-compiled binaries for Microsoft Windows `are also available
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
155 <https://www.orthanc-server.com/browse.php?path=/plugin-python>`__.
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
156
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
157 Beware that one version of the Python plugin can only be run against
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
158 one version of the Python interpreter. This version is clearly
442
8b2c648c0f46 clarifications about windows precompiled binaries
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 405
diff changeset
159 indicated in the filename of the precompiled binaries.
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
160
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
161 .. highlight:: text
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
162
442
8b2c648c0f46 clarifications about windows precompiled binaries
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 405
diff changeset
163 You are of course free to compile the plugin from sources. You'll have
8b2c648c0f46 clarifications about windows precompiled binaries
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 405
diff changeset
164 to explicitly specify the path to your Python installation while
8b2c648c0f46 clarifications about windows precompiled binaries
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 405
diff changeset
165 invoking CMake. For instance::
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
166
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
167 C:\orthanc-python\Build> cmake .. -DPYTHON_VERSION=2.7 -DPYTHON_WINDOWS_ROOT=C:/Python27 \
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
168 -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release -G "Visual Studio 15 2017"
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
169
442
8b2c648c0f46 clarifications about windows precompiled binaries
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 405
diff changeset
170 **Note about debug builds**: Usually, building Python modules such as the Python
377
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
171 plugin for Orthanc in debug mode (where ``_DEBUG`` is defined) leads to a module
442
8b2c648c0f46 clarifications about windows precompiled binaries
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 405
diff changeset
172 (``.exe`` or ``.dll``) that requires a debug build of Python, and debug versions of all
377
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
173 the Python libraries. This is quite cumbersome, for it requires building Python
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
174 on your own or downloading additional debug files.
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
175
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
176 Since using a debug build of Python is only necessary in very specific cases
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
177 (such as the debugging of code at the boundary between Python and an extension),
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
178 we have changed the default behavior to use the release Python library by default.
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
179
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
180 This means that you are able to build this plugin in debug mode with the
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
181 standard Python distribution.
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
182
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
183 In case you need to use the Python debug libraries, you can instruct the build
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
184 system to do so by setting the ``PYTHON_WINDOWS_USE_RELEASE_LIBS`` CMake option,
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
185 that is ``ON`` by default, to ``OFF``. The previous build example would then be,
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
186 should you require a full debug build::
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
187
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
188 C:\orthanc-python\Build> cmake .. -DPYTHON_VERSION=2.7 -DPYTHON_WINDOWS_ROOT=C:/Python27 \
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
189 -DSTATIC_BUILD=ON -DPYTHON_WINDOWS_USE_RELEASE_LIBS=OFF \
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
190 -DCMAKE_BUILD_TYPE=Debug -G "Visual Studio 15 2017"
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
191
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
192 Please note that this CMake option only impacts **debug** builds under Windows,
ffe62e6c086f Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents: 375
diff changeset
193 when using (any version of) the Microsoft Visual Studio compiler.
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
194
442
8b2c648c0f46 clarifications about windows precompiled binaries
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 405
diff changeset
195 The precompiled binaries all use release (i.e. non-debug) versions of Python.
8b2c648c0f46 clarifications about windows precompiled binaries
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 405
diff changeset
196
8b2c648c0f46 clarifications about windows precompiled binaries
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 405
diff changeset
197
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
198 Configuration options
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
199 ---------------------
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
200
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
201 The only two configuration options that are available for this plugin
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
202 are the following:
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
203
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
204 * ``PythonScript`` indicates where the Python script is located. If
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
205 this configuration option is not provided, the Python plugin is not
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
206 started.
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
207
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
208 * ``PythonVerbose`` is a Boolean value to make the Python interpreter
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
209 verbose.
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 354
diff changeset
210
343
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
211
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
212 Samples
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
213 -------
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
214
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
215 Extending the REST API
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
216 ......................
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
217
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
218 .. highlight:: python
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
219
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
220 Here is a basic Python script that registers two new routes in the
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
221 REST API::
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
222
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
223 import orthanc
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
224 import pprint
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
225
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
226 def OnRest(output, uri, **request):
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
227 pprint.pprint(request)
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
228 print('Accessing uri: %s' % uri)
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
229 output.AnswerBuffer('ok\n', 'text/plain')
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
230
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
231 orthanc.RegisterRestCallback('/(to)(t)o', OnRest)
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
232 orthanc.RegisterRestCallback('/tata', OnRest)
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
233
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
234 .. highlight:: json
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
235
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
236 Here is the associated minimal configuration file for Orthanc
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
237 (provided the Python script is saved as ``rest.py``)::
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
238
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
239 {
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
240 "Plugins" : [ "." ],
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
241 "PythonScript" : "rest.py",
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
242 "PythonVerbose" : false
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
243 }
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
244
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
245 .. highlight:: bash
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
246
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
247 The route can then be accessed as::
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
248
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
249 $ curl http://localhost:8042/toto
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
250 ok
fff45618262d creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
251
469
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
252
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
253 .. _python-changes:
345
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
254
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
255 Listening to changes
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
256 ....................
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
257
346
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
258 .. highlight:: python
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
259
345
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
260 This sample uploads a DICOM file as soon as Orthanc is started::
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
261
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
262 import orthanc
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
263
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
264 def OnChange(changeType, level, resource):
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
265 if changeType == orthanc.ChangeType.ORTHANC_STARTED:
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
266 print('Started')
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
267
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
268 with open('/tmp/sample.dcm', 'rb') as f:
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
269 orthanc.RestApiPost('/instances', f.read())
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
270
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
271 elif changeType == orthanc.ChangeType.ORTHANC_STOPPED:
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
272 print('Stopped')
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
273
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
274 elif changeType == orthanc.ChangeType.NEW_INSTANCE:
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
275 print('A new instance was uploaded: %s' % resource)
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
276
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
277 orthanc.RegisterOnChangeCallback(OnChange)
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
278
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
279
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
280 Accessing the content of a new instance
346
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
281 .......................................
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
282
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
283 .. highlight:: python
345
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
284
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
285 ::
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
286
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
287 import orthanc
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
288 import json
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
289 import pprint
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
290
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
291 def OnStoredInstance(dicom, instanceId):
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
292 print('Received instance %s of size %d (transfer syntax %s, SOP class UID %s)' % (
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
293 instanceId, dicom.GetInstanceSize(),
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
294 dicom.GetInstanceMetadata('TransferSyntax'),
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
295 dicom.GetInstanceMetadata('SopClassUid')))
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
296
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
297 # Print the origin information
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
298 if dicom.GetInstanceOrigin() == orthanc.InstanceOrigin.DICOM_PROTOCOL:
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
299 print('This instance was received through the DICOM protocol')
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
300 elif dicom.GetInstanceOrigin() == orthanc.InstanceOrigin.REST_API:
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
301 print('This instance was received through the REST API')
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
302
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
303 # Print the DICOM tags
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
304 pprint.pprint(json.loads(dicom.GetInstanceSimplifiedJson()))
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
305
f81b533a0fd0 python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 343
diff changeset
306 orthanc.RegisterOnStoredInstanceCallback(OnStoredInstance)
346
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
307
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
308
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
309 Calling pydicom
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
310 ...............
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
311
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
312 .. highlight:: python
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
313
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
314 Here is a sample Python plugin that registers a REST callback to dump
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
315 the content of the dataset of one given DICOM instance stored in
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
316 Orthanc, using `pydicom <https://pydicom.github.io/>`__::
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
317
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
318 import io
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
319 import orthanc
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
320 import pydicom
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
321
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
322 def DecodeInstance(output, uri, **request):
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
323 if request['method'] == 'GET':
347
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
324 # Retrieve the instance ID from the regular expression (*)
346
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
325 instanceId = request['groups'][0]
347
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
326 # Get the content of the DICOM file
346
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
327 f = orthanc.GetDicomForInstance(instanceId)
347
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
328 # Parse it using pydicom
346
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
329 dicom = pydicom.dcmread(io.BytesIO(f))
347
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
330 # Return a string representation the dataset to the caller
346
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
331 output.AnswerBuffer(str(dicom), 'text/plain')
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
332 else:
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
333 output.SendMethodNotAllowed('GET')
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
334
347
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
335 orthanc.RegisterRestCallback('/pydicom/(.*)', DecodeInstance) # (*)
346
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
336
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
337 .. highlight:: bash
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
338
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
339 This can be called as follows::
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
340
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
341 $ curl http://localhost:8042/pydicom/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5
bdf8757449e3 more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 345
diff changeset
342
347
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
343
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
344 Auto-routing studies
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
345 ....................
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
346
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
347 .. highlight:: python
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
348
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
349 Here is a sample Python plugin that routes any :ref:`stable study
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
350 <lua-callbacks>` to a modality named ``samples`` (as declared in the
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
351 ``DicomModalities`` configuration option)::
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
352
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
353 import orthanc
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
354
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
355 def OnChange(changeType, level, resourceId):
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
356 if changeType == orthanc.ChangeType.STABLE_STUDY:
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
357 print('Stable study: %s' % resourceId)
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
358 orthanc.RestApiPost('/modalities/sample/store', resourceId)
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
359
04fae9d4b65f auto-routing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 346
diff changeset
360 orthanc.RegisterOnChangeCallback(OnChange)
348
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
361
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
362
352
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
363 Rendering a thumbnail using PIL/Pillow
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
364 ......................................
348
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
365
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
366 .. highlight:: python
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
367
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
368 ::
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
369
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
370 from PIL import Image
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
371 import io
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
372 import orthanc
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
373
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
374 def DecodeInstance(output, uri, **request):
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
375 if request['method'] == 'GET':
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
376 # Retrieve the instance ID from the regular expression (*)
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
377 instanceId = request['groups'][0]
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
378
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
379 # Render the instance, then open it in Python using PIL/Pillow
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
380 png = orthanc.RestApiGet('/instances/%s/rendered' % instanceId)
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
381 image = Image.open(io.BytesIO(png))
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
382
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
383 # Downsize the image as a 64x64 thumbnail
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
384 image.thumbnail((64, 64), Image.ANTIALIAS)
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
385
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
386 # Save the thumbnail as JPEG, then send the buffer to the caller
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
387 jpeg = io.BytesIO()
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
388 image.save(jpeg, format = "JPEG", quality = 80)
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
389 jpeg.seek(0)
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
390 output.AnswerBuffer(jpeg.read(), 'text/plain')
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
391
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
392 else:
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
393 output.SendMethodNotAllowed('GET')
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
394
d8359cecdc89 pillow sample
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 347
diff changeset
395 orthanc.RegisterRestCallback('/pydicom/(.*)', DecodeInstance) # (*)
351
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
396
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
397
369
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
398 .. _python-introspection:
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
399
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
400 Inspecting the available API
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
401 ............................
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
402
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
403 .. highlight:: python
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
404
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
405 Thanks to Python's introspection primitives, it is possible to inspect
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
406 the API of the ``orthanc`` module in order to dump all the available
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
407 features::
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
408
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
409 import inspect
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
410 import numbers
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
411 import orthanc
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
412
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
413 # Loop over the members of the "orthanc" module
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
414 for (name, obj) in inspect.getmembers(orthanc):
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
415 if inspect.isroutine(obj):
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
416 print('Function %s():\n Documentation: %s\n' % (name, inspect.getdoc(obj)))
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
417
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
418 elif inspect.isclass(obj):
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
419 print('Class %s:\n Documentation: %s' % (name, inspect.getdoc(obj)))
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
420
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
421 # Loop over the members of the class
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
422 for (subname, subobj) in inspect.getmembers(obj):
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
423 if isinstance(subobj, numbers.Number):
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
424 print(' - Enumeration value %s: %s' % (subname, subobj))
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
425 elif (not subname.startswith('_') and
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
426 inspect.ismethoddescriptor(subobj)):
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
427 print(' - Method %s(): %s' % (subname, inspect.getdoc(subobj)))
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
428 print('')
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
429
373
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
430
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
431 .. _python-scheduler:
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
432
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
433 Scheduling a task for periodic execution
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
434 ........................................
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
435
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
436 .. highlight:: python
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
437
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
438 The following Python script will periodically (every second) run the
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
439 function ``Hello()`` thanks to the ``threading`` module::
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
440
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
441 import orthanc
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
442 import threading
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
443
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
444 TIMER = None
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
445
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
446 def Hello():
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
447 global TIMER
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
448 TIMER = None
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
449 orthanc.LogWarning("In Hello()")
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
450 # Do stuff...
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
451 TIMER = threading.Timer(1, Hello) # Re-schedule after 1 second
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
452 TIMER.start()
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
453
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
454 def OnChange(changeType, level, resource):
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
455 if changeType == orthanc.ChangeType.ORTHANC_STARTED:
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
456 orthanc.LogWarning("Starting the scheduler")
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
457 Hello()
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
458
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
459 elif changeType == orthanc.ChangeType.ORTHANC_STOPPED:
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
460 if TIMER != None:
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
461 orthanc.LogWarning("Stopping the scheduler")
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
462 TIMER.cancel()
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
463
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
464 orthanc.RegisterOnChangeCallback(OnChange)
847996394688 Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 369
diff changeset
465
378
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
466
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
467 .. _python-metadata:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
468
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
469 Filtering and returning metadata
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
470 ................................
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
471
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
472 Besides the main DICOM tags, Orthanc associates some metadata to each
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
473 resource it stores (this includes the date of last update, the
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
474 transfer syntax, the remote AET...). People are often interested in
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
475 getting such metadata while calling the ``/tools/find`` route in the
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
476 :ref:`REST API <rest-find>`, or even in filtering this metadata the
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
477 same way they look for DICOM tags.
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
478
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
479 This feature is not built in the core of Orthanc, as metadata is not
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
480 indexed in the Orthanc database, contrarily to the main DICOM
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
481 tags. Filtering metadata requires a linear search over all the
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
482 matching resources, which induces a cost in the performance.
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
483
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
484 .. highlight:: python
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
485
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
486 Nevertheless, here is a full sample Python script that overwrites the
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
487 ``/tools/find`` route in order to give access to metadata::
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
488
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
489 import json
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
490 import orthanc
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
491 import re
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
492
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
493 # Get the path in the REST API to the given resource that was returned
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
494 # by a call to "/tools/find"
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
495 def GetPath(resource):
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
496 if resource['Type'] == 'Patient':
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
497 return '/patients/%s' % resource['ID']
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
498 elif resource['Type'] == 'Study':
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
499 return '/studies/%s' % resource['ID']
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
500 elif resource['Type'] == 'Series':
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
501 return '/series/%s' % resource['ID']
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
502 elif resource['Type'] == 'Instance':
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
503 return '/instances/%s' % resource['ID']
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
504 else:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
505 raise Exception('Unknown resource level')
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
506
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
507 def FindWithMetadata(output, uri, **request):
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
508 # The "/tools/find" route expects a POST method
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
509 if request['method'] != 'POST':
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
510 output.SendMethodNotAllowed('POST')
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
511 else:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
512 # Parse the query provided by the user, and backup the "Expand" field
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
513 query = json.loads(request['body'])
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
514
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
515 if 'Expand' in query:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
516 originalExpand = query['Expand']
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
517 else:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
518 originalExpand = False
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
519
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
520 # Call the core "/tools/find" route
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
521 query['Expand'] = True
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
522 answers = orthanc.RestApiPost('/tools/find', json.dumps(query))
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
523
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
524 # Loop over the matching resources
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
525 filteredAnswers = []
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
526 for answer in json.loads(answers):
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
527 try:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
528 # Read the metadata that is associated with the resource
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
529 metadata = json.loads(orthanc.RestApiGet('%s/metadata?expand' % GetPath(answer)))
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
530
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
531 # Check whether the metadata matches the regular expressions
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
532 # that were provided in the "Metadata" field of the user request
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
533 isMetadataMatch = True
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
534 if 'Metadata' in query:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
535 for (name, pattern) in query['Metadata'].items():
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
536 if name in metadata:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
537 value = metadata[name]
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
538 else:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
539 value = ''
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
540
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
541 if re.match(pattern, value) == None:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
542 isMetadataMatch = False
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
543 break
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
544
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
545 # If all the metadata matches the provided regular
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
546 # expressions, add the resource to the filtered answers
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
547 if isMetadataMatch:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
548 if originalExpand:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
549 answer['Metadata'] = metadata
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
550 filteredAnswers.append(answer)
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
551 else:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
552 filteredAnswers.append(answer['ID'])
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
553 except:
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
554 # The resource was deleted since the call to "/tools/find"
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
555 pass
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
556
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
557 # Return the filtered answers in the JSON format
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
558 output.AnswerBuffer(json.dumps(filteredAnswers, indent = 3), 'application/json')
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
559
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
560 orthanc.RegisterRestCallback('/tools/find', FindWithMetadata)
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
561
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
562
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
563 **Warning:** In the sample above, the filtering of the metadata is
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
564 done using Python's `library for regular expressions
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
565 <https://docs.python.org/3/library/re.html>`__. It is evidently
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
566 possible to adapt this script in order to use the DICOM conventions
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
567 about `attribute matching
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
568 <http://dicom.nema.org/medical/dicom/2019e/output/chtml/part04/sect_C.2.2.2.html>`__.
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
569
469
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
570 .. highlight:: bash
378
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
571
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
572 Here is a sample call to retrieve all the studies that were last
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
573 updated in 2019 thanks to this Python script::
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
574
16dc3561b41e Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 375
diff changeset
575 $ curl http://localhost:8042/tools/find -d '{"Level":"Study","Query":{},"Expand":true,"Metadata":{"LastUpdate":"^2019.*$"}}'
369
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
576
181b02cea7ab inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 364
diff changeset
577
469
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
578 .. _python-paging:
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
579
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
580 Implementing basic paging
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
581 .........................
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
582
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
583 .. highlight:: python
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
584
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
585 As explained in the FAQ, the :ref:`Orthanc Explorer interface is
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
586 low-level <improving-interface>`, and is not adapted for
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
587 end-users. One common need is to implement paging of studies, which
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
588 calls for server-side sorting of studies. This can be done using the
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
589 following sample Python plugin that registers a new route
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
590 ``/sort-studies`` in the REST API of Orthanc::
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
591
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
592 import json
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
593 import orthanc
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
594
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
595 def GetStudyDate(study):
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
596 if 'StudyDate' in study['MainDicomTags']:
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
597 return study['MainDicomTags']['StudyDate']
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
598 else:
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
599 return ''
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
600
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
601 def SortStudiesByDate(output, uri, **request):
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
602 if request['method'] == 'GET':
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
603 # Retrieve all the studies
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
604 studies = json.loads(orthanc.RestApiGet('/studies?expand'))
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
605
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
606 # Sort the studies according to the "StudyDate" DICOM tag
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
607 studies = sorted(studies, key = GetStudyDate)
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
608
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
609 # Read the limit/offset arguments provided by the user
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
610 offset = 0
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
611 if 'offset' in request['get']:
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
612 offset = int(request['get']['offset'])
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
613
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
614 limit = 0
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
615 if 'limit' in request['get']:
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
616 limit = int(request['get']['limit'])
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
617
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
618 # Truncate the list of studies
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
619 if limit == 0:
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
620 studies = studies[offset : ]
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
621 else:
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
622 studies = studies[offset : offset + limit]
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
623
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
624 # Return the truncated list of studies
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
625 output.AnswerBuffer(json.dumps(studies), 'application/json')
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
626 else:
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
627 output.SendMethodNotAllowed('GET')
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
628
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
629 orthanc.RegisterRestCallback('/sort-studies', SortStudiesByDate)
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
630
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
631
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
632 .. highlight:: bash
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
633
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
634 Here is a sample call to this new REST route, that could be issued by
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
635 any JavaScript framework (the ``json_pp`` command-line pretty-prints a
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
636 JSON file)::
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
637
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
638 $ curl http://localhost:8042/sort-studies | json_pp
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
639
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
640 This route also implement paging (i.e. it can limit and offset the
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
641 returned studies)::
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
642
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
643 $ curl 'http://localhost:8042/sort-studies?offset=2&limit=2' | json_pp
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
644
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
645 Obviously, this basic sample can be improved in many ways. To improve
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
646 performance, one could for instance cache the result of
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
647 ``/studies?expand`` in memory by :ref:`listening to changes
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
648 <python-changes>` in the list of studies
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
649 (cf. ``orthanc.ChangeType.NEW_STUDY`` and
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
650 ``orthanc.ChangeType.DELETED``).
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
651
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
652
46949efa5818 Implementing basic paging using a Python script
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
653
351
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
654 Performance and concurrency
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
655 ---------------------------
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
656
471
a735476a0e6e note about fork on windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
657 **Important:** This section only applies to UNIX-like systems. The
a735476a0e6e note about fork on windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
658 ``multiprocessing`` package will not work on Microsoft Windows as the
a735476a0e6e note about fork on windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
659 latter OS has a different model for `forking processes
a735476a0e6e note about fork on windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
660 <https://en.wikipedia.org/wiki/Fork_(system_call)>`__.
a735476a0e6e note about fork on windows
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 462
diff changeset
661
351
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
662 .. highlight:: python
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
663
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
664 Let us consider the following sample Python script that makes a
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
665 CPU-intensive computation on a REST callback::
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
666
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
667 import math
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
668 import orthanc
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
669 import time
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
670
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
671 # CPU-intensive computation taking about 4 seconds
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
672 def SlowComputation():
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
673 start = time.time()
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
674 for i in range(1000):
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
675 for j in range(30000):
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
676 math.sqrt(float(j))
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
677 end = time.time()
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
678 duration = (end - start)
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
679 return 'computation done in %.03f seconds\n' % duration
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
680
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
681 def OnRest(output, uri, **request):
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
682 answer = SlowComputation()
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
683 output.AnswerBuffer(answer, 'text/plain')
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
684
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
685 orthanc.RegisterRestCallback('/computation', OnRest)
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
686
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
687
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
688 .. highlight:: text
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
689
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
690 Calling this REST route from the command-line returns the time that is
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
691 needed to compute 30 million times a squared root on your CPU::
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
692
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
693 $ curl http://localhost:8042/computation
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
694 computation done in 4.208 seconds
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
695
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
696 Now, let us call this route three times concurrently (we use bash)::
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
697
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
698 $ (curl http://localhost:8042/computation & curl http://localhost:8042/computation & curl http://localhost:8042/computation )
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
699 computation done in 11.262 seconds
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
700 computation done in 12.457 seconds
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
701 computation done in 13.360 seconds
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
702
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
703 As can be seen, the computation time has tripled. This means that the
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
704 computations were not distributed across the available CPU cores.
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
705 This might seem surprising, as Orthanc is a threaded server (in
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
706 Orthanc, a pool of C++ threads serves concurrent requests).
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
707
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
708 The explanation is that the Python interpreter (`CPython
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
709 <https://en.wikipedia.org/wiki/CPython>`__ actually) is built on the
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
710 top of a so-called `Global Interpreter Lock (GIL)
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
711 <https://en.wikipedia.org/wiki/Global_interpreter_lock>`__. The GIL is
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
712 basically a mutex that protects all the calls to the Python
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
713 interpreter. If multiple C++ threads from Orthanc call a Python
353
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
714 callback, only one can proceed at any given time. Note however that
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
715 the GIL only applies to the Python script: The baseline REST API of
0122c668f4ec python licensing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 352
diff changeset
716 Orthanc is not affected by the GIL.
351
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
717
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
718 .. highlight:: python
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
719
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
720 The solution is to use the `multiprocessing primitives
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
721 <https://docs.python.org/3/library/multiprocessing.html>`__ of Python.
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
722 The "master" Python interpreter that is initially started by the
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
723 Orthanc plugin, can start several `children processes
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
724 <https://en.wikipedia.org/wiki/Process_(computing)>`__, each of these
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
725 processes running a separate Python interpreter. This allows to
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
726 offload intensive computations from the "master" Python interpreter of
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
727 Orthanc onto those "slave" interpreters. The ``multiprocessing``
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
728 library is actually quite straightforward to use::
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
729
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
730 import math
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
731 import multiprocessing
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
732 import orthanc
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
733 import signal
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
734 import time
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
735
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
736 # CPU-intensive computation taking about 4 seconds
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
737 # (same code as above)
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
738 def SlowComputation():
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
739 start = time.time()
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
740 for i in range(1000):
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
741 for j in range(30000):
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
742 math.sqrt(float(j))
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
743 end = time.time()
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
744 duration = (end - start)
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
745 return 'computation done in %.03f seconds\n' % duration
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
746
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
747 # Ignore CTRL+C in the slave processes
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
748 def Initializer():
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
749 signal.signal(signal.SIGINT, signal.SIG_IGN)
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
750
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
751 # Create a pool of 4 slave Python interpreters
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
752 POOL = multiprocessing.Pool(4, initializer = Initializer)
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
753
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
754 def OnRest(output, uri, **request):
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
755 # Offload the call to "SlowComputation" onto one slave process.
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
756 # The GIL is unlocked until the slave sends its answer back.
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
757 answer = POOL.apply(SlowComputation)
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
758 output.AnswerBuffer(answer, 'text/plain')
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
759
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
760 orthanc.RegisterRestCallback('/computation', OnRest)
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
761
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
762 .. highlight:: text
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
763
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
764 Here is now the result of calling this route three times concurrently::
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
765
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
766 $ (curl http://localhost:8042/computation & curl http://localhost:8042/computation & curl http://localhost:8042/computation )
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
767 computation done in 4.211 seconds
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
768 computation done in 4.215 seconds
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
769 computation done in 4.225 seconds
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
770
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
771 As can be seen, the calls to the Python computation now fully run in
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
772 parallel (the time is cut down from 12 seconds to 4 seconds, the same
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
773 as for one isolated request).
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
774
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
775 Note also how the ``multiprocessing`` library allows to make a fine
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
776 control over the computational resources that are available to the
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
777 Python script: The number of "slave" interpreters can be easily
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
778 changed in the constructor of the ``multiprocessing.Pool`` object, and
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
779 are fully independent of the threads used by the Orthanc server.
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
780
352
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
781 .. highlight:: python
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
782
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
783 Very importantly, pay attention to the fact that only the "master"
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
784 Python interpreter has access to the Orthanc SDK. For instance, here
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
785 is how you would parse a DICOM file in a slave process::
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
786
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
787 import pydicom
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
788 import io
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
789
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
790 def OffloadedDicomParsing(dicom):
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
791 # No access to the "orthanc" library here, as we are in the slave process
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
792 dataset = pydicom.dcmread(io.BytesIO(dicom))
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
793 return str(dataset)
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
794
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
795 def OnRest(output, uri, **request):
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
796 # The call to "orthanc.RestApiGet()" is only possible in the master process
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
797 dicom = orthanc.RestApiGet('/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/file')
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
798 answer = POOL.apply(OffloadedDicomParsing, args = (dicom, ))
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
799 output.AnswerBuffer(answer, 'text/plain')
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
800
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
801 Communication primitives such as ``multiprocessing.Queue`` are
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
802 available to exchange messages from the "slave" Python interpreters to
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
803 the "master" Python interpreter if further calls to the Orthanc SDK
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
804 are required.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 351
diff changeset
805
351
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
806 Obviously, an in-depth discussion about the ``multiprocessing``
e2863083fa30 multiprocessing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 350
diff changeset
807 library is out of the scope of this document. There are many
375
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 374
diff changeset
808 references available on Internet. Also, note that ``threading`` is not
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 374
diff changeset
809 useful here, as Python multithreading is also limited by the GIL, and
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 374
diff changeset
810 is more targeted at dealing with costly I/O operations or with the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 374
diff changeset
811 :ref:`scheduling of commands <python-scheduler>`.