Mercurial > hg > orthanc-book
annotate Sphinx/source/faq/features.rst @ 218:8bb11cd0f20f
links
author | amazy |
---|---|
date | Mon, 25 Feb 2019 19:01:45 +0100 |
parents | a577963a2176 |
children | 02399e86f046 |
rev | line source |
---|---|
0 | 1 Terminology of advanced features |
2 ================================ | |
3 | |
4 .. _peers: | |
5 | |
6 Peers | |
7 ----- | |
8 | |
9 An "Orthanc peer" is another instance of Orthanc, possibly running on | |
10 a remote computer. | |
11 | |
12 Contrarily to a "modality", it is possible to communicate with a peer | |
13 through the **HTTP/HTTPS protocol** (i.e. through the REST API of | |
14 Orthanc), and not through the DICOM protocol. This implies a much | |
15 easier configuration: It is only required to know the URL, the | |
16 username and the password to communicate with an Orthanc peer. This | |
17 contrasts with DICOM query/retrieve, that is quite complex and that | |
18 involves a lot of pitfalls (cf. the FAQ entry about :ref:`troubleshooting | |
19 DICOM communications <dicom>`) that can be bypassed if using HTTP. | |
20 | |
21 Furthermore, as HTTP(S) communications are generally not blocked by | |
22 firewalls (contrarily to the DICOM protocol that is inherently an | |
23 Intranet protocol and that often requires the setup of VPN tunnels), | |
24 it is much easier to setup communications of medical images through | |
218 | 25 the Internet with :ref:`Orthanc peers <peering>`. |
0 | 26 |
27 | |
28 .. _recycling: | |
29 | |
30 Recycling/Protection | |
31 -------------------- | |
32 | |
33 Because of its focus on low-end computers, Orthanc implements **disk | |
34 space recycling**: The patient that has been stored for the longest | |
35 time inside Orthanc can be automatically deleted when the disk space | |
36 used by Orthanc grows above a threshold, or when the number of stored | |
37 patients grows above a threshold. This feature enables the automated | |
106 | 38 control of the disk space dedicated to Orthanc. Note that pushing a |
39 new study for an existing patient will not change its position in the | |
40 recycling order. | |
0 | 41 |
42 Recycling is controlled by the ``MaximumStorageSize`` and the | |
43 ``MaximumPatientCount`` options in the :ref:`Orthanc configuration | |
106 | 44 file <configuration>`. Setting both these values to 0 will disable |
45 recycling. | |
0 | 46 |
47 It is possible to prevent important data from being automatically | |
48 recycled. This mechanism is called **protection**. Each patient can be | |
49 individually protected against recycling by using the | |
50 ``Unprotected/Protected`` switch that is available from Orthanc | |
51 Explorer. | |
52 | |
53 Note that protection is only available at the patient level. It | |
54 protects all the studies/series/instances of the patient against | |
55 recycling. The rationale is that we think it is important to keep | |
56 available all the data related to one patient. Unwillingly losing a | |
57 study/series that is part of the same patient might lead to a loss in | |
58 consistency with respect to the medical history of this patient. | |
59 | |
60 .. _compression: | |
61 | |
62 Compression | |
63 ----------- | |
64 | |
65 If your disk space is limited, besides :ref:`recycling`, you should | |
66 also consider using **disk space compression**. When compression is | |
67 enabled, Orthanc compresses the incoming DICOM instances on-the-fly | |
68 before writing them to the filesystem, using `zlib | |
25 | 69 <https://en.wikipedia.org/wiki/Zlib>`_. This is useful, because the |
0 | 70 images are often stored as raw, uncompressed arrays in DICOM |
71 instances: The size of a typical DICOM instance can hopefully be | |
72 divided by a factor 2 through lossless compression. This compression | |
73 process is transparent to the user, as Orthanc automatically | |
74 decompresses the file before sending it back to the external world. | |
75 | |
76 Compression is controlled by the ``StorageCompression`` option in the | |
77 :ref:`Orthanc configuration file <configuration>`. | |
78 | 78 |
79 | |
80 .. _metadata: | |
81 | |
92 | 82 Metadata & attachments |
83 ---------------------- | |
78 | 84 |
85 Metadata consists in an **associative key-value array** (mapping a | |
86 integer key in the range [0,65535] to a string value) that is | |
87 associated with each :ref:`DICOM resource <orthanc-ids>` stored inside | |
88 Orthanc (may it be a patient, a study, a series or a DICOM | |
89 instance). Metadata can be either referred to using the integer key, | |
90 or using a symbolic name (if configured). Metadata records | |
91 information that is not readily available in the DICOM tags. | |
92 | |
93 In spirit, the metadata mechanism is similar to the :ref:`attachment | |
94 mechanism <orthanc-storage>`. However, metadata is stored directly | |
95 inside the database, whereas attachments are stored as separate files | |
96 on the filesystem (the database only stores a reference to the | |
97 attachments). Choosing between metadata and attachments is a matter of | |
98 trade-off: Metadata must be kept small (as a rule of thumb, under 1KB) | |
99 and used if fast access is needed, whereas attachments can be used to | |
100 store arbitrarily large piece of data. | |
101 | |
79 | 102 Also note that metadata and attachments are only available for |
103 resources stored inside Orthanc. Once one DICOM instance leaves the | |
104 Orthanc ecosystem, its associated metadata and attachments are lost. | |
105 | |
78 | 106 |
107 Core metadata | |
108 ^^^^^^^^^^^^^ | |
109 | |
110 Here are the main metadata handled by the Orthanc core: | |
111 | |
112 * ``ReceptionDate`` records when a DICOM instance was received by | |
113 Orthanc. Similarly, ``LastUpdate`` records, for each | |
114 patient/study/series, the last time a DICOM instance was added to | |
115 this resource. | |
116 * ``RemoteAet`` records the AET of the modality that has sent some | |
117 DICOM instance to Orthanc. | |
118 * ``ModifiedFrom`` and ``AnonymizedFrom`` hold from which original | |
119 resource, a resource was modified or anonymized. The presence of | |
120 this metadata indicates that the resource is the result of a | |
121 modification or anonymization that was carried on by Orthanc. | |
122 * ``Origin`` records through which mechanism the instance was received | |
123 by Orthanc (may be ``Unknown``, ``DicomProtocol``, ``RestApi``, | |
124 ``Plugins``, or ``Lua``). | |
125 * ``IndexInSeries`` records the expected index of a DICOM instance | |
126 inside its parent series. Conversely, ``ExpectedNumberOfInstances`` | |
127 associates to each series, the number of DICOM instances this series | |
128 is expected to contain. | |
129 * Starting with Orthanc 1.2.0, ``TransferSyntax`` and ``SopClassUid`` | |
130 respectively stores the transfer syntax UID and the SOP class UID of | |
131 DICOM instances, in order to speed up the access to this | |
132 information. | |
133 | |
134 Metadata listed above are set privately by the Orthanc core. They are | |
135 **read-only** from the perspective of the end user, as Orthanc | |
136 internally relies on them. | |
137 | |
138 | |
139 User-defined metadata | |
140 ^^^^^^^^^^^^^^^^^^^^^ | |
141 | |
142 The metadata described above where handled by the core of Orthanc. | |
143 Orthanc users are however allowed to define their own **user-defined | |
144 metadata**. Such metadata are associated with an integer key that is | |
145 greater or equal to 1024 (whereas keys below 1023 are reserved for | |
146 core metadata). | |
147 | |
148 You can associate a symbolic name to user-defined metadata using the | |
149 ``UserMetadata`` option inside the :ref:`configuration of Orthanc | |
92 | 150 <configuration>`:: |
151 | |
152 "UserMetadata" : { | |
153 "SampleMetaData1" : 1024, | |
154 "SampleMetaData2" : 1025 | |
155 } | |
78 | 156 |
157 | |
158 Accessing metadata | |
159 ^^^^^^^^^^^^^^^^^^ | |
160 | |
161 .. highlight:: bash | |
162 | |
163 Metadata associated with one DICOM resource can be accessed through | |
80 | 164 the :ref:`REST API <rest>`, for instance:: |
78 | 165 |
166 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata | |
167 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/RemoteAet | |
92 | 168 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/SampleMetaData1 |
78 | 169 |
170 User-defined metadata can be modified by issuing a HTTP PUT against | |
171 the REST API:: | |
172 | |
173 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024 -X PUT -d 'hello' | |
174 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024 | |
175 hello | |
176 | |
177 | |
178 | |
92 | 179 .. _attachments: |
180 | |
181 User-defined attachments | |
182 ^^^^^^^^^^^^^^^^^^^^^^^^ | |
183 | |
184 Orthanc users are allowed to define their own **user-defined attachments**. | |
185 Such attachments are associated with an integer key that is | |
186 greater or equal to 1024 (whereas keys below 1023 are reserved for | |
187 core attachments). | |
188 | |
189 You can associate a symbolic name to user-defined attachments using the | |
190 ``UserContentType`` option inside the :ref:`configuration of Orthanc | |
191 <configuration>`. Optionally, the user may specify a MIME content type | |
192 for the attachment:: | |
193 | |
194 "UserContentType" : { | |
195 "samplePdf" : [1024, "application/pdf"], | |
196 "sampleJson" : [1025, "application/json"], | |
197 "sampleRaw" : 1026 | |
198 } | |
199 | |
200 Accessing attachments | |
201 ^^^^^^^^^^^^^^^^^^^^^ | |
202 | |
203 .. highlight:: bash | |
204 | |
205 Attachments associated with one DICOM resource can be accessed through | |
206 the :ref:`REST API <rest>`, for instance:: | |
207 | |
208 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/attachments/samplePdf/data | |
209 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/attachments/sampleJson/data | |
210 | |
211 User-defined attachments can be modified by issuing a HTTP PUT against | |
212 the REST API:: | |
213 | |
214 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/attachments/samplePdf -X PUT --data-binary @sample.pdf | |
215 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/attachments/sampleRaw -X PUT -d 'raw data' | |
216 | |
217 | |
78 | 218 .. _registry: |
219 | |
220 Central registry of metadata and attachments | |
221 -------------------------------------------- | |
222 | |
223 Obviously, one must pay attention to the fact that different | |
224 applications might use the same key to store different user-defined | |
225 :ref:`metadata <metadata>`, which might result in incompatibilities | |
226 between such applications. Similarly, incompatibilities might show up | |
227 for user-defined :ref:`attachments <orthanc-storage>`. | |
228 | |
229 Developers of applications/plugins that use user-defined metadata or | |
230 attachments are therefore kindly invited to complete the **central | |
231 registry** below: | |
232 | |
233 * ``Metadata 4200`` is used by the plugin for :ref:`whole-slide imaging <wsi>`. | |
170 | 234 * ``Attachment 9997`` is used by the `Osimis WebViewer plugin <https://bitbucket.org/osimis/osimis-webviewer-plugin>`__ to store series information. |
131 | 235 * ``Attachment 9998`` is used by the `Osimis WebViewer plugin <https://bitbucket.org/osimis/osimis-webviewer-plugin>`__ to store instance information. |
95
065350232191
added reference to attachment ids used by the Osimis Web Viewer
amazy
parents:
92
diff
changeset
|
236 * ``Attachment 9999`` is used by the `Osimis WebViewer plugin <https://bitbucket.org/osimis/osimis-webviewer-plugin>`__ to store annotations. |
065350232191
added reference to attachment ids used by the Osimis Web Viewer
amazy
parents:
92
diff
changeset
|
237 * ``Attachments 10000-13999`` are used by the `Osimis WebViewer plugin <https://bitbucket.org/osimis/osimis-webviewer-plugin>`__ to store reduced quality images. |