# HG changeset patch # User Sebastien Jodogne # Date 1481712671 -3600 # Node ID d6bd1dd820e55a06c9714a2154fed8c568fbda55 # Parent 48c7d2eb98da6ae139375abd98e44f69760b4ebb metadata diff -r 48c7d2eb98da -r d6bd1dd820e5 Sphinx/source/faq/features.rst --- a/Sphinx/source/faq/features.rst Wed Dec 14 11:04:32 2016 +0100 +++ b/Sphinx/source/faq/features.rst Wed Dec 14 11:51:11 2016 +0100 @@ -73,3 +73,110 @@ Compression is controlled by the ``StorageCompression`` option in the :ref:`Orthanc configuration file `. + + +.. _metadata: + +Metadata +-------- + +Metadata consists in an **associative key-value array** (mapping a +integer key in the range [0,65535] to a string value) that is +associated with each :ref:`DICOM resource ` stored inside +Orthanc (may it be a patient, a study, a series or a DICOM +instance). Metadata can be either referred to using the integer key, +or using a symbolic name (if configured). Metadata records +information that is not readily available in the DICOM tags. + +In spirit, the metadata mechanism is similar to the :ref:`attachment +mechanism `. However, metadata is stored directly +inside the database, whereas attachments are stored as separate files +on the filesystem (the database only stores a reference to the +attachments). Choosing between metadata and attachments is a matter of +trade-off: Metadata must be kept small (as a rule of thumb, under 1KB) +and used if fast access is needed, whereas attachments can be used to +store arbitrarily large piece of data. + + +Core metadata +^^^^^^^^^^^^^ + +Here are the main metadata handled by the Orthanc core: + +* ``ReceptionDate`` records when a DICOM instance was received by + Orthanc. Similarly, ``LastUpdate`` records, for each + patient/study/series, the last time a DICOM instance was added to + this resource. +* ``RemoteAet`` records the AET of the modality that has sent some + DICOM instance to Orthanc. +* ``ModifiedFrom`` and ``AnonymizedFrom`` hold from which original + resource, a resource was modified or anonymized. The presence of + this metadata indicates that the resource is the result of a + modification or anonymization that was carried on by Orthanc. +* ``Origin`` records through which mechanism the instance was received + by Orthanc (may be ``Unknown``, ``DicomProtocol``, ``RestApi``, + ``Plugins``, or ``Lua``). +* ``IndexInSeries`` records the expected index of a DICOM instance + inside its parent series. Conversely, ``ExpectedNumberOfInstances`` + associates to each series, the number of DICOM instances this series + is expected to contain. +* Starting with Orthanc 1.2.0, ``TransferSyntax`` and ``SopClassUid`` + respectively stores the transfer syntax UID and the SOP class UID of + DICOM instances, in order to speed up the access to this + information. + +Metadata listed above are set privately by the Orthanc core. They are +**read-only** from the perspective of the end user, as Orthanc +internally relies on them. + + +User-defined metadata +^^^^^^^^^^^^^^^^^^^^^ + +The metadata described above where handled by the core of Orthanc. +Orthanc users are however allowed to define their own **user-defined +metadata**. Such metadata are associated with an integer key that is +greater or equal to 1024 (whereas keys below 1023 are reserved for +core metadata). + +You can associate a symbolic name to user-defined metadata using the +``UserMetadata`` option inside the :ref:`configuration of Orthanc +`. + + +Accessing metadata +^^^^^^^^^^^^^^^^^^ + +.. highlight:: bash + +Metadata associated with one DICOM resource can be accessed through +the REST API, for instance:: + + $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata + $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/RemoteAet + +User-defined metadata can be modified by issuing a HTTP PUT against +the REST API:: + + $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024 -X PUT -d 'hello' + $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024 + hello + + + +.. _registry: + +Central registry of metadata and attachments +-------------------------------------------- + +Obviously, one must pay attention to the fact that different +applications might use the same key to store different user-defined +:ref:`metadata `, which might result in incompatibilities +between such applications. Similarly, incompatibilities might show up +for user-defined :ref:`attachments `. + +Developers of applications/plugins that use user-defined metadata or +attachments are therefore kindly invited to complete the **central +registry** below: + +* ``Metadata 4200`` is used by the plugin for :ref:`whole-slide imaging `. diff -r 48c7d2eb98da -r d6bd1dd820e5 Sphinx/source/users/lua.rst --- a/Sphinx/source/users/lua.rst Wed Dec 14 11:04:32 2016 +0100 +++ b/Sphinx/source/users/lua.rst Wed Dec 14 11:51:11 2016 +0100 @@ -86,7 +86,7 @@ amount of time (cf. the option ``StableAge`` in the :ref:`configuration file `). The :ref:`identifier ` of the patient is provided, together with her DICOM - tags and her metadata. + tags and her :ref:`metadata `. * ``function OnStableSeries(seriesId, tags, metadata)``: Invoked whenever a series has not received any new instance for a certain amount of time.