Mercurial > hg > orthanc-book
annotate Sphinx/source/users/lua.rst @ 781:ededfacf9a8d
new index plugin in osimis images
| author | Alain Mazy <am@osimis.io> |
|---|---|
| date | Mon, 27 Sep 2021 12:16:29 +0200 |
| parents | 15a0635eef4b |
| children | 0fbe952b2906 |
| 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 | |
| 449 | 16 <https://hg.orthanc-server.com/orthanc/file/default/OrthancServer/Resources/Samples/Lua/>`__. |
| 0 | 17 |
|
606
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
18 A more expressive alternative to Lua scripts is provided by |
|
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
19 :ref:`Python plugins <python-plugins>`. |
|
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
20 |
| 0 | 21 |
| 75 | 22 Installing a Lua script |
| 0 | 23 ----------------------- |
| 24 | |
| 25 .. highlight:: bash | |
| 26 | |
| 27 A custom Lua script can be installed either by the :ref:`configuration | |
| 28 file <configuration>`, or by uploading it | |
| 29 through the :ref:`REST API <rest-samples>`. | |
| 30 | |
| 31 To install it by the **configuration file** method, you just have to | |
| 32 specify the path to the file containing the Lua script in the | |
| 357 | 33 ``LuaScripts`` variable. A comma-separated list of paths can be |
| 34 specified to install multiple scripts. | |
| 0 | 35 |
| 36 To upload a script stored in the file "``script.lua``" through the | |
| 37 **REST API**, use the following command:: | |
| 38 | |
| 39 $ curl -X POST http://localhost:8042/tools/execute-script --data-binary @script.lua | |
| 40 | |
| 41 Pay attention to the fact that, contrarily to the scripts installed | |
| 42 from the configuration file, the scripts installed through the REST | |
| 43 API are non-persistent: They are discarded after a restart of Orthanc, | |
| 44 which makes them useful for script prototyping. You can also interpret | |
| 45 a single Lua command through the REST API:: | |
| 46 | |
| 47 $ curl -X POST http://localhost:8042/tools/execute-script --data-binary "print(42)" | |
| 48 | |
| 49 *Note:* The ``--data-binary`` cURL option is used instead of | |
| 50 ``--data`` to prevent the interpretation of newlines by cURL, which is | |
| 51 `mandatory for the proper evaluation | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
357
diff
changeset
|
52 <https://stackoverflow.com/questions/3872427/how-to-send-line-break-with-curl>`__ |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
357
diff
changeset
|
53 of the possible comments inside the Lua script. |
| 0 | 54 |
| 55 Lua API | |
| 56 ------- | |
| 57 | |
| 58 | |
| 59 .. _lua-callbacks: | |
| 60 | |
| 61 Callbacks to react to events | |
| 62 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 63 | |
|
355
e4e9cca89c64
clarified mutual exclusion of Lua scripts callbacks.
David Wikler <david.wikler@ulb.ac.be>
parents:
319
diff
changeset
|
64 The Lua engine of Orthanc invokes the following callbacks that |
| 0 | 65 are triggered on various events. Here are the **generic events**: |
| 66 | |
| 67 * ``function Initialize()``: Invoked as soon as the Orthanc server is started. | |
| 68 * ``function Finalize()``: Invoked just before the Orthanc server is stopped. | |
| 69 | |
| 70 Some **permission-related events** allow to filter incoming requests: | |
| 71 | |
|
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
72 * ``function ReceivedInstanceFilter(dicom, origin, info)``: Invoked to |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
73 known whether an incoming DICOM instance should be |
| 0 | 74 accepted. :ref:`See this section <lua-filter-dicom>`. The ``origin`` |
|
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
75 parameter is :ref:`documented separately <lua-origin>`. The ``info`` |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
76 parameter contains additional information and was added in Orthanc |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
77 1.6.1. |
| 0 | 78 * ``function IncomingHttpRequestFilter(method, uri, ip, username, |
| 79 httpHeaders)``: Invoked to known whether a REST request should be | |
| 80 accepted. :ref:`See this section <lua-filter-rest>`. | |
| 81 | |
| 232 | 82 Some **job-related events** allow to react to :ref:`job <jobs>` completion/failure: |
| 83 | |
| 84 * ``function OnJobSubmitted(jobId)``: | |
| 85 Invoked when a new job has been submitted. Note that this does not | |
| 86 mean the the job execution has started. | |
| 87 * ``function OnJobFailure(jobId)``: | |
| 88 Invoked when a job has failed. | |
| 89 * ``function OnJobSuccess(jobId)``: | |
| 90 Invoked when a job has completed successfully. | |
| 91 | |
| 0 | 92 Some **DICOM-related events** allow to react to the reception of |
| 93 new medical images: | |
| 94 | |
| 95 * ``function OnStoredInstance(instanceId, tags, metadata, origin)``: | |
| 96 Invoked whenever a new instance has been stored into Orthanc. | |
| 97 This is especially useful for :ref:`lua-auto-routing`. The ``origin`` | |
| 98 parameter is :ref:`documented separately <lua-origin>`. | |
| 99 * ``function OnStablePatient(patientId, tags, metadata)``: Invoked | |
| 100 whenever a patient has not received any new instance for a certain | |
| 101 amount of time (cf. the option ``StableAge`` in the | |
| 102 :ref:`configuration file <configuration>`). The :ref:`identifier | |
| 103 <orthanc-ids>` of the patient is provided, together with her DICOM | |
| 78 | 104 tags and her :ref:`metadata <metadata>`. |
| 0 | 105 * ``function OnStableSeries(seriesId, tags, metadata)``: Invoked |
| 106 whenever a series has not received any new instance for a certain | |
| 107 amount of time. | |
| 108 * ``function OnStableStudy(studyId, tags, metadata)``: Invoked | |
| 109 whenever a study has not received any new instance for a certain | |
| 110 amount of time. | |
| 111 * ``function IncomingFindRequestFilter(source, origin)``: Invoked | |
| 112 whenever Orthanc receives an incoming C-Find query through the DICOM | |
| 113 protocol. This allows to inspect the content of the C-Find query, | |
| 114 and possibly modify it if a patch is needed for some manufacturer. A | |
| 115 `sample script is available | |
| 449 | 116 <https://hg.orthanc-server.com/orthanc/file/default/OrthancServer/Resources/Samples/Lua/IncomingFindRequestFilter.lua>`__. |
| 0 | 117 |
|
319
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
118 Some other **resource-related events** are available: |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
119 |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
120 * ``function OnDeletedPatient(patientId)``: Invoked when a patient has |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
121 been removed from the Orthanc database (new in Orthanc 1.6.0). |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
122 * ``function OnDeletedStudy(studyId)``: Invoked when a study has been |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
123 removed from the Orthanc database (new in Orthanc 1.6.0). |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
124 * ``function OnDeletedSeries(seriesId)``: Invoked when a series has |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
125 been removed from the Orthanc database (new in Orthanc 1.6.0). |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
126 * ``function OnDeletedInstance(instanceId)``: Invoked when a instance |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
127 has been removed from the Orthanc database (new in Orthanc 1.6.0). |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
128 * ``function OnUpdatedPatient(patientId)``: Invoked when some metadata |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
129 or some attachment associated with the given patient has been |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
130 updated (new in Orthanc 1.6.0). |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
131 * ``function OnUpdatedStudy(studyId)``: Invoked when some metadata or |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
132 some attachment associated with the given study has been updated |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
133 (new in Orthanc 1.6.0). |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
134 * ``function OnUpdatedSeries(seriesId)``: Invoked when some metadata |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
135 or some attachment associated with the given series has been updated |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
136 (new in Orthanc 1.6.0). |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
137 * ``function OnUpdatedInstance(instanceId)``: Invoked when some |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
138 metadata or some attachment associated with the given instance has |
|
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
139 been updated (new in Orthanc 1.6.0). |
|
606
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
140 |
|
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
141 Furthermore, in versions of Orthanc <= 1.8.2, whenever a DICOM |
|
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
142 association is negotiated for C-Store SCP, several callbacks are |
|
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
143 successively invoked to specify which **transfer syntaxes** are |
|
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
144 accepted for the association. These callbacks are listed in `this |
|
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
145 sample script |
|
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
146 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.8.2/OrthancServer/Resources/Samples/Lua/TransferSyntaxEnable.lua>`__. |
|
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
147 These callbacks were removed in Orthanc 1.9.0. |
| 0 | 148 |
| 149 *Note:* All of these callbacks are guaranteed to be **invoked in | |
| 150 mutual exclusion**. This implies that Lua scripting in Orthanc does | |
| 357 | 151 not support any kind of concurrency. |
| 152 | |
| 153 If a callback is specified multiple times in separate scripts, the | |
| 154 event handler of the latest loaded script is used. | |
| 0 | 155 |
| 156 | |
| 157 .. _lua-rest: | |
| 158 | |
| 159 Calling the REST API of Orthanc | |
| 160 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 161 | |
| 162 Lua scripts have :ref:`full access to the REST API <rest>` of Orthanc | |
| 163 through the following functions: | |
| 164 | |
|
252
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
165 * ``RestApiGet(uri, builtin, headers)`` |
|
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
166 * ``RestApiPost(uri, body, builtin, headers)`` |
|
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
167 * ``RestApiPut(uri, body, builtin, headers)`` |
|
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
168 * ``RestApiDelete(uri, builtin, headers)`` |
| 0 | 169 |
| 237 | 170 Here is a description of the parameters: |
|
235
17f8eda5fccb
Documented some parameter types, expected string formatting and added samples.
Tomas Zubiri <me@tomaszubiri.com>
parents:
191
diff
changeset
|
171 |
| 237 | 172 * ``uri`` specifies the resource being accessed |
| 173 (e.g. ``/instances``). It must not include the URL schema | |
| 174 (protocol), hostname or port. | |
| 0 | 175 |
| 237 | 176 * In the context of a POST or PUT request, ``body`` is a string |
| 177 containing the body of the request | |
| 178 (e.g. ``{"Keep":"StudyDate"}``). This string will often correspond | |
| 179 to a JSON-formatted version of a `Lua table | |
| 180 <http://lua-users.org/wiki/TablesTutorial>`__. The ``DumpJson()`` | |
| 181 function (see below) is very useful to achieve this conversion from | |
| 182 a Lua table to a plain string. | |
|
235
17f8eda5fccb
Documented some parameter types, expected string formatting and added samples.
Tomas Zubiri <me@tomaszubiri.com>
parents:
191
diff
changeset
|
183 |
| 237 | 184 * ``builtin`` is an optional Boolean that specifies whether the |
| 185 request targets only the built-in REST API of Orthanc (if set to | |
| 186 ``true``), or the full the REST API after being tainted by plugins | |
| 187 (if set to ``false``). | |
|
235
17f8eda5fccb
Documented some parameter types, expected string formatting and added samples.
Tomas Zubiri <me@tomaszubiri.com>
parents:
191
diff
changeset
|
188 |
|
252
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
189 * ``headers`` is an optional argument and was added in release |
|
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
190 1.5.7. It allows to provide the REST API endpoint with HTTP headers. |
|
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
191 |
| 237 | 192 .. highlight:: bash |
| 193 | |
| 194 For instance:: | |
| 195 | |
| 196 RestApiPost('/instances/5af318ac-78fb-47ff-b0b0-0df18b0588e0/anonymize', '{}') | |
| 197 | |
| 0 | 198 |
| 199 General-purpose functions | |
| 200 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 201 | |
| 202 The Lua engine of Orthanc contain several general-purpose ancillary | |
| 203 functions: | |
| 204 | |
| 205 * ``PrintRecursive(v)`` recursively prints the content of a `Lua table | |
| 206 <http://www.lua.org/pil/2.5.html>`__ to the log file of Orthanc. | |
| 207 * ``ParseJson(s)`` converts a string encoded in the `JSON format | |
| 208 <https://en.wikipedia.org/wiki/JSON>`__ to a Lua table. | |
| 209 * ``DumpJson(v, keepStrings)`` encodes a Lua table as a JSON string. | |
| 210 Setting the optional argument ``keepStrings`` (available from | |
| 211 release 0.9.5) to ``true`` prevents the automatic conversion of | |
| 212 strings to integers. | |
| 213 * ``GetOrthancConfiguration()`` returns a Lua table containing the | |
| 214 content of the :ref:`configuration files <configuration>` of | |
| 215 Orthanc. | |
| 216 | |
| 217 | |
| 218 Similarly to the functions to :ref:`call the REST API of Orthanc | |
| 219 <lua-rest>`, several functions are available to make generic HTTP | |
| 220 requests to Web services: | |
| 221 | |
| 90 | 222 * ``HttpGet(url, headers)`` |
| 223 * ``HttpPost(url, body, headers)`` | |
| 224 * ``HttpPut(url, body, headers)`` | |
| 225 * ``HttpDelete(url, headers)`` | |
| 0 | 226 * ``SetHttpCredentials(username, password)`` can be used to setup the |
| 227 HTTP credentials. | |
| 228 | |
|
252
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
229 The ``headers`` argument is optional and was added in release |
| 91 | 230 1.2.1. It allows to set the HTTP headers for the HTTP client request. |
| 0 | 231 |
| 283 | 232 Example:: |
| 233 | |
| 234 local preview = RestApiGet('/instances/' .. instanceId .. '/preview') | |
| 235 local headers = { | |
| 236 ["content-type"] = "image/png", | |
| 237 } | |
| 238 HttpPost("http://localhost/my-web-service/instance-preview", preview, headers) | |
| 239 | |
| 0 | 240 .. _lua-origin: |
| 241 | |
| 242 Origin of the instances | |
| 243 ^^^^^^^^^^^^^^^^^^^^^^^ | |
| 244 | |
| 245 Whenever Orthanc decides whether it should should store a new instance | |
| 246 (cf. the ``ReceivedInstanceFilter()`` callback), or whenever it has | |
| 247 actually stored a new instance (cf. the ``OnStoredInstance`` | |
| 248 callback), an ``origin`` parameter is provided. This parameter is a | |
| 249 `Lua table <http://www.lua.org/pil/2.5.html>`__ that describes from | |
| 250 which Orthanc subsystem the new instance comes from. | |
| 251 | |
| 252 There are 4 possible subsystems, that can be distinguished according | |
| 253 to the value of ``origin["RequestOrigin"]``: | |
| 254 | |
| 255 * ``RestApi``: The instance originates from some HTTP request to the REST | |
| 256 API. In this case, the ``RemoteIp`` and ``Username`` fields are | |
| 257 available in ``origin``. They respectively describe the IP address | |
| 258 of the HTTP client, and the username that was used for HTTP | |
| 259 authentication (as defined in the ``RegisteredUsers`` | |
| 260 :ref:`configuration variable <configuration>`). | |
| 261 * ``DicomProtocol``: The instance originates from a DICOM C-Store. | |
| 262 The fields ``RemoteIp``, ``RemoteAet`` and ``CalledAet`` | |
| 263 respectively provide the IP address of the DICOM SCU (client), the | |
| 264 application entity title of the DICOM SCU client, and the | |
| 265 application entity title of the Orthanc SCP server. The | |
| 266 ``CalledAet`` can be used for :ref:`advanced auto-routing scenarios | |
| 267 <lua-auto-routing>`, when a single instance of Orthanc acts as a | |
| 268 proxy for several DICOM SCU clients. | |
| 269 * ``Lua``: The instance originates from a Lua script. | |
| 270 * ``Plugins``: The instance originates from a plugin. | |
| 271 | |
| 272 | |
| 273 .. _lua-filter-dicom: | |
| 274 | |
| 75 | 275 Filtering incoming DICOM instances |
| 0 | 276 ---------------------------------- |
| 277 | |
| 278 .. highlight:: lua | |
| 279 | |
| 280 Each time a DICOM instance is received by Orthanc (either through the | |
| 281 DICOM protocol or through the REST API), the | |
| 282 ``ReceivedInstanceFilter()`` Lua function is invoked. If this callback | |
| 283 returns ``true``, the instance is accepted for storage. If it returns | |
| 284 ``false``, the instance is discarded. This mechanism can be used to | |
| 285 filter the incoming DICOM instances. Here is an example of a Lua | |
| 286 filter that only allows incoming instances of MR modality:: | |
| 287 | |
|
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
288 function ReceivedInstanceFilter(dicom, origin, info) |
| 0 | 289 -- Only allow incoming MR images |
| 290 if dicom.Modality == 'MR' then | |
| 291 return true | |
| 292 else | |
| 293 return false | |
| 294 end | |
| 295 end | |
| 296 | |
|
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
297 The argument ``dicom`` corresponds to a `Lua table |
| 0 | 298 <http://www.lua.org/pil/2.5.html>`__ (i.e. an associative array) that |
| 299 contains the DICOM tags of the incoming instance. For debugging | |
| 300 purpose, you can print this structure as follows:: | |
| 301 | |
|
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
302 function ReceivedInstanceFilter(dicom, origin, info) |
| 0 | 303 PrintRecursive(dicom) |
| 304 -- Accept all incoming instances (default behavior) | |
| 305 return true | |
| 306 end | |
| 307 | |
| 308 The argument ``origin`` is :ref:`documented separately <lua-origin>`. | |
| 309 | |
|
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
310 The argument ``info`` was introduced in Orthanc 1.6.1. It contains |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
311 some additional information about the received DICOM instance, |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
312 notably: |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
313 |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
314 * ``HasPixelData`` is ``true`` iff. the Pixel Data (7FE0,0010) tag is |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
315 present. |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
316 * ``TransferSyntaxUID`` contains the transfer syntax UID of the |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
317 dataset of the instance (if applicable). |
|
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
318 |
| 0 | 319 |
| 320 .. _lua-filter-rest: | |
| 321 | |
| 75 | 322 Filtering incoming REST requests |
| 0 | 323 -------------------------------- |
| 324 | |
| 325 .. highlight:: lua | |
| 326 | |
| 327 Lua scripting can be used to control the access to the various URI of | |
| 328 the REST API. Each time an incoming HTTP request is received, the | |
| 329 ``IncomingHttpRequestFilter()`` Lua function is called. The access to | |
| 330 the resource is granted if and only if this callback script returns | |
| 331 ``true``. | |
| 332 | |
| 333 This mechanism can be used to implement fine-grained `access control | |
| 25 | 334 lists <https://en.wikipedia.org/wiki/Access_control_list>`__. Here is |
| 0 | 335 an example of a Lua script that limits POST, PUT and DELETE requests |
| 336 to an user that is called "admin":: | |
| 337 | |
| 338 function IncomingHttpRequestFilter(method, uri, ip, username, httpHeaders) | |
| 339 -- Only allow GET requests for non-admin users | |
| 340 | |
| 341 if method == 'GET' then | |
| 342 return true | |
| 343 elseif username == 'admin' then | |
| 344 return true | |
| 345 else | |
| 346 return false | |
| 347 end | |
| 348 end | |
| 349 | |
| 350 Here is a description of the arguments of this Lua callback: | |
| 351 | |
| 352 * ``method``: The HTTP method (GET, POST, PUT or DELETE). | |
| 353 * ``uri``: The path to the resource (e.g. ``/tools/generate-uid``). | |
| 354 * ``ip``: The IP address of the host that has issued the HTTP request (e.g. ``127.0.0.1``). | |
| 355 * ``username``: If HTTP Basic Authentication is enabled in the | |
| 356 :ref:`configuration file <configuration>`, the name of the user that | |
| 357 has issued the HTTP request (as defined in the ``RegisteredUsers`` | |
| 358 configuration variable). If the authentication is disabled, this | |
| 359 argument is set to the empty string. | |
| 360 * ``httpHeaders``: The HTTP headers of the incoming request. This | |
| 361 argument is available since Orthanc 1.0.1. It is useful if the | |
| 362 authentication should be achieved through tokens, for instance | |
| 363 against a `LDAP | |
| 364 <https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol>`__ | |
| 365 or `OAuth2 <https://en.wikipedia.org/wiki/OAuth>`__ server. | |
| 366 | |
| 367 | |
| 368 .. _lua-auto-routing: | |
| 369 | |
| 75 | 370 Auto-routing of DICOM images |
| 0 | 371 ---------------------------- |
| 372 | |
| 373 .. highlight:: lua | |
| 374 | |
| 375 Since release 0.8.0, the routing of DICOM flows can be very easily | |
| 376 automated with Orthanc. All you have to do is to declare your | |
| 377 destination modality in the :ref:`configuration file <configuration>` | |
| 378 (section ``DicomModalities``), then to create and install a Lua | |
| 379 script. For instance, here is a sample script:: | |
| 380 | |
| 381 function OnStoredInstance(instanceId, tags, metadata) | |
| 382 Delete(SendToModality(instanceId, 'sample')) | |
| 383 end | |
| 384 | |
| 385 If this script is loaded into Orthanc, whenever a new DICOM instance | |
| 386 is received by Orthanc, it will be routed to the modality whose | |
| 387 symbolic name is ``sample`` (through a Store-SCU command), then it | |
| 388 will be removed from Orthanc. In other words, this is a **one-liner | |
| 389 script to implement DICOM auto-routing**. | |
| 390 | |
| 391 Very importantly, thanks to this feature, you do not have to use the | |
| 392 REST API or to create external scripts in order to automate simple | |
| 393 imaging flows. The scripting engine is entirely contained inside the | |
| 394 Orthanc core system. | |
| 395 | |
| 396 Thanks to Lua expressiveness, you can also implement conditional | |
| 397 auto-routing. For instance, if you wish to route only patients whose | |
| 398 name contains "David", you would simply write:: | |
| 399 | |
| 400 function OnStoredInstance(instanceId, tags, metadata) | |
| 401 -- Extract the value of the "PatientName" DICOM tag | |
| 402 local patientName = string.lower(tags['PatientName']) | |
| 403 | |
| 404 if string.find(patientName, 'david') ~= nil then | |
| 405 -- Only route patients whose name contains "David" | |
| 406 Delete(SendToModality(instanceId, 'sample')) | |
| 407 | |
| 408 else | |
| 409 -- Delete the patients that are not called "David" | |
| 410 Delete(instanceId) | |
| 411 end | |
| 412 end | |
| 413 | |
| 414 Besides ``SendToModality()``, a mostly identical function with the | |
| 415 same arguments called ``SendToPeer()`` can be used to route instances | |
| 416 to :ref:`Orthanc peers <peers>`. It is also possible to modify the | |
| 417 received instances before routing them. For instance, here is how you | |
| 418 would replace the ``StationName`` DICOM tag:: | |
| 419 | |
| 420 function OnStoredInstance(instanceId, tags, metadata) | |
| 421 -- Ignore the instances that result from a modification to avoid | |
| 422 -- infinite loops | |
| 423 if (metadata['ModifiedFrom'] == nil and | |
| 424 metadata['AnonymizedFrom'] == nil) then | |
| 425 | |
| 426 -- The tags to be replaced | |
| 427 local replace = {} | |
| 428 replace['StationName'] = 'My Medical Device' | |
| 429 | |
| 430 -- The tags to be removed | |
| 431 local remove = { 'MilitaryRank' } | |
| 432 | |
| 433 -- Modify the instance, send it, then delete the modified instance | |
| 434 Delete(SendToModality(ModifyInstance(instanceId, replace, remove, true), 'sample')) | |
| 435 | |
| 436 -- Delete the original instance | |
| 437 Delete(instanceId) | |
| 438 end | |
| 439 end | |
| 440 | |
| 441 | |
| 75 | 442 Important remarks about auto-routing |
| 443 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
|
19
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
444 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
445 The ``SendToModality()``, ``SendToPeer()``, ``ModifyInstance()`` and |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
446 ``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
|
447 (implying a single DICOM instance, and possibly a basic modification |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
448 of this instance). The ``ModifyInstance()`` function `could also lead |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
449 to problems |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
450 <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
|
451 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
|
452 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
453 For more evolved auto-routing scenarios, remember that Lua scripts |
| 191 | 454 :ref:`have full access to the REST API of Orthanc <lua-rest>`. This is |
|
19
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
455 illustrated by the ``AutoroutingModification.lua`` sample available in |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
456 the source distribution of Orthanc:: |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
457 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
458 function OnStoredInstance(instanceId, tags, metadata, origin) |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
459 -- 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
|
460 -- avoid infinite loops |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
461 if origin['RequestOrigin'] ~= 'Lua' then |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
462 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
463 -- The tags to be replaced |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
464 local replace = {} |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
465 replace['StationName'] = 'My Medical Device' |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
466 replace['0031-1020'] = 'Some private tag' |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
467 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
468 -- The tags to be removed |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
469 local remove = { 'MilitaryRank' } |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
470 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
471 -- Modify the instance |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
472 local command = {} |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
473 command['Replace'] = replace |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
474 command['Remove'] = remove |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
475 local modifiedFile = RestApiPost('/instances/' .. instanceId .. '/modify', DumpJson(command, true)) |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
476 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
477 -- Upload the modified instance to the Orthanc database so that |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
478 -- it can be sent by Orthanc to other modalities |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
479 local modifiedId = ParseJson(RestApiPost('/instances/', modifiedFile)) ['ID'] |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
480 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
481 -- Send the modified instance to another modality |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
482 RestApiPost('/modalities/sample/store', modifiedId) |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
483 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
484 -- Delete the original and the modified instances |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
485 RestApiDelete('/instances/' .. instanceId) |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
486 RestApiDelete('/instances/' .. modifiedId) |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
487 end |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
488 end |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
489 |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
490 Also note that :ref:`other callbacks are available <lua-callbacks>` |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
491 (``OnStablePatient()``, ``OnStableStudy()`` and ``OnStableSeries()``) |
|
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
492 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
|
493 with ``OnStoredInstance()``. |
| 75 | 494 |
|
99
e83da2f99e45
added 'troubleshooting C-Find queries' in the worklist section
amazy
parents:
91
diff
changeset
|
495 .. _lua-fix-cfind: |
| 75 | 496 |
|
77
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
497 Fixing C-Find requests |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
498 ---------------------- |
| 75 | 499 |
| 500 :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
|
501 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
|
502 `reported by users |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
503 <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
|
504 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
|
505 (cf. `this real-world example |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
506 <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
|
507 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
|
508 outgoing C-Find queries using a Lua script. |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
509 |
|
165
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
510 Sanitizing incoming C-Find requests can be done by implementing the |
|
77
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
511 ``IncomingFindRequestFilter(query, origin)`` callback that is called |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
512 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
|
513 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
|
514 by some manufacturer:: |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
515 |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
516 function IncomingFindRequestFilter(query, origin) |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
517 -- First display the content of the C-Find query |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
518 PrintRecursive(query) |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
519 PrintRecursive(origin) |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
520 |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
521 -- Remove the "PrivateCreator" tag from the query |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
522 local v = query |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
523 v['5555,0010'] = nil |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
524 |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
525 return v |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
526 end |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
527 |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
528 The ``origin`` argument contains information about which modality has |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
529 issued the request. |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
530 |
|
443
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
531 Note that this callback allows you to modify the incoming request |
|
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
532 but will not modify the list of tags that Orthanc will return. |
|
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
533 |
|
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
534 Also note that the ``IncomingFindRequestFilter`` callback is not applied to |
|
165
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
535 C-Find requests targeting :ref:`modality worklists |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
536 <worklists-plugin>`. Since Orthanc 1.4.2, the corresponding |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
537 ``IncomingWorklistRequestFilter`` callback can be used to sanitize |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
538 C-FIND requests against worklists:: |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
539 |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
540 function IncomingWorklistRequestFilter(query, origin) |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
541 PrintRecursive(query) |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
542 PrintRecursive(origin) |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
543 |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
544 -- Implements the same behavior as the "FilterIssuerAet" |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
545 -- option of the sample worklist plugin |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
546 query['0040,0100'][1]['0040,0001'] = origin['RemoteAet'] |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
547 |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
548 return query |
|
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
549 end |
|
105
268ec482f051
IncomingFindRequestFilter not applied to worklist plugin
amazy
parents:
99
diff
changeset
|
550 |
|
443
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
551 |
|
77
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
552 Similarly, the callback ``OutgoingFindRequestFilter(query, modality)`` |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
553 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
|
554 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
|
555 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
|
556 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
|
557 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
|
558 from Orthanc Explorer):: |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
559 |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
560 function OutgoingFindRequestFilter(query, modality) |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
561 for key, value in pairs(query) do |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
562 if value == '*' then |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
563 query[key] = '' |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
564 end |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
565 end |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
566 |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
567 return query |
|
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
568 end |
| 668 | 569 |
| 570 | |
| 571 .. _lua-external-modules: | |
| 572 | |
| 573 Using external modules | |
| 574 ---------------------- | |
| 575 | |
| 576 Starting with Orthanc 1.3.2, it is possible to use external Lua | |
| 577 modules if Orthanc was compiled with the ``-DENABLE_LUA_MODULES=ON`` | |
| 578 while invoking CMake. | |
| 579 | |
| 580 Importantly, the modules and the Orthanc server must use the same | |
| 581 version of Lua for external modules to be properly loaded. | |
| 582 | |
| 583 Check out the Orthanc Users forum for old discussions about this | |
| 584 topic: `reference 1 | |
| 585 <https://groups.google.com/g/orthanc-users/c/BXfmwU786B0/m/M47slt5GFwAJ>`__, | |
| 586 `reference 2 | |
| 587 <https://groups.google.com/g/orthanc-users/c/BXfmwU786B0/m/qpVe8UvGAwAJ>`__, | |
| 588 `reference 3 | |
| 589 <https://groups.google.com/g/orthanc-users/c/LDAN5jA0X8M/m/4zrk0_AaBAAJ>`__. |