changeset 420:8afbe10c03d9 c-get

integration mainline->c-get
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 20 May 2020 07:06:41 +0200
parents 0c9a52bc20d9 (current diff) 24b1c64002b8 (diff)
children e0b4b88446a8
files
diffstat 4 files changed, 187 insertions(+), 16 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/faq/transcoding.rst	Mon May 18 17:12:47 2020 +0200
+++ b/Sphinx/source/faq/transcoding.rst	Wed May 20 07:06:41 2020 +0200
@@ -17,12 +17,20 @@
 * 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
 
+* ``IngestTranscoding``
+
+* ``BuiltinDecoderTranscoderOrder``
+
+* ``DicomLossyCompressionLevel``
+
+* Routes to create archives: ``Transcode`` option
+
 
 General information
 -------------------
--- a/Sphinx/source/plugins.rst	Mon May 18 17:12:47 2020 +0200
+++ b/Sphinx/source/plugins.rst	Wed May 20 07:06:41 2020 +0200
@@ -62,6 +62,7 @@
 * :ref:`transfers`
 * :ref:`google`    
 * :ref:`python-plugin`    
+* :ref:`gdcm`    
 
 .. _plugins-contributed:
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/gdcm.rst	Wed May 20 07:06:41 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.
+
+* Starting with Orthanc 1.7.0, ``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
+      ]
+    }
+  }
--- a/Sphinx/source/plugins/webviewer.rst	Mon May 18 17:12:47 2020 +0200
+++ b/Sphinx/source/plugins/webviewer.rst	Wed May 20 07:06:41 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 <binaries>`. 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
-<https://hg.orthanc-server.com/orthanc-webviewer/file/tip/Resources/BuildInstructions.txt>`__.
+<https://hg.orthanc-server.com/orthanc-webviewer/file/default/Resources/BuildInstructions.txt>`__.
 
 
 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
+<gdcm>`. 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
   <https://sourceforge.net/projects/gdcm/>`__ should be used to decode
   DICOM images, replacing the built-in decoder of Orthanc that
   internally uses `DCMTK <https://dicom.offis.de/dcmtk.php.en>`__.
-  This is notably necessary to deal with DICOM images encoded using
+  This was 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.  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
-<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::
+* As a complement to the ``EnableGdcm`` option, it was also possible
+  to restrict the GDCM decoder to some specific `transfer syntaxes
+  <http://dicom.nema.org/medical/dicom/current/output/html/part05.html#chapter_10>`__
+  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::
 
   {
     [...]