annotate Sphinx/source/plugins/gdcm.rst @ 415:b224cb85a96c

cont
author Sebastien Jodogne <s.jodogne@gmail.com>
date Fri, 15 May 2020 16:38:17 +0200
parents 83f36bc9e725
children 525d59a7c198
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
414
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _gdcm:
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 GDCM plugin for Orthanc
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5 =======================
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 .. contents::
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 This **official** plugin extends Orthanc with a decoder/transcoder of
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 DICOM images that takes advantage of the `Grassroots GDCM library
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11 <https://en.wikipedia.org/wiki/GDCM>`__.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13 This plugin notably replaces the built-in decoder/transcoder of
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14 Orthanc that internally uses `DCMTK
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 <https://dicom.offis.de/dcmtk.php.en>`__. This is notably necessary to
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16 deal with DICOM images encoded using `JPEG2000
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 <https://en.wikipedia.org/wiki/JPEG_2000>`__, as this format is not
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18 readily supported by the core version of DCMTK.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 History
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22 -------
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
23
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24 Originally, this plugin was a sample snippet that was shipped with the
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25 source code of Orthanc versions below 1.7.0, in the folder
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26 ``Plugins/Samples/GdcmDecoder/``. This sample code was itself bundled
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 in the :ref:`Orthanc Web viewer <webviewer>` (up to release 2.5) and
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28 in the :ref:`Osimis Web viewer <osimis_webviewer>` plugins (up to
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29 releases 1.3.x).
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
30
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
31 In May 2020, starting with Orthanc 1.7.0, as a part of the large
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
32 refactoring necessary to implement :ref:`transcoding <transcoding>`,
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
33 the GDCM plugin was migrated as separate plugin. The reasons are
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34 twofold:
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 * To avoid redundancies between the two viewers, and to improve
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37 performance by avoiding multiple calls to GDCM on unsupported DICOM
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38 instances.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
39
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40 * To uncouple the viewers and the :ref:`DICOMweb <dicomweb>` plugins
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
41 from the dependency on GDCM. This notably allows to more easily
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
42 follow new releases of the GDCM library.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
43
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 Compilation
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
46 -----------
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
48 .. highlight:: bash
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50 The procedure to compile this plugin is similar of that for the
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51 :ref:`core of Orthanc <binaries>`. The following commands should work
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 for every UNIX-like distribution (including GNU/Linux)::
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54 $ mkdir Build
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55 $ cd Build
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 $ make
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59 The compilation will produce a shared library ``OrthancGdcm`` that
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60 contains the GDCM decoder/transcoder plugin. Pre-compiled binaries for
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61 Microsoft Windows `are also available
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62 <https://www.orthanc-server.com/browse.php?path=/plugin-gdcm>`__.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
63
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
64 *Remark:* Some older build instructions are also available in the
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65 `source distribution
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
66 <https://hg.orthanc-server.com/orthanc-gdcm/file/default/Resources/BuildInstructions.txt>`__.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
67
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
68
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69 Usage
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 -----
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
71
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
72 .. highlight:: json
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
73
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
74 You of course first have to :ref:`install Orthanc <compiling>`. Once
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75 Orthanc is installed, you must change the :ref:`configuration file
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
76 <configuration>` to tell Orthanc where it can find the plugin: This is
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
77 done by properly modifying the ``Plugins`` option. You could for
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78 instance use the following configuration file::
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80 {
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
81 "Name" : "MyOrthanc",
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
82 [...]
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
83 "Plugins" : [
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
84 "/home/user/OrthancGdcm/Build/libOrthancGdcm.so"
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
85 ]
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86 }
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
87
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
88 .. highlight:: text
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
89
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
90 Orthanc must of course be restarted after the modification of its
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
91 configuration file. Carefully inspect the :ref:`logs <log>` to make
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
92 sure that the GDCM plugin is properly loaded.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
93
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
94
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
95 Advanced options
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
96 ----------------
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
98 .. highlight:: json
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
99
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
100 The configuration of the GDCM plugin can be fine-tuned by adding some options::
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
101
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
102 {
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
103 "Name" : "MyOrthanc",
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
104 [...]
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
105 "Plugins" : [
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
106 "/home/user/OrthancGdcm/Build/libOrthancGdcm.so"
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
107 ],
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
108 "Gdcm" : {
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
109 "Enable" : false,
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
110 "Throttling" : 4
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
111 },
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
112 "BuiltinDecoderTranscoderOrder" : "After"
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
113 }
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
114
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
115 * ``Enable`` specifies whether the GDCM decoder/transcoder is enabled.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
116 By default, this option is set to ``true``.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
117
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
118 * ``Throttling`` specifies the maximum number of threads that can
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
119 simultaneously call the GDCM decoder/transcoder. This is useful to
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
120 avoid uncontrolled CPU or RAM usage if many people are connected to
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
121 the same Orthanc server. By default, no throttling is applied, and
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
122 an unrestricted number of threads can call GDCM simultaneously.
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
123
415
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 414
diff changeset
124 * Starting with Orthanc 1.7.0, ``BuiltinDecoderTranscoderOrder`` is a
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 414
diff changeset
125 configuration option of the Orthanc core (i.e. outside of the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 414
diff changeset
126 ``Gdcm`` section) that can be used to control whether the built-in
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 414
diff changeset
127 DCMTK decoder/transcoder is applied before or after GDCM.
414
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
128
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
129 As a complement to the ``Enable`` option, you also have the
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
130 possibility to restrict the GDCM decoder/transcoder to some specific
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
131 `transfer syntaxes
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
132 <http://dicom.nema.org/medical/dicom/current/output/html/part05.html#chapter_10>`__
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
133 using the ``RestrictTransferSyntaxes`` option. For instance, the
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
134 following configuration would use GDCM to decode JPEG 2000 images,
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
135 while using DCMTK to decode the other transfer syntaxes::
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
136
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
137 {
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
138 [...]
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
139 "Gdcm" : {
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
140 "Enable" : true,
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
141 "RestrictTransferSyntaxes" : [
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
142 "1.2.840.10008.1.2.4.90", // JPEG 2000 Image Compression (Lossless Only)
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
143 "1.2.840.10008.1.2.4.91", // JPEG 2000 Image Compression
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
144 "1.2.840.10008.1.2.4.92", // JPEG 2000 Part 2 Multicomponent Image Compression (Lossless Only)
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
145 "1.2.840.10008.1.2.4.93" // JPEG 2000 Part 2 Multicomponent Image Compression
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
146 ]
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
147 }
83f36bc9e725 gdcm plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
148 }