# HG changeset patch # User Sebastien Jodogne # Date 1589553322 -7200 # Node ID 83f36bc9e72580112df865c74ca3a53139ca1bde # Parent b4cc2b6a9f1335939b42c1ea6f8c330c98b64ca5 gdcm plugin diff -r b4cc2b6a9f13 -r 83f36bc9e725 Sphinx/source/faq/transcoding.rst --- a/Sphinx/source/faq/transcoding.rst Thu May 07 14:47:22 2020 +0200 +++ b/Sphinx/source/faq/transcoding.rst Fri May 15 16:35:22 2020 +0200 @@ -17,12 +17,14 @@ * Explanation of DICOM protocol (transparent transcoding from compressed transfer syntaxes to uncompressed transfer syntaxes). - * ``TranscodingEnabled`` global configuration option + * ``TranscodeDicomProtocol`` global configuration option * ``AllowTranscoding`` in ``DicomModalities`` configuration option * ``/instances/.../modify`` route: ``Transcode`` option +* Routes to create archives: ``Transcode`` option + General information ------------------- diff -r b4cc2b6a9f13 -r 83f36bc9e725 Sphinx/source/plugins.rst --- a/Sphinx/source/plugins.rst Thu May 07 14:47:22 2020 +0200 +++ b/Sphinx/source/plugins.rst Fri May 15 16:35:22 2020 +0200 @@ -62,6 +62,7 @@ * :ref:`transfers` * :ref:`google` * :ref:`python-plugin` +* :ref:`gdcm` .. _plugins-contributed: diff -r b4cc2b6a9f13 -r 83f36bc9e725 Sphinx/source/plugins/gdcm.rst --- /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 +`__. + +This plugin notably replaces the built-in decoder/transcoder of +Orthanc that internally uses `DCMTK +`__. This is notably necessary to +deal with DICOM images encoded using `JPEG2000 +`__, 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 ` (up to release 2.5) and +in the :ref:`Osimis Web viewer ` 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 `, +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 ` 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 `. 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 +`__. + +*Remark:* Some older build instructions are also available in the +`source distribution +`__. + + +Usage +----- + +.. highlight:: json + +You of course first have to :ref:`install Orthanc `. Once +Orthanc is installed, you must change the :ref:`configuration file +` 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 ` 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 +`__ +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 + ] + } + } diff -r b4cc2b6a9f13 -r 83f36bc9e725 Sphinx/source/plugins/webviewer.rst --- a/Sphinx/source/plugins/webviewer.rst Thu May 07 14:47:22 2020 +0200 +++ b/Sphinx/source/plugins/webviewer.rst Fri May 15 16:35:22 2020 +0200 @@ -17,7 +17,7 @@ .. highlight:: bash -The procedure to compile these plugins is similar of that for the +The procedure to compile this plugin is similar of that for the :ref:`core of Orthanc `. The following commands should work for every UNIX-like distribution (including GNU/Linux):: @@ -33,7 +33,7 @@ *Remark:* Some older build instructions are also available in the `source distribution -`__. +`__. Usage @@ -96,8 +96,7 @@ "WebViewer" : { "CachePath" : "WebViewerCache", "CacheSize" : 10, - "Threads" : 4, - "EnableGdcm" : false + "Threads" : 4 } } @@ -108,22 +107,37 @@ megabytes. By default, a cache of 100 MB is used. * ``Threads`` specifies the number of threads that are used by the plugin to decode the DICOM images. -* ``EnableGdcm`` specifies whether `GDCM + + +Old advanced options (up to 2.5) +-------------------------------- + +Up to release 2.5 of the Orthanc Web Viewer plugin, the plugin was +shipping a decoder of DICOM images using the GDCM library. In May +2020, the support of GDCM has been :ref:`moved as a separate plugin +`. As a consequence, releases up to 2.5 had two more advanced +options, that were removed starting with version 3.0: + +* ``EnableGdcm`` specified whether `GDCM `__ should be used to decode DICOM images, replacing the built-in decoder of Orthanc that internally uses `DCMTK `__. - This is notably necessary to deal with DICOM images encoded using + This was notably necessary to deal with DICOM images encoded using `JPEG2000 `__, as this - format is not readily supported by the core version of DCMTK. By - default, this option is set to ``true``. + format is not readily supported by the core version of DCMTK. By + default, this option was set to ``true``. -As a complement to the ``EnableGdcm`` option, you also have the -possibility to restrict the GDCM decoder to some specific `transfer -syntaxes -`__ -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:: +* As a complement to the ``EnableGdcm`` option, it was also possible + to restrict the GDCM decoder to some specific `transfer syntaxes + `__ + using the ``RestrictTransferSyntaxes`` option. + + +.. highlight:: json + +For instance, the following configuration would enable GDCM to decode +JPEG 2000 images, while using DCMTK to decode the other transfer +syntaxes:: { [...]