changeset 953:2038eb1f55bb

finalized ohif documentation
author Sebastien Jodogne <s.jodogne@gmail.com>
date Mon, 19 Jun 2023 08:00:51 +0200
parents 4a76327e83fb
children 19fd9eab4ec0
files Sphinx/source/faq/features.rst Sphinx/source/plugins/ohif.rst
diffstat 2 files changed, 98 insertions(+), 9 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/faq/features.rst	Mon Jun 19 07:05:38 2023 +0200
+++ b/Sphinx/source/faq/features.rst	Mon Jun 19 08:00:51 2023 +0200
@@ -329,6 +329,7 @@
 * ``Global property 5468`` is used by the :ref:`DICOMweb plugin <dicomweb>` to store the DICOMweb servers into the Orthanc database.
 * ``Metadata 4200`` is used by the plugin for :ref:`whole-slide imaging <wsi>` with version <= 0.7.
 * ``Metadata 4201`` is used by the plugin for :ref:`whole-slide imaging <wsi>` with version >= 1.0.
+* ``Metadata 4202`` is used by the :ref:`OHIF plugin <ohif>` to store precomputed information about the DICOM instances.
 
 
 Jobs
--- a/Sphinx/source/plugins/ohif.rst	Mon Jun 19 07:05:38 2023 +0200
+++ b/Sphinx/source/plugins/ohif.rst	Mon Jun 19 08:00:51 2023 +0200
@@ -11,6 +11,10 @@
 Orthanc with the `OHIF <https://ohif.org/>`__ extensible Web imaging
 platform.
 
+The plugin greatly simplifies the deployment of OHIF, as it does not
+necessitate the setup of any reverse proxy. It also speeds up the
+loading of 
+
 
 Usage
 -----
@@ -25,9 +29,6 @@
            :target: https://www.youtube.com/watch?v=-lzddzq9iT4
 |
 
-The plugin greatly simplifies the deployment of OHIF, as it does not
-necessitate the setup of any reverse proxy.
-
 
 Compilation
 -----------
@@ -88,27 +89,31 @@
 Using DICOMweb
 ^^^^^^^^^^^^^^
 
+.. highlight:: json
+
 By default, the plugin uses the `DICOM JSON data source
 <https://v3-docs.ohif.org/configuration/datasources/dicom-json/>`__ of
 OHIF. This data source is optimized to provide the fastest access to
 the DICOM images, while requiring no additional plugin. However, in
 order to deliver fast access, the OHIF plugin will cache additional
-information about each DICOM instance in the Orthanc database, which
-results in a larger size of the Orthanc database (an additional 1KB is
-roughly needed per instance).
+information about each DICOM instance as :ref:`metadata <metadata>` in
+the Orthanc database, which results in a larger size of the Orthanc
+database (an additional 1KB is roughly needed per instance).
 
-It is also possible to enable the `DICOMweb data source
+As an alternative, it is possible to enable the `DICOMweb data source
 <https://v3-docs.ohif.org/configuration/dataSources/dicom-web>`__. In
 this case, the :ref:`DICOMweb plugin of Orthanc <dicomweb>` must also
 be loaded. It can also be useful to load the :ref:`GDCM plugin <gdcm>`
-if the images use a compressed transfer syntax.
+if the DICOM images are encoded using a JPEG2k compressed transfer
+syntax.
 
 The advantages of using DICOMweb over the default DICOM JSON are:
 
 * More standard-compliant.
 
 * The OHIF study list is accessible, notably as a button on the
-  welcome screen of Orthanc Explorer.
+  welcome screen of Orthanc Explorer. The study list is not available
+  if using the DICOM JSON data source.
 
 * No additional space is used in the Orthanc database.
   
@@ -128,6 +133,8 @@
 Router basename
 ^^^^^^^^^^^^^^^
 
+.. highlight:: json
+
 If Orthanc is not branched at the root of a Web server thanks of the
 presence of a reverse proxy, the configuration option
 ``RouterBasename`` must be adapted.
@@ -148,6 +155,87 @@
 The default value of ``RouterBasename`` is ``/ohif/``.
 
 
+.. _ohif-preloading:
+
 Preloading
 ^^^^^^^^^^
 
+.. highlight:: json
+
+If using the DICOM JSON data source, whenever a new DICOM instance is
+received by Orthanc, the OHIF plugin will compute a summary of the
+DICOM tags of interest to OHIF, and will store it as :ref:`metadata
+<metadata>` in the Orthanc database. This process has the advantage of
+speeding up even the first opening of the DICOM study by OHIF, which
+probably corresponds to the expectations of most radiologists.
+
+However, if your Orthanc deployment is focused on speed, this
+preloading might be undesirable, as it slows down the ingestion of new
+DICOM instances by Orthanc. Furthermore, if your Orthanc server will
+contain a large number of DICOM studies that will never be displayed
+using OHIF, this can result in a waste of space in the Orthanc
+database because of the metadata that will be preloaded, but that will
+never be read.
+
+It is consequently possible to turn off the automated preloading
+of metadata using the following configuration::
+
+  {
+    "Plugins" : [
+      "/home/user/orthanc-ohif/Build/libOHIF.so"
+    ],
+    "OHIF" : {
+      "DataSource" : "dicom-json",
+      "Preload" : false
+    }
+  }
+
+If the ``Preload`` option is set to ``false``, the first display of a
+DICOM study can take several seconds because of the computation of the
+metadata, but subsequent displays will run much faster.
+
+Note that preloading is only applied to the newly received instances:
+The DICOM instances that were stored in the Orthanc server before the
+installation of the OHIF plugin will only benefit from the
+optimization starting with their second display using OHIF.
+
+
+For developers
+--------------
+
+Extensions to the REST API
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. highlight:: bash
+
+The content of the `DICOM JSON data source
+<https://v3-docs.ohif.org/configuration/datasources/dicom-json/>`__
+for a DICOM study of interest can be retrieved as follows::
+
+  $ curl http://demo.orthanc-server.com/studies/6b9e19d9-62094390-5f9ddb01-4a191ae7-9766b715/ohif-dicom-json
+
+This data source is constructed from the :ref:`metadata 4202
+<registry>` associated with the individual DICOM instances of the
+DICOM study. The metadata corresponds to the `Base64 encoding
+<https://en.wikipedia.org/wiki/Base64>`__ of a gzipped JSON file. For
+debugging, the JSON file associated with a DICOM instance can be
+inspected using::
+
+  $ curl http://demo.orthanc-server.com/instances/1f3c00bd-49df10b7-f416a598-1b3bb5a2-cb791b52/metadata/4202 | base64 -d | gunzip -c
+  
+
+Preloading existing studies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:ref:`As explained above <ohif-preloading>`, the metadata associated
+with DICOM instances are only preloaded for the newly ingested DICOM
+instances. Using the REST API of Orthanc, it is easy to create a
+script that would preload the metadata for the already existing DICOM
+studies, hereby greatly speeding up the first opening of those studies
+as well.
+
+This script would loop over the :ref:`the DICOM studies that are stored
+by Orthanc <rest-access>` using ``GET /studies``. For each study whose
+:ref:`Orthanc identifier <orthanc-identifiers>` is ``id``, the script
+would simply call ``GET /studies/{id}/ohif-dicom-json``.
+