Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/transfers.rst @ 164:05aa4f426621

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
transfers
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 18 Sep 2018 17:32:04 +0200
parents
children 26441131d725
comparison
equal deleted inserted replaced
163:11d1a08e0906 164:05aa4f426621
1 .. _transfers:
2
3
4 Transfers accelerator plugin
5 ============================
6
7 .. contents::
8
9 Osimis provides a `transfers accelerator plugin
10 <https://bitbucket.org/sjodogne/orthanc-transfers/src>`__ whose
11 purpose is to speed up the transfers of DICOM instances over networks
12 (with respect to the native DICOM protocol or to the built-in
13 :ref:`Orthanc peers <peers>` mechanism).
14
15
16 Description
17 -----------
18
19 This plugin can be used to **send** local images to remote Orthanc
20 peers, or to locally **retrieve** images stored on remote Orthanc
21 peers.
22
23 The plugin also implements **storage commitment**, i.e. the peer that
24 initiates the transfer is informed whether *all* the DICOM instances
25 have been properly received by the other peer. The DICOM instances are
26 individually validated using their MD5 checksum. In other words, this
27 plugin provides atomicity in the transfers (i.e. a study/series is
28 considered as a whole, and partial transfers are prevented).
29
30 Note that the protocol is **entirely built over HTTP/HTTPS** (and not
31 directly over TCP), making it friendly with network firewalls and Web
32 caches. Also, the plugin takes advantage of the **jobs engine** of
33 Orthanc, so that transfers can be easily paused/canceled/resubmitted.
34
35 Technically, this plugin extends the REST API of Orthanc with
36 endpoints that optimize the use of the network bandwidth over the HTTP
37 and HTTPS protocols, through the combination of the following
38 mechanisms:
39
40 * Small DICOM instances are grouped together to form so-called
41 "buckets" of some megabytes in order to reduce the number of HTTP
42 handshakes.
43
44 * Large DICOM instances are split as a set of smaller buckets in
45 order to bypass nasty effects of TCP congestion control on
46 low-quality network links.
47
48 * Buckets are downloaded/uploaded concurrently by several threads.
49
50 * Buckets can be individually compressed using the gzip algorithm,
51 hereby reducing the network usage. On a typical medical image, this
52 can divide the volume of the transmission by a factor 2 to 3, at
53 the price of a larger CPU usage.
54
55 * Sending images to remote Orthanc peers can either be done with HTTP
56 ``PUT`` requests (so-called "push mode"), or with HTTP ``GET``
57 requests if the local Orthanc server has a public IP address
58 (so-called "pull mode").
59
60
61
62 Compilation
63 -----------
64
65 Static linking
66 ^^^^^^^^^^^^^^
67
68 .. highlight:: text
69
70 The procedure to compile the plugin is similar to that for the
71 :ref:`core of Orthanc <compiling>`. The following commands should work
72 for most UNIX-like distribution (including GNU/Linux)::
73
74 $ mkdir BuildTransfers
75 $ cd BuildTransfers
76 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
77 $ make
78
79 The compilation will produce the shared library ``OrthancTransfers``
80 that can be loaded as a plugin by Orthanc.
81
82
83 Microsoft Windows
84 ^^^^^^^^^^^^^^^^^
85
86 Pre-compiled binaries for Microsoft Windows `are available
87 <http://www.orthanc-server.com/browse.php?path=/plugin-transfers>`__.
88
89
90 Dynamic linking on Ubuntu 16.04
91 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
92
93 .. highlight:: text
94
95 If static linking is not desired, here are build instructions for
96 Ubuntu 16.04 (provided build dependencies for the :ref:`core of
97 Orthanc <compiling>` have already been installed)::
98
99 $ mkdir BuildTransfers
100 $ cd BuildTransfers
101 $ cmake .. -DCMAKE_BUILD_TYPE=Release \
102 -DALLOW_DOWNLOADS=ON \
103 -DUSE_SYSTEM_GOOGLE_TEST=OFF \
104 -DUSE_SYSTEM_ORTHANC_SDK=OFF
105 $ make
106
107
108 Basic usage: Sending images
109 ---------------------------
110
111 .. highlight:: json
112
113 You of course first have to :ref:`install Orthanc <binaries>`, with a
114 version above 1.4.2. Secondly, you have to load the plugin and to
115 **declare the remote Orthanc peers** in the :ref:`configuration file
116 <configuration>`. Here is a minimal example (obviously, adapt the
117 parameters)::
118
119 {
120 "Name" : "MyOrthanc",
121 "Plugins" : [
122 "/home/user/orthanc-transfers/BuildTransfers/libOrthancTransfers.so"
123 ],
124 "OrthancPeers" : {
125 "remote" : [ "http://1.2.3.4:8042/" ]
126 }
127 }
128
129 Once Orthanc is running, when you open a patient, a study, or a series
130 in :ref:`Orthanc Explorer <orthanc-explorer>`, you will see a new
131 yellow button entitled ``Transfers accelerator``. By clicking on this
132 button, you will be able to send the local patient/study/series to one
133 of the remote Orthanc peers (provided they are also equipped with the
134 transfers accelerator plugin).
135
136
137 REST API
138 --------
139
140 .. highlight:: bash
141
142 Here is a sample command line to **receive** a patient from the remote
143 peer called ``remote``::
144
145 $ curl -v http://localhost:8042/transfers/pull -X POST -d '{"Resources":[{"Level":"Patient","ID":"16738bc3-e47ed42a-43ce044c-a3414a45-cb069bd0"}],"Compression":"gzip","Peer":"remote"}'
146
147 Note that several resources from different levels (patient, study,
148 series or instances) can be retrieved at once.
149
150 Conversely, here is a sample command line to **send** the same patient
151 to the remote peer ``remote``::
152
153 $ curl -v http://localhost:8042/transfers/send -X POST -d '{"Resources":[{"Level":"Patient","ID":"16738bc3-e47ed42a-43ce044c-a3414a45-cb069bd0"}],"Compression":"gzip","Peer":"remote"}'
154
155 The command above is the one that is issued by Orthanc Explorer under
156 the hood (see section above).
157
158
159
160 Sending in pull vs. push mode
161 -----------------------------
162
163 In the case DICOM instances are being **sent** to a remote peer, the
164 plugin can work in two different modes:
165
166 * In **"pull" mode**, the plugin will transfer images by using as many
167 HTTP ``GET`` requests as possible.
168
169 * In **"push" mode**, it will use a sequence of HTTP ``PUT`` requests.
170
171 Push mode is easier to setup, but pull mode should be favored, as it
172 might lead to improved performance in the presence of Web caches. For
173 pull mode to work, the remote peer must be able to make calls to the
174 REST API of the local peer. This often means that the local peer has a
175 public IP address.
176
177 In order to enable pull mode to send image from Orthanc peer "A" to
178 another Orthanc peer "B", 2 actions must be taken:
179
180 1. "B" must have "A" defined as one of its peers, by adding "A" to its
181 ``OrthancPeers`` configuration section.
182
183 2. "A" must also have "B" defined as one of its peers, and the
184 ``RemoteSelf`` property must be provided for peer "B". This option
185 specifies the symbolic name under which "B" is known to "A".
186
187 .. highlight:: json
188
189 Here is a sample configuration for "A"::
190
191 {
192 "Name" : "A",
193 "Plugins" : [
194 "/home/user/orthanc-transfers/BuildTransfers/libOrthancTransfers.so"
195 ],
196 "OrthancPeers" : {
197 "B" : {
198 "Url" : "http://b.myinstitution.com:8042/",
199 "RemoteSelf" : "A"
200 }
201 }
202 }
203
204 And here is a sample configuration for "B"::
205
206 {
207 "Name" : "B",
208 "Plugins" : [
209 "/home/user/orthanc-transfers/BuildTransfers/libOrthancTransfers.so"
210 ],
211 "OrthancPeers" : {
212 "A" : {
213 "Url" : "http://a.myinstitution.com:8042/"
214 }
215 }
216 }
217
218
219
220 NB: **Receiving** images is always done in pull mode.
221
222
223
224 Advanced options
225 ----------------
226
227 Besides the ``OrthancPeers`` configuration option, several advanced
228 options are available to fine-tune the configuration of the
229 plugin. They are listed below::
230
231 {
232 ...
233 "HttpTimeout" : 120, // Can be increased on slow networks
234 "Transfers" : {
235 "Threads" : 6, // Number of worker threads for one transfer
236 "BucketSize" : 4096, // Optimal size for a bucket (in KB)
237 "CacheSize" : 128, // Size of the memory cache to process DICOM files (in MB)
238 "MaxPushTransactions" : 4 // Maximum number of simultaneous receptions in push mode
239 }
240 }