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