annotate Sphinx/source/faq/features.rst @ 946:d7f03f325544

LastUpdate for delete
author Alain Mazy <am@osimis.io>
date Mon, 22 May 2023 18:01:31 +0200
parents b9eb59d73a42
children 2038eb1f55bb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 Terminology of advanced features
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2 ================================
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
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
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 .. _peers:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 Peers
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 -----
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12 An "Orthanc peer" is another instance of Orthanc, possibly running on
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13 a remote computer.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 Contrarily to a "modality", it is possible to communicate with a peer
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16 through the **HTTP/HTTPS protocol** (i.e. through the REST API of
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 Orthanc), and not through the DICOM protocol. This implies a much
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18 easier configuration: It is only required to know the URL, the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19 username and the password to communicate with an Orthanc peer. This
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20 contrasts with DICOM query/retrieve, that is quite complex and that
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 involves a lot of pitfalls (cf. the FAQ entry about :ref:`troubleshooting
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22 DICOM communications <dicom>`) that can be bypassed if using HTTP.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
23
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24 Furthermore, as HTTP(S) communications are generally not blocked by
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25 firewalls (contrarily to the DICOM protocol that is inherently an
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26 Intranet protocol and that often requires the setup of VPN tunnels),
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 it is much easier to setup communications of medical images through
218
amazy
parents: 170
diff changeset
28 the Internet with :ref:`Orthanc peers <peering>`.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
30
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
31 .. _recycling:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
32
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
33 Recycling/Protection
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34 --------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 Because of its focus on low-end computers, Orthanc implements **disk
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37 space recycling**: The patient that has been stored for the longest
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38 time inside Orthanc can be automatically deleted when the disk space
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
39 used by Orthanc grows above a threshold, or when the number of stored
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40 patients grows above a threshold. This feature enables the automated
278
9bf644571511 fix doc wrt recycling order
amazy
parents: 224
diff changeset
41 control of the disk space dedicated to Orthanc. Note that each time
9bf644571511 fix doc wrt recycling order
amazy
parents: 224
diff changeset
42 a new instance is received for an existing patient, the patient will
9bf644571511 fix doc wrt recycling order
amazy
parents: 224
diff changeset
43 be marked as the most recent one in the recycling order.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 Recycling is controlled by the ``MaximumStorageSize`` and the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
46 ``MaximumPatientCount`` options in the :ref:`Orthanc configuration
106
7063afe5748c added info about recycling
amazy
parents: 95
diff changeset
47 file <configuration>`. Setting both these values to 0 will disable
7063afe5748c added info about recycling
amazy
parents: 95
diff changeset
48 recycling.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50 It is possible to prevent important data from being automatically
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51 recycled. This mechanism is called **protection**. Each patient can be
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 individually protected against recycling by using the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53 ``Unprotected/Protected`` switch that is available from Orthanc
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54 Explorer.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 Note that protection is only available at the patient level. It
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 protects all the studies/series/instances of the patient against
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58 recycling. The rationale is that we think it is important to keep
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59 available all the data related to one patient. Unwillingly losing a
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60 study/series that is part of the same patient might lead to a loss in
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61 consistency with respect to the medical history of this patient.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62
871
ab39093b898f MaximumStorageMode
Alain Mazy <am@osimis.io>
parents: 839
diff changeset
63 Starting with version 1.11.2, Orthanc also implements another **rejection**
ab39093b898f MaximumStorageMode
Alain Mazy <am@osimis.io>
parents: 839
diff changeset
64 behaviour when the ``MaximumStorageSize`` or ``MaximumPatientCount`` is
ab39093b898f MaximumStorageMode
Alain Mazy <am@osimis.io>
parents: 839
diff changeset
65 reached. In this case, patients are not recycled but Orthanc rejects new incoming
ab39093b898f MaximumStorageMode
Alain Mazy <am@osimis.io>
parents: 839
diff changeset
66 data. Check the ``MaximumStorageMode`` option in the :ref:`Orthanc configuration
ab39093b898f MaximumStorageMode
Alain Mazy <am@osimis.io>
parents: 839
diff changeset
67 file <configuration>`.
ab39093b898f MaximumStorageMode
Alain Mazy <am@osimis.io>
parents: 839
diff changeset
68
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69 .. _compression:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
71 Compression
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
72 -----------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
73
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
74 If your disk space is limited, besides :ref:`recycling`, you should
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75 also consider using **disk space compression**. When compression is
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
76 enabled, Orthanc compresses the incoming DICOM instances on-the-fly
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
77 before writing them to the filesystem, using `zlib
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
78 <https://en.wikipedia.org/wiki/Zlib>`_. This is useful, because the
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79 images are often stored as raw, uncompressed arrays in DICOM
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80 instances: The size of a typical DICOM instance can hopefully be
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
81 divided by a factor 2 through lossless compression. This compression
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
82 process is transparent to the user, as Orthanc automatically
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
83 decompresses the file before sending it back to the external world.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
84
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
85 Compression is controlled by the ``StorageCompression`` option in the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86 :ref:`Orthanc configuration file <configuration>`.
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
87
908
34e9e5e3b609 OrthancRecoverCompressedFile
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 871
diff changeset
88 Note that the Orthanc distribution comes with the
34e9e5e3b609 OrthancRecoverCompressedFile
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 871
diff changeset
89 ``OrthancRecoverCompressedFile`` command-line tool if a system
34e9e5e3b609 OrthancRecoverCompressedFile
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 871
diff changeset
90 administrator needs to recover one attachment compressed by Orthanc.
34e9e5e3b609 OrthancRecoverCompressedFile
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 871
diff changeset
91
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
92
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
93 .. _metadata:
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
94
92
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
95 Metadata & attachments
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
96 ----------------------
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
97
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
98 Metadata consists in an **associative key-value array** (mapping a
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
99 integer key in the range [0,65535] to a string value) that is
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
100 associated with each :ref:`DICOM resource <orthanc-ids>` stored inside
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
101 Orthanc (may it be a patient, a study, a series or a DICOM
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
102 instance). Metadata can be either referred to using the integer key,
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
103 or using a symbolic name (if configured). Metadata records
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
104 information that is not readily available in the DICOM tags.
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
105
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
106 In spirit, the metadata mechanism is similar to the :ref:`attachment
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
107 mechanism <orthanc-storage>`. However, metadata is stored directly
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
108 inside the database, whereas attachments are stored as separate files
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
109 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
110 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
111 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
112 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
113 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
114
38face2a84a4 metadata are utf-8 strings
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 622
diff changeset
115 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
116 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
117 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
118 <https://en.wikipedia.org/wiki/Base64>`__.
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
119
79
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 78
diff changeset
120 Also note that metadata and attachments are only available for
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 78
diff changeset
121 resources stored inside Orthanc. Once one DICOM instance leaves the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 78
diff changeset
122 Orthanc ecosystem, its associated metadata and attachments are lost.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 78
diff changeset
123
732
bfc31c51809f download pdf and videos
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 681
diff changeset
124 .. _metadata-core:
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
125
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
126 Core metadata
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
127 ^^^^^^^^^^^^^
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
128
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
129 Here are the main metadata handled by the Orthanc core:
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
130
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
131 * ``ReceptionDate`` records when a DICOM instance was received by
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
132 Orthanc. Similarly, ``LastUpdate`` records, for each
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
133 patient/study/series, the last time a DICOM instance was added to
946
d7f03f325544 LastUpdate for delete
Alain Mazy <am@osimis.io>
parents: 937
diff changeset
134 this resource. Starting with Orthanc 1.12.1, ``LastUpdate`` is also
d7f03f325544 LastUpdate for delete
Alain Mazy <am@osimis.io>
parents: 937
diff changeset
135 updated when a child resource is deleted.
661
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
136 * ``RemoteAET`` records the AET of the modality that has sent some
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
137 DICOM instance to Orthanc using the DICOM protocol.
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
138 * ``ModifiedFrom`` and ``AnonymizedFrom`` hold from which original
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
139 resource, a resource was modified or anonymized. The presence of
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
140 this metadata indicates that the resource is the result of a
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
141 modification or anonymization that was carried on by Orthanc.
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
142 * ``Origin`` records through which mechanism the instance was received
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
143 by Orthanc (may be ``Unknown``, ``DicomProtocol``, ``RestApi``,
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
144 ``Plugins``, or ``Lua``).
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
145 * ``IndexInSeries`` records the expected index of a DICOM instance
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
146 inside its parent series. Conversely, ``ExpectedNumberOfInstances``
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
147 associates to each series, the number of DICOM instances this series
661
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
148 is expected to contain. This information is :ref:`not always
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
149 available <series-completion>`.
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
150 * Starting with Orthanc 1.2.0, ``TransferSyntax`` and ``SopClassUid``
732
bfc31c51809f download pdf and videos
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 681
diff changeset
151 respectively stores the `transfer syntax UID
bfc31c51809f download pdf and videos
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 681
diff changeset
152 <http://dicom.nema.org/medical/dicom/current/output/html/part05.html#chapter_10>`__
bfc31c51809f download pdf and videos
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 681
diff changeset
153 and the `SOP class UID
bfc31c51809f download pdf and videos
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 681
diff changeset
154 <http://dicom.nema.org/medical/dicom/current/output/chtml/part02/sect_A.1.html>`__
bfc31c51809f download pdf and videos
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 681
diff changeset
155 of DICOM instances, in order to speed up the access to this
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
156 information.
661
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
157 * ``RemoteIP`` (new in Orthanc 1.4.0): The IP address of the remote
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
158 SCU (for REST API and DICOM protocol).
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
159 * ``CalledAET`` (new in Orthanc 1.4.0): The AET that was called by the
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
160 SCU, which normally matches the AET of Orthanc (for DICOM protocol).
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
161 * ``HttpUsername`` (new in Orthanc 1.4.0): The username that created
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
162 the instance (for REST API).
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
163 * ``PixelDataOffset`` (new in Orthanc 1.9.1): Offset (in bytes) of the
36bf58dfb7f7 added core metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 660
diff changeset
164 Pixel Data DICOM tag in the DICOM file, if available.
839
c29ac12e3160 Orthanc-1.11.0
Alain Mazy <am@osimis.io>
parents: 838
diff changeset
165 * ``MainDicomTagsSignature`` (new in Orthanc 1.11.0):
838
6afc236cd60a dicom-web & main-dicom-tags
Alain Mazy <am@osimis.io>
parents: 837
diff changeset
166 The list of :ref:`MainDicomTags <main-dicom-tags>` that have been
6afc236cd60a dicom-web & main-dicom-tags
Alain Mazy <am@osimis.io>
parents: 837
diff changeset
167 saved in DB for this resource.
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
168
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
169 Metadata listed above are set privately by the Orthanc core. They are
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
170 **read-only** from the perspective of the end user, as Orthanc
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
171 internally relies on them.
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
172
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
173
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
174 User-defined metadata
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
175 ^^^^^^^^^^^^^^^^^^^^^
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
176
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
177 The metadata described above where handled by the core of Orthanc.
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
178 Orthanc users are however allowed to define their own **user-defined
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
179 metadata**. Such metadata are associated with an integer key that is
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
180 greater or equal to 1024 (whereas keys below 1023 are reserved for
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
181 core metadata).
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
182
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
183 You can associate a symbolic name to user-defined metadata using the
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
184 ``UserMetadata`` option inside the :ref:`configuration of Orthanc
92
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
185 <configuration>`::
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
186
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
187 "UserMetadata" : {
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
188 "SampleMetaData1" : 1024,
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
189 "SampleMetaData2" : 1025
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
190 }
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
191
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
192
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
193 Accessing metadata
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
194 ^^^^^^^^^^^^^^^^^^
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
195
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
196 .. highlight:: bash
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
197
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
198 Metadata associated with one DICOM resource can be accessed through
80
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 79
diff changeset
199 the :ref:`REST API <rest>`, for instance::
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
200
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
201 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata
838
6afc236cd60a dicom-web & main-dicom-tags
Alain Mazy <am@osimis.io>
parents: 837
diff changeset
202 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata?expand
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
203 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/RemoteAet
92
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
204 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/SampleMetaData1
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
205
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
206 User-defined metadata can be modified by issuing a HTTP PUT against
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
207 the REST API::
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
208
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
209 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024 -X PUT -d 'hello'
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
210 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
211 hello
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
212
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
213
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
214
92
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
215 .. _attachments:
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
216
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
217 User-defined attachments
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
218 ^^^^^^^^^^^^^^^^^^^^^^^^
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
219
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
220 Orthanc users are allowed to define their own **user-defined attachments**.
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
221 Such attachments are associated with an integer key that is
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
222 greater or equal to 1024 (whereas keys below 1023 are reserved for
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
223 core attachments).
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
224
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
225 You can associate a symbolic name to user-defined attachments using the
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
226 ``UserContentType`` option inside the :ref:`configuration of Orthanc
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
227 <configuration>`. Optionally, the user may specify a MIME content type
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
228 for the attachment::
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
229
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
230 "UserContentType" : {
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
231 "samplePdf" : [1024, "application/pdf"],
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
232 "sampleJson" : [1025, "application/json"],
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
233 "sampleRaw" : 1026
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
234 }
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
235
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
236 Accessing attachments
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
237 ^^^^^^^^^^^^^^^^^^^^^
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
238
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
239 .. highlight:: bash
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
240
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
241 Attachments associated with one DICOM resource can be accessed through
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
242 the :ref:`REST API <rest>`, for instance::
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
243
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
244 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/attachments/samplePdf/data
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
245 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/attachments/sampleJson/data
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
246
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
247 User-defined attachments can be modified by issuing a HTTP PUT against
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
248 the REST API::
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
249
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
250 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/attachments/samplePdf -X PUT --data-binary @sample.pdf
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
251 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/attachments/sampleRaw -X PUT -d 'raw data'
660
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
252
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
253
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
254 DICOM-as-JSON attachments
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
255 ^^^^^^^^^^^^^^^^^^^^^^^^^
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
256
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
257 In the version of Orthanc <= 1.9.0, whenever Orthanc receives a DICOM
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
258 file, it pre-computes a JSON summary of its DICOM tags, and caches
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
259 this JSON file as an attachment to the DICOM instance (accessible at
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
260 the ``/instances/{...}/attachments/dicom-as-json/`` URI). This
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
261 attachment is used as a cache to seep up future accesses to
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
262 ``/instances/.../tags``, lookups using ``/tools/find`` or C-FIND
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
263 queries.
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
264
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
265 This caching might cause issues if the dictionary of DICOM tags is
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
266 subsequently modified, which implies that the cached JSON file does
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
267 not perfectly match the new dictionary.
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
268
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
269 .. highlight:: bash
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
270
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
271 Since Orthanc 1.2.0, you can force the re-generation of the cached
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
272 JSON file by DELETE-ing it, for instance::
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
273
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
274 $ curl -X DELETE http://localhost:8042/instances/301896f2-1416807b-3e05dcce-ff4ce9bb-a6138832/attachments/dicom-as-json
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
275
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
276 .. highlight:: text
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
277
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
278 The next time you open this particular instance with Orthanc Explorer,
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
279 you will see messages in the Orthanc logs (in verbose mode) stating
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
280 that the Orthanc server has reconstructed the JSON summary, which will
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
281 match the new content of the dictionary::
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
282
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
283 I0222 08:56:00.923070 FilesystemStorage.cpp:155] Reading attachment "2309c47b-1cbd-4601-89b5-1be1ad80382c" of "DICOM" content type
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
284 I0222 08:56:00.923394 ServerContext.cpp:401] Reconstructing the missing DICOM-as-JSON summary for instance: 301896f2-1416807b-3e05dcce-ff4ce9bb-a6138832
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
285 I0222 08:56:00.929117 ServerContext.cpp:540] Adding attachment dicom-as-json to resource 301896f2-1416807b-3e05dcce-ff4ce9bb-a6138832
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
286 I0222 08:56:00.929425 FilesystemStorage.cpp:118] Creating attachment "3c830b66-8a00-42f0-aa3a-5e37b4a8b5a4" of "JSON summary of DICOM" type (size: 1MB)
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
287
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
288 These DICOM-as-JSON attachments are not automatically generated
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
289 anymore starting with Orthanc 1.9.1.
a6e371768a70 dicom-as-json
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 645
diff changeset
290
92
a3d3ff83024d attachments doc + build with docker
amazy
parents: 80
diff changeset
291
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
292 .. _registry:
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
293
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
294 Central registry of metadata and attachments
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
295 --------------------------------------------
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
296
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
297 Obviously, one must pay attention to the fact that different
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
298 applications might use the same key to store different user-defined
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
299 :ref:`metadata <metadata>`, which might result in incompatibilities
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
300 between such applications. Similarly, incompatibilities might show up
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
301 for user-defined :ref:`attachments <orthanc-storage>`.
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
302
601
4c19a897803e global property 5467
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 595
diff changeset
303 Developers of applications/plugins that use user-defined metadata,
4c19a897803e global property 5467
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 595
diff changeset
304 attachments or global properties (using
4c19a897803e global property 5467
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 595
diff changeset
305 ``OrthancPluginSetGlobalProperty()``) are therefore kindly invited to
4c19a897803e global property 5467
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 595
diff changeset
306 complete the **central registry** below:
78
d6bd1dd820e5 metadata
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
307
622
debcf6b6d070 dicom-as-json is now deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 621
diff changeset
308 * ``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
309 file associated with one instance.
debcf6b6d070 dicom-as-json is now deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 621
diff changeset
310 * ``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
311 ``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
312 ``/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
313 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
314 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
315 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
316 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
317 modified in the future).
debcf6b6d070 dicom-as-json is now deprecated
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 621
diff changeset
318 * ``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
319 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
320 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
321 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
322 avoid downloading the full DICOM instance if not necessary.
359
9acb9354da1a links to hg
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 278
diff changeset
323 * ``Attachment 9997`` is used by the :ref:`Osimis WebViewer plugin <osimis_webviewer>` to store series information.
9acb9354da1a links to hg
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 278
diff changeset
324 * ``Attachment 9998`` is used by the :ref:`Osimis WebViewer plugin <osimis_webviewer>` to store instance information.
9acb9354da1a links to hg
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 278
diff changeset
325 * ``Attachment 9999`` is used by the :ref:`Osimis WebViewer plugin <osimis_webviewer>` to store annotations.
9acb9354da1a links to hg
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 278
diff changeset
326 * ``Attachments 10000-13999`` are used by the :ref:`Osimis WebViewer plugin <osimis_webviewer>` to store reduced quality images.
837
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents: 750
diff changeset
327 * ``Global property 1025`` is used by default by the Housekeeper plugin.
601
4c19a897803e global property 5467
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 595
diff changeset
328 * ``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
329 * ``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
330 * ``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
331 * ``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
332
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 218
diff changeset
333
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 218
diff changeset
334 Jobs
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 218
diff changeset
335 ----
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 218
diff changeset
336
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 218
diff changeset
337 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
338
642
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
339
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
340
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
341 .. _stable-resources:
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
342
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
343 Stable resources
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
344 ----------------
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
345
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
346 A DICOM resource (patient, study or series) is referred to as
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
347 **stable** if it has not received any new instance for a certain
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
348 amount of time.
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
349
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
350 This amount of time is configured by the the option ``StableAge`` in
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
351 the :ref:`configuration file <configuration>`.
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
352
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
353 When some resource becomes stable, an event is generated as a log
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
354 entry in the ``/changes`` :ref:`URI in the REST API <changes>`, a
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
355 :ref:`Lua callback <lua-callbacks>` is invoked, the callback function
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
356 registered by ``OrthancPluginRegisterOnChangeCallback()`` in
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
357 :ref:`C/C++ plugins <creating-plugins>` is executed, as well as the
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
358 :ref:`Python callback <python-changes>` registered by
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
359 ``orthanc.RegisterOnChangeCallback()``.
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
360
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
361 The ``IsStable`` field is also available to get the status of an
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
362 individual patient/study/series using the REST API of Orthanc.
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
363
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
364 In the multiple readers/writers scenario enabled since Orthanc 1.9.2,
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
365 each Orthanc server is considered separately: The "stable" information
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
366 is monitored by threads inside the Orthanc process, and is **not**
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
367 shared in the database. In other words, the "stable" information is
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
368 local to the Orthanc server that is queried. Synchronization between
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
369 multiple readers/writers must be implemented at a higher level
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
370 (e.g. using a distributed `message-broker system
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
371 <https://en.wikipedia.org/wiki/Message_broker>`__ such as RabbitMQ
a76d83a00c68 definition of stable resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 632
diff changeset
372 that is fed by an Orthanc plugin).
643
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
373
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
374
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
375 .. _revisions:
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
376
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
377 Revisions
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
378 ---------
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
379
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
380 .. highlight:: bash
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
381
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
382 Higher-level applications built on the top of Orthanc might have to
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
383 modify metadata and/or attachments. This can cause concurrency
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
384 problems if multiple clients modify the same metadata/attachment
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
385 simultaneously. To avoid such problems, Orthanc implements a so-called
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
386 **revision mechanism** to protect from concurrent modifications.
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
387
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
388 The revision mechanism is optional, was introduced in **Orthanc
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
389 1.9.2** and must be enabled by setting :ref:`configuration option
681
9c23356b9464 typo: replaced "CheckRevision" by "CheckRevisions"
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 672
diff changeset
390 <configuration>` ``CheckRevisions`` to ``true``. It is strongly
643
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
391 inspired by the `CouchDB API
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
392 <https://docs.couchdb.org/en/stable/api/document/common.html>`__.
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
393
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
394 When the revision mechanism is enabled, each metadata and attachment
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
395 is associated with a **revision number**. Whenever one sets a metadata
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
396 for the first time using a ``PUT`` query, this revision number can be
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
397 found in the HTTP header ``ETag`` that is reported by Orthanc::
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
398
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
399 $ curl -v http://localhost:8042/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/metadata/1024 -X PUT -d 'Hello'
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
400 [...]
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
401 < ETag: "0"
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
402
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
403 Any ``GET`` query will also return the current value of ``ETag``::
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
404
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
405 $ curl -v http://localhost:8042/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/metadata/1024
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
406 [...]
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
407 < ETag: "0"
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
408
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
409 If one needs to subsequently modify or delete this metadata, the HTTP
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
410 client must set this value of ``ETag`` into the ``If-Match`` HTTP
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
411 header::
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
412
645
187a18c6c646 fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
413 $ curl -v http://localhost:8042/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/metadata/1024 -X PUT -d 'Hello 2' -H 'If-Match: "0"'
643
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
414 [...]
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
415 < ETag: "1"
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
416
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
417 Note how this second call has incremented the value of ``ETag``: This
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
418 is the new revision number to be used in future updates. If a bad
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
419 revision number is provided, the HTTP error ``409 Conflict`` is
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
420 generated::
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
421
645
187a18c6c646 fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
422 $ curl -v http://localhost:8042/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/metadata/1024 -X PUT -d 'Hello 3' -H 'If-Match: "0"'
643
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
423 [...]
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
424 < HTTP/1.1 409 Conflict
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
425
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
426 Such a ``409`` error must be handled by the higher-level
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
427 application. The revision number must similarly be given if deleting a
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
428 metadata/attachment::
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
429
645
187a18c6c646 fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
430 $ curl -v http://localhost:8042/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/metadata/1024 -X DELETE -H 'If-Match: "1"'
643
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
431 [...]
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
432 < HTTP/1.1 200 OK
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
433
645
187a18c6c646 fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
434 Check out the `OpenAPI reference <https://api.orthanc-server.com/>`__
187a18c6c646 fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 643
diff changeset
435 of the REST API of Orthanc for more information.
643
411e82bb3a9f documenting revisions and multiple writers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 642
diff changeset
436
936
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
437 **Warning:** The database index back-end must implement support for
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
438 revisions. As of writing, only the **PostgreSQL plugins** in versions
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
439 above 4.0 and the **ODBC plugins** implement support for revisions.
672
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
440
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
441
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
442 Synchronous vs. asynchronous C-MOVE SCP
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
443 ---------------------------------------
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
444
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
445 The :ref:`C-MOVE SCP <dicom-move>` of Orthanc (i.e. the component of
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
446 the Orthanc server that is responsible for routing DICOM instances
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
447 from Orthanc to other modalities) can be configured to run either in
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
448 synchronous or in asynchronous mode, depending on the value of the
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
449 ``SynchronousCMove`` :ref:`configuration option <configuration>`:
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
450
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
451 * In **synchronous mode** (if ``SynchronousCMove`` is ``true``),
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
452 Orthanc will interleave its C-STORE SCU commands with the C-MOVE
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
453 instructions received from the remote modality. In other words,
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
454 Orthanc immediately sends the DICOM instances while it handles the
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
455 C-MOVE command from the remote modality. This mode is for
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
456 compatibility with simple DICOM client software that considers that
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
457 when its C-MOVE SCU is over, it should have received all the
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
458 instructed DICOM instances. This is the default behavior of Orthanc.
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
459
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
460 * In **asynchronous mode** (if ``SynchronousCMove`` is ``false``),
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
461 Orthanc will queue the C-MOVE instructions and :ref:`creates a job
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
462 <jobs-synchronicity>` that will issue the C-STORE SCU commands
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
463 afterward. This behavior is typically encountered in hospital-wide
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
464 PACS systems, but requires the client software to be more complex as
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
465 it must be handle the delay between its C-MOVE queries and the
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
466 actual reception of the DICOM instances through C-STORE.
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
467
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
468 As a consequence, by setting ``SynchronousCMove`` to ``true``, Orthanc
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
469 can be used as a buffer that enables communications between a simple
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
470 C-MOVE client and a hospital-wide PACS. This can be interesting to
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
471 introduce compatibility with specialized image processing
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 661
diff changeset
472 applications.
936
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
473
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
474
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
475 .. _labels:
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
476
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
477 Labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
478 ------
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
479
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
480 .. highlight:: text
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
481
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
482 Orthanc 1.12.0 introduces the concept of **labels**. A label is a
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
483 string that can be attached to any DICOM resource (i.e. patients,
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
484 studies, series, or instances). In contrast with :ref:`metadata
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
485 <metadata>`, labels are not associated with a value, however labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
486 are **indexed in the Orthanc database** for efficient lookups.
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
487
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
488 Labels can notably be used as the building block to implement
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
489 **multi-tenancy**, which means that a single database could be shared
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
490 between different tenants that are distinguished by different labels.
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
491 This idea is illustrated by the :ref:`multitenant DICOM server
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
492 <multitenant-dicom>` sample plugin. A similar approach could be used
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
493 to implement Web interfaces that restrict the resources that are
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
494 accessible to some users by assigning labels to users. Labels are also
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
495 useful in **machine learning** (or deep learning) workflows to
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
496 separate DICOM resources belonging to the training set or to the
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
497 testing set.
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
498
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
499 The labels attached to one given DICOM resource can be read through
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
500 the REST API::
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
501
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
502 $ curl http://localhost:8042/instances/19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5/labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
503 $ curl http://localhost:8042/series/3774320f-ccda46d8-69ee8641-9e791cbf-3ecbbcc6/labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
504 $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
505 $ curl http://localhost:8042/patients/ef9d77db-eb3b2bef-9b31fd3e-bf42ae46-dbdb0cc3/labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
506
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
507 A label can be added to one DICOM resource using the PUT HTTP method,
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
508 and can be removed using the DELETE HTTP method::
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
509
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
510 $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
511 []
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
512 $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels/hello -X PUT -d ''
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
513 $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
514 [ "hello" ]
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
515 $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels/hello -X DELETE
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
516 $ curl http://localhost:8042/studies/66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e/labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
517 []
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
518
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
519 The built-in :ref:`Orthanc Explorer <orthanc-explorer>` Web interface
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
520 can be used to display, add, and remove labels.
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
521
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
522 Once labels are set, the ``/tools/find`` :ref:`route of the REST API
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
523 <rest-find>` of Orthanc can be used to efficiently look for the DICOM
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
524 resources that are associated with given labels. This is done by
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
525 providing the set of labels of interest in the ``Labels`` field, as
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
526 illustrated in the following request::
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
527
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
528 $ curl --request POST --url http://localhost:8042/tools/find \
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
529 --data '{
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
530 "Level" : "Study",
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
531 "Labels" : [ "hello" ],
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
532 "LabelsConstraint" : "All",
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
533 "Query" : { }
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
534 }'
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
535
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
536 The ``LabelsConstraint`` field can be used to control the request over
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
537 the labels. Its value can be ``All`` (to return the resources that are
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
538 associated with all the labels provided in the ``Labels`` field at
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
539 once), ``Any`` (to return the resources that are associated with at
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
540 least one of the labels provided in the ``Labels`` field), or ``None``
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
541 (to return the resources that are associated with none of the labels
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
542 provided in the ``Labels`` field). If not provided,
937
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 936
diff changeset
543 ``LabelsConstraint`` defaults to ``All``. Note that if there is only
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 936
diff changeset
544 one label in the ``Labels`` field, both ``Any`` and ``All`` have the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 936
diff changeset
545 same behavior.
936
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
546
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
547
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
548 **Warning:** The database index back-end must implement support for
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
549 labels. As of writing, only the **PostgreSQL plugins** in versions
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
550 above 5.0 and the **MySQL plugins** in version above 5.0 implement
5491953f7492 documentation of labels
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 908
diff changeset
551 support for labels.