Mercurial > hg > orthanc-book
diff Sphinx/source/plugins/gdcm.rst @ 414:83f36bc9e725
gdcm plugin
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Fri, 15 May 2020 16:35:22 +0200 |
parents | |
children | b224cb85a96c |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/plugins/gdcm.rst Fri May 15 16:35:22 2020 +0200 @@ -0,0 +1,148 @@ +.. _gdcm: + + +GDCM plugin for Orthanc +======================= + +.. contents:: + +This **official** plugin extends Orthanc with a decoder/transcoder of +DICOM images that takes advantage of the `Grassroots GDCM library +<https://en.wikipedia.org/wiki/GDCM>`__. + +This plugin notably replaces the built-in decoder/transcoder of +Orthanc that internally uses `DCMTK +<https://dicom.offis.de/dcmtk.php.en>`__. This is notably necessary to +deal with DICOM images encoded using `JPEG2000 +<https://en.wikipedia.org/wiki/JPEG_2000>`__, as this format is not +readily supported by the core version of DCMTK. + + +History +------- + +Originally, this plugin was a sample snippet that was shipped with the +source code of Orthanc versions below 1.7.0, in the folder +``Plugins/Samples/GdcmDecoder/``. This sample code was itself bundled +in the :ref:`Orthanc Web viewer <webviewer>` (up to release 2.5) and +in the :ref:`Osimis Web viewer <osimis_webviewer>` plugins (up to +releases 1.3.x). + +In May 2020, starting with Orthanc 1.7.0, as a part of the large +refactoring necessary to implement :ref:`transcoding <transcoding>`, +the GDCM plugin was migrated as separate plugin. The reasons are +twofold: + +* To avoid redundancies between the two viewers, and to improve + performance by avoiding multiple calls to GDCM on unsupported DICOM + instances. + +* To uncouple the viewers and the :ref:`DICOMweb <dicomweb>` plugins + from the dependency on GDCM. This notably allows to more easily + follow new releases of the GDCM library. + + +Compilation +----------- + +.. highlight:: bash + +The procedure to compile this plugin is similar of that for the +:ref:`core of Orthanc <binaries>`. The following commands should work +for every UNIX-like distribution (including GNU/Linux):: + + $ mkdir Build + $ cd Build + $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release + $ make + +The compilation will produce a shared library ``OrthancGdcm`` that +contains the GDCM decoder/transcoder plugin. Pre-compiled binaries for +Microsoft Windows `are also available +<https://www.orthanc-server.com/browse.php?path=/plugin-gdcm>`__. + +*Remark:* Some older build instructions are also available in the +`source distribution +<https://hg.orthanc-server.com/orthanc-gdcm/file/default/Resources/BuildInstructions.txt>`__. + + +Usage +----- + +.. highlight:: json + +You of course first have to :ref:`install Orthanc <compiling>`. Once +Orthanc is installed, you must change the :ref:`configuration file +<configuration>` to tell Orthanc where it can find the plugin: This is +done by properly modifying the ``Plugins`` option. You could for +instance use the following configuration file:: + + { + "Name" : "MyOrthanc", + [...] + "Plugins" : [ + "/home/user/OrthancGdcm/Build/libOrthancGdcm.so" + ] + } + +.. highlight:: text + +Orthanc must of course be restarted after the modification of its +configuration file. Carefully inspect the :ref:`logs <log>` to make +sure that the GDCM plugin is properly loaded. + + +Advanced options +---------------- + +.. highlight:: json + +The configuration of the GDCM plugin can be fine-tuned by adding some options:: + + { + "Name" : "MyOrthanc", + [...] + "Plugins" : [ + "/home/user/OrthancGdcm/Build/libOrthancGdcm.so" + ], + "Gdcm" : { + "Enable" : false, + "Throttling" : 4 + }, + "BuiltinDecoderTranscoderOrder" : "After" + } + +* ``Enable`` specifies whether the GDCM decoder/transcoder is enabled. + By default, this option is set to ``true``. + +* ``Throttling`` specifies the maximum number of threads that can + simultaneously call the GDCM decoder/transcoder. This is useful to + avoid uncontrolled CPU or RAM usage if many people are connected to + the same Orthanc server. By default, no throttling is applied, and + an unrestricted number of threads can call GDCM simultaneously. + +* ``BuiltinDecoderTranscoderOrder`` is a configuration option of the + Orthanc core (i.e. outside of the ``Gdcm`` section) that can be used + to control whether the built-in DCMTK decoder/transcoder is applied + before or after GDCM. + +As a complement to the ``Enable`` option, you also have the +possibility to restrict the GDCM decoder/transcoder to some specific +`transfer syntaxes +<http://dicom.nema.org/medical/dicom/current/output/html/part05.html#chapter_10>`__ +using the ``RestrictTransferSyntaxes`` option. For instance, the +following configuration would use GDCM to decode JPEG 2000 images, +while using DCMTK to decode the other transfer syntaxes:: + + { + [...] + "Gdcm" : { + "Enable" : true, + "RestrictTransferSyntaxes" : [ + "1.2.840.10008.1.2.4.90", // JPEG 2000 Image Compression (Lossless Only) + "1.2.840.10008.1.2.4.91", // JPEG 2000 Image Compression + "1.2.840.10008.1.2.4.92", // JPEG 2000 Part 2 Multicomponent Image Compression (Lossless Only) + "1.2.840.10008.1.2.4.93" // JPEG 2000 Part 2 Multicomponent Image Compression + ] + } + }