164
|
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 }
|