fix: Overlays were broken. (#2614)

* fix(OHIFv3):Overlays were broken.

Adds a retrieveBulkData to elements containing BulkDataURI so that
anyone display the data can retrieve the required information.

* fix(OHIFv3):Added a call in the wrong spot, removed it.

* docs(OHIFv3):Added some documentation as requested

extensions/default/src/DicomWebDataSource/index.js

@@ -162,9 +162,9 @@ function createDicomWebApi(dicomWebConfig, UserAuthenticationService) {
             );
           }
 
+
           const storeInstances = instances => {
             const naturalizedInstances = instances.map(naturalizeDataset);
-
             DicomMetadataStore.addInstances(naturalizedInstances);
             callback(naturalizedInstances);
           };
@@ -252,9 +252,47 @@ function createDicomWebApi(dicomWebConfig, UserAuthenticationService) {
         sortFunction
       );
 
+      /**
+       * naturalizes the dataset, and adds a retrieve bulkdata method
+       * to any values containing BulkDataURI.
+       * @param {*} instance
+       * @returns naturalized dataset, with retrieveBulkData methods
+       */
+      const addRetrieveBulkData = instance => {
+        const naturalized = naturalizeDataset(instance);
+        Object.keys(naturalized).forEach(key => {
+          const value = naturalized[key];
+          // The value.Value will be set with the bulkdata read value
+          // in which case it isn't necessary to re-read this.
+          if (value && value.BulkDataURI && !value.Value) {
+            // Provide a method to fetch bulkdata
+            value.retrieveBulkData = () => {
+              const options = {
+                // The bulkdata fetches work with either multipart or
+                // singlepart, so set multipart to false to let the server
+                // decide which type to respond with.
+                multipart: false,
+                BulkDataURI: value.BulkDataURI,
+                // The study instance UID is required if the bulkdata uri
+                // is relative - that isn't disallowed by DICOMweb, but
+                // isn't well specified in the standard, but is needed in
+                // any implementation that stores static copies of the metadata
+                StudyInstanceUID: naturalized.StudyInstanceUID,
+              };
+              return qidoDicomWebClient.retrieveBulkData(options).then(val => {
+                const ret = val && val[0] || undefined;
+                value.Value = ret;
+                return ret;
+              });
+            };
+          }
+        });
+        return naturalized
+      };
+
       // Async load series, store as retrieved
       function storeInstances(instances) {
-        const naturalizedInstances = instances.map(naturalizeDataset);
+        const naturalizedInstances = instances.map(addRetrieveBulkData);
 
         DicomMetadataStore.addInstances(naturalizedInstances, madeInClient);
       }