Mercurial > hg > orthanc-book
annotate Sphinx/source/users/lua.rst @ 91:025744919357
additional info
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Fri, 03 Feb 2017 10:43:16 +0100 |
parents | e6a15f619786 |
children | e83da2f99e45 |
rev | line source |
---|---|
0 | 1 .. _lua: |
2 | |
3 Server-side scripting with Lua | |
4 ============================== | |
5 | |
6 .. contents:: | |
7 | |
8 Since release 0.5.2, Orthanc supports server-side scripting through | |
25 | 9 the `Lua <https://en.wikipedia.org/wiki/Lua_(programming_language)>`__ |
0 | 10 scripting language. Thanks to this major feature, Orthanc can be tuned |
11 to specific medical workflows without being driven by an external | |
12 script. This page summarizes the possibilities of Orthanc server-side | |
13 scripting. | |
14 | |
15 Many other examples are `available in the source distribution | |
16 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Lua/>`__. | |
17 | |
18 | |
75 | 19 Installing a Lua script |
0 | 20 ----------------------- |
21 | |
22 .. highlight:: bash | |
23 | |
24 A custom Lua script can be installed either by the :ref:`configuration | |
25 file <configuration>`, or by uploading it | |
26 through the :ref:`REST API <rest-samples>`. | |
27 | |
28 To install it by the **configuration file** method, you just have to | |
29 specify the path to the file containing the Lua script in the | |
30 ``LuaScripts`` variable. | |
31 | |
32 To upload a script stored in the file "``script.lua``" through the | |
33 **REST API**, use the following command:: | |
34 | |
35 $ curl -X POST http://localhost:8042/tools/execute-script --data-binary @script.lua | |
36 | |
37 Pay attention to the fact that, contrarily to the scripts installed | |
38 from the configuration file, the scripts installed through the REST | |
39 API are non-persistent: They are discarded after a restart of Orthanc, | |
40 which makes them useful for script prototyping. You can also interpret | |
41 a single Lua command through the REST API:: | |
42 | |
43 $ curl -X POST http://localhost:8042/tools/execute-script --data-binary "print(42)" | |
44 | |
45 *Note:* The ``--data-binary`` cURL option is used instead of | |
46 ``--data`` to prevent the interpretation of newlines by cURL, which is | |
47 `mandatory for the proper evaluation | |
25 | 48 <http://stackoverflow.com/questions/3872427/how-to-send-line-break-with-curl>`__ of the possible |
0 | 49 comments inside the Lua script. |
50 | |
51 | |
52 Lua API | |
53 ------- | |
54 | |
55 | |
56 .. _lua-callbacks: | |
57 | |
58 Callbacks to react to events | |
59 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
60 | |
61 The Lua engine of Orthanc comes invokes the following callbacks that | |
62 are triggered on various events. Here are the **generic events**: | |
63 | |
64 * ``function Initialize()``: Invoked as soon as the Orthanc server is started. | |
65 * ``function Finalize()``: Invoked just before the Orthanc server is stopped. | |
66 | |
67 Some **permission-related events** allow to filter incoming requests: | |
68 | |
69 * ``function ReceivedInstanceFilter(dicom, origin)``: | |
70 Invoked to known whether an incoming DICOM instance should be | |
71 accepted. :ref:`See this section <lua-filter-dicom>`. The ``origin`` | |
72 parameter is :ref:`documented separately <lua-origin>`. | |
73 * ``function IncomingHttpRequestFilter(method, uri, ip, username, | |
74 httpHeaders)``: Invoked to known whether a REST request should be | |
75 accepted. :ref:`See this section <lua-filter-rest>`. | |
76 | |
77 Some **DICOM-related events** allow to react to the reception of | |
78 new medical images: | |
79 | |
80 * ``function OnStoredInstance(instanceId, tags, metadata, origin)``: | |
81 Invoked whenever a new instance has been stored into Orthanc. | |
82 This is especially useful for :ref:`lua-auto-routing`. The ``origin`` | |
83 parameter is :ref:`documented separately <lua-origin>`. | |
84 * ``function OnStablePatient(patientId, tags, metadata)``: Invoked | |
85 whenever a patient has not received any new instance for a certain | |
86 amount of time (cf. the option ``StableAge`` in the | |
87 :ref:`configuration file <configuration>`). The :ref:`identifier | |
88 <orthanc-ids>` of the patient is provided, together with her DICOM | |
78 | 89 tags and her :ref:`metadata <metadata>`. |
0 | 90 * ``function OnStableSeries(seriesId, tags, metadata)``: Invoked |
91 whenever a series has not received any new instance for a certain | |
92 amount of time. | |
93 * ``function OnStableStudy(studyId, tags, metadata)``: Invoked | |
94 whenever a study has not received any new instance for a certain | |
95 amount of time. | |
96 * ``function IncomingFindRequestFilter(source, origin)``: Invoked | |
97 whenever Orthanc receives an incoming C-Find query through the DICOM | |
98 protocol. This allows to inspect the content of the C-Find query, | |
99 and possibly modify it if a patch is needed for some manufacturer. A | |
100 `sample script is available | |
101 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Lua/IncomingFindRequestFilter.lua>`__. | |
102 | |
64
a3df3c2b68cf
import the documentation of the Worklists sample plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
103 Furthermore, whenever a DICOM association is negotiated for C-Store |
0 | 104 SCP, several callbacks are successively invoked to specify which |
105 **transfer syntaxes** are accepted for the association. These | |
106 callbacks are listed in `this sample script | |
107 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Lua/TransferSyntaxEnable.lua>`__. | |
108 | |
109 *Note:* All of these callbacks are guaranteed to be **invoked in | |
110 mutual exclusion**. This implies that Lua scripting in Orthanc does | |
111 not support any kind of concurrency. | |
112 | |
113 | |
114 .. _lua-rest: | |
115 | |
116 Calling the REST API of Orthanc | |
117 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
118 | |
119 Lua scripts have :ref:`full access to the REST API <rest>` of Orthanc | |
120 through the following functions: | |
121 | |
122 * ``RestApiGet(uri, builtin)`` | |
123 * ``RestApiPost(uri, body, builtin)`` | |
124 * ``RestApiPut(uri, body, builtin)`` | |
125 * ``RestApiDelete(uri, builtin)`` | |
126 | |
127 The ``uri`` arguments specifies the URI against which to make the | |
128 request, and ``body`` is a string containing the body of POST/PUT | |
129 request. The ``builtin`` parameter is an optional Boolean that | |
130 specifies whether the request targets only the built-in REST API of | |
131 Orthanc (if set to ``true``), or the full the REST API after being | |
132 tainted by the plugins (if set to ``false``). | |
133 | |
134 | |
135 General-purpose functions | |
136 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
137 | |
138 The Lua engine of Orthanc contain several general-purpose ancillary | |
139 functions: | |
140 | |
141 * ``PrintRecursive(v)`` recursively prints the content of a `Lua table | |
142 <http://www.lua.org/pil/2.5.html>`__ to the log file of Orthanc. | |
143 * ``ParseJson(s)`` converts a string encoded in the `JSON format | |
144 <https://en.wikipedia.org/wiki/JSON>`__ to a Lua table. | |
145 * ``DumpJson(v, keepStrings)`` encodes a Lua table as a JSON string. | |
146 Setting the optional argument ``keepStrings`` (available from | |
147 release 0.9.5) to ``true`` prevents the automatic conversion of | |
148 strings to integers. | |
149 * ``GetOrthancConfiguration()`` returns a Lua table containing the | |
150 content of the :ref:`configuration files <configuration>` of | |
151 Orthanc. | |
152 | |
153 | |
154 Similarly to the functions to :ref:`call the REST API of Orthanc | |
155 <lua-rest>`, several functions are available to make generic HTTP | |
156 requests to Web services: | |
157 | |
90 | 158 * ``HttpGet(url, headers)`` |
159 * ``HttpPost(url, body, headers)`` | |
160 * ``HttpPut(url, body, headers)`` | |
161 * ``HttpDelete(url, headers)`` | |
0 | 162 * ``SetHttpCredentials(username, password)`` can be used to setup the |
163 HTTP credentials. | |
164 | |
91 | 165 The ``headers`` argument is optional and has been added in release |
166 1.2.1. It allows to set the HTTP headers for the HTTP client request. | |
0 | 167 |
168 .. _lua-origin: | |
169 | |
170 Origin of the instances | |
171 ^^^^^^^^^^^^^^^^^^^^^^^ | |
172 | |
173 Whenever Orthanc decides whether it should should store a new instance | |
174 (cf. the ``ReceivedInstanceFilter()`` callback), or whenever it has | |
175 actually stored a new instance (cf. the ``OnStoredInstance`` | |
176 callback), an ``origin`` parameter is provided. This parameter is a | |
177 `Lua table <http://www.lua.org/pil/2.5.html>`__ that describes from | |
178 which Orthanc subsystem the new instance comes from. | |
179 | |
180 There are 4 possible subsystems, that can be distinguished according | |
181 to the value of ``origin["RequestOrigin"]``: | |
182 | |
183 * ``RestApi``: The instance originates from some HTTP request to the REST | |
184 API. In this case, the ``RemoteIp`` and ``Username`` fields are | |
185 available in ``origin``. They respectively describe the IP address | |
186 of the HTTP client, and the username that was used for HTTP | |
187 authentication (as defined in the ``RegisteredUsers`` | |
188 :ref:`configuration variable <configuration>`). | |
189 * ``DicomProtocol``: The instance originates from a DICOM C-Store. | |
190 The fields ``RemoteIp``, ``RemoteAet`` and ``CalledAet`` | |
191 respectively provide the IP address of the DICOM SCU (client), the | |
192 application entity title of the DICOM SCU client, and the | |
193 application entity title of the Orthanc SCP server. The | |
194 ``CalledAet`` can be used for :ref:`advanced auto-routing scenarios | |
195 <lua-auto-routing>`, when a single instance of Orthanc acts as a | |
196 proxy for several DICOM SCU clients. | |
197 * ``Lua``: The instance originates from a Lua script. | |
198 * ``Plugins``: The instance originates from a plugin. | |
199 | |
200 | |
201 .. _lua-filter-dicom: | |
202 | |
75 | 203 Filtering incoming DICOM instances |
0 | 204 ---------------------------------- |
205 | |
206 .. highlight:: lua | |
207 | |
208 Each time a DICOM instance is received by Orthanc (either through the | |
209 DICOM protocol or through the REST API), the | |
210 ``ReceivedInstanceFilter()`` Lua function is invoked. If this callback | |
211 returns ``true``, the instance is accepted for storage. If it returns | |
212 ``false``, the instance is discarded. This mechanism can be used to | |
213 filter the incoming DICOM instances. Here is an example of a Lua | |
214 filter that only allows incoming instances of MR modality:: | |
215 | |
216 function ReceivedInstanceFilter(dicom, origin) | |
217 -- Only allow incoming MR images | |
218 if dicom.Modality == 'MR' then | |
219 return true | |
220 else | |
221 return false | |
222 end | |
223 end | |
224 | |
225 The argument dicom corresponds to a `Lua table | |
226 <http://www.lua.org/pil/2.5.html>`__ (i.e. an associative array) that | |
227 contains the DICOM tags of the incoming instance. For debugging | |
228 purpose, you can print this structure as follows:: | |
229 | |
230 function ReceivedInstanceFilter(dicom, origin) | |
231 PrintRecursive(dicom) | |
232 -- Accept all incoming instances (default behavior) | |
233 return true | |
234 end | |
235 | |
236 The argument ``origin`` is :ref:`documented separately <lua-origin>`. | |
237 | |
238 | |
239 .. _lua-filter-rest: | |
240 | |
75 | 241 Filtering incoming REST requests |
0 | 242 -------------------------------- |
243 | |
244 .. highlight:: lua | |
245 | |
246 Lua scripting can be used to control the access to the various URI of | |
247 the REST API. Each time an incoming HTTP request is received, the | |
248 ``IncomingHttpRequestFilter()`` Lua function is called. The access to | |
249 the resource is granted if and only if this callback script returns | |
250 ``true``. | |
251 | |
252 This mechanism can be used to implement fine-grained `access control | |
25 | 253 lists <https://en.wikipedia.org/wiki/Access_control_list>`__. Here is |
0 | 254 an example of a Lua script that limits POST, PUT and DELETE requests |
255 to an user that is called "admin":: | |
256 | |
257 function IncomingHttpRequestFilter(method, uri, ip, username, httpHeaders) | |
258 -- Only allow GET requests for non-admin users | |
259 | |
260 if method == 'GET' then | |
261 return true | |
262 elseif username == 'admin' then | |
263 return true | |
264 else | |
265 return false | |
266 end | |
267 end | |
268 | |
269 Here is a description of the arguments of this Lua callback: | |
270 | |
271 * ``method``: The HTTP method (GET, POST, PUT or DELETE). | |
272 * ``uri``: The path to the resource (e.g. ``/tools/generate-uid``). | |
273 * ``ip``: The IP address of the host that has issued the HTTP request (e.g. ``127.0.0.1``). | |
274 * ``username``: If HTTP Basic Authentication is enabled in the | |
275 :ref:`configuration file <configuration>`, the name of the user that | |
276 has issued the HTTP request (as defined in the ``RegisteredUsers`` | |
277 configuration variable). If the authentication is disabled, this | |
278 argument is set to the empty string. | |
279 * ``httpHeaders``: The HTTP headers of the incoming request. This | |
280 argument is available since Orthanc 1.0.1. It is useful if the | |
281 authentication should be achieved through tokens, for instance | |
282 against a `LDAP | |
283 <https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol>`__ | |
284 or `OAuth2 <https://en.wikipedia.org/wiki/OAuth>`__ server. | |
285 | |
286 | |
287 .. _lua-auto-routing: | |
288 | |
75 | 289 Auto-routing of DICOM images |
0 | 290 ---------------------------- |
291 | |
292 .. highlight:: lua | |
293 | |
294 Since release 0.8.0, the routing of DICOM flows can be very easily | |
295 automated with Orthanc. All you have to do is to declare your | |
296 destination modality in the :ref:`configuration file <configuration>` | |
297 (section ``DicomModalities``), then to create and install a Lua | |
298 script. For instance, here is a sample script:: | |
299 | |
300 function OnStoredInstance(instanceId, tags, metadata) | |
301 Delete(SendToModality(instanceId, 'sample')) | |
302 end | |
303 | |
304 If this script is loaded into Orthanc, whenever a new DICOM instance | |
305 is received by Orthanc, it will be routed to the modality whose | |
306 symbolic name is ``sample`` (through a Store-SCU command), then it | |
307 will be removed from Orthanc. In other words, this is a **one-liner | |
308 script to implement DICOM auto-routing**. | |
309 | |
310 Very importantly, thanks to this feature, you do not have to use the | |
311 REST API or to create external scripts in order to automate simple | |
312 imaging flows. The scripting engine is entirely contained inside the | |
313 Orthanc core system. | |
314 | |
315 Thanks to Lua expressiveness, you can also implement conditional | |
316 auto-routing. For instance, if you wish to route only patients whose | |
317 name contains "David", you would simply write:: | |
318 | |
319 function OnStoredInstance(instanceId, tags, metadata) | |
320 -- Extract the value of the "PatientName" DICOM tag | |
321 local patientName = string.lower(tags['PatientName']) | |
322 | |
323 if string.find(patientName, 'david') ~= nil then | |
324 -- Only route patients whose name contains "David" | |
325 Delete(SendToModality(instanceId, 'sample')) | |
326 | |
327 else | |
328 -- Delete the patients that are not called "David" | |
329 Delete(instanceId) | |
330 end | |
331 end | |
332 | |
333 Besides ``SendToModality()``, a mostly identical function with the | |
334 same arguments called ``SendToPeer()`` can be used to route instances | |
335 to :ref:`Orthanc peers <peers>`. It is also possible to modify the | |
336 received instances before routing them. For instance, here is how you | |
337 would replace the ``StationName`` DICOM tag:: | |
338 | |
339 function OnStoredInstance(instanceId, tags, metadata) | |
340 -- Ignore the instances that result from a modification to avoid | |
341 -- infinite loops | |
342 if (metadata['ModifiedFrom'] == nil and | |
343 metadata['AnonymizedFrom'] == nil) then | |
344 | |
345 -- The tags to be replaced | |
346 local replace = {} | |
347 replace['StationName'] = 'My Medical Device' | |
348 | |
349 -- The tags to be removed | |
350 local remove = { 'MilitaryRank' } | |
351 | |
352 -- Modify the instance, send it, then delete the modified instance | |
353 Delete(SendToModality(ModifyInstance(instanceId, replace, remove, true), 'sample')) | |
354 | |
355 -- Delete the original instance | |
356 Delete(instanceId) | |
357 end | |
358 end | |
359 | |
360 | |
75 | 361 Important remarks about auto-routing |
362 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
19
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
363 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
364 The ``SendToModality()``, ``SendToPeer()``, ``ModifyInstance()`` and |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
365 ``Delete()`` functions are for the most basic cases of auto-routing |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
366 (implying a single DICOM instance, and possibly a basic modification |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
367 of this instance). The ``ModifyInstance()`` function `could also lead |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
368 to problems |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
369 <https://groups.google.com/d/msg/orthanc-users/hmv2y-LgKm8/oMAuGJWMBgAJ>`__ |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
370 if it deals with tags wrongly interpreted as numbers by Lua. |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
371 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
372 For more evolved auto-routing scenarios, remember that Lua scripts |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
373 :ref:`have full to the REST API of Orthanc <lua-rest>`. This is |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
374 illustrated by the ``AutoroutingModification.lua`` sample available in |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
375 the source distribution of Orthanc:: |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
376 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
377 function OnStoredInstance(instanceId, tags, metadata, origin) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
378 -- Ignore the instances that result from the present Lua script to |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
379 -- avoid infinite loops |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
380 if origin['RequestOrigin'] ~= 'Lua' then |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
381 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
382 -- The tags to be replaced |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
383 local replace = {} |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
384 replace['StationName'] = 'My Medical Device' |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
385 replace['0031-1020'] = 'Some private tag' |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
386 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
387 -- The tags to be removed |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
388 local remove = { 'MilitaryRank' } |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
389 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
390 -- Modify the instance |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
391 local command = {} |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
392 command['Replace'] = replace |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
393 command['Remove'] = remove |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
394 local modifiedFile = RestApiPost('/instances/' .. instanceId .. '/modify', DumpJson(command, true)) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
395 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
396 -- Upload the modified instance to the Orthanc database so that |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
397 -- it can be sent by Orthanc to other modalities |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
398 local modifiedId = ParseJson(RestApiPost('/instances/', modifiedFile)) ['ID'] |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
399 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
400 -- Send the modified instance to another modality |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
401 RestApiPost('/modalities/sample/store', modifiedId) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
402 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
403 -- Delete the original and the modified instances |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
404 RestApiDelete('/instances/' .. instanceId) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
405 RestApiDelete('/instances/' .. modifiedId) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
406 end |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
407 end |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
408 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
409 Also note that :ref:`other callbacks are available <lua-callbacks>` |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
410 (``OnStablePatient()``, ``OnStableStudy()`` and ``OnStableSeries()``) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
411 to react to other events than the reception of a single instance |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
412 with ``OnStoredInstance()``. |
75 | 413 |
414 | |
77
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
415 Fixing C-Find requests |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
416 ---------------------- |
75 | 417 |
418 :ref:`C-Find requests <dicom-find>` are sometimes interpreted | |
77
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
419 differently by different DICOM servers (e.g. the ``*`` wildcard, as |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
420 `reported by users |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
421 <https://groups.google.com/d/msg/orthanc-users/3g7V7kqr3g0/IREL88RWAwAJ>`__), |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
422 and sometimes a querying modality might set unexpected DICOM tags |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
423 (cf. `this real-world example |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
424 <https://groups.google.com/d/msg/orthanc-users/PLWKqVVaXLs/n_0x4vKhAgAJ>`__). In |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
425 such situations, it is possible to dynamically fix incoming or |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
426 outgoing C-Find queries using a Lua script. |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
427 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
428 Fixing incoming C-Find requests can be done by implementing the |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
429 ``IncomingFindRequestFilter(query, origin)`` callback that is called |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
430 whenever the Orthanc C-Find SCP is queried by a remote modality. For |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
431 instance, here is Lua script to remove a private tag that is specified |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
432 by some manufacturer:: |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
433 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
434 function IncomingFindRequestFilter(query, origin) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
435 -- First display the content of the C-Find query |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
436 PrintRecursive(query) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
437 PrintRecursive(origin) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
438 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
439 -- Remove the "PrivateCreator" tag from the query |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
440 local v = query |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
441 v['5555,0010'] = nil |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
442 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
443 return v |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
444 end |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
445 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
446 The ``origin`` argument contains information about which modality has |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
447 issued the request. |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
448 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
449 Similarly, the callback ``OutgoingFindRequestFilter(query, modality)`` |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
450 is invoked whenever Orthanc acts as a C-Find SCU, which gives the |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
451 opportunity to dynamically fix outgoing C-Find requests before they |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
452 are actually sent to the queried modality. For instance, here is a |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
453 sample Lua callback that would replace asterisk wildcards (i.e. ``*``) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
454 by an empty string for any query/retrieve issued by Orthanc (including |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
455 from Orthanc Explorer):: |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
456 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
457 function OutgoingFindRequestFilter(query, modality) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
458 for key, value in pairs(query) do |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
459 if value == '*' then |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
460 query[key] = '' |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
461 end |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
462 end |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
463 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
464 return query |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
465 end |