Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/orthanc-explorer-2.rst @ 1092:eb6be558334b
note on oe2
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Fri, 12 Jul 2024 09:37:11 +0200 |
| parents | bb92aeb7dbde |
| children | ad86e352fce1 |
| rev | line source |
|---|---|
| 845 | 1 .. _orthanc-explorer-2: |
| 2 | |
| 3 | |
| 4 Orthanc Explorer 2 plugin | |
| 5 ========================= | |
| 6 | |
| 7 .. contents:: | |
| 8 | |
| 9 | |
| 10 Introduction | |
| 11 ------------ | |
| 12 | |
| 13 This plugin provides a new User Interface (UI) to Orthanc. It aims at being | |
| 14 more user-friendly, more configurable and more evolutive than the default | |
| 15 Orthanc UI which was developed mainly for testing/administrative purpose. | |
| 16 | |
| 17 .. image:: ../images/OE2-screenshot-study-list.png | |
| 18 :align: center | |
| 19 :width: 1000px | |
| 20 | |
| 21 | | |
| 22 | |
| 23 Note that a major difference between the legacy UI and Orthanc Explorer 2 (OE2) | |
| 24 is that OE2 works only at the study level, not the patient level. The main page is | |
| 25 the study list in which, of course, you can apply a filter to display only the studies of a single patient. | |
| 26 | |
| 924 | 27 Since version 0.7.0, once connected to `Keycloak <https://www.keycloak.org/>`__ and the `orthanc-auth-service <https://github.com/orthanc-team/orthanc-auth-service>`__, |
| 28 OE2 is able to handle user permissions and sharing of links to access a single study. This is demonstrated in `this sample <https://github.com/orthanc-team/orthanc-auth-service/tree/main/minimal-setup/keycloak>`__. | |
| 845 | 29 |
| 30 How to get it ? | |
| 31 --------------- | |
| 32 | |
| 33 The source code is available on `GitHub <https://github.com/orthanc-server/orthanc-explorer-2>`__. | |
| 34 | |
| 35 Binaries are included in: | |
| 36 | |
|
1023
5d4701d8fe28
replaced osimis/orthanc by orthancteam/orthanc
Alain Mazy <am@osimis.io>
parents:
994
diff
changeset
|
37 - The `orthancteam/orthanc Docker image <https://hub.docker.com/r/orthancteam/orthanc>`__ |
| 1092 | 38 - The :ref:`jodogne/orthanc-plugins Docker image <https://orthanc.uclouvain.be/book/users/docker.html>` |
| 39 - The `Windows Installers <https://orthanc.uclouvain.be/downloads/windows-64/installers/index.html>`__ | |
|
994
df9162e80fc8
Osimis has discontinued the sample demo server for the Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
924
diff
changeset
|
40 - The `macOS packages <https://orthanc.uclouvain.be/downloads/macos/packages/index.html>`__ |
| 845 | 41 |
| 42 Release notes are available `here <https://github.com/orthanc-server/orthanc-explorer-2/blob/master/release-notes.md>`__. | |
| 43 | |
| 44 Depending on the configuration, the plugin can replace the default Orthanc UI you are redirected to when accessing orthanc at `http://localhost:8042/ <http://localhost:8042/>`__. | |
| 45 In any case, the new and old UI can coexist: | |
| 46 | |
| 47 - Orthanc Explorer 2 is available at `http://localhost:8042/ui/app/ <http://localhost:8042/ui/app/>`__ | |
| 48 - Legacy UI remains available at `http://localhost:8042/app/explorer.html <http://localhost:8042/app/explorer.html>`__ | |
| 49 | |
| 50 | |
| 51 Configuration | |
| 52 ------------- | |
| 53 | |
| 54 .. highlight:: json | |
| 55 | |
| 56 The plugin must be configured through a configuration file. The minimal configuration to include in your orthanc configuration file is:: | |
| 57 | |
| 58 "OrthancExplorer2" : { | |
| 59 "Enable": true, | |
| 60 "IsDefaultOrthancUI": true | |
| 61 } | |
| 62 | |
| 63 There are many more options that are documented in the | |
| 64 `default configuration file <https://github.com/orthanc-server/orthanc-explorer-2/blob/master/Plugin/DefaultConfiguration.json>`__. | |
| 65 | |
| 66 | |
| 67 Advanced features | |
| 68 ----------------- | |
| 69 | |
| 924 | 70 User permissions and web diffusion |
| 71 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 72 | |
| 73 Check the documentation of the `orthanc-auth-service <https://github.com/orthanc-team/orthanc-auth-service>`__ | |
| 74 companion web service that provides user permissions and sharing of studies. | |
| 75 | |
| 915 | 76 |
| 77 Direct access to a selection of studies | |
| 78 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 79 | |
| 845 | 80 You may open the OE2 interface directly on a specific study or patient by specifying DICOM Tags directly in the URL. |
| 81 e.g:: | |
| 82 | |
| 869 | 83 http://localhost:8042/ui/app/#/filtered-studies?PatientID="00000169" |
| 845 | 84 http://localhost:8042/ui/app/#/filtered-studies?StudyDate=20220512-20220513&ModalitiesInStudy=CR\DX |
| 869 | 85 http://localhost:8042/ui/app/#/filtered-studies?StudyInstanceUID="1.2.3" |
| 86 http://localhost:8042/ui/app/#/filtered-studies?StudyInstanceUID="1.2.3"&expand | |
| 87 http://localhost:8042/ui/app/#/filtered-studies?StudyInstanceUID="1.2.3"&expand=study | |
| 88 http://localhost:8042/ui/app/#/filtered-studies?StudyInstanceUID="1.2.3"&expand=series | |
| 89 | |
| 90 By default, OE2 will add a wildcard ``*`` at the beginning and at the end of the search text. Therefore, searching | |
| 91 for ``PatientID=1234`` will actually search for ``PatientID=*1234*``. If you do not want to have these extra wildcards | |
| 92 added, you should use ``"`` at the beginning and/or at the end of the search text. Therefore, searching for | |
| 93 ``PatientID="1234"`` will return only the studies whose ``PatientID`` is exactly ``1234``. | |
| 94 These ``"`` can also be used in the User Interface search fields. | |
| 845 | 95 |
| 96 | |
| 915 | 97 DICOM Modifications |
| 98 ^^^^^^^^^^^^^^^^^^^ | |
| 99 | |
| 100 Since version 0.6.0, it is possible to edit some of the DICOM Tags directly in the User Interface. | |
| 101 :ref:`DICOM Modification <anonymization>` is quite a complex topic that is provided by Orthanc | |
| 102 Rest API. The Orthanc Explorer 2 User Interface aims at simplifying its use but is also limiting | |
| 103 it to common use cases mainly related to correcting errors in Patient and Study DICOM Tags. | |
| 104 | |
| 105 At study level, it is possible to: | |
| 106 | |
| 107 - Modify a Study | |
| 108 | |
| 109 - to attach it to another existing patient by providing the ``PatientID`` if e.g. the study was | |
| 110 acquired for the wrong patient. | |
| 111 - to edit the patient in all its studies if e.g. the ``PatientName`` was misspelled. | |
| 112 - correct patient or study tags in this study only if e.g. the ``StudyDescription`` was incorrect. | |
| 113 | |
| 114 - Anonymize a Study and possibly provide the anonymized ``PatientID`` or ``PatientName`` to | |
| 115 e.g. force it to a specific identifier for a clinical study. | |
| 116 | |
| 117 .. image:: ../images/OE2-modify-study.png | |
| 118 :align: center | |
| 119 :width: 1000px | |
| 120 | |
| 121 | | |
| 122 | |
| 123 | |
| 124 At series level, it is possible to: | |
| 125 | |
| 126 - Modify a Series | |
| 127 | |
| 128 - to move it to another existing study by providing the ``StudyInstanceUID`` if e.g. the operator | |
| 129 forgot to switch patient in the modality | |
| 130 - to move it to a new study if e.g. the operator forgot to switch patient in the modality | |
| 131 - correct series tags in this series only if e.g. the ``SeriesDescription`` was incorrect. | |
| 132 | |
| 133 - Anonymize a Series and possibly provide the anonymized ``PatientID`` or ``PatientName`` to | |
| 134 e.g. force it to a specific identifier for a clinical study. | |
| 135 | |
| 136 .. image:: ../images/OE2-modify-series.png | |
| 137 :align: center | |
| 138 :width: 1000px | |
| 139 | |
| 140 | | |
| 141 | |
| 142 Each time you modify a study, the user interface might propose you 3 modification modes related to | |
| 143 the handling of the :ref:`DICOM identifiers <dicom-identifiers>` . | |
| 144 | |
| 145 - You may modify the original study and have Orthanc generates new ``StudyInstanceUID``, ``SeriesInstanceUID`` | |
| 146 and ``SOPInstanceUID`` DICOM Tags. This means the that orthanc identifiers will change and the source | |
| 147 study will be deleted. | |
| 148 - You may keep the original ``StudyInstanceUID``, ``SeriesInstanceUID`` and ``SOPInstanceUID`` DICOM Tags. | |
| 149 This means the that orthanc identifiers will not change (unless you also change the ``PatientID`` and the | |
| 916 | 150 study will be modified "in place"). |
| 915 | 151 - You may keep the original study and create a modified copy. In this case, of course, the new modified copy |
| 152 will have a different orthanc identifiers. | |
| 153 | |
| 154 | |
| 155 .. image:: ../images/OE2-modify-options.png | |
| 156 :align: center | |
| 157 :width: 700px | |
| 158 | |
| 159 | | |
| 160 | |
| 161 There are many options related to DICOM Modification in the plugin | |
| 162 `default configuration file <https://github.com/orthanc-server/orthanc-explorer-2/blob/master/Plugin/DefaultConfiguration.json>`__. | |
| 163 Check the ``Modifications`` section and the ``PatientMainTags``, ``StudyMainTags``, ``SeriesMainTags``, ``EnableAnonymization`` | |
| 164 and ``EnableModification`` configurations. | |
| 165 | |
| 166 | |
| 922 | 167 Retrieve a study from a distant modality and open the viewer |
| 168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 845 | 169 |
| 922 | 170 If you want to open e.g. the :ref:`Stone Web viewer <stone_webviewer>`:: on a study that is not yet |
| 171 stored in Orthanc but that you know that it is stored in a remote modality, you may use this endpoint:: | |
| 172 | |
| 923 | 173 http://localhost:8042/ui/app/retrieve-and-view.html?StudyInstanceUID=1.2.3....&modality=pacs&viewer=stone-viewer |
| 845 | 174 |
| 922 | 175 This will first check if the study is already in Orthanc, if not, it will retrieve it from the modality and, |
| 176 once the transfer is complete, open the viewer. | |
| 845 | 177 |
| 922 | 178 This feature has been introduced in v 0.7.0. |
| 845 | 179 |
| 180 | |
| 1044 | 181 Theming the interface |
| 182 ^^^^^^^^^^^^^^^^^^^^^ | |
| 183 | |
| 184 Since v 1.3.0, one can chose between 2 default themes: ``dark`` and ``light`` through the ``"Theme"`` configuration. | |
| 185 | |
| 186 Furthermore, it is also possible to customize further the UI by providing a custom logo from a file or url. | |
| 187 | |
| 188 For advanced users, it is also possible to provide a custom `CSS <https://en.wikipedia.org/wiki/CSS>`__ to customize | |
| 189 the UI appearance. You may get inspiration from the default `dark <https://github.com/orthanc-server/orthanc-explorer-2/blob/master/WebApplication/src/assets/css/defaults-dark.css>`__ | |
| 190 and `light <https://github.com/orthanc-server/orthanc-explorer-2/blob/master/WebApplication/src/assets/css/defaults-light.css>`__ CSS:: | |
| 191 | |
| 192 { | |
| 193 "OrthancExplorer2": { | |
| 1045 | 194 "Theme": "light", // or "dark" |
| 195 "CustomCssPath": "/home/my/path/to/custom.css" // optional customized CSS | |
| 196 "CustomLogoUrl": "https://my.company/logo.png", // optional custom logo from url | |
| 197 "CustomLogoPath": "/home/my/path/to/logo.png", // optional custom logo from file | |
| 198 "UiOptions" : { | |
| 199 // ... | |
| 1044 | 200 } |
| 201 } | |
| 202 } | |
| 203 | |
| 204 You'll also find a full sample of OE2 customization `here <https://github.com/orthanc-server/orthanc-setup-samples/tree/master/docker/oe2-custom>`__. | |
| 205 | |
| 206 | |
| 845 | 207 Bug reports & support |
| 208 --------------------- | |
| 209 | |
| 1044 | 210 As usual, you can get support and report issues from the `Orthanc Users group <https://discourse.orthanc-server.org/>`__. |
| 845 | 211 |
| 212 You may also directly introduce bugs or feature requests in `GitHub <https://github.com/orthanc-server/orthanc-explorer-2/issues>`__. | |
| 213 | |
| 922 | 214 The plugin is currently maintained by the `Orthanc Team <https://orthanc.team/>`__ who, like many of you, enjoys |
| 215 receiving a salary for his work. Feel free to hire us if you need a specific feature or bug fixed. | |
| 845 | 216 |
| 217 Donations to `Open Collective <https://opencollective.com/orthanc>`__ may also be used to maintain/develop this plugin. |