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. |