orthanc-book: Sphinx/source/plugins/python.rst annotate

annotate Sphinx/source/plugins/python.rst @ 374:f5bbdabb04d9

merge

author	Sebastien Jodogne <s.jodogne@gmail.com>
date	Sun, 05 Apr 2020 10:25:51 +0200
parents	847996394688 cb1d9a5bb043
children	766fe39fdf35

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 f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	21 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.5.7/Plugins/Include/orthanc/OrthancCPlugin.h>`__
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
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 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 1ba75bac55fd cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 353 diff changeset	51 community under the terms of the AGPL license.
1ba75bac55fd cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 353 diff changeset	52
1ba75bac55fd cont 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
1ba75bac55fd cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 353 diff changeset	54 dedicated `"OrthancContributed" repository on GitHub
1ba75bac55fd cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 353 diff changeset	55 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__,
1ba75bac55fd cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 353 diff changeset	56 and/or to send it to the `Orthanc Users
1ba75bac55fd cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 353 diff changeset	57 <https://groups.google.com/forum/#!forum/orthanc-users>`__ discussion
1ba75bac55fd cont 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
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	111 Compiling from source
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	112 .....................
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	113
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	114 .. highlight:: bash
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 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	117 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	118 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	119
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	120 $ mkdir Build
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	121 $ cd Build
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	122 $ 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	123 $ make
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	124
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	125 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	126 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	127 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	128 ``python3.7``.
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	129
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	130 The compilation will produce the shared library ``OrthancPython``,
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	131 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	132 :ref:`configuration option <configuration>` of Orthanc.
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	133
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	134 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	135 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	136 ``PYTHON_VERSION`` argument that was given to CMake.
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	137
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	138
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	139 Microsoft Windows
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 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	143 <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	144
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	145 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	146 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	147 indicated in the name of the folder.
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	148
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	149 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	150 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	151 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	152 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	153 than 10 years.
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	154
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	155 .. highlight:: text
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 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	158 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	159 your Python installation while invoking CMake. For instance::
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 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	162 -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	163
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	164
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	165 Configuration options
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
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	168 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	169 are the following:
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	170
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	171 * ``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	172 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	173 started.
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	174
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	175 * ``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	176 verbose.
234de55ed125 usage of the python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: 354 diff changeset	177
343 fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	178
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	179 Samples
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	180 -------
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	181
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	182 Extending the REST API
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	183 ......................
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	184
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	185 .. highlight:: python
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	186
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	187 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	188 REST API::
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	189
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	190 import orthanc
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	191 import pprint
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	192
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	193 def OnRest(output, uri, **request):
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	194 pprint.pprint(request)
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	195 print('Accessing uri: %s' % uri)
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	196 output.AnswerBuffer('ok\n', 'text/plain')
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	197
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	198 orthanc.RegisterRestCallback('/(to)(t)o', OnRest)
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	199 orthanc.RegisterRestCallback('/tata', OnRest)
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	200
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	201 .. highlight:: json
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	202
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	203 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	204 (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	205
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	206 {
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	207 "Plugins" : [ "." ],
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	208 "PythonScript" : "rest.py",
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	209 "PythonVerbose" : false
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:: bash
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 The route can then be accessed as::
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	215
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	216 $ curl http://localhost:8042/toto
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	217 ok
fff45618262d creating the documentation of the Python plugin Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	218
345 f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	219
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	220 Listening to changes
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	221 ....................
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	222
346 bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	223 .. highlight:: python
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	224
345 f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	225 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	226
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	227 import orthanc
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	228
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	229 def OnChange(changeType, level, resource):
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	230 if changeType == orthanc.ChangeType.ORTHANC_STARTED:
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	231 print('Started')
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	232
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	233 with open('/tmp/sample.dcm', 'rb') as f:
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	234 orthanc.RestApiPost('/instances', f.read())
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	235
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	236 elif changeType == orthanc.ChangeType.ORTHANC_STOPPED:
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	237 print('Stopped')
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	238
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	239 elif changeType == orthanc.ChangeType.NEW_INSTANCE:
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	240 print('A new instance was uploaded: %s' % resource)
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	241
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	242 orthanc.RegisterOnChangeCallback(OnChange)
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	243
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	244
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	245 Accessing the content of a new instance
346 bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	246 .......................................
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	247
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	248 .. highlight:: python
345 f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	249
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	250 ::
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	251
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	252 import orthanc
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	253 import json
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	254 import pprint
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	255
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	256 def OnStoredInstance(dicom, instanceId):
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	257 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	258 instanceId, dicom.GetInstanceSize(),
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	259 dicom.GetInstanceMetadata('TransferSyntax'),
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	260 dicom.GetInstanceMetadata('SopClassUid')))
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 # Print the origin information
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	263 if dicom.GetInstanceOrigin() == orthanc.InstanceOrigin.DICOM_PROTOCOL:
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	264 print('This instance was received through the DICOM protocol')
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	265 elif dicom.GetInstanceOrigin() == orthanc.InstanceOrigin.REST_API:
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	266 print('This instance was received through the REST API')
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 # Print the DICOM tags
f81b533a0fd0 python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 343 diff changeset	269 pprint.pprint(json.loads(dicom.GetInstanceSimplifiedJson()))
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 orthanc.RegisterOnStoredInstanceCallback(OnStoredInstance)
346 bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	272
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 Calling pydicom
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	275 ...............
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	276
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	277 .. highlight:: python
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	278
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	279 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	280 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	281 Orthanc, using `pydicom <https://pydicom.github.io/>`__::
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 import io
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	284 import orthanc
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	285 import pydicom
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	286
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	287 def DecodeInstance(output, uri, **request):
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	288 if request['method'] == 'GET':
347 04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	289 # Retrieve the instance ID from the regular expression (*)
346 bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	290 instanceId = request['groups'][0]
347 04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	291 # Get the content of the DICOM file
346 bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	292 f = orthanc.GetDicomForInstance(instanceId)
347 04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	293 # Parse it using pydicom
346 bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	294 dicom = pydicom.dcmread(io.BytesIO(f))
347 04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	295 # Return a string representation the dataset to the caller
346 bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	296 output.AnswerBuffer(str(dicom), 'text/plain')
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	297 else:
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	298 output.SendMethodNotAllowed('GET')
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	299
347 04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	300 orthanc.RegisterRestCallback('/pydicom/(.)', DecodeInstance) # ()
346 bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	301
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	302 .. highlight:: bash
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 This can be called as follows::
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 $ curl http://localhost:8042/pydicom/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5
bdf8757449e3 more python samples Sebastien Jodogne <s.jodogne@gmail.com> parents: 345 diff changeset	307
347 04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	308
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	309 Auto-routing studies
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	310 ....................
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	311
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	312 .. highlight:: python
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	313
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	314 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	315 <lua-callbacks>` to a modality named ``samples`` (as declared in the
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	316 ``DicomModalities`` configuration option)::
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	317
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	318 import orthanc
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	319
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	320 def OnChange(changeType, level, resourceId):
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	321 if changeType == orthanc.ChangeType.STABLE_STUDY:
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	322 print('Stable study: %s' % resourceId)
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	323 orthanc.RestApiPost('/modalities/sample/store', resourceId)
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	324
04fae9d4b65f auto-routing Sebastien Jodogne <s.jodogne@gmail.com> parents: 346 diff changeset	325 orthanc.RegisterOnChangeCallback(OnChange)
348 d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	326
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	327
352 6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	328 Rendering a thumbnail using PIL/Pillow
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	329 ......................................
348 d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	330
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	331 .. highlight:: python
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	332
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	333 ::
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	334
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	335 from PIL import Image
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	336 import io
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	337 import orthanc
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	338
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	339 def DecodeInstance(output, uri, **request):
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	340 if request['method'] == 'GET':
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	341 # Retrieve the instance ID from the regular expression (*)
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	342 instanceId = request['groups'][0]
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	343
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	344 # Render the instance, then open it in Python using PIL/Pillow
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	345 png = orthanc.RestApiGet('/instances/%s/rendered' % instanceId)
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	346 image = Image.open(io.BytesIO(png))
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	347
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	348 # Downsize the image as a 64x64 thumbnail
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	349 image.thumbnail((64, 64), Image.ANTIALIAS)
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	350
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	351 # 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	352 jpeg = io.BytesIO()
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	353 image.save(jpeg, format = "JPEG", quality = 80)
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	354 jpeg.seek(0)
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	355 output.AnswerBuffer(jpeg.read(), 'text/plain')
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	356
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	357 else:
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	358 output.SendMethodNotAllowed('GET')
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	359
d8359cecdc89 pillow sample Sebastien Jodogne <s.jodogne@gmail.com> parents: 347 diff changeset	360 orthanc.RegisterRestCallback('/pydicom/(.)', DecodeInstance) # ()
351 e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	361
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	362
369 181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	363 .. _python-introspection:
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	364
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	365 Inspecting the available API
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	366 ............................
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	367
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	368 .. highlight:: python
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	369
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	370 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	371 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	372 features::
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	373
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	374 import inspect
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	375 import numbers
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	376 import orthanc
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	377
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	378 # Loop over the members of the "orthanc" module
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	379 for (name, obj) in inspect.getmembers(orthanc):
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	380 if inspect.isroutine(obj):
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	381 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	382
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	383 elif inspect.isclass(obj):
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	384 print('Class %s:\n Documentation: %s' % (name, inspect.getdoc(obj)))
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	385
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	386 # Loop over the members of the class
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	387 for (subname, subobj) in inspect.getmembers(obj):
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	388 if isinstance(subobj, numbers.Number):
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	389 print(' - Enumeration value %s: %s' % (subname, subobj))
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	390 elif (not subname.startswith('_') and
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	391 inspect.ismethoddescriptor(subobj)):
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	392 print(' - Method %s(): %s' % (subname, inspect.getdoc(subobj)))
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	393 print('')
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	394
373 847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	395
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	396 .. _python-scheduler:
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	397
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	398 Scheduling a task for periodic execution
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	399 ........................................
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	400
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	401 .. highlight:: python
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	402
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	403 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	404 function ``Hello()`` thanks to the ``threading`` module::
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	405
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	406 import orthanc
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	407 import threading
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	408
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	409 TIMER = None
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	410
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	411 def Hello():
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	412 global TIMER
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	413 TIMER = None
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	414 orthanc.LogWarning("In Hello()")
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	415 # Do stuff...
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	416 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	417 TIMER.start()
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	418
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	419 def OnChange(changeType, level, resource):
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	420 if changeType == orthanc.ChangeType.ORTHANC_STARTED:
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	421 orthanc.LogWarning("Starting the scheduler")
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	422 Hello()
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	423
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	424 elif changeType == orthanc.ChangeType.ORTHANC_STOPPED:
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	425 if TIMER != None:
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	426 orthanc.LogWarning("Stopping the scheduler")
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	427 TIMER.cancel()
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	428
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	429 orthanc.RegisterOnChangeCallback(OnChange)
847996394688 Scheduling a task for periodic execution Sebastien Jodogne <s.jodogne@gmail.com> parents: 369 diff changeset	430
369 181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	431
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	432
181b02cea7ab inspecting Python API Sebastien Jodogne <s.jodogne@gmail.com> parents: 364 diff changeset	433
351 e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	434 Performance and concurrency
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	435 ---------------------------
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	436
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	437 .. highlight:: python
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	438
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	439 Let us consider the following sample Python script that makes a
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	440 CPU-intensive computation on a REST callback::
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	441
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	442 import math
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	443 import orthanc
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	444 import time
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	445
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	446 # CPU-intensive computation taking about 4 seconds
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	447 def SlowComputation():
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	448 start = time.time()
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	449 for i in range(1000):
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	450 for j in range(30000):
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	451 math.sqrt(float(j))
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	452 end = time.time()
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	453 duration = (end - start)
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	454 return 'computation done in %.03f seconds\n' % duration
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	455
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	456 def OnRest(output, uri, **request):
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	457 answer = SlowComputation()
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	458 output.AnswerBuffer(answer, 'text/plain')
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	459
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	460 orthanc.RegisterRestCallback('/computation', OnRest)
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	461
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	462
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	463 .. highlight:: text
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	464
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	465 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	466 needed to compute 30 million times a squared root on your CPU::
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	467
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	468 $ curl http://localhost:8042/computation
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	469 computation done in 4.208 seconds
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	470
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	471 Now, let us call this route three times concurrently (we use bash)::
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	472
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	473 $ (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	474 computation done in 11.262 seconds
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	475 computation done in 12.457 seconds
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	476 computation done in 13.360 seconds
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	477
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	478 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	479 computations were not distributed across the available CPU cores.
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	480 This might seem surprising, as Orthanc is a threaded server (in
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	481 Orthanc, a pool of C++ threads serves concurrent requests).
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	482
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	483 The explanation is that the Python interpreter (`CPython
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	484 <https://en.wikipedia.org/wiki/CPython>`__ actually) is built on the
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	485 top of a so-called `Global Interpreter Lock (GIL)
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	486 <https://en.wikipedia.org/wiki/Global_interpreter_lock>`__. The GIL is
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	487 basically a mutex that protects all the calls to the Python
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	488 interpreter. If multiple C++ threads from Orthanc call a Python
353 0122c668f4ec python licensing Sebastien Jodogne <s.jodogne@gmail.com> parents: 352 diff changeset	489 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	490 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	491 Orthanc is not affected by the GIL.
351 e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	492
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	493 .. highlight:: python
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	494
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	495 The solution is to use the `multiprocessing primitives
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	496 <https://docs.python.org/3/library/multiprocessing.html>`__ of Python.
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	497 The "master" Python interpreter that is initially started by the
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	498 Orthanc plugin, can start several `children processes
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	499 <https://en.wikipedia.org/wiki/Process_(computing)>`__, each of these
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	500 processes running a separate Python interpreter. This allows to
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	501 offload intensive computations from the "master" Python interpreter of
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	502 Orthanc onto those "slave" interpreters. The ``multiprocessing``
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	503 library is actually quite straightforward to use::
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	504
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	505 import math
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	506 import multiprocessing
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	507 import orthanc
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	508 import signal
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	509 import time
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	510
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	511 # CPU-intensive computation taking about 4 seconds
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	512 # (same code as above)
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	513 def SlowComputation():
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	514 start = time.time()
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	515 for i in range(1000):
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	516 for j in range(30000):
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	517 math.sqrt(float(j))
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	518 end = time.time()
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	519 duration = (end - start)
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	520 return 'computation done in %.03f seconds\n' % duration
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	521
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	522 # Ignore CTRL+C in the slave processes
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	523 def Initializer():
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	524 signal.signal(signal.SIGINT, signal.SIG_IGN)
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	525
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	526 # Create a pool of 4 slave Python interpreters
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	527 POOL = multiprocessing.Pool(4, initializer = Initializer)
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	528
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	529 def OnRest(output, uri, **request):
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	530 # Offload the call to "SlowComputation" onto one slave process.
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	531 # The GIL is unlocked until the slave sends its answer back.
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	532 answer = POOL.apply(SlowComputation)
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	533 output.AnswerBuffer(answer, 'text/plain')
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	534
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	535 orthanc.RegisterRestCallback('/computation', OnRest)
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	536
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	537 .. highlight:: text
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	538
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	539 Here is now the result of calling this route three times concurrently::
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	540
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	541 $ (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	542 computation done in 4.211 seconds
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	543 computation done in 4.215 seconds
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	544 computation done in 4.225 seconds
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	545
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	546 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	547 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	548 as for one isolated request).
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	549
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	550 Note also how the ``multiprocessing`` library allows to make a fine
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	551 control over the computational resources that are available to the
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	552 Python script: The number of "slave" interpreters can be easily
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	553 changed in the constructor of the ``multiprocessing.Pool`` object, and
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	554 are fully independent of the threads used by the Orthanc server.
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	555
352 6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	556 .. highlight:: python
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	557
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	558 Very importantly, pay attention to the fact that only the "master"
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	559 Python interpreter has access to the Orthanc SDK. For instance, here
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	560 is how you would parse a DICOM file in a slave process::
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	561
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	562 import pydicom
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	563 import io
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	564
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	565 def OffloadedDicomParsing(dicom):
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	566 # No access to the "orthanc" library here, as we are in the slave process
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	567 dataset = pydicom.dcmread(io.BytesIO(dicom))
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	568 return str(dataset)
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	569
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	570 def OnRest(output, uri, **request):
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	571 # The call to "orthanc.RestApiGet()" is only possible in the master process
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	572 dicom = orthanc.RestApiGet('/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/file')
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	573 answer = POOL.apply(OffloadedDicomParsing, args = (dicom, ))
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	574 output.AnswerBuffer(answer, 'text/plain')
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	575
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	576 Communication primitives such as ``multiprocessing.Queue`` are
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	577 available to exchange messages from the "slave" Python interpreters to
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	578 the "master" Python interpreter if further calls to the Orthanc SDK
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	579 are required.
6258b2c14e56 cont Sebastien Jodogne <s.jodogne@gmail.com> parents: 351 diff changeset	580
351 e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	581 Obviously, an in-depth discussion about the ``multiprocessing``
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	582 library is out of the scope of this document. There are many
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	583 references available on Internet. Also, note that ``multithreading``
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	584 is not useful here, as Python multithreading is also limited by the
e2863083fa30 multiprocessing Sebastien Jodogne <s.jodogne@gmail.com> parents: 350 diff changeset	585 GIL, and is more targeted at dealing with costly I/O operations.

Mercurial > hg > orthanc-book

annotate Sphinx/source/plugins/python.rst @ 374:f5bbdabb04d9