Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/gdcm.rst @ 414:83f36bc9e725

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