Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/python.rst @ 405:ba486cac480a
link to python sample
| author | Alain Mazy <alain@mazy.be> |
|---|---|
| date | Wed, 29 Apr 2020 12:59:58 +0200 |
| parents | c9fe3d0d0fa1 |
| children | 8b2c648c0f46 |
| 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 |
| 345 | 21 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.5.7/Plugins/Include/orthanc/OrthancCPlugin.h>`__ |
| 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 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
25 As of initial release 1.0 of the plugin, the coverage of the C SDK is |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
26 about 75% (105 functions are automatically wrapped in Python out of a |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
27 total of 139 functions in the Orthanc SDK 1.5.7). |
|
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 | 40 Licensing |
| 41 --------- | |
| 42 | |
| 43 Pay attention to the fact that this plugin is licensed under the terms | |
| 44 of the `AGPL license | |
| 45 <https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License>`__. | |
| 46 | |
| 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 | 51 community under the terms of the AGPL license. |
| 52 | |
| 53 We suggest you to put the source code of your Python scripts on the | |
| 54 dedicated `"OrthancContributed" repository on GitHub | |
| 55 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__, | |
| 56 and/or to send it to the `Orthanc Users | |
| 57 <https://groups.google.com/forum/#!forum/orthanc-users>`__ discussion | |
| 58 group. | |
| 353 | 59 |
| 60 Check out the :ref:`FAQ about licensing <licensing>` for more context. | |
| 61 | |
| 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 | 111 `Here <https://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/python/>`__ is a full example |
| 112 of a more complex setup using the :ref:`osimis/orthanc <docker-osimis>` images. | |
| 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. |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
140 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
141 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
142 Microsoft Windows |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
143 ................. |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
144 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
145 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
|
146 <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
|
147 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
148 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
|
149 one version of the Python interpreter. This version is clearly |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
150 indicated in the name of the folder. |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
151 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
152 As of release 1.0, the Orthanc project only provides pre-compiled |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
153 binaries for Microsoft Windows 32bit and Python 2.7. Even though this |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
154 version of Python is not supported anymore, it can still run on all |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
155 the versions of Microsoft Windows that have been released for more |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
156 than 10 years. |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
157 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
158 .. highlight:: text |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
159 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
160 You are of course free to compile the plugin from sources if you need |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
161 a more recent version. You'll have to explicitly specify the path to |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
162 your Python installation while invoking CMake. For instance:: |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
163 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
164 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
|
165 -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
|
166 |
|
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
|
167 **Note about debug builds**: usually, building Python modules such as the 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
|
168 plugin for Orthanc in debug mode (where ``_DEBUG`` is defined) leads to a module |
|
ffe62e6c086f
Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents:
375
diff
changeset
|
169 (.exe or .dll) that requires a debug build of Python, and debug versions of all |
|
ffe62e6c086f
Added a note about the debug libraries when building under Windows with Visual Studio.
Benjamin Golinvaux <bgo@osimis.io>
parents:
375
diff
changeset
|
170 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
|
171 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
|
172 |
|
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 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
|
174 (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
|
175 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
|
176 |
|
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 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
|
178 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
|
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 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
|
181 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
|
182 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
|
183 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
|
184 |
|
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 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
|
186 -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
|
187 -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
|
188 |
|
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 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
|
190 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
|
191 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
192 Configuration options |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
193 --------------------- |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
194 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
195 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
|
196 are the following: |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
197 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
198 * ``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
|
199 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
|
200 started. |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
201 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
202 * ``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
|
203 verbose. |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
354
diff
changeset
|
204 |
|
343
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
205 |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
206 Samples |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
207 ------- |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
208 |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
209 Extending the REST API |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
210 ...................... |
|
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 .. highlight:: python |
|
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 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
|
215 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 import orthanc |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
218 import pprint |
|
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 def OnRest(output, uri, **request): |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
221 pprint.pprint(request) |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
222 print('Accessing uri: %s' % uri) |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
223 output.AnswerBuffer('ok\n', 'text/plain') |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
224 |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
225 orthanc.RegisterRestCallback('/(to)(t)o', OnRest) |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
226 orthanc.RegisterRestCallback('/tata', OnRest) |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
227 |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
228 .. highlight:: json |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
229 |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
230 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
|
231 (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
|
232 |
|
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 "Plugins" : [ "." ], |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
235 "PythonScript" : "rest.py", |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
236 "PythonVerbose" : false |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
237 } |
|
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 .. highlight:: bash |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
240 |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
241 The route can then be accessed as:: |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
242 |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
243 $ curl http://localhost:8042/toto |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
244 ok |
|
fff45618262d
creating the documentation of the Python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
245 |
| 345 | 246 |
| 247 Listening to changes | |
| 248 .................... | |
| 249 | |
|
346
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
250 .. highlight:: python |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
251 |
| 345 | 252 This sample uploads a DICOM file as soon as Orthanc is started:: |
| 253 | |
| 254 import orthanc | |
| 255 | |
| 256 def OnChange(changeType, level, resource): | |
| 257 if changeType == orthanc.ChangeType.ORTHANC_STARTED: | |
| 258 print('Started') | |
| 259 | |
| 260 with open('/tmp/sample.dcm', 'rb') as f: | |
| 261 orthanc.RestApiPost('/instances', f.read()) | |
| 262 | |
| 263 elif changeType == orthanc.ChangeType.ORTHANC_STOPPED: | |
| 264 print('Stopped') | |
| 265 | |
| 266 elif changeType == orthanc.ChangeType.NEW_INSTANCE: | |
| 267 print('A new instance was uploaded: %s' % resource) | |
| 268 | |
| 269 orthanc.RegisterOnChangeCallback(OnChange) | |
| 270 | |
| 271 | |
| 272 Accessing the content of a new instance | |
|
346
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
273 ....................................... |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
274 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
275 .. highlight:: python |
| 345 | 276 |
| 277 :: | |
| 278 | |
| 279 import orthanc | |
| 280 import json | |
| 281 import pprint | |
| 282 | |
| 283 def OnStoredInstance(dicom, instanceId): | |
| 284 print('Received instance %s of size %d (transfer syntax %s, SOP class UID %s)' % ( | |
| 285 instanceId, dicom.GetInstanceSize(), | |
| 286 dicom.GetInstanceMetadata('TransferSyntax'), | |
| 287 dicom.GetInstanceMetadata('SopClassUid'))) | |
| 288 | |
| 289 # Print the origin information | |
| 290 if dicom.GetInstanceOrigin() == orthanc.InstanceOrigin.DICOM_PROTOCOL: | |
| 291 print('This instance was received through the DICOM protocol') | |
| 292 elif dicom.GetInstanceOrigin() == orthanc.InstanceOrigin.REST_API: | |
| 293 print('This instance was received through the REST API') | |
| 294 | |
| 295 # Print the DICOM tags | |
| 296 pprint.pprint(json.loads(dicom.GetInstanceSimplifiedJson())) | |
| 297 | |
| 298 orthanc.RegisterOnStoredInstanceCallback(OnStoredInstance) | |
|
346
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
299 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
300 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
301 Calling pydicom |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
302 ............... |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
303 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
304 .. highlight:: python |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
305 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
306 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
|
307 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
|
308 Orthanc, using `pydicom <https://pydicom.github.io/>`__:: |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
309 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
310 import io |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
311 import orthanc |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
312 import pydicom |
|
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 def DecodeInstance(output, uri, **request): |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
315 if request['method'] == 'GET': |
| 347 | 316 # Retrieve the instance ID from the regular expression (*) |
|
346
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
317 instanceId = request['groups'][0] |
| 347 | 318 # Get the content of the DICOM file |
|
346
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
319 f = orthanc.GetDicomForInstance(instanceId) |
| 347 | 320 # Parse it using pydicom |
|
346
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
321 dicom = pydicom.dcmread(io.BytesIO(f)) |
| 347 | 322 # Return a string representation the dataset to the caller |
|
346
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
323 output.AnswerBuffer(str(dicom), 'text/plain') |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
324 else: |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
325 output.SendMethodNotAllowed('GET') |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
326 |
| 347 | 327 orthanc.RegisterRestCallback('/pydicom/(.*)', DecodeInstance) # (*) |
|
346
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
328 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
329 .. highlight:: bash |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
330 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
331 This can be called as follows:: |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
332 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
333 $ curl http://localhost:8042/pydicom/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5 |
|
bdf8757449e3
more python samples
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
345
diff
changeset
|
334 |
| 347 | 335 |
| 336 Auto-routing studies | |
| 337 .................... | |
| 338 | |
| 339 .. highlight:: python | |
| 340 | |
| 341 Here is a sample Python plugin that routes any :ref:`stable study | |
| 342 <lua-callbacks>` to a modality named ``samples`` (as declared in the | |
| 343 ``DicomModalities`` configuration option):: | |
| 344 | |
| 345 import orthanc | |
| 346 | |
| 347 def OnChange(changeType, level, resourceId): | |
| 348 if changeType == orthanc.ChangeType.STABLE_STUDY: | |
| 349 print('Stable study: %s' % resourceId) | |
| 350 orthanc.RestApiPost('/modalities/sample/store', resourceId) | |
| 351 | |
| 352 orthanc.RegisterOnChangeCallback(OnChange) | |
| 348 | 353 |
| 354 | |
| 352 | 355 Rendering a thumbnail using PIL/Pillow |
| 356 ...................................... | |
| 348 | 357 |
| 358 .. highlight:: python | |
| 359 | |
| 360 :: | |
| 361 | |
| 362 from PIL import Image | |
| 363 import io | |
| 364 import orthanc | |
| 365 | |
| 366 def DecodeInstance(output, uri, **request): | |
| 367 if request['method'] == 'GET': | |
| 368 # Retrieve the instance ID from the regular expression (*) | |
| 369 instanceId = request['groups'][0] | |
| 370 | |
| 371 # Render the instance, then open it in Python using PIL/Pillow | |
| 372 png = orthanc.RestApiGet('/instances/%s/rendered' % instanceId) | |
| 373 image = Image.open(io.BytesIO(png)) | |
| 374 | |
| 375 # Downsize the image as a 64x64 thumbnail | |
| 376 image.thumbnail((64, 64), Image.ANTIALIAS) | |
| 377 | |
| 378 # Save the thumbnail as JPEG, then send the buffer to the caller | |
| 379 jpeg = io.BytesIO() | |
| 380 image.save(jpeg, format = "JPEG", quality = 80) | |
| 381 jpeg.seek(0) | |
| 382 output.AnswerBuffer(jpeg.read(), 'text/plain') | |
| 383 | |
| 384 else: | |
| 385 output.SendMethodNotAllowed('GET') | |
| 386 | |
| 387 orthanc.RegisterRestCallback('/pydicom/(.*)', DecodeInstance) # (*) | |
| 351 | 388 |
| 389 | |
|
369
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
390 .. _python-introspection: |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
391 |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
392 Inspecting the available API |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
393 ............................ |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
394 |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
395 .. highlight:: python |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
396 |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
397 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
|
398 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
|
399 features:: |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
400 |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
401 import inspect |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
402 import numbers |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
403 import orthanc |
|
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 # Loop over the members of the "orthanc" module |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
406 for (name, obj) in inspect.getmembers(orthanc): |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
407 if inspect.isroutine(obj): |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
408 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
|
409 |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
410 elif inspect.isclass(obj): |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
411 print('Class %s:\n Documentation: %s' % (name, inspect.getdoc(obj))) |
|
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 class |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
414 for (subname, subobj) in inspect.getmembers(obj): |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
415 if isinstance(subobj, numbers.Number): |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
416 print(' - Enumeration value %s: %s' % (subname, subobj)) |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
417 elif (not subname.startswith('_') and |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
418 inspect.ismethoddescriptor(subobj)): |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
419 print(' - Method %s(): %s' % (subname, inspect.getdoc(subobj))) |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
420 print('') |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
421 |
|
373
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
422 |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
423 .. _python-scheduler: |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
424 |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
425 Scheduling a task for periodic execution |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
426 ........................................ |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
427 |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
428 .. highlight:: python |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
429 |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
430 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
|
431 function ``Hello()`` thanks to the ``threading`` module:: |
|
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 import orthanc |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
434 import threading |
|
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 TIMER = None |
|
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 def Hello(): |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
439 global TIMER |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
440 TIMER = None |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
441 orthanc.LogWarning("In Hello()") |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
442 # Do stuff... |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
443 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
|
444 TIMER.start() |
|
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 OnChange(changeType, level, resource): |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
447 if changeType == orthanc.ChangeType.ORTHANC_STARTED: |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
448 orthanc.LogWarning("Starting the scheduler") |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
449 Hello() |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
450 |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
451 elif changeType == orthanc.ChangeType.ORTHANC_STOPPED: |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
452 if TIMER != None: |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
453 orthanc.LogWarning("Stopping the scheduler") |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
454 TIMER.cancel() |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
455 |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
456 orthanc.RegisterOnChangeCallback(OnChange) |
|
847996394688
Scheduling a task for periodic execution
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
369
diff
changeset
|
457 |
|
378
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
458 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
459 .. _python-metadata: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
460 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
461 Filtering and returning metadata |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
462 ................................ |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
463 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
464 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
|
465 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
|
466 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
|
467 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
|
468 :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
|
469 same way they look for DICOM tags. |
|
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 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
|
472 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
|
473 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
|
474 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
|
475 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
476 .. highlight:: python |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
477 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
478 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
|
479 ``/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
|
480 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
481 import json |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
482 import orthanc |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
483 import re |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
484 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
485 # 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
|
486 # by a call to "/tools/find" |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
487 def GetPath(resource): |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
488 if resource['Type'] == 'Patient': |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
489 return '/patients/%s' % resource['ID'] |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
490 elif resource['Type'] == 'Study': |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
491 return '/studies/%s' % resource['ID'] |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
492 elif resource['Type'] == 'Series': |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
493 return '/series/%s' % resource['ID'] |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
494 elif resource['Type'] == 'Instance': |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
495 return '/instances/%s' % resource['ID'] |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
496 else: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
497 raise Exception('Unknown resource level') |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
498 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
499 def FindWithMetadata(output, uri, **request): |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
500 # 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
|
501 if request['method'] != 'POST': |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
502 output.SendMethodNotAllowed('POST') |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
503 else: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
504 # 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
|
505 query = json.loads(request['body']) |
|
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 if 'Expand' in query: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
508 originalExpand = query['Expand'] |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
509 else: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
510 originalExpand = False |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
511 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
512 # Call the core "/tools/find" route |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
513 query['Expand'] = True |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
514 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
|
515 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
516 # Loop over the matching resources |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
517 filteredAnswers = [] |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
518 for answer in json.loads(answers): |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
519 try: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
520 # 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
|
521 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
|
522 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
523 # 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
|
524 # 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
|
525 isMetadataMatch = True |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
526 if 'Metadata' in query: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
527 for (name, pattern) in query['Metadata'].items(): |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
528 if name in metadata: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
529 value = metadata[name] |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
530 else: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
531 value = '' |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
532 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
533 if re.match(pattern, value) == None: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
534 isMetadataMatch = False |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
535 break |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
536 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
537 # 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
|
538 # 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
|
539 if isMetadataMatch: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
540 if originalExpand: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
541 answer['Metadata'] = metadata |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
542 filteredAnswers.append(answer) |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
543 else: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
544 filteredAnswers.append(answer['ID']) |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
545 except: |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
546 # 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
|
547 pass |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
548 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
549 # 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
|
550 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
|
551 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
552 orthanc.RegisterRestCallback('/tools/find', FindWithMetadata) |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
553 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
554 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
555 **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
|
556 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
|
557 <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
|
558 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
|
559 about `attribute matching |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
560 <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
|
561 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
562 .. highlight:: python |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
563 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
564 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
|
565 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
|
566 |
|
16dc3561b41e
Filtering and returning metadata using Python
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
375
diff
changeset
|
567 $ 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
|
568 |
|
181b02cea7ab
inspecting Python API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
364
diff
changeset
|
569 |
| 351 | 570 Performance and concurrency |
| 571 --------------------------- | |
| 572 | |
| 573 .. highlight:: python | |
| 574 | |
| 575 Let us consider the following sample Python script that makes a | |
| 576 CPU-intensive computation on a REST callback:: | |
| 577 | |
| 578 import math | |
| 579 import orthanc | |
| 580 import time | |
| 581 | |
| 582 # CPU-intensive computation taking about 4 seconds | |
| 583 def SlowComputation(): | |
| 584 start = time.time() | |
| 585 for i in range(1000): | |
| 586 for j in range(30000): | |
| 587 math.sqrt(float(j)) | |
| 588 end = time.time() | |
| 589 duration = (end - start) | |
| 590 return 'computation done in %.03f seconds\n' % duration | |
| 591 | |
| 592 def OnRest(output, uri, **request): | |
| 593 answer = SlowComputation() | |
| 594 output.AnswerBuffer(answer, 'text/plain') | |
| 595 | |
| 596 orthanc.RegisterRestCallback('/computation', OnRest) | |
| 597 | |
| 598 | |
| 599 .. highlight:: text | |
| 600 | |
| 601 Calling this REST route from the command-line returns the time that is | |
| 602 needed to compute 30 million times a squared root on your CPU:: | |
| 603 | |
| 604 $ curl http://localhost:8042/computation | |
| 605 computation done in 4.208 seconds | |
| 606 | |
| 607 Now, let us call this route three times concurrently (we use bash):: | |
| 608 | |
| 609 $ (curl http://localhost:8042/computation & curl http://localhost:8042/computation & curl http://localhost:8042/computation ) | |
| 610 computation done in 11.262 seconds | |
| 611 computation done in 12.457 seconds | |
| 612 computation done in 13.360 seconds | |
| 613 | |
| 614 As can be seen, the computation time has tripled. This means that the | |
| 615 computations were not distributed across the available CPU cores. | |
| 616 This might seem surprising, as Orthanc is a threaded server (in | |
| 617 Orthanc, a pool of C++ threads serves concurrent requests). | |
| 618 | |
| 619 The explanation is that the Python interpreter (`CPython | |
| 620 <https://en.wikipedia.org/wiki/CPython>`__ actually) is built on the | |
| 621 top of a so-called `Global Interpreter Lock (GIL) | |
| 622 <https://en.wikipedia.org/wiki/Global_interpreter_lock>`__. The GIL is | |
| 623 basically a mutex that protects all the calls to the Python | |
| 624 interpreter. If multiple C++ threads from Orthanc call a Python | |
| 353 | 625 callback, only one can proceed at any given time. Note however that |
| 626 the GIL only applies to the Python script: The baseline REST API of | |
| 627 Orthanc is not affected by the GIL. | |
| 351 | 628 |
| 629 .. highlight:: python | |
| 630 | |
| 631 The solution is to use the `multiprocessing primitives | |
| 632 <https://docs.python.org/3/library/multiprocessing.html>`__ of Python. | |
| 633 The "master" Python interpreter that is initially started by the | |
| 634 Orthanc plugin, can start several `children processes | |
| 635 <https://en.wikipedia.org/wiki/Process_(computing)>`__, each of these | |
| 636 processes running a separate Python interpreter. This allows to | |
| 637 offload intensive computations from the "master" Python interpreter of | |
| 638 Orthanc onto those "slave" interpreters. The ``multiprocessing`` | |
| 639 library is actually quite straightforward to use:: | |
| 640 | |
| 641 import math | |
| 642 import multiprocessing | |
| 643 import orthanc | |
| 644 import signal | |
| 645 import time | |
| 646 | |
| 647 # CPU-intensive computation taking about 4 seconds | |
| 648 # (same code as above) | |
| 649 def SlowComputation(): | |
| 650 start = time.time() | |
| 651 for i in range(1000): | |
| 652 for j in range(30000): | |
| 653 math.sqrt(float(j)) | |
| 654 end = time.time() | |
| 655 duration = (end - start) | |
| 656 return 'computation done in %.03f seconds\n' % duration | |
| 657 | |
| 658 # Ignore CTRL+C in the slave processes | |
| 659 def Initializer(): | |
| 660 signal.signal(signal.SIGINT, signal.SIG_IGN) | |
| 661 | |
| 662 # Create a pool of 4 slave Python interpreters | |
| 663 POOL = multiprocessing.Pool(4, initializer = Initializer) | |
| 664 | |
| 665 def OnRest(output, uri, **request): | |
| 666 # Offload the call to "SlowComputation" onto one slave process. | |
| 667 # The GIL is unlocked until the slave sends its answer back. | |
| 668 answer = POOL.apply(SlowComputation) | |
| 669 output.AnswerBuffer(answer, 'text/plain') | |
| 670 | |
| 671 orthanc.RegisterRestCallback('/computation', OnRest) | |
| 672 | |
| 673 .. highlight:: text | |
| 674 | |
| 675 Here is now the result of calling this route three times concurrently:: | |
| 676 | |
| 677 $ (curl http://localhost:8042/computation & curl http://localhost:8042/computation & curl http://localhost:8042/computation ) | |
| 678 computation done in 4.211 seconds | |
| 679 computation done in 4.215 seconds | |
| 680 computation done in 4.225 seconds | |
| 681 | |
| 682 As can be seen, the calls to the Python computation now fully run in | |
| 683 parallel (the time is cut down from 12 seconds to 4 seconds, the same | |
| 684 as for one isolated request). | |
| 685 | |
| 686 Note also how the ``multiprocessing`` library allows to make a fine | |
| 687 control over the computational resources that are available to the | |
| 688 Python script: The number of "slave" interpreters can be easily | |
| 689 changed in the constructor of the ``multiprocessing.Pool`` object, and | |
| 690 are fully independent of the threads used by the Orthanc server. | |
| 691 | |
| 352 | 692 .. highlight:: python |
| 693 | |
| 694 Very importantly, pay attention to the fact that only the "master" | |
| 695 Python interpreter has access to the Orthanc SDK. For instance, here | |
| 696 is how you would parse a DICOM file in a slave process:: | |
| 697 | |
| 698 import pydicom | |
| 699 import io | |
| 700 | |
| 701 def OffloadedDicomParsing(dicom): | |
| 702 # No access to the "orthanc" library here, as we are in the slave process | |
| 703 dataset = pydicom.dcmread(io.BytesIO(dicom)) | |
| 704 return str(dataset) | |
| 705 | |
| 706 def OnRest(output, uri, **request): | |
| 707 # The call to "orthanc.RestApiGet()" is only possible in the master process | |
| 708 dicom = orthanc.RestApiGet('/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/file') | |
| 709 answer = POOL.apply(OffloadedDicomParsing, args = (dicom, )) | |
| 710 output.AnswerBuffer(answer, 'text/plain') | |
| 711 | |
| 712 Communication primitives such as ``multiprocessing.Queue`` are | |
| 713 available to exchange messages from the "slave" Python interpreters to | |
| 714 the "master" Python interpreter if further calls to the Orthanc SDK | |
| 715 are required. | |
| 716 | |
| 351 | 717 Obviously, an in-depth discussion about the ``multiprocessing`` |
| 718 library is out of the scope of this document. There are many | |
| 375 | 719 references available on Internet. Also, note that ``threading`` is not |
| 720 useful here, as Python multithreading is also limited by the GIL, and | |
| 721 is more targeted at dealing with costly I/O operations or with the | |
| 722 :ref:`scheduling of commands <python-scheduler>`. |