ENH:select dicom subseries scalar volumes by default (Slicer#4860)

* ENH:select dicom subseries scalar volumes by default

When there a scalar volume has the option of being broken
into subseries by a tag such as AcquisitionNumber or
ImageOrientationPatient and there is only such tag a
reasonable heuristic is to prefer loading these subseries
as volumes rather than trying to load the full series, since
the full series is unlikely to be a coherent scalar volume.

This change ups the confidence for loadables for which there
is one set of subseries loadables.

This change also allows a set of loadables that all have the
higest confidence to all be selected.

This change works well on data that was previously corruped on load
and doesn't appear to have an impact otherwise.

An example of a dataset that loads better is series 2 from
patient PD-1-Lung-00008, study 20090123 in this collection:
https://wiki.cancerimagingarchive.net/pages/viewpage.action?pageId=41517500

* ENH: add DICOMUtils.loadByInstanceUID method

Sometimes it's useful to store only the instance uid of a slice,
for example with a measurement, but even if you know the
seriesUID for that instance, it doesn't always map to a specific
MRML node, so you may end up loading a full set of nodes
corresponding to different subseries when you only needed
to load the one with this instance.

With this change the loadables are filtered so that only
the highest confidence one containing the instance is
loaded.

* DOC: add comments on loadable confidence handling

* ENH: lower subseries confidence

make more headroom for other plugins that might have more
specific interpretations of this data.

Modules/Scripted/DICOMLib/DICOMBrowser.py

@@ -355,15 +355,20 @@ def organizeLoadables(self):
           loadablesBySeries[seriesUID].append(loadable)
 
     # now for each series, find the highest confidence selected loadables
-    # and set all others to be unselected
+    # and set all others to be unselected.
+    # If there are several loadables that tie for the
+    # highest confidence value, select them all
+    # on the assumption that they represent alternate interpretations
+    # of the data or subparts of it.  The user can either use
+    # advanced mode to deselect, or simply delete the
+    # unwanted interpretations.
     for series in loadablesBySeries:
       highestConfidenceValue = -1
       for loadable in loadablesBySeries[series]:
         if loadable.confidence > highestConfidenceValue:
           highestConfidenceValue = loadable.confidence
       for loadable in loadablesBySeries[series]:
-        if loadable.confidence < highestConfidenceValue:
-          loadable.selected = False
+        loadable.selected = loadable.confidence == highestConfidenceValue
 
   def onSeriesSelected(self, seriesUIDList):
     self.loadableTable.setLoadables([])

Modules/Scripted/DICOMPlugins/DICOMScalarVolumePlugin.py

@@ -211,8 +211,10 @@ def examineFiles(self,files):
     # second, for any tags that have more than one value, create a new
     # virtual series
     #
+    subseriesCount = 0
     for tag in subseriesTags:
       if len(subseriesValues[tag]) > 1:
+        subseriesCount += 1
         for valueIndex, value in enumerate(subseriesValues[tag]):
           # default loadable includes all files for series
           loadable = DICOMLoadable()
@@ -224,6 +226,12 @@ def examineFiles(self,files):
           loadable.selected = False
           loadables.append(loadable)
 
+    if subseriesCount == 1:
+      # only one kind of subseries, then it's probably correct
+      # so make them higher confidence than the default all-files version
+      for subseriesLoadable in loadables[1:]:
+        subseriesLoadable.confidence = .55
+
     # remove any files from loadables that don't have pixel data (no point sending them to ITK for reading)
     # also remove DICOM SEG, since it is not handled by ITK readers
     newLoadables = []