# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1582302966 -3600
# Node ID 42104307e838e5a6af776efd8f95bf766cb2a164
# Parent  be69f8c86f56d88d43866d0720e3f8f87d652c60
"Extrapolate" mode of DICOMweb plugin

diff -r be69f8c86f56 -r 42104307e838 Sphinx/source/plugins/dicomweb.rst
--- a/Sphinx/source/plugins/dicomweb.rst	Wed Feb 19 14:26:05 2020 +0100
+++ b/Sphinx/source/plugins/dicomweb.rst	Fri Feb 21 17:36:06 2020 +0100
@@ -121,8 +121,8 @@
       "Ssl" : false,              // Whether HTTPS should be used for subsequent WADO-RS requests
       "QidoCaseSensitive" : true, // For QIDO-RS server, whether search is case sensitive (since release 0.5)
       "Host" : "localhost",       // Hard-codes the name of the host for subsequent WADO-RS requests (deprecated)
-      "StudiesMetadata" : "Full", // How study-level metadata is retrieved ("Full" or "MainDicomTags", since 1.1)
-      "SeriesMetadata" : "Full"   // How series-level metadata is retrieved ("Full" or "MainDicomTags", since 1.1)
+      "StudiesMetadata" : "Full", // How study-level metadata is retrieved (since release 1.1, cf. section below)
+      "SeriesMetadata" : "Full"   // How series-level metadata is retrieved (since release 1.1, cf. section below)
     }
   }
 
@@ -131,45 +131,6 @@
 QIDO-RS request. It might be a good idea to set this option to
 ``Utf8`` if you are dealing with an international environment.
 
-
-The options ``StudiesMetadata`` and ``SeriesMetadata`` were introduced
-in release 1.1 of the DICOMweb plugin. These options specify how the
-calls to ``/dicom-web/studies/.../metadata`` and
-``/dicom-web/studies/.../series/.../metadata`` (i.e. `WADO-RS Retrieve
-Metadata
-<http://dicom.nema.org/medical/dicom/2019a/output/chtml/part18/sect_6.5.6.html>`__)
-are processed:
-
-* If ``Full`` mode is used, the plugin will have to read all the DICOM
-  instances of the study/series from the :ref:`storage area
-  <orthanc-storage>`, which gives exact results but requires all the
-  individual instances to be read and parsed from the filesystem,
-  leading to bad performance (cf. `issue 162
-  <https://bitbucket.org/sjodogne/orthanc/issues/162/dicomweb-metadata-resource-reads-all>`__).
-  This is the default mode.
-
-* If ``MainDicomTags`` mode is used, the plugin will only report the
-  main DICOM tags that are stored inside the Orthanc database index.
-  The DICOM files are not read from the disk, which provides very good
-  performance. However, this is a small subset of all the tags that
-  would be retrieved if using the ``Full`` mode: A DICOMweb viewer
-  might need more tags.
-
-* *Work-in-progress:* In the future, another mode might be introduced
-  for the series level, that would assume that the value of some
-  non-main DICOM tags is constant across all the instances of the
-  series. It would then be sufficient for the DICOMweb plugin to only
-  read one instance from the series. This mode would be a compromise
-  between ``MainDicomTags`` (focus on speed) and ``Full`` (focus on
-  accuracy). This mode is still under active investigation, as it
-  might silently break DICOMweb viewers.
-
-* If you are using a DICOMweb viewer (such as forthcoming Stone Web
-  viewer or OHIF viewer) in a setup where performance is important,
-  you should most probably set ``StudiesMetadata`` to
-  ``MainDicomTags`` and ``SeriesMetadata`` to ``Full``.
-
-  
 **Remark 1:** The following configuration options were present in
 releases <= 0.6 of the plugin, but are not used anymore::
 
@@ -192,6 +153,87 @@
 clients.
 
 
+.. _dicomweb-server-metadata-config:
+
+Fine-tuning server for WADO-RS Retrieve Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The options ``StudiesMetadata`` and ``SeriesMetadata`` were introduced
+in release 1.1 of the DICOMweb plugin. These options specify how the
+calls to ``/dicom-web/studies/.../metadata`` and
+``/dicom-web/studies/.../series/.../metadata`` (i.e. `WADO-RS Retrieve
+Metadata
+<http://dicom.nema.org/medical/dicom/2019a/output/chtml/part18/sect_6.5.6.html>`__)
+are processed:
+
+* If ``Full`` mode is used, the plugin will read all the DICOM
+  instances of the study/series of interest from the :ref:`storage
+  area <orthanc-storage>`, which gives fully accurate results but
+  requires all the individual instances to be read and parsed from the
+  filesystem, leading to slow performance (cf. `issue 162
+  <https://bitbucket.org/sjodogne/orthanc/issues/162/dicomweb-metadata-resource-reads-all>`__).
+  This is the default mode.
+
+* If ``MainDicomTags`` mode is used, the plugin will only report the
+  main DICOM tags that are indexed by the Orthanc database. The DICOM
+  files are not read from the disk, which provides best
+  performance. However, this is a small subset of all the tags that
+  would be retrieved if using the ``Full`` mode: A DICOMweb viewer
+  might need more tags.
+
+* If ``Extrapolate`` mode is used, the plugin will read up to 3 DICOM
+  instances at random that belong to the study/series of interest. It
+  will then test whether the majority of these instances share the
+  same value for a predefined subset of DICOM tags. If so, this value
+  is added to the metadata response; otherwise, the tag is not
+  reported. In other words, this mode extrapolates the value of some
+  predefined tags by assuming that these tags should be constant
+  across all the instances of the study/series. This mode is a
+  compromise between ``MainDicomTags`` (focus on speed) and ``Full``
+  (focus on accuracy).
+
+* If you are using a DICOMweb viewer (such as forthcoming Stone Web
+  viewer or `OHIF viewer
+  <https://groups.google.com/d/msg/orthanc-users/y1N5zOFVk0M/a3YMdhNqBwAJ>`__)
+  in a setup where performance and accuracy are both important, you
+  should most probably set ``StudiesMetadata`` to ``MainDicomTags``
+  and ``SeriesMetadata`` to ``Full``. Forthcoming Stone Web viewer
+  will probably specify a value for the
+  ``SeriesMetadataExtrapolatedTags`` option to be used for setups
+  where performance is extremely important.
+
+
+If using the ``Extrapolate`` mode, the predefined tags are provided
+using the ``StudiesMetadataExtrapolatedTags`` and
+``SeriesMetadataExtrapolatedTags`` configuration options as follows::
+  
+  {
+    [...]
+    "DicomWeb" : {
+      [...]
+      "StudiesMetadata" : "Extrapolate",
+      "StudiesMetadataExtrapolatedTags" : [
+        "AcquisitionDate"
+      ],
+      "SeriesMetadata" : "Extrapolate",
+      "SeriesMetadataExtrapolatedTags" : [
+        "BitsAllocated",
+        "BitsStored",
+        "Columns",
+        "HighBit",
+        "PhotometricInterpretation",
+        "PixelSpacing",
+        "PlanarConfiguration",
+        "RescaleIntercept",
+        "RescaleSlope",
+        "Rows",
+        "SOPClassUID",
+        "SamplesPerPixel",
+        "SliceThickness"
+      ]
+    }
+  }
+
 
 .. _dicomweb-client-config: