Mercurial > hg > orthanc-book

comparison Sphinx/source/faq/features.rst @ 78:d6bd1dd820e5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
metadata
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 14 Dec 2016 11:51:11 +0100
parents 669ea65ba7fb
children b77aa0655389
comparison
equal deleted inserted replaced
77:48c7d2eb98da 78:d6bd1dd820e5
71 process is transparent to the user, as Orthanc automatically 71 process is transparent to the user, as Orthanc automatically
72 decompresses the file before sending it back to the external world. 72 decompresses the file before sending it back to the external world.
73 73
74 Compression is controlled by the ``StorageCompression`` option in the 74 Compression is controlled by the ``StorageCompression`` option in the
75 :ref:`Orthanc configuration file <configuration>`. 75 :ref:`Orthanc configuration file <configuration>`.
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
100
101 Core metadata
102 ^^^^^^^^^^^^^
103
104 Here are the main metadata handled by the Orthanc core:
105
106 * ``ReceptionDate`` records when a DICOM instance was received by
107 Orthanc. Similarly, ``LastUpdate`` records, for each
108 patient/study/series, the last time a DICOM instance was added to
109 this resource.
110 * ``RemoteAet`` records the AET of the modality that has sent some
111 DICOM instance to Orthanc.
112 * ``ModifiedFrom`` and ``AnonymizedFrom`` hold from which original
113 resource, a resource was modified or anonymized. The presence of
114 this metadata indicates that the resource is the result of a
115 modification or anonymization that was carried on by Orthanc.
116 * ``Origin`` records through which mechanism the instance was received
117 by Orthanc (may be ``Unknown``, ``DicomProtocol``, ``RestApi``,
118 ``Plugins``, or ``Lua``).
119 * ``IndexInSeries`` records the expected index of a DICOM instance
120 inside its parent series. Conversely, ``ExpectedNumberOfInstances``
121 associates to each series, the number of DICOM instances this series
122 is expected to contain.
123 * Starting with Orthanc 1.2.0, ``TransferSyntax`` and ``SopClassUid``
124 respectively stores the transfer syntax UID and the SOP class UID of
125 DICOM instances, in order to speed up the access to this
126 information.
127
128 Metadata listed above are set privately by the Orthanc core. They are
129 **read-only** from the perspective of the end user, as Orthanc
130 internally relies on them.
131
132
133 User-defined metadata
134 ^^^^^^^^^^^^^^^^^^^^^
135
136 The metadata described above where handled by the core of Orthanc.
137 Orthanc users are however allowed to define their own **user-defined
138 metadata**. Such metadata are associated with an integer key that is
139 greater or equal to 1024 (whereas keys below 1023 are reserved for
140 core metadata).
141
142 You can associate a symbolic name to user-defined metadata using the
143 ``UserMetadata`` option inside the :ref:`configuration of Orthanc
144 <configuration>`.
145
146
147 Accessing metadata
148 ^^^^^^^^^^^^^^^^^^
149
150 .. highlight:: bash
151
152 Metadata associated with one DICOM resource can be accessed through
153 the REST API, for instance::
154
155 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata
156 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/RemoteAet
157
158 User-defined metadata can be modified by issuing a HTTP PUT against
159 the REST API::
160
161 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024 -X PUT -d 'hello'
162 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024
163 hello
164
165
166
167 .. _registry:
168
169 Central registry of metadata and attachments
170 --------------------------------------------
171
172 Obviously, one must pay attention to the fact that different
173 applications might use the same key to store different user-defined
174 :ref:`metadata <metadata>`, which might result in incompatibilities
175 between such applications. Similarly, incompatibilities might show up
176 for user-defined :ref:`attachments <orthanc-storage>`.
177
178 Developers of applications/plugins that use user-defined metadata or
179 attachments are therefore kindly invited to complete the **central
180 registry** below:
181
182 * ``Metadata 4200`` is used by the plugin for :ref:`whole-slide imaging <wsi>`.