|
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
|
|
|
25 the Internet with Orthanc peers.
|
|
|
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
|
|
|
38 control of the disk space dedicated to Orthanc.
|
|
|
39
|
|
|
40 Recycling is controlled by the ``MaximumStorageSize`` and the
|
|
|
41 ``MaximumPatientCount`` options in the :ref:`Orthanc configuration
|
|
|
42 file <configuration>`.
|
|
|
43
|
|
|
44 It is possible to prevent important data from being automatically
|
|
|
45 recycled. This mechanism is called **protection**. Each patient can be
|
|
|
46 individually protected against recycling by using the
|
|
|
47 ``Unprotected/Protected`` switch that is available from Orthanc
|
|
|
48 Explorer.
|
|
|
49
|
|
|
50 Note that protection is only available at the patient level. It
|
|
|
51 protects all the studies/series/instances of the patient against
|
|
|
52 recycling. The rationale is that we think it is important to keep
|
|
|
53 available all the data related to one patient. Unwillingly losing a
|
|
|
54 study/series that is part of the same patient might lead to a loss in
|
|
|
55 consistency with respect to the medical history of this patient.
|
|
|
56
|
|
|
57
|
|
|
58 .. _compression:
|
|
|
59
|
|
|
60 Compression
|
|
|
61 -----------
|
|
|
62
|
|
|
63 If your disk space is limited, besides :ref:`recycling`, you should
|
|
|
64 also consider using **disk space compression**. When compression is
|
|
|
65 enabled, Orthanc compresses the incoming DICOM instances on-the-fly
|
|
|
66 before writing them to the filesystem, using `zlib
|
|
25
|
67 <https://en.wikipedia.org/wiki/Zlib>`_. This is useful, because the
|
|
0
|
68 images are often stored as raw, uncompressed arrays in DICOM
|
|
|
69 instances: The size of a typical DICOM instance can hopefully be
|
|
|
70 divided by a factor 2 through lossless compression. This compression
|
|
|
71 process is transparent to the user, as Orthanc automatically
|
|
|
72 decompresses the file before sending it back to the external world.
|
|
|
73
|
|
|
74 Compression is controlled by the ``StorageCompression`` option in the
|
|
|
75 :ref:`Orthanc configuration file <configuration>`.
|
|
78
|
76
|
|
|
77
|
|
|
78 .. _metadata:
|
|
|
79
|
|
|
80 Metadata
|
|
|
81 --------
|
|
|
82
|
|
|
83 Metadata consists in an **associative key-value array** (mapping a
|
|
|
84 integer key in the range [0,65535] to a string value) that is
|
|
|
85 associated with each :ref:`DICOM resource <orthanc-ids>` stored inside
|
|
|
86 Orthanc (may it be a patient, a study, a series or a DICOM
|
|
|
87 instance). Metadata can be either referred to using the integer key,
|
|
|
88 or using a symbolic name (if configured). Metadata records
|
|
|
89 information that is not readily available in the DICOM tags.
|
|
|
90
|
|
|
91 In spirit, the metadata mechanism is similar to the :ref:`attachment
|
|
|
92 mechanism <orthanc-storage>`. However, metadata is stored directly
|
|
|
93 inside the database, whereas attachments are stored as separate files
|
|
|
94 on the filesystem (the database only stores a reference to the
|
|
|
95 attachments). Choosing between metadata and attachments is a matter of
|
|
|
96 trade-off: Metadata must be kept small (as a rule of thumb, under 1KB)
|
|
|
97 and used if fast access is needed, whereas attachments can be used to
|
|
|
98 store arbitrarily large piece of data.
|
|
|
99
|
|
79
|
100 Also note that metadata and attachments are only available for
|
|
|
101 resources stored inside Orthanc. Once one DICOM instance leaves the
|
|
|
102 Orthanc ecosystem, its associated metadata and attachments are lost.
|
|
|
103
|
|
78
|
104
|
|
|
105 Core metadata
|
|
|
106 ^^^^^^^^^^^^^
|
|
|
107
|
|
|
108 Here are the main metadata handled by the Orthanc core:
|
|
|
109
|
|
|
110 * ``ReceptionDate`` records when a DICOM instance was received by
|
|
|
111 Orthanc. Similarly, ``LastUpdate`` records, for each
|
|
|
112 patient/study/series, the last time a DICOM instance was added to
|
|
|
113 this resource.
|
|
|
114 * ``RemoteAet`` records the AET of the modality that has sent some
|
|
|
115 DICOM instance to Orthanc.
|
|
|
116 * ``ModifiedFrom`` and ``AnonymizedFrom`` hold from which original
|
|
|
117 resource, a resource was modified or anonymized. The presence of
|
|
|
118 this metadata indicates that the resource is the result of a
|
|
|
119 modification or anonymization that was carried on by Orthanc.
|
|
|
120 * ``Origin`` records through which mechanism the instance was received
|
|
|
121 by Orthanc (may be ``Unknown``, ``DicomProtocol``, ``RestApi``,
|
|
|
122 ``Plugins``, or ``Lua``).
|
|
|
123 * ``IndexInSeries`` records the expected index of a DICOM instance
|
|
|
124 inside its parent series. Conversely, ``ExpectedNumberOfInstances``
|
|
|
125 associates to each series, the number of DICOM instances this series
|
|
|
126 is expected to contain.
|
|
|
127 * Starting with Orthanc 1.2.0, ``TransferSyntax`` and ``SopClassUid``
|
|
|
128 respectively stores the transfer syntax UID and the SOP class UID of
|
|
|
129 DICOM instances, in order to speed up the access to this
|
|
|
130 information.
|
|
|
131
|
|
|
132 Metadata listed above are set privately by the Orthanc core. They are
|
|
|
133 **read-only** from the perspective of the end user, as Orthanc
|
|
|
134 internally relies on them.
|
|
|
135
|
|
|
136
|
|
|
137 User-defined metadata
|
|
|
138 ^^^^^^^^^^^^^^^^^^^^^
|
|
|
139
|
|
|
140 The metadata described above where handled by the core of Orthanc.
|
|
|
141 Orthanc users are however allowed to define their own **user-defined
|
|
|
142 metadata**. Such metadata are associated with an integer key that is
|
|
|
143 greater or equal to 1024 (whereas keys below 1023 are reserved for
|
|
|
144 core metadata).
|
|
|
145
|
|
|
146 You can associate a symbolic name to user-defined metadata using the
|
|
|
147 ``UserMetadata`` option inside the :ref:`configuration of Orthanc
|
|
|
148 <configuration>`.
|
|
|
149
|
|
|
150
|
|
|
151 Accessing metadata
|
|
|
152 ^^^^^^^^^^^^^^^^^^
|
|
|
153
|
|
|
154 .. highlight:: bash
|
|
|
155
|
|
|
156 Metadata associated with one DICOM resource can be accessed through
|
|
80
|
157 the :ref:`REST API <rest>`, for instance::
|
|
78
|
158
|
|
|
159 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata
|
|
|
160 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/RemoteAet
|
|
|
161
|
|
|
162 User-defined metadata can be modified by issuing a HTTP PUT against
|
|
|
163 the REST API::
|
|
|
164
|
|
|
165 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024 -X PUT -d 'hello'
|
|
|
166 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024
|
|
|
167 hello
|
|
|
168
|
|
|
169
|
|
|
170
|
|
|
171 .. _registry:
|
|
|
172
|
|
|
173 Central registry of metadata and attachments
|
|
|
174 --------------------------------------------
|
|
|
175
|
|
|
176 Obviously, one must pay attention to the fact that different
|
|
|
177 applications might use the same key to store different user-defined
|
|
|
178 :ref:`metadata <metadata>`, which might result in incompatibilities
|
|
|
179 between such applications. Similarly, incompatibilities might show up
|
|
|
180 for user-defined :ref:`attachments <orthanc-storage>`.
|
|
|
181
|
|
|
182 Developers of applications/plugins that use user-defined metadata or
|
|
|
183 attachments are therefore kindly invited to complete the **central
|
|
|
184 registry** below:
|
|
|
185
|
|
|
186 * ``Metadata 4200`` is used by the plugin for :ref:`whole-slide imaging <wsi>`.
|
