# HG changeset patch # User Sebastien Jodogne # Date 1681656946 -7200 # Node ID 5491953f749211e3e8c3c8c23d0da4547248c04d # Parent 49b863e47c391c8f32eafc004317bf8bdbafa4ba documentation of labels diff -r 49b863e47c39 -r 5491953f7492 Sphinx/source/faq/features.rst --- a/Sphinx/source/faq/features.rst Sun Apr 16 13:50:18 2023 +0200 +++ b/Sphinx/source/faq/features.rst Sun Apr 16 16:55:46 2023 +0200 @@ -433,9 +433,9 @@ Check out the `OpenAPI reference `__ of the REST API of Orthanc for more information. -**Warning:** The database index back-end must support revisions. As of -writing, only the **PostgreSQL plugins** in versions above 4.0 and the -**ODBC plugins** implement support for revisions. +**Warning:** The database index back-end must implement support for +revisions. As of writing, only the **PostgreSQL plugins** in versions +above 4.0 and the **ODBC plugins** implement support for revisions. Synchronous vs. asynchronous C-MOVE SCP @@ -469,3 +469,82 @@ C-MOVE client and a hospital-wide PACS. This can be interesting to introduce compatibility with specialized image processing applications. + + +.. _labels: + +Labels +------ + +.. highlight:: text + +Orthanc 1.12.0 introduces the concept of **labels**. A label is a +string that can be attached to any DICOM resource (i.e. patients, +studies, series, or instances). In contrast with :ref:`metadata +`, labels are not associated with a value, however labels +are **indexed in the Orthanc database** for efficient lookups. + +Labels can notably be used as the building block to implement +**multi-tenancy**, which means that a single database could be shared +between different tenants that are distinguished by different labels. +This idea is illustrated by the :ref:`multitenant DICOM server +` sample plugin. A similar approach could be used +to implement Web interfaces that restrict the resources that are +accessible to some users by assigning labels to users. Labels are also +useful in **machine learning** (or deep learning) workflows to +separate DICOM resources belonging to the training set or to the +testing set. + +The labels attached to one given DICOM resource can be read through +the REST API:: + + $ curl http://localhost:8042/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/labels + $ curl http://localhost:8042/series/3774320f-ccda46d8-69ee8641-9e791cbf-3ecbbcc6/labels + $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels + $ curl http://localhost:8042/patients/ef9d77db-eb3b2bef-9b31fd3e-bf42ae46-dbdb0cc3/labels + +A label can be added to one DICOM resource using the PUT HTTP method, +and can be removed using the DELETE HTTP method:: + + $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels + [] + $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels/hello -X PUT -d '' + $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels + [ "hello" ] + $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels/hello -X DELETE + $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels + [] + +The built-in :ref:`Orthanc Explorer ` Web interface +can be used to display, add, and remove labels. + +Once labels are set, the ``/tools/find`` :ref:`route of the REST API +` of Orthanc can be used to efficiently look for the DICOM +resources that are associated with given labels. This is done by +providing the set of labels of interest in the ``Labels`` field, as +illustrated in the following request:: + + $ curl --request POST --url http://localhost:8042/tools/find \ + --data '{ + "Level" : "Study", + "Labels" : [ "hello" ], + "LabelsConstraint" : "All", + "Query" : { } + }' + +The ``LabelsConstraint`` field can be used to control the request over +the labels. Its value can be ``All`` (to return the resources that are +associated with all the labels provided in the ``Labels`` field at +once), ``Any`` (to return the resources that are associated with at +least one of the labels provided in the ``Labels`` field), or ``None`` +(to return the resources that are associated with none of the labels +provided in the ``Labels`` field). If not provided, +``LabelsConstraint`` defaults to ``All``. Note that in the if there is +only one label in the ``Labels`` field, both ``Any`` and ``All`` have +the same behavior. + + +**Warning:** The database index back-end must implement support for +labels. As of writing, only the **PostgreSQL plugins** in versions +above 5.0 and the **MySQL plugins** in version above 5.0 implement +support for labels. diff -r 49b863e47c39 -r 5491953f7492 Sphinx/source/plugins.rst --- a/Sphinx/source/plugins.rst Sun Apr 16 13:50:18 2023 +0200 +++ b/Sphinx/source/plugins.rst Sun Apr 16 16:55:46 2023 +0200 @@ -86,6 +86,7 @@ plugins/indexer.rst plugins/neuro.rst plugins/volview.rst + plugins/multitenant-dicom.rst .. _plugins-contributed: diff -r 49b863e47c39 -r 5491953f7492 Sphinx/source/plugins/multitenant-dicom.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/plugins/multitenant-dicom.rst Sun Apr 16 16:55:46 2023 +0200 @@ -0,0 +1,77 @@ +.. _multitenant-dicom: + + +Sample multitenant DICOM server +=============================== + +.. contents:: + +This **official** plugin by the `ICTEAM institute of UCLouvain +`__ can be used to +turn Orthanc into a **multitenant DICOM** server using :ref:`labels +`. More precisely, the same Orthanc database can be accessed +from different DICOM servers, that each provides a different view +depending on the presence of labels. This plugin available is part of +the `official source distribution +`__ +of Orthanc, starting with Orthanc 1.12.0. + +This plugin starts additional DICOM servers, in complement to the main +DICOM server of Orthanc that provides full access to the Orthanc +database. These additional DICOM servers support the C-Find, C-Move, +and C-Store commands, and share most of their configuration with the +main DICOM server of Orthanc. They are however distinguished from the +latter by using a **different AET** and a **different TCP +port**. Furthermore, each of those additional DICOM servers are +associated with a **set of labels** that restricts which DICOM +resources stored in Orthanc are accessible through this additional +DICOM server. + +.. highlight:: json + +Here is a sample :ref:`configuration file ` to use this +plugin:: + + { + "Plugins" : [ "." ], + "DicomModalities" : { + "sample" : [ "STORESCP", "127.0.0.1", 2000 ] + }, + "MultitenantDicom" : { + "Servers" : [ + { + "AET" : "HELLO", + "Port" : 4343, + "Labels" : [ "hello" ], + "LabelsConstraint" : "All", + "LabelsStoreLevels" : [ "Patient", "Study", "Series", "Instance" ] + } + ] + } + } + +This configuration will start an additional DICOM server with AET +``HELLO`` listening on the 4343 port. This DICOM server will work as +follows: + +* DICOM C-Find and C-Move requests are restricted to the DICOM + resources that are assigned with the ``hello`` label. + + * Note that the labels are checked by query/retrieve level: For + instance, if ``QueryRetrieveLevel (0008, 0052)`` equals ``STUDY``, + the plugin will only report the studies that are associated with + the ``hello`` label. + + * The ``LabelsConstraint`` specifies the type of constraint on the + labels. Its value can be ``All`` (default), ``Any``, or ``None``, + which corresponds to the values accepted by the ``/tools/find`` + :ref:`route in the REST API ` of Orthanc. Note that in the + sample configuration above, because there is only one label in the + ``Labels`` field, both ``Any`` and ``All`` have the same behavior. + +* Any DICOM resource that is received through DICOM C-Store requests + issued to this additional DICOM server, is automatically associated + with all the labels provided in the ``Labels`` field. The + configuration option ``LabelsStoreLevels`` can be used to restrict + the levels to which the labels are applied (it defaults to the three + study, series, and instances levels). diff -r 49b863e47c39 -r 5491953f7492 Sphinx/source/users/rest.rst --- a/Sphinx/source/users/rest.rst Sun Apr 16 13:50:18 2023 +0200 +++ b/Sphinx/source/users/rest.rst Sun Apr 16 16:55:46 2023 +0200 @@ -1090,8 +1090,7 @@ $ curl -X POST http://localhost:8042/tools/find -d '{"Level":"Series","Query":{"DeviceSerialNumber":"123\\abc"},"Expand":true}' - - + Additional Options ^^^^^^^^^^^^^^^^^^ .. highlight:: json @@ -1144,6 +1143,11 @@ ] +**Important:** Starting with Orthanc 1.12.0, this route in the REST +API also provide the ``Labels`` and ``LabelsConstraint`` options to +bring support for :ref:`labels `. + + .. _changes: Tracking changes