Mercurial > hg > orthanc-book
changeset 1250:55fff53f980a default tip
merge
| author | Benoit Crickboom <bc@orthanc.team> |
|---|---|
| date | Thu, 18 Dec 2025 10:44:28 +0100 |
| parents | 0ad3ed7cdad6 (current diff) 202b98f79bf5 (diff) |
| children | |
| files | |
| diffstat | 65 files changed, 1794 insertions(+), 342 deletions(-) [+] |
line wrap: on
line diff
--- a/.hgtags Thu Dec 18 10:39:14 2025 +0100 +++ b/.hgtags Thu Dec 18 10:44:28 2025 +0100 @@ -21,3 +21,4 @@ a23a5e08f3b40707d20162c4153155cf45b74e5b Orthanc-1.12.7 28b55ad71cb62ba7e0756adc895491a02c3276aa Orthanc-1.12.8 c977cc347e8c7dd5e31d0a7fae13b42df39a1f08 Orthanc-1.12.9 +e15a7861fdcd852df8ff10a67daad3b49f973835 Orthanc-1.12.10
--- a/OpenAPI/orthanc-openapi.json Thu Dec 18 10:39:14 2025 +0100 +++ b/OpenAPI/orthanc-openapi.json Thu Dec 18 10:44:28 2025 +0100 @@ -2,7 +2,7 @@ "info" : { "description" : "This is the full documentation of the [REST API](https://orthanc.uclouvain.be/book/users/rest.html) of Orthanc.<p>This reference is automatically generated from the source code of Orthanc. A [shorter cheat sheet](https://orthanc.uclouvain.be/book/users/rest-cheatsheet.html) is part of the Orthanc Book.<p>An earlier, manually crafted version from August 2019, is [still available](2019-08-orthanc-openapi.html), but is not up-to-date anymore ([source](https://groups.google.com/g/orthanc-users/c/NUiJTEICSl8/m/xKeqMrbqAAAJ)).", "title" : "Orthanc API", - "version" : "1.12.9" + "version" : "1.12.10" }, "openapi" : "3.0.0", "paths" : { @@ -4719,11 +4719,11 @@ "type" : "string" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "Resources" : { @@ -4811,11 +4811,11 @@ "type" : "string" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "Resources" : { @@ -4929,11 +4929,11 @@ "properties" : { "ID" : { "description" : "Identifier of the query, to be used with `/queries/{id}`", - "type" : "object" + "type" : "string" }, "Path" : { "description" : "Root path to the query in the REST API", - "type" : "object" + "type" : "string" } } } @@ -5063,7 +5063,7 @@ "type" : "number" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Port" : { @@ -5071,7 +5071,7 @@ "type" : "number" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "Resources" : { @@ -5424,11 +5424,11 @@ "type" : "number" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "PrivateCreator" : { @@ -7274,11 +7274,11 @@ "type" : "number" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "PrivateCreator" : { @@ -8064,11 +8064,11 @@ "type" : "boolean" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "Resources" : { @@ -8244,6 +8244,7 @@ "connectivity-checks", "delayed-deletion", "dicom-web", + "education", "gdcm", "housekeeper", "indexer", @@ -8326,7 +8327,7 @@ "ExtendsOrthancExplorer" : true, "ID" : "dicom-web", "RootUri" : "../dicom-web/app/client/index.html", - "Version" : "1.20" + "Version" : "1.21" } } } @@ -8822,11 +8823,11 @@ "type" : "boolean" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "RetrieveMethod" : { @@ -9034,11 +9035,11 @@ "type" : "boolean" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "RetrieveMethod" : { @@ -9349,11 +9350,11 @@ "type" : "number" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "PrivateCreator" : { @@ -11053,11 +11054,11 @@ "type" : "number" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "PrivateCreator" : { @@ -11944,7 +11945,7 @@ "/storage-commitment/{id}/remove" : { "post" : { "deprecated" : false, - "description" : "Remove out of Orthanc, the DICOM instances that have been reported to have been properly received the storage commitment report whose identifier is provided in the URL. This is only possible if the `Status` of the storage commitment report is `Success`. https://orthanc.uclouvain.be/book/users/storage-commitment.html#removing-the-instances", + "description" : "Remove out of Orthanc, the DICOM instances that have been reported to have been properly received in the storage commitment report whose identifier is provided in the URL. This is only possible if the `Status` of the storage commitment report is `Success`. https://orthanc.uclouvain.be/book/users/storage-commitment.html#removing-the-instances", "parameters" : [ { "description" : "Identifier of the storage commitment report", @@ -12225,11 +12226,11 @@ "type" : "number" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "PrivateCreator" : { @@ -13866,11 +13867,11 @@ "type" : "boolean" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "Resources" : { @@ -14159,11 +14160,11 @@ "type" : "number" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "PrivateCreator" : { @@ -14835,11 +14836,11 @@ "type" : "boolean" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "Remove" : { @@ -15002,7 +15003,8 @@ "HasExtendedChanges" : true, "HasExtendedFind" : true, "HasKeyValueStores" : true, - "HasQueues" : true + "HasQueues" : true, + "HasReserveQueueValue" : true }, "CheckRevisions" : false, "DatabaseBackendPlugin" : null, @@ -15031,7 +15033,7 @@ "StorageAreaPlugin" : null, "StorageCompression" : false, "UserMetadata" : {}, - "Version" : "1.12.9" + "Version" : "1.12.10" }, "properties" : { "ApiVersion" : { @@ -15039,7 +15041,7 @@ "type" : "number" }, "Capabilities" : { - "description" : "Whether the back-end supports optional features like 'HasExtendedChanges', 'HasExtendedFind' (new in Orthanc 1.12.5) ", + "description" : "Whether the database back-end supports optional features like 'HasExtendedChanges', 'HasExtendedFind' (new in Orthanc 1.12.5), 'HasKeyValueStores', 'HasQueues' (new in Orthanc 1.12.8), and 'HasReserveQueueValue' (new in Orthanc 1.12.10)", "type" : "object" }, "CheckRevisions" : { @@ -15329,11 +15331,11 @@ "type" : "number" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "PrivateCreator" : { @@ -15521,11 +15523,11 @@ "type" : "number" }, "Permissive" : { - "description" : "If `true`, ignore errors during the individual steps of the job.", + "description" : "If `true`, ignore errors during the individual steps of the job. Default value is `false`.", "type" : "boolean" }, "Priority" : { - "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority.", + "description" : "In asynchronous mode, the priority of the job. The higher the value, the higher the priority. Default value is `0`", "type" : "number" }, "PrivateCreator" : { @@ -16913,7 +16915,7 @@ "200" : { "content" : { "text/plain" : { - "example" : "orthanc_available_dicom_threads 4 1754933485145\northanc_available_http_threads_count 49 1754933683397\northanc_count_instances 2552 1754933691628\northanc_count_patients 8 1754933691628\northanc_count_series 26 1754933691628\northanc_count_studies 8 1754933691628\northanc_dicom_cache_count 1 1754933691628\northanc_dicom_cache_size_mb 0.502557755 1754933691628\northanc_disk_size_mb 983.235352 1754933691628\northanc_jobs_completed 0 1754933691628\northanc_jobs_failed 0 1754933691628\northanc_jobs_pending 0 1754933691628\northanc_jobs_running 0 1754933691628\northanc_jobs_success 0 1754933691628\northanc_last_change 6551 1754933691628\northanc_rest_api_active_requests 1 1754933683397\northanc_rest_api_duration_ms 650 1754933690143\northanc_storage_cache_count 400 1754933691629\northanc_storage_cache_hit_count 407 1754933691400\northanc_storage_cache_miss_count 400 1754933689980\northanc_storage_cache_size_mb 3.17403412 1754933691628\northanc_storage_read_bytes 3328216 1754933689980\northanc_storage_read_duration_ms 0 1754933683841\northanc_uncompressed_size_mb 983.235352 1754933691628\northanc_up_time_s 206 1754933691628\n" + "example" : "orthanc_available_dicom_threads 4 1764171884784\northanc_available_http_threads_count 49 1764172093743\northanc_count_instances 2552 1764172100539\northanc_count_patients 8 1764172100539\northanc_count_series 26 1764172100539\northanc_count_studies 8 1764172100539\northanc_dicom_cache_count 167 1764172100539\northanc_dicom_cache_size_mb 83.9109268 1764172100539\northanc_disk_size_mb 983.235352 1764172100539\northanc_jobs_completed 0 1764172100539\northanc_jobs_failed 0 1764172100539\northanc_jobs_pending 0 1764172100539\northanc_jobs_running 0 1764172100539\northanc_jobs_success 0 1764172100539\northanc_last_change 6551 1764172100539\northanc_rest_api_active_requests 1 1764172093743\northanc_rest_api_duration_ms 604 1764172099042\northanc_storage_cache_count 408 1764172100539\northanc_storage_cache_hit_count 683 1764172100350\northanc_storage_cache_miss_count 408 1764172098910\northanc_storage_cache_size_mb 98.1075974 1764172100539\northanc_storage_read_bytes 102873274 1764172098911\northanc_storage_read_duration_ms 0 1764172094128\northanc_uncompressed_size_mb 983.235352 1764172100539\northanc_up_time_s 216 1764172100539\n" } }, "description" : "" @@ -16932,7 +16934,7 @@ "200" : { "content" : { "text/plain" : { - "example" : "20250811T173451", + "example" : "20251126T154820", "schema" : { "description" : "The UTC time" } @@ -16954,7 +16956,7 @@ "200" : { "content" : { "text/plain" : { - "example" : "20250811T173451", + "example" : "20251126T154820", "schema" : { "description" : "The local time" }
--- a/Sphinx/source/developers/creating-plugins.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/developers/creating-plugins.rst Thu Dec 18 10:44:28 2025 +0100 @@ -15,7 +15,7 @@ Native Orthanc plugins must use the `plugin SDK <https://orthanc.uclouvain.be/sdk/>`__ whose interface is available as a `C header -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__. +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__. As a consequence, an Orthanc plugin will typically be written using C or C++, although it is also possible to create native plugins using languages that feature compatibility with C headers and with `FFI of @@ -103,7 +103,7 @@ that is part of the Orthanc source distribution: * `Plugins/Include/orthanc/OrthancCPlugin.h - <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ + <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ `Online documentation <https://orthanc.uclouvain.be/sdk/>`__ for this C header is available, as generated by `Doxygen @@ -117,8 +117,8 @@ ``HAS_ORTHANC_EXCEPTION`` is set to ``0``: * `Plugins/Samples/Common/OrthanPluginCppWrapper.h - <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__ + <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__ * `Plugins/Samples/Common/OrthanPluginCppWrapper.cpp - <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__ + <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__ * `Plugins/Samples/Common/OrthanPluginException.h - <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Plugins/Samples/Common/OrthancPluginException.h>`__ + <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Plugins/Samples/Common/OrthancPluginException.h>`__
--- a/Sphinx/source/developers/db-versioning.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/developers/db-versioning.rst Thu Dec 18 10:44:28 2025 +0100 @@ -26,7 +26,7 @@ Version DB v2 DB v3 DB v4 DB v5 DB v6 =============================== ===== ===== ===== ===== ===== Mainline u u u x -Orthanc 0.9.5 - Orthanc 1.12.9 u u u x +Orthanc 0.9.5 - Orthanc 1.12.10 u u u x Orthanc 0.8.5 - Orthanc 0.9.4 u u x Orthanc 0.7.3 - Orthanc 0.8.4 u x Orthanc 0.4.0 - Orthanc 0.7.2 x
--- a/Sphinx/source/developers/repositories.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/developers/repositories.rst Thu Dec 18 10:44:28 2025 +0100 @@ -91,12 +91,12 @@ In such a case, you must explicitly add the cryptographic fingerprint of our code server using a more recent option than the ``hostfingerprints`` option. To this end, edit the `configuration file -<https://www.mercurial-scm.org/doc/hgrc.5.html#files>`__ of Mercurial +<https://mercurial-scm.org/help/topics/config>`__ of Mercurial (by default on Microsoft Windows, ``%USERPROFILE%\Mercurial.ini``), and add the following lines:: [hostsecurity] - orthanc.uclouvain.be:fingerprints=sha256:30:1d:d8:b6:a2:50:23:6a:a1:b7:da:66:b6:aa:2f:fa:59:f3:9d:cd:ed:f8:2c:49:14:57:25:39:84:b9:60:db + orthanc.uclouvain.be:fingerprints=sha256:B0:EF:A4:6C:89:62:03:96:32:6B:80:A9:39:FC:91:C5:12:98:6C:25:27:54:ED:E4:98:DA:C2:C8:ED:7A:1F:72 .. highlight:: bash @@ -121,7 +121,7 @@ following lines to your ``~/.hgrc`` file:: [hostfingerprints] - orthanc.uclouvain.be = 69:C0:EF:E7:05:BB:2A:0B:88:EA:E8:00:C6:1A:95:A3:53:74:C1:D4 + orthanc.uclouvain.be = 7A:7A:74:92:41:97:A5:C0:16:3E:C8:17:67:FD:16:60:2A:C0:42:D3 .. highlight:: bash
--- a/Sphinx/source/faq.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq.rst Thu Dec 18 10:44:28 2025 +0100 @@ -61,6 +61,7 @@ faq/orthanc-ids.rst faq/main-dicom-tags.rst faq/versioning.rst + faq/db-benchmark.rst faq/debian-daemon.rst faq/redhat.rst faq/apache.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/faq/db-benchmark.rst Thu Dec 18 10:44:28 2025 +0100 @@ -0,0 +1,69 @@ +.. _db-benchmark: + +Which Database engine should I use ? +==================================== + +By default, Orthanc stores the index of the DICOM instances as an +embedded `SQLite database <https://www.sqlite.org/index.html>`_ saved +in the ``IndexStorageDirectory``. This is very convenient when +you simply want to try Orthanc or need to handle a relatively +small amount of data. + +If, at some point, you need to store large amounts of data and require +more stable performance, you should use an external database server. +Although we provide plugins for :ref:`PostgreSQL <postgresql>`, +:ref:`MySQL <mysql>` and :ref:`ODBC <odbc>`, we strongly recommend +using the :ref:`PostgreSQL <postgresql>` plugin since this is the one +we focus on when implementing new features or optimizing performance. + +Benchmark +--------- + +We have setup a `test scenario <https://github.com/orthanc-server/orthanc-setup-samples/tree/master/docker/databases-benchmark>`_ +to compare the performances of the default SQLite engine against the PostgreSQL and the MySQL plugins. + +Note: these tests have been performed with the ``orthancteam/orthanc:25.10.3`` Docker images. + +.. image:: ../images/db-benchmark.png + :align: center + :width: 1000px + +The first plot shows the time required to ingest 5 studies, each with 4 series of 250 instances. +The ingest is performed with 5 parallel HTTP clients and the :ref:`DICOMweb <dicomweb>` plugin +is enabled which means it starts caching the ``/metadata`` routes during the ingest. + +The second plot shows the time required to ingest and generate the ``/metadata``. As you can see, +the ingest performance of SQLite clearly deteriorates as soon as you have 25.000 instances +in the DB while the PostgreSQL remains, ingesting around 250 instances per second. + +The third plot shows the time required to perform 5 calls to ``/tools/find`` at study level. +This plot is actually not very representative since the DB contains a very small number of studies. + +The fourth plot shows the time required to retrieve a single instance through :ref:`DICOMweb WADO-RS <dicomweb>`. +This is typical of API calls performed by the :ref:`Stone Web viewer <stone_webviewer>` or the :ref:`OHIF viewer <ohif>`. + +The bad performance of the DICOMweb plugin with SQLite to compute the ``metadata`` cache can +actually be explained by the fourth plot that shows that even simple search operations in the database get slower. + + +Conclusions +----------- + +From a performance point of view, you may stick with SQLite if you do not plan to store more than +25.000 - 50.000 instances. + +Typically, if you are only handling ``CR, DX`` or simple ``US`` images, SQLite is a very good option. +SQLite also remains a good option if you are using Orthanc as a buffer to transfer, convert or sanitize images +in a workflow, especially if you do not need the DICOMweb plugin. + +As soon as you plan to store thousands of ``MR, CT, MG`` or other large image sets, you should +switch to the :ref:`PostgreSQL <postgresql>`. + +You should only use :ref:`MySQL <mysql>` or :ref:`ODBC <odbc>` if your company policy requires it, +as their performance is not optimal and they currently lack the latest DB features like: + +* The ``ExtendedFind`` extension to perform ordering and more advanced filtering in ``/tools/find``. +* Key-Value Stores and Queues to enable some features like the REST API + of the :ref:`Worklist plugin <worklist>` or enable the :ref:`advanced storage <advanced-storage>` plugin. + +
--- a/Sphinx/source/faq/debugging-encodings.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq/debugging-encodings.rst Thu Dec 18 10:44:28 2025 +0100 @@ -11,7 +11,7 @@ -------------------------------------------------- If your DICOM files are valid, Orthanc should display all strings correctly both -in the UI and in the Rest API in which all strings are converted to UTF-8. +in the UI and in the REST API in which all strings are converted to UTF-8. However, it might still be useful to understand what's wrong with your files such that you can possibly fix your files once they have been stored in Orthanc
--- a/Sphinx/source/faq/how-do-you-spell-orthanc.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq/how-do-you-spell-orthanc.rst Thu Dec 18 10:44:28 2025 +0100 @@ -18,6 +18,7 @@ - ORTHANAC - ORTHANK - ORTHANS +- ORTHGAC - ORTHNAC - ORTHONC - ORTNAC
--- a/Sphinx/source/faq/main-dicom-tags.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq/main-dicom-tags.rst Thu Dec 18 10:44:28 2025 +0100 @@ -138,7 +138,7 @@ ``SeriesDescription`` at ``Study`` level will lead to unpredictible results. Orthanc will **not** check that the tags levels are adequate. -*Note:* As of Orthanc 1.12.9, it is not possible to store Private DICOM tags +*Note:* As of Orthanc 1.12.10, it is not possible to store Private DICOM tags in the ``ExtraMainDicomTags``. @@ -164,13 +164,13 @@ } -DICOMWeb +DICOMweb ======== Below is a sample configuration that is well suited to -optimize DICOMWeb routes in general in case you are using the +optimize DICOMweb routes in general in case you are using the ``MainDicomTags`` metadata mode. However, note that, from version -1.15 of the :ref:`DICOMWeb plugin <dicomweb-server-metadata-config>`, you should favor the ``Full`` mode:: +1.15 of the :ref:`DICOMweb plugin <dicomweb-server-metadata-config>`, you should favor the ``Full`` mode:: { "ExtraMainDicomTags" : {
--- a/Sphinx/source/faq/orthanc-storage.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq/orthanc-storage.rst Thu Dec 18 10:44:28 2025 +0100 @@ -105,9 +105,9 @@ The database schema is kept as simple as possible, e.g, for SQLite, the schema can be found in the following two files of the source code of Orthanc: `PrepareDatabase.sql -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Sources/Database/PrepareDatabase.sql>`__ +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Sources/Database/PrepareDatabase.sql>`__ and `InstallTrackAttachmentsSize.sql -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Sources/Database/InstallTrackAttachmentsSize.sql>`__. +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Sources/Database/InstallTrackAttachmentsSize.sql>`__. Direct access
--- a/Sphinx/source/faq/scalability.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq/scalability.rst Thu Dec 18 10:44:28 2025 +0100 @@ -53,7 +53,7 @@ Here is a generic setup that should provide best performance in the presence of large databases: -* Make sure to use the latest release of Orthanc (1.12.9 at the time of +* Make sure to use the latest release of Orthanc (1.12.10 at the time of writing) running on a GNU/Linux distribution. * We suggest to use the latest release of the :ref:`PostgreSQL plugin @@ -118,7 +118,7 @@ * From Orthanc 1.11.0: you have the ability to add more :ref:`main DICOM tags <main-dicom-tags>` in the Orthanc Index - to speed up C-Find, ``tools/find``, DICOMWeb QIDO-RS, WADO-RS and + to speed up C-Find, ``tools/find``, DICOMweb QIDO-RS, WADO-RS and especially WADO-RS Retrieve Metadata. * Make sure to carefully :ref:`read the logs <log>` in ``--verbose``
--- a/Sphinx/source/faq/transfer-atomicity.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq/transfer-atomicity.rst Thu Dec 18 10:44:28 2025 +0100 @@ -54,7 +54,7 @@ | | * If ``/dicom-web/servers/sample/stow`` returns | study in a single STOW-RS request | | | a 200 or if job is successfull | | +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ -| **Orthanc Rest API** | * If every call to ``/instances`` receives a | No | +| **Orthanc REST API** | * If every call to ``/instances`` receives a | No | | | 200 | | | | * If ``/peers/sample/store`` receives a | | | | 200 or if job is successfull | | @@ -123,10 +123,10 @@ -Orthanc Rest API +Orthanc REST API ---------------- -When transferring a study through the Orthanc Rest API, each instance is transferred individually. +When transferring a study through the Orthanc REST API, each instance is transferred individually. Therefore, on server side, if the transfer is interrupted, the destination has no way to know that the study has been fully transmitted or not.
--- a/Sphinx/source/faq/troubleshooting.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq/troubleshooting.rst Thu Dec 18 10:44:28 2025 +0100 @@ -120,9 +120,8 @@ As a rule of thumb, the performance of the default SQLite engine built in Orthanc should run fine up to about 50,000 DICOM instances. - However, we have seen Orthanc running fairly well with more than 2 - millions of instances. This limit really depends upon your - application, and upon the patterns of access to the database. + This limit really depends upon your application, and upon the patterns + of access to the database. Check the FAQ about :ref:`db-benchmark`. Also check out the section about the :ref:`scalability`.
--- a/Sphinx/source/faq/viewers.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq/viewers.rst Thu Dec 18 10:44:28 2025 +0100 @@ -29,7 +29,7 @@ * `Aeskulap <https://github.com/pipelka/aeskulap>`__. * `Weasis <https://nroduit.github.io/en/basics/customize/integration/#orthanc-web-server>`__ - (through the :ref:`DICOM web plugin <dicomweb>`). The Orthanc Users + (through the :ref:`DICOMweb plugin <dicomweb>`). The Orthanc Users discussion group contains a `reportedly working configuration <https://groups.google.com/g/orthanc-users/c/lFa47FOL-Ok/m/Lu_QKIN8BAAJ>`__. * `Oviyam <http://oviyam.raster.in/>`__ (`instructions are available
--- a/Sphinx/source/faq/worklist.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/faq/worklist.rst Thu Dec 18 10:44:28 2025 +0100 @@ -20,11 +20,10 @@ Orthanc user to provide the worklist generator that is best suited for her use. -A :ref:`sample plugin <worklists-plugin>` is available in the source -distribution of Orthanc to serve the worklists stored in some folder -on the filesystem. This sample plugin mimics the behavior of the -``wlmscpfs`` command-line tool from the `DCMTK software -<https://support.dcmtk.org/docs/wlmscpfs.html>`__. +A :ref:`worklists plugin <worklists-plugin-new>` is available to serve +the worklists stored in some folder on the filesystem or directly in the +Orthanc database. It also provides a REST API to create and manage +worklists. For more complex or integrated workflows where you must implement a custom MWL plugin, please check the `documentation of the part of the
--- a/Sphinx/source/integrations/integrate-osirix-using-dicomweb.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/integrations/integrate-osirix-using-dicomweb.rst Thu Dec 18 10:44:28 2025 +0100 @@ -1,6 +1,6 @@ .. _integrate-osirix-using-dicomweb: -Integrate Osirix using DICOMWeb +Integrate Osirix using DICOMweb =============================== .. note:: The OsiriX team has a blog post entitled "`Installing @@ -14,14 +14,14 @@ ----------------------- - In ``Preferences->Listener``, activate and configure AETitle and Port (e.g. Osirix 11112) -- In ``Preferences->Locations->DICOMWeb Node``, add a DICOM Node: +- In ``Preferences->Locations->DICOMweb Node``, add a DICOM Node: - with the URL of the Orthanc server - with the DICOMweb API path of Orthanc (default is ``/dicom-web``) - with a name (eg ``MYORTHANC``) - with Q&R activated - without authentication - - with Send Transfers syntax : Explicit Little Endian + - with Send Transfers syntax: Explicit Little Endian Configuration of Orthanc @@ -49,11 +49,11 @@ This section applies if you are using the :ref:`orthancteam/orthanc Docker image <docker-orthancteam>` to run Orthanc. -Make sure Orthanc has the Dicom Web protocol enabled:: +Make sure Orthanc has the DICOMweb protocol enabled:: DICOM_WEB_PLUGIN_ENABLED: "true" -If using Orthanc in a docker container, map the Orthanc DICOMWeb Http Port. Eg in docker-compose file:: +If using Orthanc in a Docker container, map the Orthanc DICOMweb HTTP port. Eg in docker-compose file:: ports: - "8042:8042"
--- a/Sphinx/source/plugins.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins.rst Thu Dec 18 10:44:28 2025 +0100 @@ -68,7 +68,7 @@ :maxdepth: 1 plugins/dicomweb.rst - plugins/worklists-plugin.rst + plugins/worklists-plugin-new.rst plugins/wsi.rst plugins/neuro.rst plugins/stl.rst @@ -121,6 +121,16 @@ plugins/multitenant-dicom.rst plugins/serve-folders.rst plugins/transfers.rst + plugins/pixels-masker.rst + + +Samples +^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + plugins/worklists-plugin.rst .. _plugins-contributed: @@ -160,6 +170,13 @@ `associated description <https://github.com/jodogne/OrthancContributed/tree/master/Plugins/orthanc-mongodb>`__. +* `JPEG-XL Support + <https://github.com/kaitakeradiology/orthanc-jxl/>`__ by Ryan + Walklin: This plugin brings support for the JPEG-XL transfer syntax + for decoding and transcoding. Check out the `initial announcement + <https://discourse.orthanc-server.org/t/jpeg-xl-support-transfer-syntax-decode-and-transcode-plugins/>`__. + + Python plugins ^^^^^^^^^^^^^^
--- a/Sphinx/source/plugins/authorization.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/authorization.rst Thu Dec 18 10:44:28 2025 +0100 @@ -535,7 +535,7 @@ url search params when opening the Orthanc explorer, i.e. ``http://localhost:8042/app/explorer.html?token=1234``. This token will be included as an HTTP header in every request sent to the -Orthanc Rest API. It will also be included in the URL search params +Orthanc REST API. It will also be included in the URL search params when opening the Orthanc or :ref:`Osimis Web viewer <osimis_webviewer>`.
--- a/Sphinx/source/plugins/education.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/education.rst Thu Dec 18 10:44:28 2025 +0100 @@ -7,7 +7,709 @@ .. contents:: +The Education plugin turns Orthanc into a tool for sharing medical +images with students for **educational purposes**. The plugin also +supports the **LTI 1.3 protocol**, allowing integration with Learning +Management Systems such as Moodle. + +The images can be displayed using the **Web viewers** that are +integrated as plugins for Orthanc (i.e., :ref:`Stone Web viewer +<stone_webviewer>`, :ref:`OHIF <ohif>`, and :ref:`Kitware VolView +<volview>`). The plugin also includes support for **virtual +microscopy**: It facilitates the DICOM-ization of whole-slide images +and offers a Web-based viewer through an intuitive interface to the +:ref:`whole-slide imaging primitives <wsi>` of Orthanc. + +The Education plugin requires the version of Orthanc to be above or +equal to 1.12.9. It is released under the AGPL license. Note that this +plugin overwrites the way users are authenticated by Orthanc. + +**Acknowledgments**: + +* This development was partially funded by the `Virtual Hospital grant + <https://www.virtual-hospital.org/>`__ at `Louvain School of + Engineering (EPL) <https://www.uclouvain.be/facultes/epl>`__. + +* The initial exploration of the LTI protocol for Orthanc was carried + out in Python as part of `Florentin Botton's master's thesis + <https://thesis.dial.uclouvain.be/entities/masterthesis/11370371-59e6-4dd4-a24f-c2055df78d8f>`__ + at EPL, under the supervision of Sébastien Jodogne and entitled + *"Medical Imaging Education and Learning Management Systems."* + + Overview -------- -WIP. +The Orthanc plugin supports two modes of operation. The **standalone +mode** allows Orthanc to operate as a Web server for sharing +collections of medical images with learners. In this mode, instructors +can provide learners with a URL linking to a Web page that lists the +images in the collection, allowing them to view the images using their +preferred Web viewer. The following screenshot shows this page: + +.. image:: education/standalone.png + :align: center + :width: 800 + +| + +The second mode of operation integrates Orthanc with a **Learning +Management System (LMS)**, such as Moodle. This integration is +implemented according to the LTI protocol 1.3. Click on the following +image to view a demo video: + +.. image:: education/moodle.jpeg + :align: center + :width: 800 + :target: https://www.youtube.com/watch?v=GD-oPukwxyc + +| + +In this video, the left portion of the screen presents the +administrative interface of the Education plugin, used to associate +medical images with **collections of images** (those collections are +referred to as "projects"). The right portion displays the Moodle user +interface, enabling learners to access the images and open Web viewers +managed by Orthanc. Contrarily to the standalone mode, + +Both modes of operation include a **permission system** ensuring that +learners can only view images they are authorized to +access. Additionally, the Education plugin supports multiple +collections, which can be associated with different instructors. + + +Compilation +----------- + +.. highlight:: bash + +Official releases of the plugin can be `downloaded from the Orthanc +homepage +<https://orthanc.uclouvain.be/downloads/sources/orthanc-education/index.html>`__. As +an alternative, the `repository containing the source code +<https://orthanc.uclouvain.be/hg/orthanc-education/file/default>`__ +can be accessed using Mercurial. + +The procedure to compile this plugin is similar of that for the +:ref:`core of Orthanc <binaries>`. The following commands should work +on most GNU/Linux distributions:: + + $ mkdir Build + $ cd Build + $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release + $ make + +The compilation will produce a shared library +``libOrthancEducation.so`` that contains the Education plugin for +Orthanc. + +Pre-compiled Linux Standard Base (LSB) binaries `are available for +download <https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc-education/index.html>`__. +Pre-compiled binaries for `Microsoft Windows <https://orthanc.uclouvain.be/downloads/windows-64/orthanc-education/index.html>`__ +and `macOS <https://orthanc.uclouvain.be/downloads/macos/orthanc-education/index.html>`__ are available as well. + +Furthermore, the :ref:`Docker images <docker>` +``jodogne/orthanc-plugins`` and ``orthancteam/orthanc`` also contain the +plugin. Debian and Ubuntu packages can be found in the +:ref:`standalone repository <binaries>` +``https://debian.orthanc-labs.com/``. + + +Usage +----- + +This section introduces the various concepts that are necessary to +understand how the Education plugin for Orthanc works. + + +User management +^^^^^^^^^^^^^^^ + +The Education plugin for Orthanc makes the distinction between 3 +categories of users: + +* **Administrators** are responsible for the configuration of Orthanc + and for the management of the collections of medical images + (referred to as "projects"). It is up to the administrators to + **upload the DICOM resources**, to create the projects, to dispatch + the images among the different projects, and to associate projects + with instructors and learners. To this end, administrators have full + access to the administrative interface of the Education plugin, to + the configuration of all of the projects, as well as to both + :ref:`Orthanc Explorer <orthanc-explorer>` and :ref:`Orthanc + Explorer 2 <orthanc-explorer-2>`. + +* **Standard users** represent either instructors or learners. These + users *cannot* modify the configuration of the platform, upload + medical images, or distribute images across projects. Instructors + can modify project-specific settings based on their pedagogical + objectives, such as controlling project visibility or selecting + which viewers are available for a given project. A user may act as + an instructor in certain projects and as a learner in others. For + this reason, the "teacher vs. student" terminology is avoided, as it + implies a fixed role for each user. + +* **Guest users** are users who are not authenticated by the + platform. They behave like learners but can only access projects + with public visibility. This functionality can be used to publish + massive open online courses (MOOCs) in the standalone mode of + operation. + + +User authentication +^^^^^^^^^^^^^^^^^^^ + +The way the Education plugin authenticates administrators and standard +users is specified in the :ref:`configuration file of Orthanc +<configuration>`. The authentication process for administrators can +differ from the one used for standard users. As of release 1.0 of the +Education plugin, the following authentication mechanisms are +available: + +* **Login**. In this case, the Education plugin displays a login page + where the user can enter their credentials, which are specified in + the configuration file. Internally, after a successful login, user + information is stored as a `JWT + <https://en.wikipedia.org/wiki/JSON_Web_Token>`__ session cookie + named ``orthanc-education-user``. + +* **HTTP headers**. In this case, the user identity is determined by + the presence of a specific HTTP header, specified in the + ``AuthenticationHttpHeader`` configuration option. This approach can + be used in the standalone mode of operation, when `single sign-on + (SSO) <https://en.wikipedia.org/wiki/Single_sign-on>`__ is + implemented within an institution. At UCLouvain, this authentication + mode has been validated with `Shibboleth + <https://en.wikipedia.org/wiki/Shibboleth_(software)>`__ in + combination with the ``libapache2-mod-shib`` module, with Apache + acting as a :ref:`reverse proxy <apache>`. Two options are available + for header-based authentication: + + * **Unrestricted**: If the specified HTTP header is present, the + user is authenticated immediately, and the header value is + interpreted as the user identifier. + + * **Restricted**: A user is authenticated only if the HTTP header + value matches one of the allowed entries defined in the + configuration. This option can be used to grant + administrator-level access to a specific subset of users. + +* **None**. In this mode, the login page is displayed, but no user can + log in. This can be used to disable administrator-level access in + order to freeze the platform configuration, or to prevent standard + users from logging in when LTI-based authentication is available. + +* **LTI-based authentication**. This authentication mechanism is + automatically activated when LTI support is enabled for integration + with a Learning Management System (LMS), such as + Moodle. Authentication is then handled through `OIDC-based + authentication <https://www.imsglobal.org/spec/lti/v1p3>`__ + initiated by the LTI platform. The mechanism grants instructor or + learner access to a single project, corresponding to the **deep + link** from which the request originates. The role (instructor or + learner) is determined by the value of the + ``https://purl.imsglobal.org/spec/lti/claim/roles`` field, and the + user identifier is derived from the e-mail address provided by the + LTI platform. Upon successful authentication, user information is + stored in a JWT session cookie named ``orthanc-education-lti``. + +Note that if both the ``orthanc-education-user`` and +``orthanc-education-lti`` cookies are present, login-based +authentication takes precedence, since LTI-based authentication +provides more limited access. + + +.. _education_projects: + +Projects +^^^^^^^^ + +A project is defined as a collection of :ref:`DICOM resources +<dicom-format>`. These resources can be studies, series, or +instances. The same DICOM resource can be shared by multiple projects. +Projects are created and managed by administrators. A project is +defined by the following parameters: + +* The **list of instructors** specifies the standard users who are + permitted to change the project configuration and to review its + stored images before the project is published to the learners. + +* The **list of learners** specifies which standard users are allowed + to view the medical images in the collection. In standalone mode, + learners can choose from a pre-selected set of Web viewers, as + defined by the project instructors. + +* The **access policy** determines which standard users or guest users + are permitted to access the DICOM resources linked to a + project. Three policies are available: + + * **Hidden**: The project is accessible only to its instructors and + to the platform administrators. This allows instructors to prepare + course material before granting students access to the medical + images (for example, when setting up examinations). + + * **Active**: The project becomes accessible to the specified list + of learners. Guest users cannot access the collection. + + * **Public**: The project is accessible to any standard user, as + well as to any guest user. This policy can be used in the context + of MOOCs. + +* The **primary viewer** is the default Web viewer for the project, + whose usage is recommended to learners by the project + instructors. As of release 1.0, the following viewers are recognized + by the Education plugin: :ref:`Stone Web viewer <stone_webviewer>`, + :ref:`OHIF <ohif>`, :ref:`Kitware VolView <volview>`, and + :ref:`Whole-slide imaging <wsi>`. + +* The **secondary viewers** are a list of additional viewers that may + be useful to learners alongside the primary viewer. + +* **LTI context ID**: When the Education plugin is used with a + Learning Management System (LMS) such as Moodle, this parameter + specifies the identifier of the course in the LTI platform. Deep + links in the LMS course can only be created to the project whose LTI + context ID matches this course. + +Here is a screenshot of how projects can be configured in the +administrative interface of the Education plugin: + +.. image:: education/projects-1.png + :align: center + :width: 800 + +The individual parameters of a project look as follows: + +.. image:: education/projects-2.png + :align: center + :width: 500 + +| + + +.. _education_content: + +Collection of images +^^^^^^^^^^^^^^^^^^^^ + +The Education plugin offers an administrative interface for **linking +DICOM resources** to the collection of medical images associated with +each project: + +.. image:: education/images.png + :align: center + :width: 800 + +Various filters are available to help identify DICOM resources that +are not yet assigned to any project. The association of DICOM studies, +series, and instances to projects is implemented internally using the +:ref:`labels feature of Orthanc <labels>`. + +The **content of individual projects** can be inspected as well: + +.. image:: education/content.png + :align: center + :width: 800 + +Besides allowing access to the medical images in the collection, this +page provides three important pieces of information highlighted in +red: + +* The **Orthanc label** that is used to associate DICOM resources with + the project. Consequently, as an alternative to the built-in + administrative interface of the Education plugin, :ref:`Orthanc + Explorer <orthanc-explorer>` or :ref:`Orthanc Explorer 2 + <orthanc-explorer-2>` can be used to link or unlink images with the + project by **manually editing the labels** of the DICOM resources of + interest. Note that the built-in interface only supports the + association of studies and series. If you need to link a **DICOM + instance** to a project, you must manually edit the labels. + +* The **URL to access the content** of the project by instructors, + learners, or guest users (if the project is public). + +* An edit box is provided to facilitate adding an image to the project + while it is being reviewed in one of the Web viewers supported by + Orthanc. To do so, simply **paste the URL of the viewer**. This + necessitates the ``PublicRoots`` configuration option to include the + base URL of the Orthanc instance. + + +.. _education_learners: + +Access to learners +^^^^^^^^^^^^^^^^^^ + +After authentication, non-administrator users are redirected to a Web +page giving access to all projects for which they appear on the list +of learners: + +.. image:: education/learner.png + :align: center + :width: 800 + +**Guest users** also have access to this page, but only see the +projects with a public access policy. + +If the authenticated standard user is also an **instructor of the +project**, this user can modify some parameters of the project (i.e., +its access policy, its primary viewer, and its list of secondary +viewers). + +By default, this page lists all the projects that are available to the +user. This behavior can be disabled by setting the configuration +option ``ListProjectsAsLearner`` to ``false``. In this case, the +instructor will have share the URL tagged as *"Access by instructors +and learners"* in the :ref:`page listing the content of the project +<education_content>`. + + +Virtual microscope +^^^^^^^^^^^^^^^^^^ + +An important use case of the Education plugin for Orthanc is to +provide a **virtual microscope** for teaching histology and digital +pathology. This use case takes advantage of the :ref:`whole-slide +imaging <wsi>` support implemented by the Orthanc project. +DICOM-ization is accessible from the administrative interface +of the Education plugin: + +.. image:: education/dicomization.png + :align: center + :width: 800 + +| + +This interface is only accessible if the +``WholeSlideImagingDicomizer`` configuration option contains the path +to the ``OrthancWSIDicomizer`` command-line tool from the +:ref:`whole-slide imaging framework of Orthanc <wsi>`. Once the upload +is done, the page named *"Upload status"* provides the status of the +DICOM-ization, including the logs of the command-line tool. + +Some proprietary formats (such as MRXS or NDPI) requires the +DICOM-ization command-line tool to use the `OpenSlide library +<https://openslide.org/>`__. In this case, the ``OpenSlideLibrary`` +configuration option must contain the path to the ``openslide.so`` +(GNU/Linux) or ``openslide.dll`` (Microsoft Windows) shared library. + +To associate a DICOM-ized whole-slide image with a project, make sure +to associate the DICOM series in the :ref:`content of the project +<education_content>` (*not* the DICOM study). Indeed, the whole-slide +imaging viewer only works at the instance or series level. + +Note that future releases may include DICOM-ization of additional +types of images (e.g., :ref:`3D models <stl-plugin>`, PNG or JPEG +images,...). + +Configuration file +------------------ + +Generic configuration +^^^^^^^^^^^^^^^^^^^^^ + +.. highlight:: json + +To enable the Education plugin, the :ref:`configuration file +<configuration>` must contain a specific section named ``Education``:: + + { + "Plugins" : [ + "${HOME}/Downloads/libOrthancEducation.so" + ], + "Education" : { + /* Generic options */ + "Enabled" : true, + "PublicRoots" : [ + "http://localhost:8042" /* Public base URL where the Orthanc Web server is mapped */ + ], + "ListProjectsAsLearner" : true, + + /* Options for the virtual microscope */ + "WholeSlideImagingDicomizer" : "${HOME}/Downloads/OrthancWSIDicomizer", + "OpenSlideLibrary" : "libopenslide.so", + + /* ...other options... */ + } + } + +If you want to use :ref:`Orthanc Explorer 2 <orthanc-explorer-2>` +together with the Education plugin, make sure to disable its default +behavior that sets it as the default Web interface of Orthanc:: + + { + /* ... */ + "OrthancExplorer2" : { + "IsDefaultOrthancUI": false + } + } + + +Login-based deployments +^^^^^^^^^^^^^^^^^^^^^^^ + +Here is a possible configuration for a **standalone deployment** of +the Education plugin using a login page:: + + { + /* ... */ + "Education" : { + /* ... */ + "AuthenticationHttpHeader" : "Mail", + "Administrators" : { + "Authentication" : "Login", + "Credentials" : { + "admin" : "pass1" + } + }, + "StandardUsers" : { + "Authentication" : "Login", + "Credentials" : { + "instructor" : "pass2", + "learner" : "pass3" + } + } + } + } + +This configuration defines one administrator (whose identifier is +``admin``) and two standard users (with identifiers ``instructor`` and +``learner``). Because their passwords are hard-coded, the +configuration file must not be publicly accessible. + +All the requests requiring an authentication will be redirected to the +login page. The page with the :ref:`list of projects for learners +<education_learners>` is reachable without login, allowing guest users +to access public projects (e.g., in the context of MOOCs). + + +Deployments with HTTP headers (SSO) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here is a possible configuration for a **standalone deployment** of +the Education plugin behind a `single sign-on (SSO) +<https://en.wikipedia.org/wiki/Single_sign-on>`__ infrastructure:: + + { + /* ... */ + "Education" : { + /* ... */ + "Administrators" : { + "Authentication" : "RestrictedHttpHeader", + "RestrictedHeaders" : [ + "admin@uclouvain.be" + ] + }, + "StandardUsers" : { + "Authentication" : "RestrictedHttpHeader", + "RestrictedHeaders" : [ + "instructor@uclouvain.be", + "learner@uclouvain.be" + ] + } + } + } + +This configuration authenticates administrators and standard users +based on the presence of the ``Mail`` HTTP header, which must be set +by the SSO infrastructure. In this example, there is one administrator +(``admin@uclouvain.be``) and two standard users +(``instructor@uclouvain.be`` and ``learner@uclouvain.be``). If the +``Mail`` header matches none of those e-mails, the authentication +results in the guest user. + +Evidently, you can emulate a SSO infrastructure by putting a reverse +proxy (e.g., :ref:`nginx <nginx>` or :ref:`Apache <apache>`) in front +of Orthanc, asking the reverse proxy to automatically set some HTTP +header (cf. ``proxy_set_header`` if nginx is used). + +When handling large cohorts of learners, it is not practical to list +all of them in the configuration files. In this case, the +``Authentication`` option for standard users can be set to +``HttpHeader``:: + + { + /* ... */ + "Education" : { + /* ... */ + "AuthenticationHttpHeader" : "Mail", + "Administrators" : { + "Authentication" : "RestrictedHttpHeader", + "RestrictedHeaders" : [ + "admin@uclouvain.be" + ] + }, + "StandardUsers" : { + "Authentication" : "HttpHeader" + } + } + } + +When this option is enabled, any HTTP request containing the ``Mail`` +header is authenticated as a standard user. The value of the ``Mail`` +header defines the user identity. + + +.. _education_lti: + +LTI deployments +^^^^^^^^^^^^^^^ + +Here is the recommended configuration file to integrate the Education +plugin with a Learning Management Systems such as Moodle:: + + { + /* ... */ + "RemoteAccessAllowed" : true, + "Education" : { + /* ... */ + "Administrators" : { + "Authentication" : "Login", + "Credentials" : { + "admin" : "pass" + } + }, + "StandardUsers" : { + "Authentication" : "None" + }, + "LTI": { + "Enabled": true, + "OrthancUrl" : "https://lti.local:5000", + "PlatformUrl" : "http://moodle.local:8100" + }, + "PublicRoots" : [ + "https://lti.local:5000" + ] + } + } + +In this configuration, the administrator is authenticated through a +login page. Standard users are not authenticated by the mechanisms +provided by the Education plugin (hence the ``None`` value), but +instead through the primitives defined by the `LTI 1.3 protocol +<https://www.imsglobal.org/spec/lti/v1p3>`__. + +In this case, Orthanc must also be explicitly provided with its own +public base URL (``https://lti.local:5000``) and the base URL of the +LMS (``http://moodle.local:8100``). This information is used to verify +the security of the bidirectional communication between Orthanc and +the LMS through the LTI protocol. + +Once Orthanc is running, you can configure the LMS platform. In this +section, we use Moodle as an example, as it is the only LMS that has +been tested with release 1.0 of the Education plugin. The screenshots +below are taken from the `video illustrating the configuration steps +<https://www.youtube.com/watch?v=GD-oPukwxyc>`__. Open the +configuration interface of external tools in Moodle: + +.. image:: education/lti-1.jpeg + :align: center + :width: 800 + +Then click on the *"Add LTI Advantage"* button with the +``https://lti.local:5000/education/lti/register`` URL. Evidently, you +will have to adapt this URL with the public root of your Orthanc +server. This results in the addition of the tool: + +.. image:: education/lti-2.jpeg + :align: center + :width: 256 + +If you edit the configuration of this newly added external tool (by +clicking on the pen icon), you see all the parameters that have been +automatically negotiated between Orthanc and Moodle: + +.. image:: education/lti-4.jpeg + :align: center + :width: 800 + +An important piece of information is the *"LTI Client ID"*, which +should also have been filled on the *"Settings"* page of the +administrative interface of the Education plugin in Orthanc. + +For best operation, it is necessary to manually change the default +values of the *"Tool configuration usage"* and "*Default launch +container*" as follows: + +.. image:: education/lti-3.jpeg + :align: center + :width: 600 + +You can then click on the *"Activate"* button to make the "Orthanc for +Education" external tool available in the Moodle courses. + +The LTI context ID for the :ref:`configuration of the project +<education_projects>` can be retrieved by copying the identifier of +the course from the URL of the course in Moodle: + +.. image:: education/lti-5.jpeg + :align: center + :width: 600 + + + + +Other options +^^^^^^^^^^^^^ + +Note that it is always recommended to enable :ref:`HTTPS encryption in +Orthanc <https>` for security reasons, especially for :ref:`LTI +deployments <education_lti>`. Some additional security-related options +are available in the Education plugin:: + + { + /* ... */ + "Education" : { + /* ... */ + "MaxLoginAge" : 3600, /* After how many seconds login-based authentication expires */ + "SecureCookies" : true, /* Whether cookies are tagged as "Secure", only set to "false" for debugging */ + } + } + + +Troubleshooting +--------------- + +Several problems can be encountered if using LTI integration with +Moodle: + +* **Error 400** with message ``"Missing field: \"id_token\""`` during the creation of a deep link. + + **Explanation**: This means that the *"LTI Client ID"* in the + settings of the Education plugin is out of sync with the Moodle + configuration. + + **Resolution**: Modify the settings in Orthanc, or reinstall the + "Orthanc for Education" external from scratch. + +* **Error 500** with message ``"Unknown LTI context ID"`` during the creation of a deep link. + + **Explanation**: This means that the Moodle course has not been + correctly associated with a project in the Orthanc Education plugin. + + **Resolution**: Edit the project settings in Orthanc, and + appropriately set the field *"LTI context ID"*. + +* Moodle shows the following error during the creation of a deep link: + ``"Exception - mod_lti\local\ltiopenid\jwks_helper::fix_jwks_alg(): + Argument #1 ($jwks) must be of type array, null given, called in + [dirroot]/mod/lti/locallib.php"`` + + **Explanation**: This means that the cURL library used by Moodle is + not allowed to contact the Orthanc Web server, notably the route + that provides the OIDC JSON web key (JWK) endpoint (in our example, + ``https://lti.local:5000/education/lti/jwks``). + + **Resolution**: + + * Make sure that the domain name used by Orthanc (in our example, + ``lti.local``) is secured by a valid HTTPS certificate, and that + the HTTPS certificate is trusted by the machine running Moodle. + + * Make sure that the security settings of Moodle (in our example, + those settings are accessible at + ``http://moodle.local:8100/admin/settings.php?section=httpsecurity``) + allow to contact the TCP port on which Orthanc is listening (in + our example, the port is ``5000``, but by default it would be + ``8042``), and to contact the IP address on which Orthanc is + installed.
--- a/Sphinx/source/plugins/java.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/java.rst Thu Dec 18 10:44:28 2025 +0100 @@ -18,7 +18,7 @@ Java applications for Orthanc have access to more features and a more consistent SDK than :ref:`Lua scripts <lua>`. The largest part of the Java API is automatically generated from the `Orthanc plugin SDK in C -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler front-end.
--- a/Sphinx/source/plugins/object-storage.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/object-storage.rst Thu Dec 18 10:44:28 2025 +0100 @@ -107,6 +107,8 @@ "StorageEncryption" : {}, // optional: see the section related to encryption "HybridMode": "Disabled", // optional: see the section related to Hybrid storage "UseTransferManager": false, // optional: see below (available from version 2.3.0) + "TransferPoolSize": 10, // optional: see below (available from version 2.3.0) + "TransferBufferSize": 5, // optional: see below (available from version 2.3.0) "EnableAwsSdkLogs": false, // optional: include AWS SDK logs in Orthanc logs "StorageClass": "STANDARD" // optional: see below (available from version 2.5.0) } @@ -124,6 +126,7 @@ The **UseTransferManager** configuration is used to select the `Transfer Manager <https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/examples-s3-transfermanager.html>`__ mode in the AWS SDK client. This option was introduced in version 2.3.0. If set to false (default value), the default "object" mode is used. +The **TransferPoolSize** and **TransferBufferSize** configurations can be used to fine tune the Transfer Manager mode. The **StorageClass** configuration is used to select the `Storage Class <https://aws.amazon.com/s3/storage-classes/>`__ of the uploaded files. This option was introduced in version 2.5.0. Allowed values are ``"STANDARD", "REDUCED_REDUNDANCY", "STANDARD_IA", "ONEZONE_IA", @@ -264,7 +267,7 @@ When the ``HybridMode`` is set to ``WriteToObjectStorage``, it is useful to move file from the file system to the object storage to perform a full data migration to object-storage. -To move files from one storage to the other, you should call the plugin Rest API:: +To move files from one storage to the other, you should call the plugin REST API:: $ curl -X POST http://localhost:8042/move-storage \ --data '{
--- a/Sphinx/source/plugins/orthanc-explorer-2.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/orthanc-explorer-2.rst Thu Dec 18 10:44:28 2025 +0100 @@ -105,7 +105,7 @@ Since version 0.6.0, it is possible to edit some of the DICOM Tags directly in the User Interface. :ref:`DICOM Modification <anonymization>` is quite a complex topic that is provided by Orthanc -Rest API. The Orthanc Explorer 2 User Interface aims at simplifying its use but is also limiting +REST API. The Orthanc Explorer 2 User Interface aims at simplifying its use but is also limiting it to common use cases mainly related to correcting errors in Patient and Study DICOM Tags. At study level, it is possible to:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/plugins/pixels-masker.rst Thu Dec 18 10:44:28 2025 +0100 @@ -0,0 +1,157 @@ +.. _pixels-masker-plugin: + + +Pixels Masker plugin +==================== + +.. contents:: + +This page describes a plugin that extends the ``/modify`` and ``/anonymize`` +REST API routes enabling masking of pixels in the image. + +.. Disclaimer:: + This plugin is very low-level and does not detect the area to masks. + This plugin does not have a UI; it is only available through the REST API. + + +Configuration +------------- + +.. highlight:: json + +Here's a sample configuration section for this plugin with its default values:: + + { + "PixelsMasker": { + + // Enables/disables the plugin + "Enable": false + } + + +REST API +-------- + +The plugins does not replace the default ``/modify`` and ``/anonymize`` API routes but provides new +variants at: + +- ``/plugins/pixels-masker/studies/../modify`` +- ``/plugins/pixels-masker/studies/../anonymize`` +- ``/plugins/pixels-masker/series/../modify`` +- ``/plugins/pixels-masker/series/../anonymize`` +- ``/plugins/pixels-masker/instances/../modify`` +- ``/plugins/pixels-masker/instances/../anonymize`` + + +These are the additional fields that can be added to regular ``/modify`` and ``/anonymize`` payloads:: + + { + "MaskPixelData" : { + "Regions": [ + { + "MaskType": "MeanFilter", + "FilterWidth": 20, + "RegionType" : "2D", // area is defined by an area in pixel coordinates + "Origin": [150, 100], // X, Y in pixel coordinates + "End": [400, 200], // X, Y in pixel coordinates + "TargetSeries" : [ // the series the pixel mask applies to. If empty -> applies to all series + "cd589a09-6e705e06-57997219-7812eb49-709873a9" + ], + "TargetInstances" : [ // the instances the pixel mask applies to. If empty -> applies to all instances + ] + }, + { + "MaskType": "Fill", + "FillValue": 0, + "RegionType" : "3D", // area is defined by a volume in world coordinates + "Origin": [-150.5, -250.4, -811], // X, Y, Z in World coordinates + "End": [148.4, 220.7, -955], // X, Y, Z in World coordinates + "TargetSeries" : [ // in this mode, no need to list the instances since the Z coordinate shall handle that ! + "94df9100-3b476f5b-f4e8c381-d78c327f-a387bc7e" + ] + } + ] + } + } + + +Here's a sample REST API call to mask the pixels with a constant value in a 3D image:: + + $ curl -X POST http://localhost:8042/plugins/pixels-masker/studies/321d3848-40c81c82-49f6f235-df6b1ec7-ed52f2fa/modify \ + --data-binary '{ + "Replace" : { + "StudyInstanceUID": "1.2.3", + "StudyDescription": "Filled Area" + }, + "Force": true, + "MaskPixelData": { + "Regions": [{ + "MaskType": "Fill", + "FillValue": 0, + "RegionType" : "3D", + "Origin": [-150.0, -300, -750], + "End": [150.0, -250, -1000] + }] + } + }' + +.. image:: ../images/pixels-masker-fill-face.png + :align: center + :width: 250px + + +And the same request to apply a mean filter on the same area:: + + $ curl -X POST http://localhost:8042/plugins/pixels-masker/studies/321d3848-40c81c82-49f6f235-df6b1ec7-ed52f2fa/modify \ + --data-binary '{ + "Replace" : { + "StudyInstanceUID": "1.2.4", + "StudyDescription": "Mean Filter" + }, + "Force": true, + "MaskPixelData": { + "Regions": [{ + "MaskType": "MeanFilter", + "FilterWidth": 30, + "RegionType" : "3D", + "Origin": [-150.0, -300, -750], + "End": [150.0, -250, -1000] + }] + } + }' + +.. image:: ../images/pixels-masker-mean-filter-30-face.png + :align: center + :width: 250px + +Here is a request to apply multiple 2D masks on an US series:: + + $ curl -X POST http://localhost:8042/plugins/pixels-masker/series/4583e108-24b5e113-2be9a691-7183e535-902578c7/modify \ + --data-binary '{ + "Replace" : { + "StudyInstanceUID": "1.2.5", + "StudyDescription": "Masked US" + }, + "Force": true, + "MaskPixelData": { + "Regions": [{ + "MaskType": "MeanFilter", + "FilterWidth": 20, + "RegionType" : "2D", + "Origin": [0, 0], + "End": [400, 60] + }, { + "MaskType": "Fill", + "FillValue": 100, + "RegionType" : "2D", + "Origin": [1080, 0], + "End": [1380, 60] + }] + } + }' + +.. image:: ../images/pixels-masker-us.png + :align: center + :width: 400px + +
--- a/Sphinx/source/plugins/postgresql.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/postgresql.rst Thu Dec 18 10:44:28 2025 +0100 @@ -74,8 +74,8 @@ "HousekeepingInterval": 1, // New in release 7.0 "AllowInconsistentChildCounts": false, // New in release 7.2 "UseDynamicConnectionPool": false, // New in release 9.0 - "Schema": "public", // New in release 9.0+ (not released yet) - "ApplicationName": "", // New in release 9.0+ (not released yet) + "Schema": "public", // New in release 10.0 + "ApplicationName": "", // New in release 10.0 }, "Plugins" : [ "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLIndex.so", @@ -201,7 +201,7 @@ and ``ReadCommitted`` that is available only from release 6.0 and is the default value starting from version 7.0. See below. -* ``Schema`` has been added in the release 9.0+ (not released yet). By default, +* ``Schema`` has been added in the release 10.0. By default, Orthanc uses the ``public`` default schema. If you wish to use another schema, you must create it before starting Orthanc; Orthanc will not create it. Note that Orthanc might try to install the ``pg_trgm`` extension in the ``public`` @@ -210,7 +210,7 @@ Internals: plugin calls ``SET search_path TO $schema`` when opening a new connection to the DB. -* ``ApplicationName`` has been added in the release 9.0+ (not released yet). +* ``ApplicationName`` has been added in the release 10.0. This value is copied in the ``application_name`` argument in the connection string. This name is used to identify the origin of queries in statistics and logs in the PostgreSQL server. @@ -338,14 +338,22 @@ +---------------------------+-------------------------------------------+ | 9.0 | 6 | +---------------------------+-------------------------------------------+ +| 10.0 | 10 (skipped 7, 8 and 9 to sync schema | +| | revision and plugin version) | ++---------------------------+-------------------------------------------+ Upgrades from one revision to the other is always automatic. Furthermore, if you are upgrading -from e.g plugin 3.3 to 9.0, Orthanc will apply all migration steps autonomously. +from e.g plugin 3.3 to 10.0, Orthanc will apply all migration steps autonomously. However, if, for some reasons, you would like to reinstall a previous plugin version, the older plugin might refuse to start because the revision is newer and unknown to it. +To downgrade from revision 10 to revision 6, one might run this procedure:: + + $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/Downgrades/Rev10ToRev6.sql + $ psql -U postgres -f Rev10ToRev6.sql + To downgrade from revision 6 to revision 5, one might run this procedure:: $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/Downgrades/Rev6ToRev5.sql @@ -396,12 +404,14 @@ $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/Upgrades/Rev3ToRev4.sql $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/Upgrades/Rev4ToRev5.sql $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/Upgrades/Rev5ToRev6.sql + $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/Upgrades/Rev6ToRev10.sql $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/PrepareIndex.sql $ psql -U postgres -f Rev1ToRev2.sql # skip this step if you are already in Rev2 or higher $ psql -U postgres -f Rev2ToRev3.sql # skip this step if you are already in Rev3 or higher $ psql -U postgres -f Rev3ToRev4.sql # skip this step if you are already in Rev4 or higher $ psql -U postgres -f Rev4ToRev5.sql # skip this step if you are already in Rev5 or higher - $ psql -U postgres -f Rev5ToRev6.sql + $ psql -U postgres -f Rev5ToRev6.sql # skip this step if you are already in Rev6 or higher + $ psql -U postgres -f Rev6ToRev10.sql $ psql -U postgres -f PrepareIndex.sql These procedures are identical to the ones performed automatically by Orthanc when it detects that an upgraded is required. @@ -414,7 +424,7 @@ - Upgrade from revision 2 to revision 3: around 7 minutes. - Upgrade from revision 3 to revision 5: immediate. - Upgrade from revision 5 to revision 6: around 22 minutes. -- Then, after upgrading to revision 6, the ``DB HOUSEKEEIPING`` task needs to update some ``ChildCount`` entries. +- Then, after upgrading to revision 6, the ``DB HOUSEKEEPING`` task needs to update some ``ChildCount`` entries. This is performed while Orthanc is running and accessible and 50 entries are updated every second and this must be performed for every series, study and patient. With a DB with 350.000 studies, this took around 50 hours.
--- a/Sphinx/source/plugins/python.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/python.rst Thu Dec 18 10:44:28 2025 +0100 @@ -30,7 +30,7 @@ Python plugins have access to more features and a more consistent SDK than :ref:`Lua scripts <lua>`. The largest part of the Python API is automatically generated from the `Orthanc plugin SDK in C -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler front-end. @@ -373,10 +373,10 @@ call ``RestApiPostAfterPlugin`` to call the REST API from plugins. -Note however, that, as of Orthanc 1.12.9, the Orthanc plugin SDK +Note however, that, as of Orthanc 1.12.10, the Orthanc plugin SDK does not support multiple plugins implementing the same route. Orthanc will actually accept e.g a Python plugin that overrides -a DICOMWeb route but it is impossible to tell which route +a DICOMweb route but it is impossible to tell which route will be called in the end since this depends on the registration order of the plugins that is not deterministic. @@ -702,12 +702,11 @@ Starting with release 3.2 of the Python plugin, it is possible to replace the C-FIND SCP and C-MOVE SCP of Orthanc by a Python script. This feature can notably be used to create a custom DICOM -proxy. Here is a minimal example: +proxy. Here is a minimal example for a C-Find handler: -.. literalinclude:: python/dicom-find-move-scp.py +.. literalinclude:: python/dicom-find-scp.py :language: python - .. highlight:: text In this sample, the C-FIND SCP will send one single answer that @@ -730,38 +729,19 @@ Orthanc using ``orthanc.RestApiPost()``, in order to query the content a remote modality through a second C-FIND SCU request (this time issued by Orthanc as a SCU). + +Here is a minimal example for a C-Move handler: + +.. literalinclude:: python/dicom-move-scp.py + :language: python + The C-MOVE SCP can be invoked as follows:: $ movescu localhost 4242 -aem TARGET -aec SOURCE -aet MOVESCU -S -k QueryRetrieveLevel=IMAGE -k StudyInstanceUID=1.2.3.4 -The C-MOVE request above would print the following information in the -Orthanc logs:: - W0610 18:30:36.840865 PluginsManager.cpp:168] C-MOVE request to be handled in Python: { - "AccessionNumber": "", - "Level": "INSTANCE", - "OriginatorAET": "MOVESCU", - "OriginatorID": 1, - "PatientID": "", - "SOPInstanceUID": "", - "SeriesInstanceUID": "", - "SourceAET": "SOURCE", - "StudyInstanceUID": "1.2.3.4", - "TargetAET": "TARGET" - } - -It is now up to your Python callback to process the C-MOVE SCU request, -for instance by calling the route ``/modalities/{...}/store`` in the -:ref:`REST API <rest-store-scu>` of Orthanc using -``orthanc.RestApiPost()``. It is highly advised to create a Python -thread to handle the request, in order to avoid blocking Orthanc as -much as possible. - - -**Note:** In version 4.2, we have introduced a new version of the C-MOVE SCP -handler that can be registered through ``orthanc.RegisterMoveCallback2(CreateMoveCallback, GetMoveSizeCallback, ApplyMoveCallback, FreeMoveCallback)``. -This `DICOM to DICOMWeb proxy sample project <https://github.com/orthanc-team/dicom-dicomweb-proxy/blob/main/proxy.py>`__ demonstrates how it can be used. +**Note:** A full sample is available in this `DICOM to DICOMweb proxy sample project <https://github.com/orthanc-team/dicom-dicomweb-proxy/blob/main/proxy.py>`__. .. _python_worklists: @@ -962,7 +942,7 @@ * The call to ``orthanc.ExtendOrthancExplorer()`` installs the button with JavaScript code that uses the `jQuery Mobile framework - <https://demos.jquerymobile.com/1.1.0/>`__ (as of Orthanc 1.12.9, + <https://demos.jquerymobile.com/1.1.0/>`__ (as of Orthanc 1.12.10, version 1.1.0 of jQuery Mobile is used in Orthanc Explorer). * If clicking on the button, a GET call to the REST API is made to @@ -1011,7 +991,7 @@ .. _python_set_stable_status: Changing the Stable status of a resource (new in 6.0) -................................... +..................................................... Starting from v 6.0, it is possible to change the ``Stable`` status of a resource without waiting for the stabilization time defined by the ``StableAge`` @@ -1022,7 +1002,7 @@ :language: python Using Key-Value Stores and Queues (new in 6.0) -................................... +.............................................. Starting from v 6.0, it is possible to store messages in queues that are stored in the Orthanc DB or to store values in Key-Value Stores that are also stored in DB.
--- a/Sphinx/source/plugins/python/dicom-find-move-scp.py Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/python/dicom-find-move-scp.py Thu Dec 18 10:44:28 2025 +0100 @@ -2,6 +2,9 @@ import orthanc import pprint +# this file is not referenced anymore in the book but is still used by Sébastien's +# release procedure when releasing the python plugin -> don't remove ! + def OnFind(answers, query, issuerAet, calledAet): print('Received incoming C-FIND request from %s:' % issuerAet)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/plugins/python/dicom-find-scp.py Thu Dec 18 10:44:28 2025 +0100 @@ -0,0 +1,25 @@ +import json +import orthanc + + +def OnFind(answers, query, connection): # new from v 7.0: issuerAet and calledAet are available from the connection object + print('Received incoming C-FIND request from %s %s %s:' % (connection.GetConnectionRemoteAet(), connection.GetConnectionRemoteIp(), connection.GetConnectionCalledAet())) + + # old prototype still available + # def OnFindLegacy(answers, query, issuerAet, calledAet): + # print('Received incoming C-FIND request from %s:' % issuerAet) + + answer = {} + for i in range(query.GetFindQuerySize()): + print(' %s (%04x,%04x) = [%s]' % (query.GetFindQueryTagName(i), + query.GetFindQueryTagGroup(i), + query.GetFindQueryTagElement(i), + query.GetFindQueryValue(i))) + answer[query.GetFindQueryTagName(i)] = ('HELLO%d-%s' % (i, query.GetFindQueryValue(i))) + + answers.FindAddAnswer(orthanc.CreateDicom( + json.dumps(answer), None, orthanc.CreateDicomFlags.NONE)) + +orthanc.RegisterFindCallback2(OnFind) # new from v 7.0 +#orthanc.RegisterFindCallback(OnFindLegacy) # old version, still available +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/plugins/python/dicom-move-scp.py Thu Dec 18 10:44:28 2025 +0100 @@ -0,0 +1,82 @@ +import json +import orthanc +import pprint + +def OnMoveBasic(**request): + orthanc.LogWarning('C-MOVE request to be handled in Python: %s' % + json.dumps(request, indent = 4, sort_keys = True)) + + # The C-MOVE request above would print the following information in the + # Orthanc logs:: + + # W0610 18:30:36.840865 PluginsManager.cpp:168] C-MOVE request to be handled in Python: { + # "AccessionNumber": "", + # "Level": "INSTANCE", + # "OriginatorAET": "MOVESCU", + # "OriginatorID": 1, + # "PatientID": "", + # "SOPInstanceUID": "", + # "SeriesInstanceUID": "", + # "SourceAET": "SOURCE", + # "StudyInstanceUID": "1.2.3.4", + # "TargetAET": "TARGET" + # } + + # To indicate a failure in the processing, one can raise an exception: + # raise Exception('Cannot handle C-MOVE') + + # It is now up to your Python callback to process the C-MOVE SCU request, + # for instance by calling the route /modalities/{...}/store. + + +# More advanced Move driver, providing progress reporting to the MOVE SCU originator and +# providing more information about the DicomConnection. +# For a full sample, see https://github.com/orthanc-team/dicom-dicomweb-proxy/blob/main/proxy.py +class MoveDriver: + + def __init__(self, request, connection) -> None: + self.request = request # dictionnary containing the C-MOVE request e.g: { + # "AccessionNumber": "", + # "Level": "INSTANCE", + # "OriginatorID": 1, + # "PatientID": "", + # "SOPInstanceUID": "", + # "SeriesInstanceUID": "", + # "StudyInstanceUID": "1.2.3.4", + # "TargetAET": "TARGET" + # } + + # connection.GetConnectionCalledAet() is equivalent to request["SourceAET"] in older versions of the callback + # connection.GetConnectionRemoteAet() is equivalent to request["OriginatorAET"] in older versions of the callback + # connection.GetConnectionRemoteIp() is new in v 7.0 + + self.instances_ids_to_transfer = [] # TODO: build a list of instances to transfer from the query + self.instance_counter = 0 + + +def CreateMoveCallback(connection, **request): # from v 7.0; to use with orthanc.RegisterMoveCallback3() + # simply create the move driver object now and return it to Orthanc + orthanc.LogInfo("CreateMoveCallback") + driver = MoveDriver(request=request, connection=connection) + return driver + +def GetMoveSizeCallback(driver: MoveDriver): + # query the remote server to list and count the instances to retrieve + orthanc.LogInfo("GetMoveSizeCallback") + return len(driver.instances_ids_to_transfer) + +def ApplyMoveCallback(driver: MoveDriver): + # move one instance at a time + orthanc.LogInfo("ApplyMoveCallback") + instance_id = driver.instances_ids_to_transfer[driver.instance_counter] + driver.instance_counter += 1 + # TODO store the instance in the destination + return orthanc.ErrorCode.SUCCESS + +def FreeMoveCallback(driver): + # free the resources that have been allocated by the move driver - if any + orthanc.LogInfo("FreeMoveCallback") + + +orthanc.RegisterMoveCallback3(CreateMoveCallback, GetMoveSizeCallback, ApplyMoveCallback, FreeMoveCallback) +# orthanc.RegisterMoveCallback(OnMoveBasic)
--- a/Sphinx/source/plugins/python/extending-rest-api-2.py Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/python/extending-rest-api-2.py Thu Dec 18 10:44:28 2025 +0100 @@ -18,7 +18,7 @@ instances = orthanc.RestApiGet(uri) output.AnswerBuffer(instances, "application/json") -# reimplement a DICOMWeb /studies/../metadata route +# reimplement a DICOMweb /studies/../metadata route def OnDicomWebStudiesMetadata(output, uri, **request): orthanc.LogWarning("My DICOMWEB /studies/../metadata") @@ -39,8 +39,8 @@ orthanc.RegisterRestCallback('/instances', OnInstances) # The code below should be avoided since you actually don't know which route will finally be called: -# the one from the DICOMWeb plugin or the one from this python plugin +# the one from the DICOMweb plugin or the one from this python plugin # orthanc.RegisterRestCallback('/dicom-web/studies/(.*)/metadata', OnDicomWebStudiesMetadata) -# Therefore, you should use another base route to differentiate it from the DICOMWeb plugin route +# Therefore, you should use another base route to differentiate it from the DICOMweb plugin route orthanc.RegisterRestCallback('/my-dicom-web/studies/(.*)/metadata', OnDicomWebStudiesMetadata)
--- a/Sphinx/source/plugins/python/queues-and-kvs.py Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/python/queues-and-kvs.py Thu Dec 18 10:44:28 2025 +0100 @@ -10,6 +10,8 @@ def ProcessQueueMessages(): global is_worker_running + orthanc.SetCurrentThreadName("QUEUE-PROC") + while is_worker_running: # get messages from the queue named "instances-to-process" that is stored in Orthanc DB. # Get the message from the FRONT for FIFO and from the BACK for a LIFO
--- a/Sphinx/source/plugins/python/storage-commitment-default.py Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/python/storage-commitment-default.py Thu Dec 18 10:44:28 2025 +0100 @@ -3,11 +3,18 @@ # this plugins provides the same behavior as the default Orthanc implementation -def StorageCommitmentScpCallback(jobId, transactionUid, sopClassUids, sopInstanceUids, remoteAet, calledAet): +# new callback format from v 7.0; to use with RegisterStorageCommitmentScpCallback2 +def StorageCommitmentScpCallback(jobId, transactionUid, sopClassUids, sopInstanceUids, connection): # At the beginning of a Storage Commitment operation, you can build a custom data structure # that will be provided as the "data" argument in the StorageCommitmentLookup return None +# old prototype to use with RegisterStorageCommitmentScpCallback +# def StorageCommitmentScpCallback(jobId, transactionUid, sopClassUids, sopInstanceUids, remoteAet, calledAet): +# # At the beginning of a Storage Commitment operation, you can build a custom data structure +# # that will be provided as the "data" argument in the StorageCommitmentLookup +# return None + # Reference: `StorageCommitmentScpJob::Lookup` in `OrthancServer/Sources/ServerJobs/StorageCommitmentScpJob.cpp` def StorageCommitmentLookup(sopClassUid, sopInstanceUid, data): @@ -31,4 +38,5 @@ return reason -orthanc.RegisterStorageCommitmentScpCallback(StorageCommitmentScpCallback, StorageCommitmentLookup) \ No newline at end of file +orthanc.RegisterStorageCommitmentScpCallback2(StorageCommitmentScpCallback, StorageCommitmentLookup) # from v 7.0 +# orthanc.RegisterStorageCommitmentScpCallback(StorageCommitmentScpCallback, StorageCommitmentLookup) \ No newline at end of file
--- a/Sphinx/source/plugins/python/worklist.py Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/python/worklist.py Thu Dec 18 10:44:28 2025 +0100 @@ -6,8 +6,12 @@ # https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.11.0/OrthancServer/Plugins/Samples/ModalityWorklists/WorklistsDatabase WORKLIST_DIR = '/tmp/WorklistsDatabase' -def OnWorklist(answers, query, issuerAet, calledAet): - print('Received incoming C-FIND worklist request from %s:' % issuerAet) +def OnWorklist(answers, query, connection): # new from v 7.0: issuerAet and calledAet are available from the connection object + print('Received incoming C-FIND worklist request from %s %s %s:' % (connection.GetConnectionRemoteAet(), connection.GetConnectionRemoteIp(), connection.GetConnectionCalledAet())) + + # old prototype still available + # def OnWorklist(answers, query, issuerAet, calledAet): + # print('Received incoming C-FIND worklist request from %s:' % issuerAet) # Get a memory buffer containing the DICOM instance dicom = query.WorklistGetDicomQuery() @@ -30,4 +34,5 @@ orthanc.LogWarning('Matching worklist: %s' % path) answers.WorklistAddAnswer(query, content) -orthanc.RegisterWorklistCallback(OnWorklist) +orthanc.RegisterWorklistCallback2(OnWorklist) # new from v 7.0 +# orthanc.RegisterWorklistCallback(OnWorklist)
--- a/Sphinx/source/plugins/stone-webviewer.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/stone-webviewer.rst Thu Dec 18 10:44:28 2025 +0100 @@ -44,7 +44,7 @@ The compilation process is quite complex since it requires using the `Emscripten <https://emscripten.org/>`__ compiler toolchain. The full build instructions are available in the `source code -<https://orthanc.uclouvain.be/hg/orthanc-stone/file/StoneWebViewer-2.6/Applications/StoneWebViewer/WebAssembly/NOTES.txt>`__. +<https://orthanc.uclouvain.be/hg/orthanc-stone/file/StoneWebViewer-3.0/Applications/StoneWebViewer/WebAssembly/NOTES.txt>`__. Usage @@ -103,11 +103,11 @@ * The configuration of the Web viewer can be fine-tuned by adapting some **advanced options** in the `configuration file - <https://orthanc.uclouvain.be/hg/orthanc-stone/file/StoneWebViewer-2.6/Applications/StoneWebViewer/WebApplication/configuration.json>`__. + <https://orthanc.uclouvain.be/hg/orthanc-stone/file/StoneWebViewer-3.0/Applications/StoneWebViewer/WebApplication/configuration.json>`__. * The source distribution of the Stone Web viewer contains a `NOTES.txt file - <https://orthanc.uclouvain.be/hg/orthanc-stone/file/StoneWebViewer-2.6/Applications/StoneWebViewer/NOTES.txt>`__ + <https://orthanc.uclouvain.be/hg/orthanc-stone/file/StoneWebViewer-3.0/Applications/StoneWebViewer/NOTES.txt>`__ that discusses the differences with the :ref:`Osimis Web viewer <osimis_webviewer>` as well as **advanced features** of the software (opening multiple studies, authorization, display of OsiriX @@ -151,17 +151,21 @@ - **Can I use the Stone Web viewer in a medical environment?** - The Stone Web viewer is not a Medical Device; it is not CE marked or FDA - approved. The Stone Web viewer is free and open-source software that - cannot be used for diagnostic or therapeutic purposes. + The Stone Web Viewer is not a medical device and is not CE-marked or + FDA-approved. The Stone Web viewer is free and open-source software + that should not be used for diagnostic or therapeutic purposes. Any + clinical use is undertaken solely at the discretion and + responsibility of the physician. - However, the viewer can be used as a communication tool that allows - researchers, teachers, technicians, medical physicists, general - practitioner or patients to visualize medical images for information - only. + The viewer may be used as a communication and visualization tool to + support activities such as research, education, technical analysis, + quality control, or general image review by physicians, scientists, + educators, technicians, medical physicists, general practitioners, + or patients. - Check out your local regulations to ensure you're using it in a - legal manner. + Please consult and comply with all applicable local laws and + regulations to ensure that your use of the software is lawful and + appropriate. - **Can the Stone Web viewer display DICOM-SR (structured reports)?** @@ -226,7 +230,7 @@ - **How can I migrate from Osimis Web viewer to Stone Web viewer?** Full instructions are provided in the `source distribution - <https://orthanc.uclouvain.be/hg/orthanc-stone/file/StoneWebViewer-2.6/Applications/StoneWebViewer/NOTES.txt>`__. + <https://orthanc.uclouvain.be/hg/orthanc-stone/file/StoneWebViewer-3.0/Applications/StoneWebViewer/NOTES.txt>`__. - **What are the future plans?**
--- a/Sphinx/source/plugins/transfers.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/transfers.rst Thu Dec 18 10:44:28 2025 +0100 @@ -247,10 +247,16 @@ "Threads" : 6, // Number of worker threads for one transfer "BucketSize" : 4096, // Optimal size for a bucket (in KB) "CacheSize" : 128, // Size of the memory cache to process DICOM files (in MB) + // This cache is used by the sender of a Push job and keeps + // a copy of compressed instances while they are being split + // in buckets and sent to the destination. "MaxPushTransactions" : 4, // Maximum number of simultaneous receptions in push mode "MaxHttpRetries" : 0, // Maximum number of HTTP retries for one bucket "PeerConnectivityTimeout": 2, // HTTP Timeout (in seconds) used when checking if a remote peer has the transfer plugin enabled in /transfers/peers GET route - "PeerCommitTimeout": 600 // HTTP Timeout (in seconds) used when committing a push transaction (new in 1.6 - not released yet) + "PeerCommitTimeout": 600, // HTTP Timeout (in seconds) used when committing a push transaction (new in 1.6) + "CommitThreadsCount": 1 // Number of threads used to perform the "commit" phase of a Push/Pull transfer. + // A value > 1 is meaningful only if the storage is a distributed network storage (e.g object storage plugin). + // (new in 1.7) } }
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/plugins/worklists-plugin-new.rst Thu Dec 18 10:44:28 2025 +0100 @@ -0,0 +1,242 @@ +.. _worklists-plugin-new: + + +Worklists plugin +================ + +.. warning:: + This page documents the new ``Worklists plugin`` that supersedes the + legacy :ref:`Sample Modality Worklists plugin <worklists-plugin>` that is + provided as a sample project with the Orthanc source code since 1.0.0. + +.. contents:: + +The worklists plugin turns Orthanc +into a server of DICOM worklists. General information about how +Orthanc supports DICOM worklists through plugins is explained in the +:ref:`FAQ <worklist>`. + +The plugin serves the worklists stored in some folder on the filesystem +or directly in the Orthanc database. It also provides a REST API to create and manage +worklists. + +The source code of this plugin is `available on GitHub +<https://github.com/orthanc-server/orthanc-worklists>`__ +(AGPLv3+ license). + +Basic configuration +------------------- + +.. highlight:: json + +1. First, generate the :ref:`default configuration of Orthanc <configuration>`. +2. Then, modify the ``Plugins`` option to point to the folder containing + the shared library of the plugin. +3. Finally, create a section "Worklists" in the configuration + file to configure the worklist server. + +A basic configuration would read as follows:: + + { + [...] + "Plugins" : [ + "." + ], + "Worklists" : { + "Enable": true, + + "FilterIssuerAet": false, // Some modalities do not specify 'ScheduledStationAETitle (0040,0001)' + // in the C-Find and may receive worklists not related to them. This option + // adds an extra filtering based on the AET of the modality issuing the C-Find. + "LimitAnswers": 0, // Maximum number of answers to be returned (new in release 1.7.3) + + "Directory": "./WorklistsDatabase", // The folder from which worklists are read or in which they are created. + + + "SaveInOrthancDatabase": false, // If set to true and if the Orthanc Database supports Key-Value stores + // (PostgreSQL or SQLite), the worklists must be created through the REST API + // and are stored in the Orthanc DB. + "SetStudyInstanceUidIfMissing": true, // Add a StudyInstanceUID to the worklist if none is provided in the REST API call to create it + "DeleteWorklistsOnStableStudy": true, // Delete the worklist as soon as a a stable study is found with the StudyInstanceUID + // provided in the worklist. + // Note that this check is performed in the Worklist Housekeeper thread. The plugin + // does not react synchronously on the Stable Study event. + // This process is only available if you are providing a StudyInstanceUID + // or if you have set the 'SetStudyInstanceUIDIfMissing' configuration to true + "HousekeepingInterval": 60, // Interval [in seconds] between 2 execution of the Worklist Housekeeper thread. + + // New options only if SaveInOrthancDatabase is set to true. + + "DeleteWorklistsDelay": 24 // Delay [in hours] after which the worklist is deleted. + // Note that this check is performed in the Worklist Housekeeper thread. + // The plugin only deletes worklists that have been created through the REST API. + // Set it to 0 if you don't want the plugin to delete worklists after a delay. + } + } + + +Tutorial +-------- + +.. highlight:: javascript + +- Download `DCMTK utilities + <https://dicom.offis.de/download/dcmtk/release/bin/>`__. +- Enable the Worklists plugin in your configuration file by adding this section:: + + "Worklists" : { + "Enable": true, + "SaveInOrthancDatabase": true + }, + +- Add the plugin to the list of plugins to load (this is an example + for Microsoft Windows):: + + "Plugins" : [ + "StoneWebViewer.dll", + "OrthancExplorer2.dll", + "OrthancWorklists.dll" // On GNU/Linux, use libOrthancWorklists.so + ], + +- The tests below will be done using the ``findscu`` command-line tool + from the `DCMTK utilities + <https://support.dcmtk.org/docs/findscu.html>`__. Assuming + ``findscu`` and Orthanc runs on the same computer (i.e. on the + ``127.0.0.1`` localhost), declare the ``FINDSCU`` AET to the list of + know modalities:: + + "DicomModalities" : { + "horos" : [ "HOROS", "192.168.0.8", 11112 ], + "findscu" : [ "FINDSCU", "127.0.0.1", 1234 ] + }, + +.. highlight:: bash + +- Launch Orthanc as usual, making sure to give the proper + configuration file (e.g. for Microsoft Windows):: + + Orthanc.exe config.json + +- Open the `Orthanc Explorer 2 User interface <http://localhost:8042/ui/app/>`__ + and create a worklist for a ``CT``. + +- In another command-line prompt, launch a ``findscu`` request to ask + Orthanc to return all worklists for ``CT`` modalities:: + + findscu -W -k "ScheduledProcedureStepSequence[0].Modality=CT" 127.0.0.1 4242 + + The ``-W`` option makes ``findscu`` issue a DICOM worklist query, + the ``-k`` option specifies the query of interest, ``127.0.0.1`` + corresponds to the localhost, and ``4242`` corresponds to the + default DICOM TCP port of Orthanc. + +- ``findscu`` will display the matching worklists. + + +How to create a worklist using the REST API +------------------------------------------- + +.. highlight:: bash + +The new worklsits plugin provides a REST API that can be +used to create worklists. For example:: + + $ curl --request POST http://localhost:8042/worklists/create \ + --data '{ + "Tags" : { + "PatientID": "PID-45", + "PatientName": "Toto", + "ScheduledProcedureStepSequence" : [ + { + "Modality": "US", + "ScheduledProcedureStepStartDate": "20251014", + "ScheduledProcedureStepDescription": "Description" + } + ] + } + }' + +In response, you'll get something like:: + + { + "ID" : "5fdc7404-f9dc-4798-b6e1-8f715e2f9e71", + "Path" : "/worklists/5fdc7404-f9dc-4798-b6e1-8f715e2f9e71" + } + +You can then check the content of the worklist by calling:: + + $ curl --request GET http://localhost:8042/worklists/5fdc7404-f9dc-4798-b6e1-8f715e2f9e71 + +To delete it, call:: + + $ curl --request DELETE http://localhost:8042/worklists/5fdc7404-f9dc-4798-b6e1-8f715e2f9e71 + +To browse all worklists, call:: + + $ curl --request GET http://localhost:8042/worklists/?format=Simplify + $ curl --request GET http://localhost:8042/worklists/?format=Short + $ curl --request GET http://localhost:8042/worklists/?format=Full + + + +Troubleshooting C-Find queries +------------------------------ + +When trying to retrieve worklists from a modality, one usually don't get debugging capabilities from the modality itself. +Therefore, it is usually convenient to mimic the modality with ``findscu`` (provided by `DCMTK software +<https://support.dcmtk.org/docs/wlmscpfs.html>`__). + +- First, you should make sure that you have configured the Worklist plugin correctly and that you have pushed + at least a ``.wl`` file in the worklist database. For this, you should issue this kind of command:: + + findscu -W 127.0.0.1 4242 -k 0008,0050="*" + + This is the most generic C-Find request and should return all AccessionNumber of all the worklists in your database. + + Note: you should make sure you have added a ``findscu`` DICOM modality in your configuration file. + + ``findscu`` should output something like this:: + + W: --------------------------- + W: Find Response: 1 (Pending) + W: + W: # Dicom-Data-Set + W: # Used TransferSyntax: Little Endian Explicit + W: (0008,0005) CS [ISO_IR 100] # 10, 1 SpecificCharacterSet + W: (0008,0050) SH [**********] # 10, 1 AccessionNumber + W: + + If you don't get any output, you may add ``-v -d`` options to the ``findscu`` command line to get additional details. + +- Everytime it receives a C-Find request, Orthanc displays the query parameters in its :ref:`logs <log>`. + With the previous C-Find command, you should expect this kind of output:: + + I0422 17:16:03.512449 CommandDispatcher.cpp:490] Association Received from AET FINDSCU on IP 127.0.0.1 + I0422 17:16:03.514433 CommandDispatcher.cpp:688] Association Acknowledged (Max Send PDV: 16372) + I0422 17:16:03.532062 main.cpp:118] No limit on the number of C-FIND results at the Patient, Study and Series levels + I0422 17:16:03.535986 main.cpp:128] No limit on the number of C-FIND results at the Instance level + I0422 17:16:03.536968 PluginsManager.cpp:171] Received worklist query from remote modality FINDSCU: + { + "0008,0050" : "*" + } + I0422 17:16:03.559539 CommandDispatcher.cpp:891] DUL Peer Requested Release + I0422 17:16:03.560520 CommandDispatcher.cpp:898] Association Release + +- Now you may try to issue a C-Find request from your modality and check Orthanc logs. You should then have a better understanding of the query + content and eventually understand why it does not match your worklists. You should also be able re-issue ``findscu`` requests with additional arguments to mimic the requests issued by your modality. + +Common problems +--------------- + +- C-FIND requests can be modified by implementing the + ``IncomingWorklistRequestFilter`` :ref:`Lua callback + <lua-fix-cfind>` since Orthanc 1.4.2. This can be useful to + fix/sanitize worklist queries. + +- According to the `specification + <http://dicom.nema.org/MEDICAL/Dicom/2015c/output/chtml/part02/sect_B.4.2.2.3.html>`__, + modalities should not include their AET name in + ``ScheduledStationAETitle`` on user initiated queries. Therefore, + they do receive worklists that do not concern them. This may be + handled by the ``FilterIssuerAet`` configuration option. Note that + the default behavior might in some cases be intended.
--- a/Sphinx/source/plugins/worklists-plugin.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/plugins/worklists-plugin.rst Thu Dec 18 10:44:28 2025 +0100 @@ -1,12 +1,23 @@ .. _worklists-plugin: -Sample Modality Worklists plugin -================================ +Sample Modality Worklists plugin (legacy - for developers) +========================================================== + +.. warning:: + This page documents the ``Sample Modality Worklists plugin`` that + is provided with Orthanc since version 1.0.0 and is mainly a sample + plugin to help developers write their own plugin. + + Starting from November 2025, a more feature rich :ref:`Worklists plugin <worklists-plugin-new>` is being + packaged independently. This new plugin provides a REST API to create, delete and edit + worklists. It also integrates nicely with :ref:`Orthanc Explorer 2 <orthanc-explorer-2>` + that provides a user interface to browse and create new worklists. + .. contents:: -This page describes the **official sample plugin** turning Orthanc +This page describes the **sample plugin** turning Orthanc into a server of DICOM worklists. General information about how Orthanc supports DICOM worklists through plugins is explained in the :ref:`FAQ <worklist>`. @@ -44,7 +55,7 @@ 1. First, generate the :ref:`default configuration of Orthanc <configuration>`. 2. Then, modify the ``Plugins`` option to point to the folder containing the shared library of the plugin. -3. Finally, create a section "ModalityWorklists" in the configuration +3. Finally, create a section "Worklists" in the configuration file to configure the worklist server. A basic configuration would read as follows:: @@ -62,31 +73,7 @@ // adds an extra filtering based on the AET of the modality issuing the C-Find. "LimitAnswers": 0, // Maximum number of answers to be returned (new in release 1.7.3) - "Directory": "./WorklistsDatabase", // The folder from which worklists are read or, from 1.12.10, - // where the worklists are created. - // Note, up to v 1.12.9, this configuration was named "Database" - // and this old naming is kept for backward compatibility reasons. - // Don't specify this option if you want to store worklists in the Orthanc DB. - // New options in v 1.12.10 - - "SaveInOrthancDatabase": false, // If set to true and if the Orthanc Database supports Key-Value stores - // (PostgreSQL or SQLite), the worklists must be created through the Rest API - // and are stored in the Orthanc DB (new in v 1.12.10) - "SetStudyInstanceUidIfMissing": true, // Add a StudyInstanceUID to the worklist if none is provided in the Rest API call to create it - "DeleteWorklistsOnStableStudy": true, // Delete the worklist as soon as a a stable study is found with the StudyInstanceUID - // provided in the worklist. - // Note that this check is performed in the Worklist Housekeeper thread. The plugin - // does not react synchronously on the Stable Study event. - // This process is only available if you are providing a StudyInstanceUID - // or if you have set the 'SetStudyInstanceUIDIfMissing' configuration to true - "HousekeepingInterval": 60, // Interval [in seconds] between 2 execution of the Worklist Housekeeper thread. - - // New options in v 1.12.10 and only if SaveInOrthancDatabase is set to true. - - "DeleteWorklistsDelay": 24 // Delay [in hours] after which the worklist is deleted. - // Note that this check is performed in the Worklist Housekeeper thread. - // The plugin only deletes worklists that have been created through the Rest API. - // Set it to 0 if you don't want the plugin to delete worklists after a delay. + "Database": "./WorklistsDatabase", // The folder from which worklists are read. } } @@ -113,7 +100,7 @@ "Worklists" : { "Enable": true, - "Directory": "WorklistsDatabase" // Path to the folder with the worklist files (note: up to v 1.12.9, use ``"Database"`` instead of ``"Directory"``) + "Database": "WorklistsDatabase" // Path to the folder with the worklist files }, - Add the plugin to the list of plugins to load (this is an example @@ -156,52 +143,6 @@ - ``findscu`` will display the matching worklists. -How to create a worklist file using the Rest API - new in 1.12.10 ------------------------------------------------------------------ - -.. highlight:: bash - -Starting from Orthanc 1.12.10, the plugin provides a Rest API that can be -used to create worklists. For example:: - - $ curl --request POST http://localhost:8042/plugins/worklists/create \ - --data '{ - "Tags" : { - "PatientID": "PID-45", - "PatientName": "Toto", - "ScheduledProcedureStepSequence" : [ - { - "Modality": "US", - "ScheduledProcedureStepStartDate": "20251014", - "ScheduledProcedureStepDescription": "Description" - } - ] - } - }' - -In response, you'll get something like:: - - { - "ID" : "5fdc7404-f9dc-4798-b6e1-8f715e2f9e71", - "Path" : "/plugins/worklists/5fdc7404-f9dc-4798-b6e1-8f715e2f9e71" - } - -You can then check the content of the worklist by calling:: - - $ curl --request GET http://localhost:8042/plugins/worklists/5fdc7404-f9dc-4798-b6e1-8f715e2f9e71 - -To delete it, call:: - - $ curl --request DELETE http://localhost:8042/plugins/worklists/5fdc7404-f9dc-4798-b6e1-8f715e2f9e71 - -To browse all worklists, call:: - - $ curl --request GET http://localhost:8042/plugins/worklists/?format=Simplify - $ curl --request GET http://localhost:8042/plugins/worklists/?format=Short - $ curl --request GET http://localhost:8042/plugins/worklists/?format=Full - - - How to create a worklist file using DCMTK -----------------------------------------
--- a/Sphinx/source/users/advanced-rest.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/advanced-rest.rst Thu Dec 18 10:44:28 2025 +0100 @@ -89,7 +89,7 @@ the ``MediaArchiveSize`` configuration that defines the maximum number of ZIP/media archives that are maintained by Orthanc, as a response to the asynchronous creation of archive. As of Orthanc -1.12.9, this value is ``1`` by default. +1.12.10, this value is ``1`` by default. .. _jobs-monitoring: @@ -139,7 +139,7 @@ ``ErrorCode`` and ``ErrorDescription`` fields for more information. * ``Paused``: The job has been paused. * ``Retry``: The job has failed internally, and has been scheduled for - re-submission after a delay. As of Orthanc 1.12.9, this feature is not + re-submission after a delay. As of Orthanc 1.12.10, this feature is not used by any type of job. In order to wait for the end of an asynchronous call, the caller will @@ -148,7 +148,7 @@ ``Failure``. Note that the `integration tests of Orthanc -<https://orthanc.uclouvain.be/hg/orthanc-tests/file/Orthanc-1.12.9/Tests/Toolbox.py>`__ +<https://orthanc.uclouvain.be/hg/orthanc-tests/file/Orthanc-1.12.10/Tests/Toolbox.py>`__ give an example about how to monitor a job in Python using the REST API (cf. function ``MonitorJob()``). @@ -221,7 +221,7 @@ Note how we retrieve the content of the archive by accessing the ``archive`` output of the job (check out the virtual method ``IJob::GetOutput()`` from the `source code -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Sources/ServerJobs/ArchiveJob.cpp>`__ +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Sources/ServerJobs/ArchiveJob.cpp>`__ of Orthanc). Here is the corresponding sequence of commands to generate a DICOMDIR @@ -230,7 +230,7 @@ $ curl http://localhost:8042/studies/27f7126f-4f66fb14-03f4081b-f9341db2-53925988/media -d '{"Asynchronous":true}' $ curl http://localhost:8042/jobs/6332be8a-0052-44fb-8cc2-ac959aeccad9/archive > a.zip -As of Orthanc 1.12.9, only the creation of a ZIP or a DICOMDIR archive +As of Orthanc 1.12.10, only the creation of a ZIP or a DICOMDIR archive produces such "outputs". @@ -427,85 +427,118 @@ The metrics only appear in the response once they have been recorded at least once. Furthermore, some plugins may add their own metrics dynamically. -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| Metrics | Meaning | Origin | -+========================================================+=============================================================================+================================================================+ -| ``orthanc_last_change`` | The current id of the last `change` event | Orthanc | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_memory_trimming_duration_ms`` | The max duration [ms] over the last 10 seconds of the last memory | Orthanc | -| | trimming duration | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_store_dicom_duration_ms`` | The max duration [ms] over the last 10 seconds needed to store a | Orthanc | -| | DICOM file (received from HTTP, DICOM protocol or from a plugin) | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_up_time_s`` | The time [s] spent since Orthanc started | Orthanc | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_count_instances`` | The number of instances stored in DB | Orthanc DB | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_count_series`` | The number of series stored in DB | Orthanc DB | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_count_studies`` | The number of studies stored in DB | Orthanc DB | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_count_patients`` | The number of patients stored in DB | Orthanc DB | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_dicom_cache_count`` | The number of DICOM files currently stored in the DICOM cache | Orthanc DICOM cache | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_dicom_cache_size_mb`` | The size [MB] of all DICOM files currently stored in the DICOM cache | Orthanc DICOM cache | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_available_dicom_threads`` | The min number of DICOM threads count available over the last 10 | Orthanc DICOM protocol server | -| | seconds | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_find_scp_duration_ms`` | The max duration [ms] over the last 10 seconds of a C-Find SCP execution | Orthanc DICOM protocol server | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_get_scp_duration_ms`` | The max duration [ms] over the last 10 seconds of a C-Get SCP execution | Orthanc DICOM protocol server | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_move_scp_duration_ms`` | The max duration [ms] over the last 10 seconds of a C-Move SCP execution | Orthanc DICOM protocol server | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_available_http_threads`` | The min number of HTTP threads count available over the last 10 | Orthanc HTTP server | -| | seconds. This is counting only the threads used by the external HTTP | | -| | server while ``orthanc_rest_api_active_requests`` also counts the internal | | -| | requests e.g. made by a plugin | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_rest_api_active_requests`` | The maximum number of concurrent HTTP requests being handled by the | Orthanc HTTP server | -| | HTTP server over the last 10 seconds. | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_rest_api_duration_ms`` | The max duration [ms] over the last 10 seconds required to handle | Orthanc HTTP server | -| | an HTTP request | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_jobs_pending`` | The current number of jobs whose execution is currently pending | Orthanc Jobs engine | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_jobs_running`` | The current number of jobs currently being executed | Orthanc Jobs engine | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_jobs_completed`` | The current number of jobs completed (failed or success) | Orthanc Jobs engine | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_jobs_success`` | The current number of jobs that have succeeded | Orthanc Jobs engine | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_jobs_failed`` | The current number of jobs that have failed | Orthanc Jobs engine | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_disk_size_mb`` | The size [MB] of all DICOM files currently stored in Orthanc | Orthanc Storage | -| | (possibly compressed size) | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_uncompressed_size_mb`` | The size [MB] of all DICOM files currently stored in Orthanc | Orthanc Storage | -| | (uncompressed size) | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_storage_cache_count`` | The number of files currently stored in the Storage cache | Orthanc Storage cache | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_storage_cache_size_mb`` | The size [MB] of all files currently stored in the Storage cache | Orthanc Storage cache | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_storage_create_duration_ms`` | The max duration [ms] over the last 10 seconds to save a file to disk | Orthanc Storage (default file system storage) | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_storage_read_duration_ms`` | The max duration [ms] over the last 10 seconds to read a file from disk | Orthanc Storage (default file system storage) | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_storage_remove_duration_ms`` | The max duration [ms] over the last 10 seconds to delete a file from disk | Orthanc Storage (default file system storage) | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_storage_read_bytes`` | The total number of bytes read from disk since Orthanc started | Orthanc Storage (default file system storage) | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_storage_written_bytes`` | The total number of bytes written to disk since Orthanc started | Orthanc Storage (default file system storage) | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ -| ``orthanc_index_active_connections_count`` | The the current number of active connections to the PostgreSQL server. | Orthanc PostgreSQL Index plugin | -+--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| Metrics | Meaning | Origin | ++=============================================================+===================================================================================+======================================================================+ +| ``orthanc_last_change`` | The current id of the last `change` event | Orthanc | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_memory_trimming_duration_ms`` | The max duration [ms] over the last 10 seconds of the last memory | Orthanc | +| | trimming duration | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_store_dicom_duration_ms`` | The max duration [ms] over the last 10 seconds needed to store a | Orthanc | +| | DICOM file (received from HTTP, DICOM protocol or from a plugin) | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_up_time_s`` | The time [s] spent since Orthanc started | Orthanc | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_count_instances`` | The number of instances stored in DB | Orthanc DB | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_count_series`` | The number of series stored in DB | Orthanc DB | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_count_studies`` | The number of studies stored in DB | Orthanc DB | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_count_patients`` | The number of patients stored in DB | Orthanc DB | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_dicom_cache_count`` | The number of DICOM files currently stored in the DICOM cache | Orthanc DICOM cache | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_dicom_cache_size_mb`` | The size [MB] of all DICOM files currently stored in the DICOM cache | Orthanc DICOM cache | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_available_dicom_threads`` | The min number of DICOM threads count available over the last 10 | Orthanc DICOM protocol server | +| | seconds | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_find_scp_duration_ms`` | The max duration [ms] over the last 10 seconds of a C-Find SCP execution | Orthanc DICOM protocol server | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_get_scp_duration_ms`` | The max duration [ms] over the last 10 seconds of a C-Get SCP execution | Orthanc DICOM protocol server | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_move_scp_duration_ms`` | The max duration [ms] over the last 10 seconds of a C-Move SCP execution | Orthanc DICOM protocol server | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_available_http_threads`` | The min number of HTTP threads count available over the last 10 | Orthanc HTTP server | +| | seconds. This is counting only the threads used by the external HTTP | | +| | server while ``orthanc_rest_api_active_requests`` also counts the internal | | +| | requests e.g. made by a plugin | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_rest_api_active_requests`` | The maximum number of concurrent HTTP requests being handled by the | Orthanc HTTP server | +| | HTTP server over the last 10 seconds. | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_rest_api_duration_ms`` | The max duration [ms] over the last 10 seconds required to handle | Orthanc HTTP server | +| | an HTTP request | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_jobs_pending`` | The current number of jobs whose execution is currently pending | Orthanc Jobs engine | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_jobs_running`` | The current number of jobs currently being executed | Orthanc Jobs engine | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_jobs_completed`` | The current number of jobs completed (failed or success) | Orthanc Jobs engine | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_jobs_success`` | The current number of jobs that have succeeded | Orthanc Jobs engine | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_jobs_failed`` | The current number of jobs that have failed | Orthanc Jobs engine | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_disk_size_mb`` | The size [MB] of all DICOM files currently stored in Orthanc | Orthanc Storage | +| | (possibly compressed size) | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_uncompressed_size_mb`` | The size [MB] of all DICOM files currently stored in Orthanc | Orthanc Storage | +| | (uncompressed size) | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_storage_cache_count`` | The number of files currently stored in the Storage cache | Orthanc Storage cache | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_storage_cache_size_mb`` | The size [MB] of all files currently stored in the Storage cache | Orthanc Storage cache | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_storage_create_duration_ms`` | The max duration [ms] over the last 10 seconds to save a file to disk | Orthanc Storage (default file system storage) | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_storage_read_duration_ms`` | The max duration [ms] over the last 10 seconds to read a file from disk | Orthanc Storage (default file system storage) | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_storage_remove_duration_ms`` | The max duration [ms] over the last 10 seconds to delete a file from disk | Orthanc Storage (default file system storage) | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_storage_read_bytes`` | The total number of bytes read from disk since Orthanc started | Orthanc Storage (default file system storage) | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_storage_written_bytes`` | The total number of bytes written to disk since Orthanc started | Orthanc Storage (default file system storage) | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_index_active_connections_count`` | The current number of active connections to the PostgreSQL server. | Orthanc PostgreSQL Index plugin | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_aborted_push_count`` | The number of push transfers that have been discarded without being | Transfers plugin | +| | committed (on the receiver side) | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_created_push_count`` | The number of push transfers that have been created | Transfers plugin | +| | (on the receiver side) | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_committed_push_count`` | The number of push transfers that have been committed | Transfers plugin | +| | (on the receiver side) | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_available_push_count`` | The number of push transfers that are available | Transfers plugin | +| | out of the ``MaxPushTransactions``. (on the receiver side) | | +| | Note: aborted transfers might consume available "slots" but will be pushed | | +| | out when room is required for a new active transfer. | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_cache_hit_count`` | The number of times the cache could be used to transfer an instance. | Transfers plugin | +| | (on the sender side) | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_cache_miss_count`` | The number of times the cache could not be used to transfer an instance. | Transfers plugin | +| | (on the sender side) | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_used_cache_size`` | The current size [bytes] of cache. | Transfers plugin | +| | (on the sender side) | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_push_total_received_bytes_count`` | The total number of bytes received during push transfers | Transfers plugin | +| | (on the receiver side). The bytes are added just at the beginning of the commit. | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_push_total_time_spent_in_commit_ms`` | The total time [ms] spent in push transfers commit operations. | Transfers plugin | +| | (on the receiver side). The value is updated at the end of the commit. | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ +| ``orthanc_transfers_push_total_time_spent_in_reception_ms`` | The total time [ms] spent in push transfers reception, before the | Transfers plugin | +| | commit operation. (on the receiver side). The value is updated at the beginning | | +| | of the commit. | | ++-------------------------------------------------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------+ - + .. highlight:: bash
--- a/Sphinx/source/users/anonymization.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/anonymization.rst Thu Dec 18 10:44:28 2025 +0100 @@ -80,7 +80,7 @@ **Implementation:** Internally, the setup of the anonymization profiles can be found in the methods ``SetupAnonymizationXXX()`` of the class ``Orthanc::DicomModification`` (cf. `source code -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancFramework/Sources/DicomParsing/DicomModification.cpp>`__). +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancFramework/Sources/DicomParsing/DicomModification.cpp>`__). Modification of a Single Instance
--- a/Sphinx/source/users/configuration.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/configuration.rst Thu Dec 18 10:44:28 2025 +0100 @@ -8,7 +8,7 @@ Configuring Orthanc simply consists in providing a configuration file. Orthanc has numerous configuration that are documented in the `default configuration file -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Resources/Configuration.json>`_. This +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Resources/Configuration.json>`_. This file is in the `JSON <https://en.wikipedia.org/wiki/JSON>`_ file format. You can generate this file file with the following call::
--- a/Sphinx/source/users/debian-packages.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/debian-packages.rst Thu Dec 18 10:44:28 2025 +0100 @@ -108,11 +108,11 @@ This can be done with this sequence of commands:: $ sudo service orthanc stop - $ sudo wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/1.12.9/Orthanc --output-document /usr/sbin/Orthanc + $ sudo wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/1.12.10/Orthanc --output-document /usr/sbin/Orthanc $ sudo chmod +x /usr/sbin/Orthanc $ sudo rm -f /usr/share/orthanc/plugins/*.so - $ sudo wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/1.12.9/libServeFolders.so --output-document /usr/share/orthanc/plugins/libServeFolders.so - $ sudo wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/1.12.9/libModalityWorklists.so --output-document /usr/share/orthanc/plugins/libModalityWorklists.so + $ sudo wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/1.12.10/libServeFolders.so --output-document /usr/share/orthanc/plugins/libServeFolders.so + $ sudo wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/1.12.10/libModalityWorklists.so --output-document /usr/share/orthanc/plugins/libModalityWorklists.so $ $ sudo wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc-dicomweb/1.20/libOrthancDicomWeb.so --output-document /usr/share/orthanc/plugins/libOrthancDicomWeb.so $ ...
--- a/Sphinx/source/users/docker-orthancteam.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/docker-orthancteam.rst Thu Dec 18 10:44:28 2025 +0100 @@ -288,7 +288,6 @@ .. below table is obtained by running orthanc-builder/docker/orthanc/generatePluginDoc.py - +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | Plugin | Environment variable | Default configuration | +==================================================+==================================================+====================================================================================================+ @@ -367,8 +366,7 @@ | | | | | | | { | | | | "Worklists": { | -| | | "Enable": true, | -| | | "Database": "/var/lib/orthanc/worklists" | +| | | "Enable": true | | | | } | | | | } | +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ @@ -398,6 +396,14 @@ | | | } | | | | } | +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **Education** | ``EDUCATION_PLUGIN_ENABLED`` | .. code-block:: json | +| | | | +| | | { | +| | | "Education": { | +| | | "Enable": true | +| | | } | +| | | } | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | **Wsi** | ``WSI_PLUGIN_ENABLED`` | | +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ | **Odbc** | ``ODBC_PLUGIN_ENABLED`` | .. code-block:: json | @@ -493,6 +499,15 @@ | | | } | | | | } | +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **PixelsMasker** | ``PIXELS_MASKER_PLUGIN_ENABLED`` | .. code-block:: json | +| | | | +| | | { | +| | | "PixelsMasker": { | +| | | "Enable": true | +| | | } | +| | | } | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ + Under the hood --------------
--- a/Sphinx/source/users/docker.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/docker.rst Thu Dec 18 10:44:28 2025 +0100 @@ -97,13 +97,13 @@ If more stability is required, you can select the official release of Orthanc to be run:: - $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc:1.12.9 + $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc:1.12.10 Passing additional command-line options (e.g. to make Orthanc verbose) can be done as follows (note the ``/etc/orthanc`` option that is required for Orthanc to find its configuration files):: - $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc:1.12.9 /etc/orthanc --verbose + $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc:1.12.10 /etc/orthanc --verbose Usage, with plugins enabled @@ -119,7 +119,7 @@ Or you can also start a specific version of Orthanc for more stability:: - $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins:1.12.9 + $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins:1.12.10 If you have an interest in the :ref:`Python plugin <python-plugin>`, you can use the ``orthanc-python`` image. The latter image is a @@ -127,7 +127,7 @@ Python 3.7 interpreter. Here is how to start this image:: $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-python - $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-python:1.12.9 + $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-python:1.12.10 Fine-tuning the configuration @@ -141,12 +141,12 @@ You can generate a custom configuration file for Orthanc as follows:: - $ docker run --rm --entrypoint=cat jodogne/orthanc:1.12.9 /etc/orthanc/orthanc.json > /tmp/orthanc.json + $ docker run --rm --entrypoint=cat jodogne/orthanc:1.12.10 /etc/orthanc/orthanc.json > /tmp/orthanc.json Then, edit the just-generated file ``/tmp/orthanc.json`` and restart Orthanc with your updated configuration:: - $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc:1.12.9 + $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc:1.12.10 *Remark:* These Docker images automatically set the environment variable ``MALLOC_ARENA_MAX`` to ``5`` in order to :ref:`control @@ -179,7 +179,7 @@ version: '3.1' # Secrets are only available since this version of Docker Compose services: orthanc: - image: jodogne/orthanc-plugins:1.12.9 + image: jodogne/orthanc-plugins:1.12.10 command: /run/secrets/ # Path to the configuration files (stored as secrets) ports: - 4242:4242 @@ -228,7 +228,7 @@ container to some path in the filesystem of your Linux host, e.g.:: $ mkdir /tmp/orthanc-db - $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc-db/:/var/lib/orthanc/db/ jodogne/orthanc:1.12.9 + $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc-db/:/var/lib/orthanc/db/ jodogne/orthanc:1.12.10 Whole-slide imaging support @@ -238,13 +238,13 @@ whole-slide imaging (WSI) <wsi>`. For instance, the following command will start the WSI viewer plugin transparently together with Orthanc:: - $ docker run -p 4242:4242 -p 8042:8042 --rm --name orthanc-wsi jodogne/orthanc-plugins:1.12.9 + $ docker run -p 4242:4242 -p 8042:8042 --rm --name orthanc-wsi jodogne/orthanc-plugins:1.12.10 Note that we gave the name ``orthanc-wsi`` to this new Docker container. Then, the Dicomizer command-line tool can be invoked as follows:: - $ docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.tif:/tmp/Source.tif:ro jodogne/orthanc-plugins:1.12.9 --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ /tmp/Source.tif + $ docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.tif:/tmp/Source.tif:ro jodogne/orthanc-plugins:1.12.10 --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ /tmp/Source.tif This command needs a few explanations: @@ -272,7 +272,7 @@ instruct the Dicomizer to use `OpenSlide <https://openslide.org/>`__ to decode it by adding the ``--openslide`` option:: - $ docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.svs:/tmp/Source.svs:ro jodogne/orthanc-plugins:1.12.9 --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ --openslide=libopenslide.so /tmp/Source.svs + $ docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.svs:/tmp/Source.svs:ro jodogne/orthanc-plugins:1.12.10 --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ --openslide=libopenslide.so /tmp/Source.svs PostgreSQL and Orthanc inside Docker @@ -293,7 +293,7 @@ $ docker inspect --format '{{ .NetworkSettings.IPAddress }}' some-postgres $ docker inspect --format '{{ .NetworkSettings.Ports }}' some-postgres - $ docker run --rm --entrypoint=cat jodogne/orthanc-plugins:1.12.9 /etc/orthanc/orthanc.json > /tmp/orthanc.json + $ docker run --rm --entrypoint=cat jodogne/orthanc-plugins:1.12.10 /etc/orthanc/orthanc.json > /tmp/orthanc.json .. highlight:: text @@ -314,7 +314,7 @@ Finally, you can start Orthanc:: - $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc-plugins:1.12.9 + $ docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc-plugins:1.12.10 Debugging @@ -325,5 +325,5 @@ For debugging purpose, you can start an interactive bash session as follows:: - $ docker run -i -t --rm --entrypoint=bash jodogne/orthanc:1.12.9 - $ docker run -i -t --rm --entrypoint=bash jodogne/orthanc-plugins:1.12.9 + $ docker run -i -t --rm --entrypoint=bash jodogne/orthanc:1.12.10 + $ docker run -i -t --rm --entrypoint=bash jodogne/orthanc-plugins:1.12.10
--- a/Sphinx/source/users/docker.rst.BAK Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/docker.rst.BAK Thu Dec 18 10:44:28 2025 +0100 @@ -20,4 +20,4 @@ * The build artifacts can be found in folder ``/root/orthanc/Build``. * This command launches the mainline version. To start a released version, - use e.g. ``jodogne/orthanc-debug:1.12.9``. + use e.g. ``jodogne/orthanc-debug:1.12.10``.
--- a/Sphinx/source/users/lua.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/lua.rst Thu Dec 18 10:44:28 2025 +0100 @@ -164,19 +164,19 @@ kind of concurrency but may also lead to some deadlocks. If a lua function (e.g. ``OnHeartBeat``) performs an HTTP call to an -external Rest API (e.g. ``http://myserver.com/orthanc_is_alive.php``) -which, in turn, calls the Orthanc Rest API (e.g. call ``http://orthanc:8042/system``), +external REST API (e.g. ``http://myserver.com/orthanc_is_alive.php``) +which, in turn, calls the Orthanc REST API (e.g. call ``http://orthanc:8042/system``), odds are high that you meet a deadlock because Orthanc, when handling a -Rest API calls, may try to execute some Lua callbacks (e.g. ``IncomingHttpRequestFilter``) +REST API calls, may try to execute some Lua callbacks (e.g. ``IncomingHttpRequestFilter``) while the Lua context is still blocked inside the ``OnHeartBeat`` function. To avoid deadlocks, always make sure to avoid such back-and-forth communications or make sure they happen asynchronously: your webservice should call the -Orthanc Rest API after it has returned from the endpoint called by +Orthanc REST API after it has returned from the endpoint called by ``OnHeartBeat``. Note that these deadlocks won't happen when a lua function calls its own -Orthanc Rest API using the ``RestApiGet``, ``RestApiPost``, ... functions. +Orthanc REST API using the ``RestApiGet``, ``RestApiPost``, ... functions. .. _lua-rest: @@ -591,7 +591,7 @@ Also note that the ``IncomingFindRequestFilter`` callback is not applied to C-Find requests targeting :ref:`modality worklists -<worklists-plugin>`. Since Orthanc 1.4.2, the corresponding +<worklists-plugin-new>`. Since Orthanc 1.4.2, the corresponding ``IncomingWorklistRequestFilter`` callback can be used to sanitize C-FIND requests against worklists::
--- a/Sphinx/source/users/man-orthanc.txt Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/man-orthanc.txt Thu Dec 18 10:44:28 2025 +0100 @@ -130,4 +130,4 @@ This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. -Orthanc 1.12.9 August 2025 ORTHANC(1) +Orthanc 1.12.10 November 2025 ORTHANC(1)
--- a/Sphinx/source/users/rest.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/rest.rst Thu Dec 18 10:44:28 2025 +0100 @@ -98,7 +98,7 @@ $ curl -X POST -H "Expect:" http://localhost:8042/instances --data-binary @CT.X.1.2.276.0.7230010.dcm The code distribution of Orthanc contains a `sample Python script -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Resources/Samples/ImportDicomFiles/ImportDicomFiles.py>`__ +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Resources/Samples/ImportDicomFiles/ImportDicomFiles.py>`__ that recursively upload the content of some folder into Orthanc using the REST API:: @@ -110,7 +110,7 @@ import the content of ``.zip``, ``.tar.gz`` or ``.tar.bz2`` archives without having to uncompress them first. It also provides more comprehensive command-line options. `Check this script out -<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.9/OrthancServer/Resources/Samples/ImportDicomFiles/OrthancImport.py>`__. +<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.10/OrthancServer/Resources/Samples/ImportDicomFiles/OrthancImport.py>`__. .. highlight:: perl @@ -1041,7 +1041,7 @@ Orthanc will propose the 120 most common SOP classes defined in the DCMTK library. If you know the resources you are going to retrieve contain uncommon SOP classes, you may provide a ``"SOPClassesInStudy"`` field in the payload. In this case, Orthanc -will only propose only these SOP classes during the association; provided that they are +will only propose these SOP classes during the association; provided that they are accepted by Orthanc (see ``"AcceptedSopClasses"/"RejectedSopClasses"`` configurations):: $ curl --request POST --url http://localhost:8042/modalities/samples/get \ @@ -1057,6 +1057,149 @@ }' +DIMSE Error status (new in Orthanc 1.12.10) +------------------------------------------- + +Starting with Orthanc 1.12.10, when performing C-Move, C-Get and C-Store +operations, you can get access to the ``DIMSE Error Status`` and, possibly, +to the instances ids that have been received during the C-Move or C-Get retrieve +operations. + +For example, for a permissive ``C-Move`` or ``C-Get`` operation to retrieve 3 studies from a remote +modality:: + + $ curl -v http://localhost:8042/modalities/sample/move \ + --data '{ + "Permissive": true, + "Level" : "Study", + "TargetAet": "ORTHANC", + "Resources" : [ + {"StudyInstanceUID" : "1.2.3"}, + {"StudyInstanceUID" : "3.4.5"} + ] + } + +You'll get this type of response:: + + { + "Description" : "REST API", + "Details" : + [ + { + "DimseErrorStatus" : 0, + "Query" : { + "0008,0052" : "STUDY", + "0020,000d" : "1.2.3" + }, + "ReceivedInstancesIds" : + ["ca58b590-8a115ed5-906f7f21-c7af8058-2637f722"] + }, + { + "DimseErrorStatus" : 49152, + "Query" : { + "0008,0052" : "STUDY", + "0020,000d" : "3.4.5" + }, + "ReceivedInstancesIds" : [] + } + ], + "LocalAet" : "ORTHANC", + "Query" : + [ + { + "0008,0052" : "STUDY", + "0020,000d" : "1.2.3" + }, + { + "0008,0052" : "STUDY", + "0020,000d" : "3.4.5" + } + ], + "RemoteAet" : "SAMPLE", + "TargetAet" : "ORTHANC" + +If you are creating an asynchronous operation, you'll get the same detailed +information in the ``Content.Details`` field of the job. + +If you are running a non-permissive operation (default), for example, a ``C-Get``:: + + $ curl -v http://localhost:8042/modalities/sample/get \ + --data '{ + "Permissive": false, + "Level" : "Study", + "Resources" : [ + {"StudyInstanceUID" : "1.2.3"}, + {"StudyInstanceUID" : "3.4.5"} + ] + } + +If one of the resource is missing, you'll get a ``RetrieveJob`` error payload +in the HTTP response:: + + { + "Details" : "C-GET SCU to AET \"SAMPLE\" has failed with DIMSE status 0xC000", + "ErrorPayload" : + { + "Content" : + [ + { + "DimseErrorStatus" : 0, + "Query" : { + "0008,0052" : "STUDY", + "0020,000d" : "1.2.3" + }, + "ReceivedInstancesIds" : + ["ca58b590-8a115ed5-906f7f21-c7af8058-2637f722"] + }, + { + "DimseErrorStatus" : 49152, + "Query" : { + "0008,0052" : "STUDY", + "0020,000d" : "3.4.5" + }, + "ReceivedInstancesIds" : [] + } + ], + "Type" : "RetrieveJob" + }, + "HttpError" : "Internal Server Error", + "HttpStatus" : 500, + "Message" : "Error in the network protocol", + "Method" : "POST", + "OrthancError" : "Error in the network protocol", + "OrthancStatus" : 9, + "Uri" : "/modalities/sample/get" + } + +If you are running a non-permissive ``C-Store`` operation that fails, for example:: + + $ curl -v http://localhost:8042/modalities/sample/store \ + --data '{ + "Resources" : ["595df1a1-74fe920a-4b9e3509-826f17a3-762a2dc3"] + } + +You'll get a simple ``Dimse`` error payload like:: + + { + "Details" : "C-STORE SCU to AET \"SAMPLE\" has failed with DIMSE status 0xA700", + "ErrorPayload" : + { + "Content" : + { + "DimseErrorStatus" : 42752 + }, + "Type" : "Dimse" + }, + "HttpError" : "Internal Server Error", + "HttpStatus" : 500, + "Message" : "Error in the network protocol", + "Method" : "POST", + "OrthancError" : "Error in the network protocol", + "OrthancStatus" : 9, + "Uri" : "/modalities/sample/store" + } + + Performing Query/Retrieve (C-Find) ----------------------------------
--- a/Sphinx/source/users/support.rst Thu Dec 18 10:39:14 2025 +0100 +++ b/Sphinx/source/users/support.rst Thu Dec 18 10:44:28 2025 +0100 @@ -188,6 +188,7 @@ * **Europe**: * `Adrian Schiopu <sc.callisto.srl@gmail.com>`__ (Romania) + * `Caio Sobreiro <mailto:caiosobreiro@gmail.com>`__ (Portuguese/English, Spain) * `Krzysztof Turkiewicz <mailto:deeveeloop@gmail.com>`__ (Polish/English, Poland) * `Salim Kanoun <https://github.com/salimkanoun>`__ (French/English/Arabic, France) * `Stephen D. Scotti <https://www.medinformatics.eu>`__ (English/Italian, Italy) @@ -203,6 +204,7 @@ * **South America**: + * `Caio Sobreiro <mailto:caiosobreiro@gmail.com>`__ (Portuguese/English, from Spain) * `Claudio Arenas <mailto:dentista.arenas@gmail.com>`__ (Spanish/English, Chile) * `Emilio Huaman <https://www.linkedin.com/in/emilio-alberto-huaman-vega-39719b22a/>`__ (English/Spanish, Perú) * `Fernando Sánchez <https://integraper.com/?page_id=529>`__ (English/Spanish, Peru) @@ -214,8 +216,8 @@ * **Africa**: * `Abdrahman Elkafil <mailto:elkafil@nextbehealthcare.com>`__ (English/French/Arabic, Belgium and Morocco) + * `Abdulazeez Alao <mailto:abdulazeezalao247@gmail.com>`__ (Nigeria) * `Olakunle Dada <mailto:holakunle69@gmail.com>`__ (English/French, Nigeria) - * `Abdulazeez Alao <mailto:abdulazeezalao247@gmail.com>`__ (Nigeria) * **Asia**: