orthanc-book: Sphinx/source/faq/features.rst annotate

annotate Sphinx/source/faq/features.rst @ 1085:05d37a5abcc4

dicom-as-json hk

author	Alain Mazy <am@orthanc.team>
date	Fri, 28 Jun 2024 11:15:17 +0200
parents	2e103fb1fa11
children	faf18bfe89a0

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 8bb11cd0f20f links 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
998 bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	36 Because of its focus on low-end computers, Orthanc may implement **disk
0 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
998 bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	50 Starting with version 1.11.2, Orthanc also implements another rejection
bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	51 behaviour when the ``MaximumStorageSize`` or ``MaximumPatientCount`` is
bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	52 reached. In this case, patients are not recycled but Orthanc rejects new incoming
bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	53 data. Check the ``MaximumStorageMode`` option in the :ref:`Orthanc configuration
bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	54 file <configuration>`.
bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	55
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	56 It is possible to prevent important data from being automatically
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	57 recycled. This mechanism is called protection. Each patient can be
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	58 individually protected against recycling by using the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	59 ``Unprotected/Protected`` switch that is available from Orthanc
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	60 Explorer.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	61
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	62 Note that protection is only available at the patient level. It
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	63 protects all the studies/series/instances of the patient against
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	64 recycling. The rationale is that we think it is important to keep
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	65 available all the data related to one patient. Unwillingly losing a
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	66 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	67 consistency with respect to the medical history of this patient.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	68
998 bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	69 To protect/unprotect a patient, one must call the ``/patients/../protected`` route::
bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	70
bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	71 $ curl -X PUT http://localhost:8042/patients/0946fcb6-cf12ab43-bad958c1-bf057ad5-0fc6f54c/protected -d "1"
bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	72 $ curl -X PUT http://localhost:8042/patients/0946fcb6-cf12ab43-bad958c1-bf057ad5-0fc6f54c/protected -d "0"
bd7fbe3042f7 recycling/protection Alain Mazy <am@osimis.io> parents: 991 diff changeset	73
871 ab39093b898f MaximumStorageMode Alain Mazy <am@osimis.io> parents: 839 diff changeset	74
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	75 .. _compression:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	76
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	77 Compression
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	78 -----------
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	79
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	80 If your disk space is limited, besides :ref:`recycling`, you should
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	81 also consider using disk space compression. When compression is
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	82 enabled, Orthanc compresses the incoming DICOM instances on-the-fly
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	83 before writing them to the filesystem, using `zlib
25 669ea65ba7fb fix links Sebastien Jodogne <s.jodogne@gmail.com> parents: 0 diff changeset	84 <https://en.wikipedia.org/wiki/Zlib>`_. This is useful, because the
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	85 images are often stored as raw, uncompressed arrays in DICOM
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	86 instances: The size of a typical DICOM instance can hopefully be
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	87 divided by a factor 2 through lossless compression. This compression
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	88 process is transparent to the user, as Orthanc automatically
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	89 decompresses the file before sending it back to the external world.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	90
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	91 Compression is controlled by the ``StorageCompression`` option in the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	92 :ref:`Orthanc configuration file <configuration>`.
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	93
908 34e9e5e3b609 OrthancRecoverCompressedFile Sebastien Jodogne <s.jodogne@gmail.com> parents: 871 diff changeset	94 Note that the Orthanc distribution comes with the
34e9e5e3b609 OrthancRecoverCompressedFile Sebastien Jodogne <s.jodogne@gmail.com> parents: 871 diff changeset	95 ``OrthancRecoverCompressedFile`` command-line tool if a system
34e9e5e3b609 OrthancRecoverCompressedFile Sebastien Jodogne <s.jodogne@gmail.com> parents: 871 diff changeset	96 administrator needs to recover one attachment compressed by Orthanc.
34e9e5e3b609 OrthancRecoverCompressedFile Sebastien Jodogne <s.jodogne@gmail.com> parents: 871 diff changeset	97
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	98
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	99 .. _metadata:
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	100
92 a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	101 Metadata & attachments
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	102 ----------------------
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	103
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	104 Metadata consists in an associative key-value array (mapping a
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	105 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	106 associated with each :ref:`DICOM resource <orthanc-ids>` stored inside
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	107 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	108 instance). Metadata can be either referred to using the integer key,
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	109 or using a symbolic name (if configured). Metadata records
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	110 information that is not readily available in the DICOM tags.
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	111
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	112 In spirit, the metadata mechanism is similar to the :ref:`attachment
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	113 mechanism <orthanc-storage>`. However, metadata is stored directly
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	114 inside the database, whereas attachments are stored as separate files
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	115 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	116 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	117 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	118 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	119 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	120
38face2a84a4 metadata are utf-8 strings Sebastien Jodogne <s.jodogne@gmail.com> parents: 622 diff changeset	121 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	122 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	123 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	124 <https://en.wikipedia.org/wiki/Base64>`__.
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	125
79 b77aa0655389 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 78 diff changeset	126 Also note that metadata and attachments are only available for
b77aa0655389 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 78 diff changeset	127 resources stored inside Orthanc. Once one DICOM instance leaves the
b77aa0655389 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 78 diff changeset	128 Orthanc ecosystem, its associated metadata and attachments are lost.
b77aa0655389 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 78 diff changeset	129
732 bfc31c51809f download pdf and videos Sebastien Jodogne <s.jodogne@gmail.com> parents: 681 diff changeset	130 .. _metadata-core:
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	131
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	132 Core metadata
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	133 ^^^^^^^^^^^^^
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	134
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	135 Here are the main metadata handled by the Orthanc core:
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	136
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	137 * ``ReceptionDate`` records when a DICOM instance was received by
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	138 Orthanc. Similarly, ``LastUpdate`` records, for each
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	139 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	140 this resource. Starting with Orthanc 1.12.1, ``LastUpdate`` is also
d7f03f325544 LastUpdate for delete Alain Mazy <am@osimis.io> parents: 937 diff changeset	141 updated when a child resource is deleted.
661 36bf58dfb7f7 added core metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 660 diff changeset	142 * ``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	143 DICOM instance to Orthanc using the DICOM protocol.
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	144 * ``ModifiedFrom`` and ``AnonymizedFrom`` hold from which original
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	145 resource, a resource was modified or anonymized. The presence of
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	146 this metadata indicates that the resource is the result of a
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	147 modification or anonymization that was carried on by Orthanc.
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	148 * ``Origin`` records through which mechanism the instance was received
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	149 by Orthanc (may be ``Unknown``, ``DicomProtocol``, ``RestApi``,
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	150 ``Plugins``, or ``Lua``).
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	151 * ``IndexInSeries`` records the expected index of a DICOM instance
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	152 inside its parent series. Conversely, ``ExpectedNumberOfInstances``
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	153 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	154 is expected to contain. This information is :ref:`not always
36bf58dfb7f7 added core metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 660 diff changeset	155 available <series-completion>`.
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	156 * 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	157 respectively stores the `transfer syntax UID
bfc31c51809f download pdf and videos Sebastien Jodogne <s.jodogne@gmail.com> parents: 681 diff changeset	158 <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	159 and the `SOP class UID
bfc31c51809f download pdf and videos Sebastien Jodogne <s.jodogne@gmail.com> parents: 681 diff changeset	160 <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	161 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	162 information.
661 36bf58dfb7f7 added core metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 660 diff changeset	163 * ``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	164 SCU (for REST API and DICOM protocol).
36bf58dfb7f7 added core metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 660 diff changeset	165 * ``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	166 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	167 * ``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	168 the instance (for REST API).
36bf58dfb7f7 added core metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 660 diff changeset	169 * ``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	170 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	171 * ``MainDicomTagsSignature`` (new in Orthanc 1.11.0):
838 6afc236cd60a dicom-web & main-dicom-tags Alain Mazy <am@osimis.io> parents: 837 diff changeset	172 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	173 saved in DB for this resource.
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	174
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	175 Metadata listed above are set privately by the Orthanc core. They are
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	176 read-only from the perspective of the end user, as Orthanc
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	177 internally relies on them.
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	178
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	179
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	180 User-defined metadata
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	181 ^^^^^^^^^^^^^^^^^^^^^
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 The metadata described above where handled by the core of Orthanc.
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	184 Orthanc users are however allowed to define their own **user-defined
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	185 metadata**. Such metadata are associated with an integer key that is
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	186 greater or equal to 1024 (whereas keys below 1023 are reserved for
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	187 core metadata).
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	188
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	189 You can associate a symbolic name to user-defined metadata using the
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	190 ``UserMetadata`` option inside the :ref:`configuration of Orthanc
92 a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	191 <configuration>`::
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	192
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	193 "UserMetadata" : {
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	194 "SampleMetaData1" : 1024,
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	195 "SampleMetaData2" : 1025
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	196 }
78 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
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	199 Accessing metadata
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
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	202 .. highlight:: bash
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	203
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	204 Metadata associated with one DICOM resource can be accessed through
80 0e8b85acf3e0 ling Sebastien Jodogne <s.jodogne@gmail.com> parents: 79 diff changeset	205 the :ref:`REST API <rest>`, for instance::
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	206
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	207 $ 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	208 $ 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	209 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/RemoteAet
92 a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	210 $ 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	211
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	212 User-defined metadata can be modified by issuing a HTTP PUT against
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	213 the REST API::
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	214
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	215 $ 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	216 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	217 hello
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	218
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	219
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	220
92 a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	221 .. _attachments:
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	222
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	223 User-defined 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
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	226 Orthanc users are allowed to define their own user-defined attachments.
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	227 Such attachments are associated with an integer key that is
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	228 greater or equal to 1024 (whereas keys below 1023 are reserved for
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	229 core attachments).
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	230
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	231 You can associate a symbolic name to user-defined attachments using the
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	232 ``UserContentType`` option inside the :ref:`configuration of Orthanc
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	233 <configuration>`. Optionally, the user may specify a MIME content type
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	234 for the attachment::
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	235
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	236 "UserContentType" : {
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	237 "samplePdf" : [1024, "application/pdf"],
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	238 "sampleJson" : [1025, "application/json"],
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	239 "sampleRaw" : 1026
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	240 }
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	241
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	242 Accessing attachments
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	243 ^^^^^^^^^^^^^^^^^^^^^
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	244
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	245 .. highlight:: bash
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	246
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	247 Attachments associated with one DICOM resource can be accessed through
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	248 the :ref:`REST API <rest>`, for instance::
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/data
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	251 $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/attachments/sampleJson/data
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	252
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	253 User-defined attachments can be modified by issuing a HTTP PUT against
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	254 the REST API::
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	255
a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	256 $ 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	257 $ 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	258
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	259
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	260 DICOM-as-JSON attachments
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	261 ^^^^^^^^^^^^^^^^^^^^^^^^^
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	262
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	263 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	264 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	265 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	266 the ``/instances/{...}/attachments/dicom-as-json/`` URI). This
1085 05d37a5abcc4 dicom-as-json hk Alain Mazy <am@orthanc.team> parents: 1000 diff changeset	267 attachment is used as a cache to speed up future accesses to
660 a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	268 ``/instances/.../tags``, lookups using ``/tools/find`` or C-FIND
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	269 queries.
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 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	272 subsequently modified, which implies that the cached JSON file does
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	273 not perfectly match the new dictionary.
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	274
1085 05d37a5abcc4 dicom-as-json hk Alain Mazy <am@orthanc.team> parents: 1000 diff changeset	275 Starting from 1.9.0, these files are not necessary anymore. They can
05d37a5abcc4 dicom-as-json hk Alain Mazy <am@orthanc.team> parents: 1000 diff changeset	276 possibly be removed by the :ref:`Housekeeper plugin <housekeeper-plugin>`
05d37a5abcc4 dicom-as-json hk Alain Mazy <am@orthanc.team> parents: 1000 diff changeset	277 to reclaim disk space.
05d37a5abcc4 dicom-as-json hk Alain Mazy <am@orthanc.team> parents: 1000 diff changeset	278
660 a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	279 .. highlight:: bash
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	280
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	281 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	282 JSON file by DELETE-ing it, for instance::
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	283
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	284 $ 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	285
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	286 .. highlight:: text
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 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	289 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	290 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	291 match the new content of the dictionary::
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	292
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	293 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	294 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	295 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	296 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	297
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	298 These DICOM-as-JSON attachments are not automatically generated
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	299 anymore starting with Orthanc 1.9.1.
a6e371768a70 dicom-as-json Sebastien Jodogne <s.jodogne@gmail.com> parents: 645 diff changeset	300
92 a3d3ff83024d attachments doc + build with docker amazy parents: 80 diff changeset	301
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	302 .. _registry:
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	303
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	304 Central registry of metadata and attachments
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	305 --------------------------------------------
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	306
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	307 Obviously, one must pay attention to the fact that different
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	308 applications might use the same key to store different user-defined
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	309 :ref:`metadata <metadata>`, which might result in incompatibilities
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	310 between such applications. Similarly, incompatibilities might show up
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	311 for user-defined :ref:`attachments <orthanc-storage>`.
d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	312
601 4c19a897803e global property 5467 Sebastien Jodogne <s.jodogne@gmail.com> parents: 595 diff changeset	313 Developers of applications/plugins that use user-defined metadata,
4c19a897803e global property 5467 Sebastien Jodogne <s.jodogne@gmail.com> parents: 595 diff changeset	314 attachments or global properties (using
4c19a897803e global property 5467 Sebastien Jodogne <s.jodogne@gmail.com> parents: 595 diff changeset	315 ``OrthancPluginSetGlobalProperty()``) are therefore kindly invited to
4c19a897803e global property 5467 Sebastien Jodogne <s.jodogne@gmail.com> parents: 595 diff changeset	316 complete the central registry below:
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 25 diff changeset	317
622 debcf6b6d070 dicom-as-json is now deprecated Sebastien Jodogne <s.jodogne@gmail.com> parents: 621 diff changeset	318 * ``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	319 file associated with one instance.
debcf6b6d070 dicom-as-json is now deprecated Sebastien Jodogne <s.jodogne@gmail.com> parents: 621 diff changeset	320 * ``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	321 ``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	322 ``/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	323 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	324 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	325 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	326 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	327 modified in the future).
debcf6b6d070 dicom-as-json is now deprecated Sebastien Jodogne <s.jodogne@gmail.com> parents: 621 diff changeset	328 * ``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	329 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	330 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	331 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	332 avoid downloading the full DICOM instance if not necessary.
969 7abb7c8ff544 doc for upcoming dicomweb 1.15 Alain Mazy <am@osimis.io> parents: 963 diff changeset	333 * ``Attachment 4301`` is used by the :ref:`DICOMweb plugin <dicomweb>` to cache WADO-RS series metadata (starting from v 1.15 of the plugin).
359 9acb9354da1a links to hg Sebastien Jodogne <s.jodogne@gmail.com> parents: 278 diff changeset	334 * ``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	335 * ``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	336 * ``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	337 * ``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	338 * ``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	339 * ``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	340 * ``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	341 * ``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	342 * ``Metadata 4201`` is used by the plugin for :ref:`whole-slide imaging <wsi>` with version >= 1.0.
953 2038eb1f55bb finalized ohif documentation Sebastien Jodogne <s.jodogne@gmail.com> parents: 946 diff changeset	343 * ``Metadata 4202`` is used by the :ref:`OHIF plugin <ohif>` to store precomputed information about the DICOM instances.
224 02399e86f046 starting documentation of jobs Sebastien Jodogne <s.jodogne@gmail.com> parents: 218 diff changeset	344
02399e86f046 starting documentation of jobs Sebastien Jodogne <s.jodogne@gmail.com> parents: 218 diff changeset	345
02399e86f046 starting documentation of jobs Sebastien Jodogne <s.jodogne@gmail.com> parents: 218 diff changeset	346 Jobs
02399e86f046 starting documentation of jobs Sebastien Jodogne <s.jodogne@gmail.com> parents: 218 diff changeset	347 ----
02399e86f046 starting documentation of jobs Sebastien Jodogne <s.jodogne@gmail.com> parents: 218 diff changeset	348
02399e86f046 starting documentation of jobs Sebastien Jodogne <s.jodogne@gmail.com> parents: 218 diff changeset	349 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	350
642 a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	351
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 .. _stable-resources:
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	354
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	355 Stable resources
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	356 ----------------
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	357
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	358 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	359 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	360 amount of time.
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	361
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	362 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	363 the :ref:`configuration file <configuration>`.
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	364
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	365 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	366 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	367 :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	368 registered by ``OrthancPluginRegisterOnChangeCallback()`` in
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	369 :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	370 :ref:`Python callback <python-changes>` registered by
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	371 ``orthanc.RegisterOnChangeCallback()``.
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	372
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	373 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	374 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	375
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	376 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	377 each Orthanc server is considered separately: The "stable" information
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	378 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	379 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	380 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	381 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	382 (e.g. using a distributed `message-broker system
a76d83a00c68 definition of stable resources Sebastien Jodogne <s.jodogne@gmail.com> parents: 632 diff changeset	383 <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	384 that is fed by an Orthanc plugin).
643 411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	385
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	386
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	387 .. _revisions:
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	388
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	389 Revisions
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	390 ---------
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	391
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	392 .. highlight:: bash
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 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	395 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	396 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	397 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	398 revision mechanism to protect from concurrent modifications.
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	399
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	400 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	401 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	402 <configuration>` ``CheckRevisions`` to ``true``. It is strongly
643 411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	403 inspired by the `CouchDB API
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	404 <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	405
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	406 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	407 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	408 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	409 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	410
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	411 $ 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	412 [...]
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	413 < ETag: "0"
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 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	416
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	417 $ 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	418 [...]
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	419 < ETag: "0"
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	420
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	421 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	422 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	423 header::
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	424
645 187a18c6c646 fix links Sebastien Jodogne <s.jodogne@gmail.com> parents: 643 diff changeset	425 $ 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	426 [...]
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	427 < ETag: "1"
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	428
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	429 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	430 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	431 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	432 generated::
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 $ 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	435 [...]
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	436 < HTTP/1.1 409 Conflict
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	437
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	438 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	439 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	440 metadata/attachment::
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	441
645 187a18c6c646 fix links Sebastien Jodogne <s.jodogne@gmail.com> parents: 643 diff changeset	442 $ 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	443 [...]
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	444 < HTTP/1.1 200 OK
411e82bb3a9f documenting revisions and multiple writers Sebastien Jodogne <s.jodogne@gmail.com> parents: 642 diff changeset	445
991 1316bc62b5d5 migration to UCLouvain servers Sebastien Jodogne <s.jodogne@gmail.com> parents: 969 diff changeset	446 Check out the `OpenAPI reference <https://orthanc.uclouvain.be/api/>`__
645 187a18c6c646 fix links Sebastien Jodogne <s.jodogne@gmail.com> parents: 643 diff changeset	447 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	448
936 5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	449 Warning: The database index back-end must implement support for
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	450 revisions. As of writing, only the PostgreSQL plugins in versions
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	451 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	452
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	453
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	454 Synchronous vs. asynchronous C-MOVE SCP
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	455 ---------------------------------------
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	456
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	457 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	458 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	459 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	460 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	461 ``SynchronousCMove`` :ref:`configuration option <configuration>`:
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	462
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	463 * 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	464 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	465 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	466 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	467 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	468 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	469 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	470 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	471
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	472 * 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	473 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	474 <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	475 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	476 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	477 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	478 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	479
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	480 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	481 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	482 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	483 introduce compatibility with specialized image processing
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP Sebastien Jodogne <s.jodogne@gmail.com> parents: 661 diff changeset	484 applications.
936 5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	485
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	486
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	487 .. _labels:
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	488
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	489 Labels
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	490 ------
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	491
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	492 .. highlight:: text
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	493
1000 2e103fb1fa11 Orthanc 1.12.2 Alain Mazy <am@osimis.io> parents: 998 diff changeset	494 Orthanc 1.12.0 introduced the concept of labels. A label is a
936 5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	495 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	496 studies, series, or instances). In contrast with :ref:`metadata
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	497 <metadata>`, labels are not associated with a value, however labels
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	498 are indexed in the Orthanc database for efficient lookups.
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	499
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	500 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	501 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	502 between different tenants that are distinguished by different labels.
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	503 This idea is illustrated by the :ref:`multitenant DICOM server
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	504 <multitenant-dicom>` sample plugin. A similar approach could be used
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	505 to implement Web interfaces that restrict the resources that are
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	506 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	507 useful in machine learning (or deep learning) workflows to
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	508 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	509 testing set.
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	510
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	511 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	512 the REST API::
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	513
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	514 $ 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	515 $ 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	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 $ 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	518
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	519 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	520 and can be removed using the DELETE HTTP method::
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 $ 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	523 []
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	524 $ 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	525 $ 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	526 [ "hello" ]
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	527 $ 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	528 $ 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	529 []
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	530
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	531 The built-in :ref:`Orthanc Explorer <orthanc-explorer>` Web interface
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	532 can be used to display, add, and remove labels.
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	533
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	534 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	535 <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	536 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	537 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	538 illustrated in the following request::
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	539
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	540 $ curl --request POST --url http://localhost:8042/tools/find \
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	541 --data '{
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	542 "Level" : "Study",
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	543 "Labels" : [ "hello" ],
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	544 "LabelsConstraint" : "All",
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	545 "Query" : { }
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 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	549 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	550 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	551 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	552 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	553 (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	554 provided in the ``Labels`` field). If not provided,
937 b9eb59d73a42 typo Sebastien Jodogne <s.jodogne@gmail.com> parents: 936 diff changeset	555 ``LabelsConstraint`` defaults to ``All``. Note that if there is only
b9eb59d73a42 typo Sebastien Jodogne <s.jodogne@gmail.com> parents: 936 diff changeset	556 one label in the ``Labels`` field, both ``Any`` and ``All`` have the
b9eb59d73a42 typo Sebastien Jodogne <s.jodogne@gmail.com> parents: 936 diff changeset	557 same behavior.
936 5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	558
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	559
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	560 Warning: The database index back-end must implement support for
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	561 labels. As of writing, only the PostgreSQL plugins in versions
5491953f7492 documentation of labels Sebastien Jodogne <s.jodogne@gmail.com> parents: 908 diff changeset	562 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	563 support for labels.

Mercurial > hg > orthanc-book

annotate Sphinx/source/faq/features.rst @ 1085:05d37a5abcc4